Step one towards stable error messages with details:

pkg/polymer/lib/src/build/common.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.
 
 /// Common methods used by transfomers.
 library polymer.src.build.common;
 
 import 'dart:async';
 
 import 'package:analyzer/src/generated/ast.dart';
 import 'package:analyzer/src/generated/error.dart';
 import 'package:analyzer/src/generated/parser.dart';
 import 'package:analyzer/src/generated/scanner.dart';
 import 'package:barback/barback.dart';
+import 'package:code_transformers/messages/build_logger.dart';
 import 'package:html5lib/dom.dart' show Document;
 import 'package:html5lib/parser.dart' show HtmlParser;
+import 'package:observe/transformer.dart' show ObservableTransformer;
 import 'package:path/path.dart' as path;
-import 'package:observe/transformer.dart' show ObservableTransformer;
+
+import 'constants.dart';
+import 'messages.dart';
+
+export 'constants.dart';
 
 const _ignoredErrors = const [
   'unexpected-dash-after-double-dash-in-comment',
   'unexpected-char-in-comment',
 ];
 
 /// Parses an HTML file [contents] and returns a DOM-like tree. Adds emitted
 /// error/warning to [logger].
-Document _parseHtml(String contents, String sourcePath, TransformLogger logger,
+Document _parseHtml(String contents, String sourcePath, BuildLogger logger,
     {bool checkDocType: true, bool showWarnings: true}) {
   // TODO(jmesserly): make HTTP encoding configurable
   var parser = new HtmlParser(contents, encoding: 'utf8',
       generateSpans: true, sourceUrl: sourcePath);
   var document = parser.parse();
 
   // Note: errors aren't fatal in HTML (unless strict mode is on).
   // So just print them as warnings.
   if (showWarnings) {
     for (var e in parser.errors) {
       if (_ignoredErrors.contains(e.errorCode)) continue;
       if (checkDocType || e.errorCode != 'expected-doctype-but-got-start-tag') {
-        logger.warning(e.message, span: e.span);
+        logger.warning(HTML5_WARNING.create({'message': e.message}),
+            span: e.span);
       }
     }
   }
   return document;
 }
 
 /// Additional options used by polymer transformers
 class TransformOptions {
   /// List of entrypoints paths. The paths are relative to the package root and
   /// are represented using posix style, which matches the representation used
@@ skipping 68 matching lines @@
     // Then check the global default setting.
     var globalDefault = inlineStylesheets['default'];
     return (globalDefault != null) ? globalDefault : true;
   }
 }
 
 /// Mixin for polymer transformers.
 abstract class PolymerTransformer {
   TransformOptions get options;
 
-  Future<Document> readPrimaryAsHtml(Transform transform) {
+  Future<Document> readPrimaryAsHtml(Transform transform, BuildLogger logger) {
     var asset = transform.primaryInput;
     var id = asset.id;
     return asset.readAsString().then((content) {
-      return _parseHtml(content, id.path, transform.logger,
+      return _parseHtml(content, id.path, logger,
         checkDocType: options.isHtmlEntryPoint(id));
     });
   }
 
   Future<Document> readAsHtml(AssetId id, Transform transform,
+      BuildLogger logger,
       {bool showWarnings: true}) {
     var primaryId = transform.primaryInput.id;
     bool samePackage = id.package == primaryId.package;
-    var url = spanUrlFor(id, transform);
+    var url = spanUrlFor(id, transform, logger);
     return transform.readInputAsString(id).then((content) {
-      return _parseHtml(content, url, transform.logger,
+      return _parseHtml(content, url, logger,
         checkDocType: samePackage && options.isHtmlEntryPoint(id),
         showWarnings: showWarnings);
     });
   }
 
   Future<bool> assetExists(AssetId id, Transform transform) =>
       transform.getInput(id).then((_) => true).catchError((_) => false);
 
   String toString() => 'polymer ($runtimeType)';
 }
 
 /// Gets the appropriate URL to use in a span to produce messages (e.g.
 /// warnings) for users. This will attempt to format the URL in the most useful
 /// way:
 ///
 /// - If the asset is within the primary package, then use the [id.path],
 ///   the user will know it is a file from their own code.
 /// - If the asset is from another package, then use [assetUrlFor], this will
 ///   likely be a "package:" url to the file in the other package, which is
 ///   enough for users to identify where the error is.
-String spanUrlFor(AssetId id, Transform transform) {
+String spanUrlFor(AssetId id, Transform transform, logger) {
   var primaryId = transform.primaryInput.id;
   bool samePackage = id.package == primaryId.package;
   return samePackage ? id.path
-      : assetUrlFor(id, primaryId, transform.logger, allowAssetUrl: true);
+      : assetUrlFor(id, primaryId, logger, allowAssetUrl: true);
 }
 
 /// Transformer phases which should be applied to the Polymer package.
 List<List<Transformer>> get phasesForPolymer =>
     [[new ObservableTransformer(['lib/src/instance.dart'])]];
 
 /// Generate the import url for a file described by [id], referenced by a file
 /// with [sourceId].
 // TODO(sigmund): this should also be in barback (dartbug.com/12610)
-String assetUrlFor(AssetId id, AssetId sourceId, TransformLogger logger,
+String assetUrlFor(AssetId id, AssetId sourceId, BuildLogger logger,
     {bool allowAssetUrl: false}) {
   // use package: and asset: urls if possible
   if (id.path.startsWith('lib/')) {
     return 'package:${id.package}/${id.path.substring(4)}';
   }
 
   if (id.path.startsWith('asset/')) {
     if (!allowAssetUrl) {
-      logger.error("asset urls not allowed. "
-          "Don't know how to refer to $id from $sourceId");
+      logger.error(INTERNAL_ERROR_DONT_KNOW_HOW_TO_IMPORT.create({
+            'target': id,
+            'source': sourceId,
+            'extra': ' (asset urls not allowed.)'}));
       return null;
     }
     return 'asset:${id.package}/${id.path.substring(6)}';
   }
 
   // Use relative urls only if it's possible.
   if (id.package != sourceId.package) {
     logger.error("don't know how to refer to $id from $sourceId");
     return null;
   }
 
   var builder = path.url;
   return builder.relative(builder.join('/', id.path),
       from: builder.join('/', builder.dirname(sourceId.path)));
 }
 
 
 /// Convert system paths to asset paths (asset paths are posix style).
 String systemToAssetPath(String assetPath) {
   if (path.Style.platform != path.Style.windows) return assetPath;
   return path.posix.joinAll(path.split(assetPath));
 }
 
-/// These names have meaning in SVG or MathML, so they aren't allowed as custom
-/// tags. See [isCustomTagName].
-const invalidTagNames = const {
-  'annotation-xml': '',
-  'color-profile': '',
-  'font-face': '',
-  'font-face-src': '',
-  'font-face-uri': '',
-  'font-face-format': '',
-  'font-face-name': '',
-  'missing-glyph': '',
-};
-
 /// Returns true if this is a valid custom element name. See:
 /// <http://w3c.github.io/webcomponents/spec/custom/#dfn-custom-element-type>
 bool isCustomTagName(String name) {
   if (name == null || !name.contains('-')) return false;
   return !invalidTagNames.containsKey(name);
 }
 
 /// Regex to split names in the 'attributes' attribute, which supports 'a b c',
 /// 'a,b,c', or even 'a b,c'. This is the same as in `lib/src/declaration.dart`.
 final ATTRIBUTES_REGEX = new RegExp(r'\s|,');
-
-const POLYMER_EXPERIMENTAL_HTML = 'packages/polymer/polymer_experimental.html';
-
-const String LOG_EXTENSION = '._buildLogs';