code_transformers/lib/messages/build_logger.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 code_transformers.messages.messages_logger;

import 'dart:async';
import 'dart:convert' show JSON;

import 'package:barback/barback.dart';
import 'package:source_span/source_span.dart';

import 'messages.dart' show Message, MessageId, BuildLogEntry, LogEntryTable;

/// A [TransformLogger] used to track error and warning messages produced during
/// a build.
///
/// This logger records all messages that were logged and then forwards
/// the calls to an underlying [TransformLogger]. The internal records support
/// serializing the errors and emiting them to an asset (so they can be
/// presented to the user in a web-based client), clustering similar messages
/// together, sorting messages in order of importance, etc.
///
/// The logger also supports reporting error messages as warnings. Barback makes
/// error messages stop the transformation process, which sometimes can surprise
/// users. Turning errors into warnings is especially useful when used within
/// `pub serve`, where we would like the transformation to continue as far as it
/// can. When this flag is turned on, the level is still recorded as an error,
/// so a web client UI can still highlight their importance.
// TODO(sigmund): also cluster messages when they are reported on the
// command-line.
class BuildLogger implements TransformLogger {
  /// Underling transform that is currently active. This can be either an
  /// [AggregateTransform] or [Transform].
  final _transform;

  /// The primary input id.
  final AssetId _primaryId;

  /// Logs created during the current transform.
  final LogEntryTable _logs = new LogEntryTable();

  /// Whether to use `warning` or `error` when forwarding error messages to the
  /// underlying logger in `_transform.logger`.
  final bool convertErrorsToWarnings;

  /// Uri prefix to link for additional details. If set, messages logged through
  /// this logger will contain an additional sentence, telling users to find
  /// more details at `$detailsUri#packagename_id`.
  final String detailsUri;

  /// If transform is a [Transform] then [primaryId] will default to the
  /// primaryInput.id, if it is an [AggregateTransform] then you must pass in
  /// a [primaryId] to be used, otherwise you will get a runtime error.
  BuildLogger(transform,
      {this.convertErrorsToWarnings: false, AssetId primaryId, this.detailsUri})
      : _transform = transform,
        _primaryId = primaryId != null ? primaryId : transform.primaryInput.id;

  /// Records a message at the fine level. If [msg] is a [Message] it is
  /// recorded directly, otherwise it is first converted to a [String].
  void fine(msg, {AssetId asset, SourceSpan span}) {
    msg = msg is Message ? msg : new Message.unknown('$msg');
    _transform.logger.fine(_snippet(msg), asset: asset, span: span);
    _logs.add(new BuildLogEntry(msg, span, LogLevel.FINE.name));
  }

  /// Records a message at the info level. If [msg] is a [Message] it is
  /// recorded directly, otherwise it is first converted to a [String].
  void info(msg, {AssetId asset, SourceSpan span}) {
    msg = msg is Message ? msg : new Message.unknown('$msg');
    _transform.logger.info(_snippet(msg), asset: asset, span: span);
    _logs.add(new BuildLogEntry(msg, span, LogLevel.INFO.name));
  }

  /// Records a warning message. If [msg] is a [Message] it is recorded
  /// directly, otherwise it is first converted to a [String].
  void warning(msg, {AssetId asset, SourceSpan span}) {
    msg = msg is Message ? msg : new Message.unknown('$msg');
    _transform.logger.warning(_snippet(msg), asset: asset, span: span);
    _logs.add(new BuildLogEntry(msg, span, LogLevel.WARNING.name));
  }

  /// Records an error message. If [msg] is a [Message] it is recorded
  /// directly, otherwise it is first converted to a [String].
  void error(msg, {AssetId asset, SourceSpan span}) {
    msg = msg is Message ? msg : new Message.unknown('$msg');
    if (convertErrorsToWarnings) {
      _transform.logger.warning(_snippet(msg), asset: asset, span: span);
    } else {
      _transform.logger.error(_snippet(msg), asset: asset, span: span);
    }
    _logs.add(new BuildLogEntry(msg, span, LogLevel.ERROR.name));
  }

  String _snippet(Message msg) {
    var s = msg.snippet;
    if (detailsUri == null) return s;
    var dot = s.endsWith('.') || s.endsWith('!') || s.endsWith('?') ? '' : '.';
    var hashTag = '${msg.id.package}_${msg.id.id}';
    return '$s$dot See $detailsUri#$hashTag for details.';
  }

  /// Outputs the log data to a JSON serialized file.
  Future writeOutput() {
    return _getNextLogAssetId().then((id) {
      _transform.addOutput(new Asset.fromString(id, JSON.encode(_logs)));
    });
  }

  // Each phase outputs a new log file with an incrementing # appended, this
  // figures out the next # to use.
  Future<AssetId> _getNextLogAssetId([int nextNumber = 1]) {
    var nextAssetPath = _primaryId.addExtension('${LOG_EXTENSION}.$nextNumber');
    return _transform.hasInput(nextAssetPath).then((exists) {
      if (!exists) return nextAssetPath;
      return _getNextLogAssetId(++nextNumber);
    });
  }

  // Reads all log files for an Asset into [logs].
  static Future _readLogFilesForAsset(
      AssetId id, Transform transform, LogEntryTable entries,
      [nextNumber = 1]) {
    var nextAssetPath = id.addExtension('${LOG_EXTENSION}.$nextNumber');
    return transform.hasInput(nextAssetPath).then((exists) {
      if (!exists) return null;
      return transform.readInputAsString(nextAssetPath).then((data) {
        entries.addAll(new LogEntryTable.fromJson(JSON.decode(data)));
        return _readLogFilesForAsset(id, transform, entries, ++nextNumber);
      });
    });
  }

  /// Combines all existing ._buildLogs.* files into a single ._buildLogs file.
  /// [transform] may be a [Transform] or [AggregateTransform]. If an
  /// [AggregateTransform] is passed then [primaryId] must also be passed.
  static Future combineLogFiles(transform, [AssetId primaryId]) {
    if (primaryId == null) primaryId = transform.primaryInput.id;
    var entries = new LogEntryTable();
    return _readLogFilesForAsset(primaryId, transform, entries).then((_) {
      return transform.addOutput(new Asset.fromString(
          primaryId.addExtension(LOG_EXTENSION),
          JSON.encode(entries.toJson())));
    });
  }

  // Reads all logs for an asset and adds them to this loggers log output.
  Future addLogFilesFromAsset(AssetId id, [int nextNumber = 1]) {
    return _readLogFilesForAsset(id, _transform, _logs);
  }
}

/// Extension used for assets that contained serialized logs.
const String LOG_EXTENSION = '._buildLogs';