診断とログ

Parcelは、フォーマットに依存しない方法でエラーと警告を記述するために使用される豊富な診断情報をサポートしています。また、Reporterプラグインがすべてのログとエラーを処理し、ユーザーに提示できるようにする組み込みのログシステムも含まれています。

診断情報

Diagnosticは、役に立つログメッセージを作成するために必要なプロパティのセットを持つJavaScriptオブジェクトです。これは、詳細なメッセージから警告やエラーまで何でもかまいません。診断情報には、メッセージ、処理中のファイルに関する情報、コードフレーム、エラー情報、問題を解決するためのヒント、および詳細を学ぶためのドキュメントへのリンクを含めることができます。

@parcel/diagnosticパッケージのThrowableDiagnosticクラスは、診断情報をサポートするJavaScriptのErrorオブジェクトを拡張します。プラグイン内でエラーをスローする場合は、ThrowableDiagnosticオブジェクトを使用して、エラーに関するコンテキストを含む診断情報を添付します。Parcelは、診断情報の起源としてプラグイン名を自動的に添付します。

import ThrowableDiagnostic from '@parcel/diagnostic';

throw new ThrowableDiagnostic({
  diagnostic: {
    message: 'An error occurred'
  }
});

ThrowableDiagnosticのdiagnosticオプションに配列を渡すことで、一度に複数の診断情報をスローすることもできます。

メッセージのフォーマット

診断情報内のメッセージをフォーマットするために、非常に最小限のMarkdownがサポートされています。このフォーマットは、特にターミナルやブラウザ、エディターなどの他のレンダリングターゲットと互換性があるように設計されており、フォーマットなしで表示された場合でも分かりにくすぎないように工夫されています。@parcel/reporter-cliは、@parcel/markdown-ansiライブラリを使用して、これらのMarkdown文字列をANSIエスケープシーケンスに変換し、ターミナルでレンダリングします。

サポートされているMarkdown機能は、**太字**、*斜体*/_斜体_、__下線__、~~取り消し線~~です。

@parcel/diagnosticパッケージには、Markdownメッセージを操作するためのいくつかのユーティリティが含まれています。mdタグ付きテンプレートリテラルは、Markdown文字列内の補間された式をエスケープします。これにより、式内の特別なMarkdown文字がフォーマットに影響を与えることがなくなります。

import {md} from '@parcel/diagnostic';

throw new ThrowableDiagnostic({
  diagnostic: {
    message: md`**Error**: Could not parse ${filePath}`
  }
});

md.bold、md.italic、md.underline、md.strikethroughなど、補間された式をフォーマットするためのユーティリティもあります。

import {md} from '@parcel/diagnostic';

throw new ThrowableDiagnostic({
  diagnostic: {
    message: md`**Error**: Could not parse ${md.underline(filePath)}`
  }
});

コードフレーム

Diagnosticには、1つ以上のコードフレームを添付できます。コードフレームには、ファイルパスと1つ以上のコードハイライトが含まれており、ファイル内のエラーが発生した場所に関するコンテキストを示します。コードハイライトは、ファイル内の行と列の位置で定義され、その位置に表示されるメッセージが含まれている場合もあります。

コードフレームには、エラーが発生したファイルのソースコードも含まれている必要があります。省略した場合、Parcelはファイルシステムからファイルを読み取ります。しかし、多くの場合、入力ソースコードはそれ以前に実行された別のプラグインから取得された可能性があり、そのためコードはなんらかの方法で変更されている可能性があります。コードフレームにコードを含めることで、この問題を回避できます。

throw new ThrowableDiagnostic({
  diagnostic: {
    message: md`Could not parse ${asset.filePath}`,
    codeFrames: [{
      filePath: asset.filePath,
      code: await asset.getCode(),
      codeHighlights: [
        {
          start: {
            line: 1,
            column: 5,
          },
          end: {
            line: 2,
            column: 3,
          },
          message: 'Expected a string but got a number'
        }
      ]
    }]
  }
});

ヒント

診断情報には、問題の解決方法に関するヒントと、ユーザーが詳細を学ぶためのドキュメントへのリンクを含めることもできます。これらは、hintsプロパティとdocumentationURLプロパティを介して提供されます。

throw new ThrowableDiagnostic({
  diagnostic: {
    message: 'Could not find a config file',
    hints: ['Create a tool.config.json file in the project root.'],
    documentationURL: 'http://example.com/'
  }
});

ロガー

Parcelのロガーは、プラグインでメッセージをログ出力するために使用できます。プラグインのすべての関数は、パラメーターとしてLoggerインスタンスを渡されます。このインスタンスには、Parcelがメッセージの起源としてプラグインを識別するために必要なすべての情報が含まれています。

