First pass at build dependency graph for barback.

pkg/barback/lib/transformer.dart

+// Copyright (c) 2013, 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.generator;
+
+import 'dart:async';
+import 'dart:io';
+
+import 'package:pathos/path.dart' as pathos;
+
+import 'barback.dart';
+
+/// A [Transformer] represents a processor that takes in one or more input
+/// assets and uses them to generate one or more output assets.
+///
+/// Dart2js, a SASS->CSS processor, a CSS spriter, and a tool to concatenate
+/// files are all examples of transformers. To define your own transformation
+/// step, extend (or implement) this class.
+abstract class Transformer {
+  /// Returns `true` if [input] can be a primary input for this transformer.
+  ///
+  /// While a transformer can read from multiple input files, one must be the
+  /// "primary" input. This asset determines whether the transformation should
+  /// be run at all. If the primary input is removed, the transformer will no
+  /// longer be run.
+  ///
+  /// A concrete example is dart2js. When you run dart2js, it will traverse
+  /// all of the imports in your Dart source files and use the contents of all
+  /// of those to generate the final JS. However you still run dart2js "on" a
+  /// single file: the entrypoint Dart file that has your `main()` method.
+  /// This entrypoint file would be the primary input.
+  Future<bool> isPrimary(AssetId input);
+
+  /// Run this transformer on on the primary input specified by [transform].
+  ///
+  /// The [transform] is used by the [Transformer] for two purposes (in
+  /// addition to accessing the primary input). It can call `getInput()` to
+  /// request additional input assets. It also calls `addOutput()` to provide
+  /// generated assets back to the system. Either can be called multiple times,
+  /// in any order.
+  ///
+  /// In other words, a Transformer's job is to find all inputs for a
+  /// transform, starting at the primary input, then generate all output assets
+  /// and yield them back to the transform.
+  Future apply(Transform transform);
+
+  String toString() => runtimeType.toString().replaceAll("Transformer", "");
+}
+
+/// While a [Transformer] represents a *kind* of transformation, this defines
+/// one specific usage of it on a set of files. This ephemeral object exists
+/// only during an actual transform application to to facilitate communication

[nweiz, 2013/06/18 23:14:46]

"to to" -> "to"

[Bob Nystrom, 2013/06/20 00:23:59]

Done.

+/// between the [Transformer] and the code hosting the transformation. It lets
+/// the [Transformer] access inputs and generate outputs.
+abstract class Transform {
+  /// Gets the ID of the primary input for this transformation. While a
+  /// transformation can use multiple input assets, one must be a special
+  /// "primary" asset. This will be the "entrypoint" or "main" input file for
+  /// a transformation.
+  ///
+  /// For example, with a dart2js transform, the primary input would be the
+  /// entrypoint Dart file. All of the other Dart files that that imports
+  /// would be secondary inputs.
+  AssetId get primaryId;
+
+  /// Gets the asset for the primary input.
+  Future<Asset> get primaryInput => getInput(primaryId);
+
+  /// Gets the asset for for an input [id]. If an input with that ID cannot be
+  /// found, throws an [AssetNotFoundException].
+  Future<Asset> getInput(AssetId id);
+
+  /// Stores [output] as the output created by this transformation for asset
+  /// [id]. A transformation can output as many assets as it wants.
+  void addOutput(AssetId id, Asset output);
+}