This repository has been archived by the owner. It is now read-only.
Fetching contributors…
Cannot retrieve contributors at this time
236 lines (192 sloc) 7.76 KB
// 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.
/// Defines messages templates and an adapter for TransformLogger to be able
/// report error messages from transformers and refer to them in a consistent
/// manner long term.
library code_transformers.messages;
// Note: this library purposely doesn't depend on dart:io, dart:html, or barback
// so it can easily be used both in the transformers and in client-side apps
// (for example in the log_injector).
import 'dart:collection' show LinkedHashMap;
import 'package:source_span/source_span.dart';
/// A globally unique identifier for an error message. This identifier should be
/// stable, that is, it should never change after it is asigned to a particular
/// message. That allows us to document our error messages and make them
/// searchable for prosperity.
class MessageId implements Comparable<MessageId> {
/// Name of the package that declares this message.
final String package;
/// Message identifier number, unique within the package.
final int id;
const MessageId(this.package,;
static const MessageId NOT_SPECIFIED = const MessageId('unknown', 0);
/// Serialize this message. We use a string and not a map to encode ids so
/// they can be used as keys in JSON maps.
String toJson() => toString();
toString() => '${package}#$id';
int compareTo(MessageId other) {
var res = package.compareTo(other.package);
if (res != 0) return res;
return id.compareTo(;
/// Creates a new [MessageId] from an encoded value produced via [toJson].
factory MessageId.fromJson(data) {
var index = data.lastIndexOf('#');
if (index == -1) throw 'Invalid message id: $data';
return new MessageId(
data.substring(0, index), int.parse(data.substring(index + 1)));
operator ==(Object other) =>
other is MessageId && package == other.package && id ==;
int get hashCode => 31 * package.hashCode + id;
/// An instance of an error message. These are typically produced from a
/// [MessageTemplate].
class Message {
/// A globally unique identifier for this message.
final MessageId id;
/// A snippet message that is presented to the user.
final String snippet;
const Message(, this.snippet);
const Message.unknown(this.snippet) : id = MessageId.NOT_SPECIFIED;
/// Serializes this message to JSON.
Map toJson() => {'id': id.toJson(), 'snippet': snippet};
String toString() => 'id: $id, snippet: $snippet';
/// Creates a new [Message] from an encoded value produced via [toJson].
factory Message.fromJson(data) =>
new Message(new MessageId.fromJson(data['id']), data['snippet']);
/// Template for a message. Templates can include placeholders to indicate
/// values that are different for each instance of the error. Calling [create]
/// will generate the actual message, with the placeholders replaced with
/// values. If there are no placeholders, an instance of [MessageTemplate] is a
/// valid instance of [Message] as well.
class MessageTemplate implements Message {
/// Unique and stable id for the message.
final MessageId id;
/// Template message with placeholders of the form `%-name-%`.
final String snippetTemplate;
/// This returns the message snippet, only if it the template has no
/// placeholders, otherwise this throws an exception. Most messages have no
/// placeholder arguments, in those cases, the snippet can be computed
/// without specifying any arguments (exactly like calling `create()` with no
/// arguments).
String get snippet => _createSnippet();
/// Short description of the error message, typically used as a title of the
/// error message in autogenerated documentation. This should be a single
/// phrase, and cannot use placeholders.
final String description;
/// Additional details about this error message. These are used to
/// automatically generate documentation.
final String details;
const MessageTemplate(, this.snippetTemplate, this.description, this.details);
static final _placeholderPattern = new RegExp(r"%-(\w*)-%");
_createSnippet([Map args = const {}, bool fillUnknowns = false]) {
var snippet = snippetTemplate.replaceAllMapped(_placeholderPattern, (m) {
var arg =;
var value = args[arg];
if (value != null) return '$value';
if (fillUnknowns) return '';
throw "missing argument $arg, for error message: $snippetTemplate";
return snippet;
create([Map args = const {}, bool fillUnknowns = false]) =>
new Message(id, _createSnippet(args, fillUnknowns));
/// Serializes this message to JSON.
Map toJson() => create().toJson();
String toString() => '${toJson()}';
/// Represents an actual log entry for a build error message. Including the
/// actual message, its severity level (warning, error, etc), and a source span
/// for a code location that is revelant to the message.
class BuildLogEntry {
/// The actual message.
final Message message;
/// Severity level.
final String level;
/// Location associated with this message, if any.
final SourceSpan span;
BuildLogEntry(this.message, this.span, this.level);
/// Creates a new [BuildLogEntry] from an encoded value produced via [toJson].
factory BuildLogEntry.fromJson(Map data) {
var spanData = data['span'];
var span = null;
if (spanData != null) {
var locData = spanData['start'];
var start = new SourceLocation(locData['offset'],
sourceUrl: Uri.parse(locData['url']),
line: locData['line'],
column: locData['column']);
locData = spanData['end'];
var end = new SourceLocation(locData['offset'],
sourceUrl: Uri.parse(locData['url']),
line: locData['line'],
column: locData['column']);
span = new SourceSpan(start, end, spanData['text']);
return new BuildLogEntry(
new Message.fromJson(data['message']), span, data['level']);
/// Serializes this log entry to JSON.
Map toJson() {
var data = {
'level': level,
'message': message.toJson(),
if (span != null) {
data['span'] = {
'start': {
'url': span.start.sourceUrl.toString(),
'offset': span.start.offset,
'line': span.start.line,
'column': span.start.column,
'end': {
'url': span.end.sourceUrl.toString(),
'offset': span.end.offset,
'line': span.end.line,
'column': span.end.column,
'text': span.text,
return data;
String toString() => '${toJson()}';
/// A table of entries, that clusters error messages by id.
class LogEntryTable {
final Map<MessageId, List<BuildLogEntry>> entries;
LogEntryTable() : entries = new LinkedHashMap();
/// Creates a new [LogEntryTable] from an encoded value produced via [toJson].
factory LogEntryTable.fromJson(Map<String, Iterable> json) {
var res = new LogEntryTable();
for (String key in json.keys) {
var id = new MessageId.fromJson(key);
res.entries[id] =
json[key].map((v) => new BuildLogEntry.fromJson(v)).toList();
return res;
/// Serializes this entire table as JSON.
Map toJson() {
var res = {};
entries.forEach((key, value) {
res['$key'] = => e.toJson()).toList();
return res;
String toString() => '${toJson()}';
void add(BuildLogEntry entry) {
entries.putIfAbsent(, () => []).add(entry);
void addAll(LogEntryTable other) {
for (var key in other.entries.keys) {
var values = entries.putIfAbsent(key, () => []);