@parcel/diagnostic 2.0.0-beta.3.1 → 2.0.0-nightly.1002

package/lib/diagnostic.d.ts

@@ -0,0 +1,131 @@
+import type { Mapping } from "json-source-map";
+/** These positions are 1-based (so <code>1</code> is the first line/column) */
+export declare type DiagnosticHighlightLocation = {
+    readonly line: number;
+    readonly column: number;
+};
+export declare type DiagnosticSeverity = "error" | "warn" | "info";
+/**
+ * Note: A tab character is always counted as a single character
+ * This is to prevent any mismatch of highlighting across machines
+ */
+export declare type DiagnosticCodeHighlight = {
+    /** Location of the first character that should get highlighted for this highlight. */
+    start: DiagnosticHighlightLocation;
+    /** Location of the last character that should get highlighted for this highlight. */
+    end: DiagnosticHighlightLocation;
+    /** A message that should be displayed at this location in the code (optional). */
+    message?: string;
+};
+/**
+ * Describes how to format a code frame.
+ * A code frame is a visualization of a piece of code with a certain amount of
+ * code highlights that point to certain chunk(s) inside the code.
+ */
+export declare type DiagnosticCodeFrame = {
+    /**
+     * The contents of the source file.
+     *
+     * If no code is passed, it will be read in from filePath, remember that
+     * the asset's current code could be different from the input contents.
+     *
+     */
+    code?: string;
+    /** Path to the file this code frame is about (optional, absolute or relative to the project root) */
+    filePath?: string;
+    /** Language of the file this code frame is about (optional) */
+    language?: string;
+    codeHighlights: Array<DiagnosticCodeHighlight>;
+};
+/**
+ * A style agnostic way of emitting errors, warnings and info.
+ * Reporters are responsible for rendering the message, codeframes, hints, ...
+ */
+export declare type Diagnostic = {
+    /** This is the message you want to log. */
+    message: string;
+    /** Name of plugin or file that threw this error */
+    origin?: string;
+    /** A stacktrace of the error (optional) */
+    stack?: string;
+    /** Name of the error (optional) */
+    name?: string;
+    /** A code frame points to a certain location(s) in the file this diagnostic is linked to (optional) */
+    codeFrames?: Array<DiagnosticCodeFrame> | null | undefined;
+    /** An optional list of strings that suggest ways to resolve this issue */
+    hints?: Array<string>;
+    /** @private */
+    skipFormatting?: boolean;
+    /** A URL to documentation to learn more about the diagnostic. */
+    documentationURL?: string;
+};
+export interface PrintableError extends Error {
+    fileName?: string;
+    filePath?: string;
+    codeFrame?: string;
+    highlightedCodeFrame?: string;
+    loc?: {
+        column: number;
+        line: number;
+    } | null | undefined;
+    source?: string;
+}
+export declare type DiagnosticWithoutOrigin = Diagnostic & {
+    origin?: string;
+};
+/** Something that can be turned into a diagnostic. */
+export declare type Diagnostifiable = Diagnostic | Array<Diagnostic> | ThrowableDiagnostic | PrintableError | Error | string;
+/** Normalize the given value into a diagnostic. */
+export declare function anyToDiagnostic(input: Diagnostifiable): Array<Diagnostic>;
+/** Normalize the given error into a diagnostic. */
+export declare function errorToDiagnostic(error: ThrowableDiagnostic | PrintableError | string, defaultValues?: {
+    origin?: string | null | undefined;
+    filePath?: string | null | undefined;
+}): Array<Diagnostic>;
+declare type ThrowableDiagnosticOpts = {
+    diagnostic: Diagnostic | Array<Diagnostic>;
+};
+/**
+ * An error wrapper around a diagnostic that can be <code>throw</code>n (e.g. to signal a
+ * build error).
+ */
+export default class ThrowableDiagnostic extends Error {
+    diagnostics: Array<Diagnostic>;
+    constructor(opts: ThrowableDiagnosticOpts);
+}
+/**
+ * Turns a list of positions in a JSON file with messages into a list of diagnostics.
+ * Uses <a href="https://github.com/epoberezkin/json-source-map">epoberezkin/json-source-map</a>.
+ *
+ * @param code the JSON code
+ * @param ids A list of JSON keypaths (<code>key: "/some/parent/child"</code>) with corresponding messages, \
+ * <code>type</code> signifies whether the key of the value in a JSON object should be highlighted.
+ */
+export declare function generateJSONCodeHighlights(data: string | {
+    data: unknown;
+    pointers: Record<string, Mapping>;
+}, ids: Array<{
+    key: string;
+    type?: ("key" | null | undefined) | "value";
+    message?: string;
+}>): Array<DiagnosticCodeHighlight>;
+/**
+ * Converts entries in <a href="https://github.com/epoberezkin/json-source-map">epoberezkin/json-source-map</a>'s
+ * <code>result.pointers</code> array.
+ */
+export declare function getJSONSourceLocation(pos: Mapping, type?: ("key" | null | undefined) | "value"): {
+    start: DiagnosticHighlightLocation;
+    end: DiagnosticHighlightLocation;
+};
+/** Sanitizes object keys before using them as <code>key</code> in generateJSONCodeHighlights */
+export declare function encodeJSONKeyComponent(component: string): string;
+export declare function escapeMarkdown(s: string): string;
+declare type TemplateInput = any;
+export declare function md(strings: Array<string>, ...params: Array<TemplateInput>): string;
+export declare namespace md {
+    var bold: (s: any) => any;
+    var italic: (s: any) => any;
+    var underline: (s: any) => any;
+    var strikethrough: (s: any) => any;
+}
+export {};

