Merge package:graphs into shared tool repository

Author: dcharkes

.github/workflows/graphs.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  # Run on PRs and pushes to the default branch.
+  push:
+    branches: [ master ]
+    paths:
+      - '.github/workflows/graphs.yml'
+      - 'pkgs/graphs/**'
+  pull_request:
+    branches: [ master ]
+    paths:
+      - '.github/workflows/graphs.yml'
+      - 'pkgs/graphs/**'
+  schedule:
+    - cron: "0 0 * * 0"
+
+env:
+  PUB_ENVIRONMENT: bot.github
+
+jobs:
+  # Check code formatting and static analysis on a single OS (linux)
+  # against Dart beta.
+  analyze:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: pkgs/graphs/
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [dev]
+    steps:
+      - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab
+      - uses: dart-lang/setup-dart@d6a63dab3335f427404425de0fbfed4686d93c4f
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        run: dart pub get
+      - run: dart format --output=none --set-exit-if-changed .
+        if: always() && steps.install.outcome == 'success'
+      - run: dart analyze --fatal-infos
+        if: always() && steps.install.outcome == 'success'
+
+  test:
+    needs: analyze
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        working-directory: pkgs/graphs/
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        sdk: [2.18.0, dev]
+    steps:
+      - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab
+      - uses: dart-lang/setup-dart@d6a63dab3335f427404425de0fbfed4686d93c4f
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        run: dart pub get
+      - run: dart test --platform vm
+        if: always() && steps.install.outcome == 'success'
+      - run: dart test --platform chrome
+        if: always() && steps.install.outcome == 'success'

pkgs/graphs/.gitignore

@@ -0,0 +1,5 @@
+.dart_tool/
+.packages
+.pub/
+build/
+pubspec.lock

pkgs/graphs/CHANGELOG.md

@@ -0,0 +1,64 @@
+# 2.3.0
+
+- Add a `transitiveClosure` function.
+- Make `stronglyConnectedComponents` and `topologicalSort` iterative rather than
+  recursive to avoid stack overflows on very large graphs.
+- Require Dart 2.18
+
+# 2.2.0
+
+- Add a `secondarySort` parameter to the `topologicalSort()` function which
+  applies an additional lexical sort where that doesn't break the topological
+  sort.
+
+# 2.1.0
+
+- Add a `topologicalSort()` function.
+
+# 2.0.0
+
+- **Breaking**: `crawlAsync` will no longer ignore a node from the graph if the
+  `readNode` callback returns null.
+
+# 1.0.0
+
+- Migrate to null safety.
+- **Breaking**: Paths from `shortestPath[s]` are now returned as iterables to
+  reduce memory consumption of the algorithm to O(n).
+
+# 0.2.0
+
+- **BREAKING** `shortestPath`, `shortestPaths` and `stronglyConnectedComponents`
+  now have one generic parameter and have replaced the `key` parameter with
+  optional params: `{bool equals(T key1, T key2), int hashCode(T key)}`.
+  This follows the pattern used in `dart:collection` classes `HashMap` and 
+  `LinkedHashMap`. It improves the usability and performance of the case where
+  the source values are directly usable in a hash data structure.
+
+# 0.1.3+1
+
+- Fixed a bug with non-identity `key` in `shortestPath` and `shortestPaths`.
+
+# 0.1.3
+
+- Added `shortestPath` and `shortestPaths` functions.
+- Use `HashMap` and `HashSet` from `dart:collection` for
+  `stronglyConnectedComponents`. Improves runtime performance.
+
+# 0.1.2+1
+
+- Allow using non-dev Dart 2 SDK.
+
+# 0.1.2
+
+- `crawlAsync` surfaces exceptions while crawling through the result stream
+  rather than as uncaught asynchronous errors.
+
+# 0.1.1
+
+- `crawlAsync` will now ignore nodes that are resolved to `null`.
+
+# 0.1.0
+
+- Initial release with an implementation of `stronglyConnectedComponents` and
+  `crawlAsync`.

