README.md

# Code Transformers
This package exposes various tools to help in the creation and testing of
barback transformers, as well as an interface for logging messages with
constant ids for documentation purposes.

## Messages and logging

This package exposes a `BuildLogger` class as well as `Message`,
`MessageTemplate`, and `MessageId` classes. These work together to provide
stable error messages with ids that can be referenced in documentation.

### MessageId

A `MessageId` is a constant definition of a message in a package. These are
used to group messages with the same id or link to sections in a document.

    const myId = const MessageId('myPackage', 0);
 
These ids should typically never change or disappear throughout the entire
lifetime of a package.

### Message

A `Message` is a const object which has a `MessageId` and `snippet`.

    const myMessage = const Message(myId, 'my message');

### MessageTemplate

TODO(jakemac): Docs on this, see
https://github.com/dart-lang/code-transformers/blob/master/lib/messages/messages.dart

### BuildLogger

The `BuildLogger` class just wraps a normal `TransformLogger` to provide some
additional functionality. You use it in the same way as a `TransformLogger`
except that the log methods can accept a `String` or a `Message`. This should
usually be created in the first step of your transformers `apply` function:

    apply(Transform transform) {
      // If detailsUri is passed, then a link will be output with each log
      // message that follows this format
      // `$detailsUri#${msg.id.package}_${msg.id.id}`.
      var logger = new BuildLogger(transform, detailsUri: 'http://foo.com');
    }

You can optionally dump out a file containing all the logs found in JSON
format by calling the `writeOutput` method on the logger when you are done.
The output file will have the same file path as the primary input of the
transformer, with an extension matching this pattern `._buildLogs.$i`. The
`i` increments starting at 0 each time that logs are output (if multiple
transformers run on the same file for instance). These can all be combined
into a single file later on by calling the static
`combineLogFiles(Transform transform)` function.

## Testing Transformers

TODO(jakemac): Docs on this, see `testPhases` in
https://github.com/dart-lang/code-transformers/blob/master/lib/tests.dart

## Using the Analyzer in Transformers

This package exposes a `Resolver` class which helps out when using the
analyzer in a transform.

TODO(jakemac): Docs on this, see
https://github.com/dart-lang/code-transformers/blob/master/lib/src/resolver.dart

## Barback AssetIds and Uris

This package also provides some helpers to convert `AssetId`s to and from `Uri`s
relative to a source asset.

TODO(jakemac): Docs on this, see `uriToAssetId` & `assetIdToUri` in
https://github.com/dart-lang/code-transformers/blob/master/lib/assets.dart