Expand barback's notion of dirtiness to understand declaredness.

pkg/barback/lib/src/node_status.dart

+// Copyright (c) 2014, 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.
+
+library barback.node_status;
+
+/// The status of a node in barback's package graph.
+///
+/// A node has three possible statuses: [DONE], [DECLARED], and [DIRTY]. These
+/// are ordered from least dirty to most dirty; the [dirtier] and [dirtiest]
+/// functions make use of this ordering.
+class NodeStatus {
+  /// The node has finished its work and won't do anything else until external
+  /// input causes it to.
+  ///
+  /// For deferred nodes, this may indicate that they're finished declaring
+  /// their outputs and waiting to be forced.
+  static const DONE = const NodeStatus("done");
+
+  /// The node has declared its outputs but their concrete values are still
+  /// being generated.
+  ///
+  /// This is only meaningful for nodes that are or contain declaring
+  /// transformers. Note that a lazy transformer that's declared its outputs but
+  /// isn't actively working to generate them is considered [DONE], not
+  /// [DECLARED].

[Bob Nystrom, 2014/04/25 22:02:33]

This is super confusing. Why isn't it DECLARED?

[nweiz, 2014/04/28 21:02:00]

Because the node's concrete value isn't being generated, which is one of the
conditions for being marked DECLARED.

Think about it in terms of the package graph as a whole. We want to emit a
BuildResult once all the work is done and nothing else will change without
external input—this is what "DONE" indicates. If some transformers are lazy, we
don't want to wait until they're materialized to emit the BuildResult, we want
to emit it as soon as they're declared.

[Bob Nystrom, 2014/04/29 18:34:43]

That makes sense, but the terminology is misleading. How about:

DONE -> IDLE
DIRTY -> RUNNING
DECLARED -> MATERIALIZING

?

[nweiz, 2014/04/29 20:11:26]

Done.

+  static const DECLARED = const NodeStatus("declared");
+
+  /// The node is actively working on declaring or generating its outputs.
+  ///
+  /// Declaring transformers are only considered dirty until they're finished
+  /// declaring their outputs; past that point, they're always either [DECLARED]
+  /// or [DONE]. Non-declaring transformers, by contrast, are always either
+  /// [DIRTY] or [DONE].
+  static const DIRTY = const NodeStatus("dirty");
+
+  final String _name;
+
+  /// Returns the dirtiest status in [statuses].
+  static NodeStatus dirtiest(Iterable<NodeStatus> statuses) =>
+      statuses.fold(NodeStatus.DONE,
+          (status1, status2) => status1.dirtier(status2));
+
+  const NodeStatus(this._name);
+
+  String toString() => _name;
+
+  /// Returns [this] or [other], whichever is dirtier.
+  NodeStatus dirtier(NodeStatus other) {
+    if (this == DIRTY || other == DIRTY) return DIRTY;
+    if (this == DECLARED || other == DECLARED) return DECLARED;
+    return DONE;
+  }
+}