package/lib/diagnostic.js

@@ -4,13 +4,13 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.anyToDiagnostic = anyToDiagnostic;
+exports.default = void 0;
+exports.encodeJSONKeyComponent = encodeJSONKeyComponent;
 exports.errorToDiagnostic = errorToDiagnostic;
+exports.escapeMarkdown = escapeMarkdown;
 exports.generateJSONCodeHighlights = generateJSONCodeHighlights;
 exports.getJSONSourceLocation = getJSONSourceLocation;
-exports.encodeJSONKeyComponent = encodeJSONKeyComponent;
-exports.escapeMarkdown = escapeMarkdown;
 exports.md = md;
-exports.default = void 0;
 
 function _assert() {
   const data = _interopRequireDefault(require("assert"));
@@ -44,37 +44,38 @@ function _jsonSourceMap() {
 
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
-
 /** Normalize the given value into a diagnostic. */
 function anyToDiagnostic(input) {
-  // $FlowFixMe
-  let diagnostic = input;
-
-  if (input instanceof ThrowableDiagnostic) {
-    diagnostic = input.diagnostics;
+  if (Array.isArray(input)) {
+    return input;
+  } else if (input instanceof ThrowableDiagnostic) {
+    return input.diagnostics;
   } else if (input instanceof Error) {
-    diagnostic = errorToDiagnostic(input);
+    return errorToDiagnostic(input);
+  } else if (typeof input === 'string') {
+    return [{
+      message: input
+    }];
+  } else if (typeof input === 'object') {
+    return [input];
+  } else {
+    return errorToDiagnostic(input);
   }
-
-  return Array.isArray(diagnostic) ? diagnostic : [diagnostic];
 }
 /** Normalize the given error into a diagnostic. */
 
 
-function errorToDiagnostic(error, defaultValues = { ...null
-}) {
-  var _defaultValues$origin2, _ref2, _ref3, _error$filePath, _ref4, _error$highlightedCod;
+function errorToDiagnostic(error, defaultValues) {
+  var _defaultValues$origin2, _ref4, _error$highlightedCod;
 
-  let codeFrame = undefined;
+  let codeFrames = undefined;
 
   if (typeof error === 'string') {
     var _defaultValues$origin;
 
     return [{
       origin: (_defaultValues$origin = defaultValues === null || defaultValues === void 0 ? void 0 : defaultValues.origin) !== null && _defaultValues$origin !== void 0 ? _defaultValues$origin : 'Error',
-      message: escapeMarkdown(error),
-      codeFrame
+      message: escapeMarkdown(error)
     }];
   }
 
@@ -89,7 +90,10 @@ function errorToDiagnostic(error, defaultValues = { ...null
   }
 
   if (error.loc && error.source != null) {
-    codeFrame = {
+    var _ref2, _ref3, _error$filePath;
+
+    codeFrames = [{
+      filePath: (_ref2 = (_ref3 = (_error$filePath = error.filePath) !== null && _error$filePath !== void 0 ? _error$filePath : error.fileName) !== null && _ref3 !== void 0 ? _ref3 : defaultValues === null || defaultValues === void 0 ? void 0 : defaultValues.filePath) !== null && _ref2 !== void 0 ? _ref2 : undefined,
       code: error.source,
       codeHighlights: [{
         start: {
@@ -101,16 +105,15 @@ function errorToDiagnostic(error, defaultValues = { ...null
           column: error.loc.column
         }
       }]
-    };
+    }];
   }
 
   return [{
     origin: (_defaultValues$origin2 = defaultValues === null || defaultValues === void 0 ? void 0 : defaultValues.origin) !== null && _defaultValues$origin2 !== void 0 ? _defaultValues$origin2 : 'Error',
     message: escapeMarkdown(error.message),
     name: error.name,
-    filePath: (_ref2 = (_ref3 = (_error$filePath = error.filePath) !== null && _error$filePath !== void 0 ? _error$filePath : error.fileName) !== null && _ref3 !== void 0 ? _ref3 : defaultValues === null || defaultValues === void 0 ? void 0 : defaultValues.filePath) !== null && _ref2 !== void 0 ? _ref2 : undefined,
-    stack: (_ref4 = (_error$highlightedCod = error.highlightedCodeFrame) !== null && _error$highlightedCod !== void 0 ? _error$highlightedCod : error.codeFrame) !== null && _ref4 !== void 0 ? _ref4 : error.stack,
-    codeFrame
+    stack: codeFrames == null ? (_ref4 = (_error$highlightedCod = error.highlightedCodeFrame) !== null && _error$highlightedCod !== void 0 ? _error$highlightedCod : error.codeFrame) !== null && _ref4 !== void 0 ? _ref4 : error.stack : undefined,
+    codeFrames
   }];
 }
 
@@ -124,11 +127,10 @@ class ThrowableDiagnostic extends Error {
 
     let diagnostics = Array.isArray(opts.diagnostic) ? opts.diagnostic : [opts.diagnostic]; // Construct error from diagnostics
 
-    super(diagnostics[0].message);
+    super(diagnostics[0].message); // @ts-ignore
 
-    _defineProperty(this, "diagnostics", void 0);
+    this.stack = (_diagnostics$0$stack = diagnostics[0].stack) !== null && _diagnostics$0$stack !== void 0 ? _diagnostics$0$stack : super.stack; // @ts-ignore
 
-    this.stack = (_diagnostics$0$stack = diagnostics[0].stack) !== null && _diagnostics$0$stack !== void 0 ? _diagnostics$0$stack : super.stack;
     this.name = (_diagnostics$0$name = diagnostics[0].name) !== null && _diagnostics$0$name !== void 0 ? _diagnostics$0$name : super.name;
     this.diagnostics = diagnostics;
   }
@@ -221,8 +223,7 @@ function escapeMarkdown(s) {
   }
 
   return result;
-} // $FlowFixMe[unclear-type]
-
+}
 
 const mdVerbatim = Symbol();
 
@@ -230,8 +231,24 @@ function md(strings, ...params) {
   let result = [];
 
   for (let i = 0; i < params.length; i++) {
+    result.push(strings[i]);
     let param = params[i];
-    result.push(strings[i], param !== null && param !== void 0 && param[mdVerbatim] ? param.value : escapeMarkdown(`${param}`));
+
+    if (Array.isArray(param)) {
+      for (let j = 0; j < param.length; j++) {
+        var _param$j$mdVerbatim, _param$j;
+
+        result.push((_param$j$mdVerbatim = (_param$j = param[j]) === null || _param$j === void 0 ? void 0 : _param$j[mdVerbatim]) !== null && _param$j$mdVerbatim !== void 0 ? _param$j$mdVerbatim : escapeMarkdown(`${param[j]}`));
+
+        if (j < param.length - 1) {
+          result.push(', ');
+        }
+      }
+    } else {
+      var _param$mdVerbatim;
+
+      result.push((_param$mdVerbatim = param === null || param === void 0 ? void 0 : param[mdVerbatim]) !== null && _param$mdVerbatim !== void 0 ? _param$mdVerbatim : escapeMarkdown(`${param}`));
+    }
   }
 
   return result.join('') + strings[strings.length - 1];
@@ -240,31 +257,27 @@ function md(strings, ...params) {
 md.bold = function (s) {
   // $FlowFixMe[invalid-computed-prop]
   return {
-    [mdVerbatim]: true,
-    value: '**' + escapeMarkdown(`${s}`) + '**'
+    [mdVerbatim]: '**' + escapeMarkdown(`${s}`) + '**'
   };
 };
 
 md.italic = function (s) {
   // $FlowFixMe[invalid-computed-prop]
   return {
-    [mdVerbatim]: true,
-    value: '_' + escapeMarkdown(`${s}`) + '_'
+    [mdVerbatim]: '_' + escapeMarkdown(`${s}`) + '_'
   };
 };
 
 md.underline = function (s) {
   // $FlowFixMe[invalid-computed-prop]
   return {
-    [mdVerbatim]: true,
-    value: '__' + escapeMarkdown(`${s}`) + '__'
+    [mdVerbatim]: '__' + escapeMarkdown(`${s}`) + '__'
   };
 };
 
 md.strikethrough = function (s) {
   // $FlowFixMe[invalid-computed-prop]
   return {
-    [mdVerbatim]: true,
-    value: '~~' + escapeMarkdown(`${s}`) + '~~'
+    [mdVerbatim]: '~~' + escapeMarkdown(`${s}`) + '~~'
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcel/diagnostic",
-  "version": "2.0.0-beta.3.1",
+  "version": "2.0.0-nightly.1002+5530a6ef",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -15,12 +15,17 @@
   },
   "main": "lib/diagnostic.js",
   "source": "src/diagnostic.js",
+  "types": "lib/diagnostic.d.ts",
   "engines": {
     "node": ">= 12.0.0"
   },
+  "scripts": {
+    "build-ts": "flow-to-ts src/*.js --write && tsc --emitDeclarationOnly --declaration --esModuleInterop src/*.ts && mkdir -p lib && mv src/*.d.ts lib/. && rm src/*.ts",
+    "check-ts": "tsc --noEmit lib/diagnostic.d.ts"
+  },
   "dependencies": {
     "json-source-map": "^0.6.1",
     "nullthrows": "^1.1.1"
   },
-  "gitHead": "daece49d003ba804bbdaa3a7ed3d6aaf446f166d"
+  "gitHead": "5530a6eff8b619873353baeb0457ae4ec591e9fa"
 }

package/src/diagnostic.js

@@ -1,5 +1,4 @@
 // @flow strict-local
-import type {FilePath} from '@parcel/types';
 
 import invariant from 'assert';
 import nullthrows from 'nullthrows';
@@ -35,11 +34,15 @@ export type DiagnosticCodeFrame = {|
   /**
    * The contents of the source file.
    *
-   * If no code is passed, it will be read in from Diagnostic#filePath, remember that
+   * If no code is passed, it will be read in from filePath, remember that
    * the asset's current code could be different from the input contents.
    *
    */
   code?: string,
+  /** Path to the file this code frame is about (optional, absolute or relative to the project root) */
+  filePath?: string,
+  /** Language of the file this code frame is about (optional) */
+  language?: string,
   codeHighlights: Array<DiagnosticCodeHighlight>,
 |};
 
@@ -58,35 +61,32 @@ export type Diagnostic = {|
   /** Name of the error (optional) */
   name?: string,
 
-  /** Path to the file this diagnostic is about (optional, absolute or relative to the project root) */
-  filePath?: FilePath,
-  /** Language of the file this diagnostic is about (optional) */
-  language?: string,
-
   /** A code frame points to a certain location(s) in the file this diagnostic is linked to (optional) */
-  codeFrame?: DiagnosticCodeFrame,
+  codeFrames?: ?Array<DiagnosticCodeFrame>,
 
   /** An optional list of strings that suggest ways to resolve this issue */
   hints?: Array<string>,
 
   /** @private */
   skipFormatting?: boolean,
+
+  /** A URL to documentation to learn more about the diagnostic. */
+  documentationURL?: string,
 |};
 
 // This type should represent all error formats Parcel can encounter...
-export type PrintableError = Error & {
-  fileName?: string,
-  filePath?: string,
-  codeFrame?: string,
-  highlightedCodeFrame?: string,
+export interface PrintableError extends Error {
+  fileName?: string;
+  filePath?: string;
+  codeFrame?: string;
+  highlightedCodeFrame?: string;
   loc?: ?{
     column: number,
     line: number,
     ...
-  },
-  source?: string,
-  ...
-};
+  };
+  source?: string;
+}
 
 export type DiagnosticWithoutOrigin = {|
   ...Diagnostic,
@@ -99,38 +99,41 @@ export type Diagnostifiable =
   | Array<Diagnostic>
   | ThrowableDiagnostic
   | PrintableError
+  | Error
   | string;
 
 /** Normalize the given value into a diagnostic. */
 export function anyToDiagnostic(input: Diagnostifiable): Array<Diagnostic> {
-  // $FlowFixMe
-  let diagnostic: Array<Diagnostic> = input;
-
-  if (input instanceof ThrowableDiagnostic) {
-    diagnostic = input.diagnostics;
+  if (Array.isArray(input)) {
+    return input;
+  } else if (input instanceof ThrowableDiagnostic) {
+    return input.diagnostics;
   } else if (input instanceof Error) {
-    diagnostic = errorToDiagnostic(input);
+    return errorToDiagnostic(input);
+  } else if (typeof input === 'string') {
+    return [{message: input}];
+  } else if (typeof input === 'object') {
+    return [input];
+  } else {
+    return errorToDiagnostic(input);
   }
-
-  return Array.isArray(diagnostic) ? diagnostic : [diagnostic];
 }
 
 /** Normalize the given error into a diagnostic. */
 export function errorToDiagnostic(
   error: ThrowableDiagnostic | PrintableError | string,
-  defaultValues: {|
+  defaultValues?: {|
     origin?: ?string,
     filePath?: ?string,
-  |} = {...null},
+  |},
 ): Array<Diagnostic> {
-  let codeFrame: DiagnosticCodeFrame | void = undefined;
+  let codeFrames: ?Array<DiagnosticCodeFrame> = undefined;
 
   if (typeof error === 'string') {
     return [
       {
         origin: defaultValues?.origin ?? 'Error',
         message: escapeMarkdown(error),
-        codeFrame,
       },
     ];
   }
@@ -145,21 +148,28 @@ export function errorToDiagnostic(
   }
 
   if (error.loc && error.source != null) {
-    codeFrame = {
-      code: error.source,
-      codeHighlights: [
-        {
-          start: {
-            line: error.loc.line,
-            column: error.loc.column,
-          },
-          end: {
-            line: error.loc.line,
-            column: error.loc.column,
+    codeFrames = [
+      {
+        filePath:
+          error.filePath ??
+          error.fileName ??
+          defaultValues?.filePath ??
+          undefined,
+        code: error.source,
+        codeHighlights: [
+          {
+            start: {
+              line: error.loc.line,
+              column: error.loc.column,
+            },
+            end: {
+              line: error.loc.line,
+              column: error.loc.column,
+            },
           },
-        },
-      ],
-    };
+        ],
+      },
+    ];
   }
 
   return [
@@ -167,13 +177,11 @@ export function errorToDiagnostic(
       origin: defaultValues?.origin ?? 'Error',
       message: escapeMarkdown(error.message),
       name: error.name,
-      filePath:
-        error.filePath ??
-        error.fileName ??
-        defaultValues?.filePath ??
-        undefined,
-      stack: error.highlightedCodeFrame ?? error.codeFrame ?? error.stack,
-      codeFrame,
+      stack:
+        codeFrames == null
+          ? error.highlightedCodeFrame ?? error.codeFrame ?? error.stack
+          : undefined,
+      codeFrames,
     },
   ];
 }
@@ -197,7 +205,9 @@ export default class ThrowableDiagnostic extends Error {
 
     // Construct error from diagnostics
     super(diagnostics[0].message);
+    // @ts-ignore
     this.stack = diagnostics[0].stack ?? super.stack;
+    // @ts-ignore
     this.name = diagnostics[0].name ?? super.name;
 
     this.diagnostics = diagnostics;
@@ -280,8 +290,7 @@ export function escapeMarkdown(s: string): string {
   return result;
 }
 
-// $FlowFixMe[unclear-type]
-type TemplateInput = any;
+type TemplateInput = $FlowFixMe;
 
 const mdVerbatim = Symbol();
 export function md(
@@ -290,31 +299,39 @@ export function md(
 ): string {
   let result = [];
   for (let i = 0; i < params.length; i++) {
+    result.push(strings[i]);
+
     let param = params[i];
-    result.push(
-      strings[i],
-      param?.[mdVerbatim] ? param.value : escapeMarkdown(`${param}`),
-    );
+    if (Array.isArray(param)) {
+      for (let j = 0; j < param.length; j++) {
+        result.push(param[j]?.[mdVerbatim] ?? escapeMarkdown(`${param[j]}`));
+        if (j < param.length - 1) {
+          result.push(', ');
+        }
+      }
+    } else {
+      result.push(param?.[mdVerbatim] ?? escapeMarkdown(`${param}`));
+    }
   }
   return result.join('') + strings[strings.length - 1];
 }
 
-md.bold = function(s: TemplateInput): {|value: string|} {
+md.bold = function (s: TemplateInput): TemplateInput {
   // $FlowFixMe[invalid-computed-prop]
-  return {[mdVerbatim]: true, value: '**' + escapeMarkdown(`${s}`) + '**'};
+  return {[mdVerbatim]: '**' + escapeMarkdown(`${s}`) + '**'};
 };
 
-md.italic = function(s: TemplateInput): {|value: string|} {
+md.italic = function (s: TemplateInput): TemplateInput {
   // $FlowFixMe[invalid-computed-prop]
-  return {[mdVerbatim]: true, value: '_' + escapeMarkdown(`${s}`) + '_'};
+  return {[mdVerbatim]: '_' + escapeMarkdown(`${s}`) + '_'};
 };
 
-md.underline = function(s: TemplateInput): {|value: string|} {
+md.underline = function (s: TemplateInput): TemplateInput {
   // $FlowFixMe[invalid-computed-prop]
-  return {[mdVerbatim]: true, value: '__' + escapeMarkdown(`${s}`) + '__'};
+  return {[mdVerbatim]: '__' + escapeMarkdown(`${s}`) + '__'};
 };
 
-md.strikethrough = function(s: TemplateInput): {|value: string|} {
+md.strikethrough = function (s: TemplateInput): TemplateInput {
   // $FlowFixMe[invalid-computed-prop]
-  return {[mdVerbatim]: true, value: '~~' + escapeMarkdown(`${s}`) + '~~'};
+  return {[mdVerbatim]: '~~' + escapeMarkdown(`${s}`) + '~~'};
 };