ロガーはDiagnosticを受け入れます。これは、ログメッセージ、その起源、コードフレームなどのコンテキストを記述する標準化されたプロパティのセットを持つJavaScriptオブジェクトです。Reporterプラグインはこの情報を使用してメッセージをログ出力しますが、このデータのフォーマットと表示方法を完全に自由に制御できます。

Loggerには、verbose、info、log、warn、errorなど、各ログレベルの関数があります。これらのログレベルはログメッセージの重大度を指定し、フォーマットとフィルタリングに役立ちます。たとえば、--log-level CLIオプションを使用して、表示するメッセージを選択できます。各ログ出力関数には、1つのパラメーターがあり、ログ出力するメッセージの数に応じて、単一のDiagnosticオブジェクトまたは診断情報の配列のいずれかになります。

ログレベル

メッセージのログ出力方法

Diagnosticのフォーマットに慣れたら、詳細なメッセージからコードフレームとヒントを含むエラーまで、何でもログ出力できます。この例では、コードフレーム、ヒント、ドキュメントURLを含む警告をログ出力する方法を示しています。

import {Transformer} from '@parcel/plugin';

export default new Transformer({
  async transform({asset, logger}) {
    // ...

    logger.warn({
      message: 'This feature is deprecated.',
      codeFrames: [{
        filePath: asset.filePath,
        code: await asset.getCode(),
        codeHighlights: [{
          start: {
            line: 1,
            column: 5
          },
          end: {
            line: 1,
            column: 10
          }
        }]
      }],
      hints: ['Please use this other feature instead.'],
      documentationURL: 'http://example.com/'
    });
  },
});

自動的に収集されたログとエラー

Parcelは、console.logおよびその他のconsoleメソッドで作成されたログを自動的に収集します。console.logが呼び出されると、Parcelはこれをキャッチし、Diagnosticオブジェクトに変換して、loggerに送信されたメッセージと同様にReporterプラグインに送信します。ただし、Parcelはloggerを直接呼び出す場合ほど多くの情報を持っていないため、これは推奨されません。

Parcelは、プラグイン内でスローされたエラーも処理します。これらはDiagnosticに変換され、プラグインに関する情報が追加されます。スローされたエラーはReporterプラグインに送信され、ビルドは停止されます。

API

interface PluginLogger {

  verbose(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void,

  info(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void,

  log(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void,

  warn(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void,

  error(input: Diagnostifiable | DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void,

}

type DiagnosticHighlightLocation = {|

  +line: number,

  +column: number,

|}

type DiagnosticSeverity = 'error' | 'warn' | 'info';

type DiagnosticCodeHighlight = {|

  start: DiagnosticHighlightLocation,

  end: DiagnosticHighlightLocation,

  message?: string,

|}

type DiagnosticCodeFrame = {|

  code?: string,

  filePath?: string,

  language?: string,

  codeHighlights: Array<DiagnosticCodeHighlight>,

|}

type Diagnostic = {|

  message: string,

  origin?: string,

  stack?: string,

  name?: string,

  codeFrames?: ?Array<DiagnosticCodeFrame>,

  hints?: Array<string>,

  documentationURL?: string,

|}

interface PrintableError extends Error {

  fileName?: string,

  filePath?: string,

  codeFrame?: string,

  highlightedCodeFrame?: string,

  loc?: ?{
    column: number,
    line: number,
    ...
  },

  source?: string,

}

type DiagnosticWithoutOrigin = {|

  ...Diagnostic,

  origin?: string,

|}

type Diagnostifiable = Diagnostic | Array<Diagnostic> | ThrowableDiagnostic | PrintableError | Error | string;

function anyToDiagnostic(input: Diagnostifiable): Array<Diagnostic> {}

function errorToDiagnostic(error: ThrowableDiagnostic | PrintableError | string, defaultValues?: {|
  origin?: ?string,
  filePath?: ?string,
|}): Array<Diagnostic> {}

type ThrowableDiagnosticOpts = {

  diagnostic: Diagnostic | Array<Diagnostic>,

}

interface ThrowableDiagnostic extends Error {

  diagnostics: Array<Diagnostic>,

  constructor(opts: ThrowableDiagnosticOpts): void,

}

function generateJSONCodeHighlights(data: string | {|
  data: mixed,
  pointers: {|
    [key: string]: Mapping
  |},
|}, ids: Array<{|
  key: string,
  type?: ?'key' | 'value',
  message?: string,
|}>): Array<DiagnosticCodeHighlight> {}

function getJSONSourceLocation(pos: Mapping, type?: ?'key' | 'value'): {|
  start: DiagnosticHighlightLocation,
  end: DiagnosticHighlightLocation,
|} {}

function encodeJSONKeyComponent(component: string): string {}

function escapeMarkdown(s: string): string {}

type TemplateInput = $FlowFixMe;

function md(strings: Array<string>, ...params: Array<TemplateInput>): string {}