pkgs/graphs/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+Want to contribute? Great! First, read this page (including the small print at
+the end).
+
+### Before you contribute
+Before we can use your code, you must sign the
+[Google Individual Contributor License Agreement](https://cla.developers.google.com/about/google-individual)
+(CLA), which you can do online. The CLA is necessary mainly because you own the
+copyright to your changes, even after your contribution becomes part of our
+codebase, so we need your permission to use and distribute your code. We also
+need to be sure of various other things—for instance that you'll tell us if you
+know that your code infringes on other people's patents. You don't have to sign
+the CLA until after you've submitted your code for review and a member has
+approved it, but you must do it before we can put your code into our codebase.
+
+Before you start working on a larger contribution, you should get in touch with
+us first through the issue tracker with your idea so that we can help out and
+possibly guide you. Coordinating up front makes it much easier to avoid
+frustration later on.
+
+### Code reviews
+All submissions, including submissions by project members, require review.
+
+### File headers
+All files in the project must start with the following header.
+
+    // Copyright (c) 2017, the Dart project authors.  Please see the AUTHORS file
+    // for details. All rights reserved. Use of this source code is governed by a
+    // BSD-style license that can be found in the LICENSE file.
+
+### The small print
+Contributions made by corporations are covered by a different agreement than the
+one above, the
+[Software Grant and Corporate Contributor License Agreement](https://developers.google.com/open-source/cla/corporate).

pkgs/graphs/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2017, the Dart project authors. 
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/graphs/README.md

@@ -0,0 +1,42 @@
+[![CI](https://github.com/dart-lang/tools/actions/workflows/graphs.yml/badge.svg)](https://github.com/dart-lang/tools/actions/workflows/graphs.yml)
+[![pub package](https://img.shields.io/pub/v/graphs.svg)](https://pub.dev/packages/graphs)
+[![package publisher](https://img.shields.io/pub/publisher/graphs.svg)](https://pub.dev/packages/graphs/publisher)
+
+Graph algorithms that do not specify a particular approach for representing a
+Graph.
+
+Functions in this package will take arguments that provide the mechanism for
+traversing the graph. For example two common approaches for representing a
+graph:
+
+```dart
+class Graph {
+  Map<Node, List<Node>> nodes;
+}
+class Node {
+  // Interesting data
+}
+```
+
+```dart
+class Graph {
+  Node root;
+}
+class Node {
+  List<Node> edges;
+  // Interesting data
+}
+```
+
+Any representation can be adapted to the needs of the algorithm:
+
+- Some algorithms need to associate data with each node in the graph. If the
+  node type `T` does not correctly or efficiently implement `hashCode` or `==`,
+  you may provide optional `equals` and/or `hashCode` functions are parameters.
+- Algorithms which need to traverse the graph take a `edges` function which provides the reachable nodes.
+  - `(node) => graph[node]`
+  - `(node) => node.edges`
+
+
+Graphs that are resolved asynchronously will have similar functions which
+return `FutureOr`.

pkgs/graphs/analysis_options.yaml

@@ -0,0 +1,56 @@
+# https://dart.dev/guides/language/analysis-options
+include: package:lints/recommended.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+
+linter:
+  rules:
+    - always_declare_return_types
+    - avoid_bool_literals_in_conditional_expressions
+    - avoid_catching_errors
+    - avoid_classes_with_only_static_members
+    - avoid_dynamic_calls
+    - avoid_private_typedef_functions
+    - avoid_redundant_argument_values
+    - avoid_returning_null
+    - avoid_returning_null_for_future
+    - avoid_returning_this
+    - avoid_unused_constructor_parameters
+    - avoid_void_async
+    - cancel_subscriptions
+    - comment_references
+    - directives_ordering
+    - join_return_with_assignment
+    - lines_longer_than_80_chars
+    - literal_only_boolean_expressions
+    - missing_whitespace_between_adjacent_strings
+    - no_adjacent_strings_in_list
+    - no_runtimeType_toString
+    - omit_local_variable_types
+    - only_throw_errors
+    - package_api_docs
+    - prefer_asserts_in_initializer_lists
+    - prefer_const_constructors
+    - prefer_const_declarations
+    - prefer_expression_function_bodies
+    - prefer_final_locals
+    - prefer_relative_imports
+    - prefer_single_quotes
+    - require_trailing_commas
+    - test_types_in_equals
+    - throw_in_finally
+    - type_annotate_public_apis
+    - unawaited_futures
+    - unnecessary_await_in_return
+    - unnecessary_lambdas
+    - unnecessary_parenthesis
+    - unnecessary_raw_strings
+    - unnecessary_statements
+    - use_if_null_to_convert_nulls_to_bools
+    - use_raw_strings
+    - use_string_buffers
+    - use_super_parameters

pkgs/graphs/benchmark/connected_components_benchmark.dart

@@ -0,0 +1,50 @@
+// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:collection';
+import 'dart:math' show Random;
+
+import 'package:graphs/graphs.dart';
+
+void main() {
+  final rnd = Random(0);
+  const size = 2000;
+  final graph = HashMap<int, List<int>>();
+
+  for (var i = 0; i < size * 3; i++) {
+    final toList = graph.putIfAbsent(rnd.nextInt(size), () => <int>[]);
+
+    final toValue = rnd.nextInt(size);
+    if (!toList.contains(toValue)) {
+      toList.add(toValue);
+    }
+  }
+
+  var maxCount = 0;
+  var maxIteration = 0;
+
+  const duration = Duration(milliseconds: 100);
+
+  for (var i = 1;; i++) {
+    var count = 0;
+    final watch = Stopwatch()..start();
+    while (watch.elapsed < duration) {
+      count++;
+      final length =
+          stronglyConnectedComponents(graph.keys, (e) => graph[e] ?? <Never>[])
+              .length;
+      assert(length == 244, '$length');
+    }
+
+    if (count > maxCount) {
+      maxCount = count;
+      maxIteration = i;
+    }
+
+    if (maxIteration == i || (i - maxIteration) % 20 == 0) {
+      print('max iterations in ${duration.inMilliseconds}ms: $maxCount\t'
+          'after $maxIteration of $i iterations');
+    }
+  }
+}