@descent-vtt/spec-brief 0.1.0

package/dist/markdown.js

@@ -0,0 +1,274 @@
+/**
+ * A structural Markdown scanner: code, comments, headings, task items and link
+ * destinations, each with its line.
+ *
+ * Not a CommonMark parser, and it does not need to be. Nothing here renders.
+ * What must be exactly right is knowing what is code or a comment, because a
+ * heading inside a fenced block is not a section and a template hint inside
+ * `<!-- -->` is not content. Everything else is deliberately simple: ATX
+ * headings only (a setext underline and a front-matter delimiter are the same
+ * three characters), fences at any indentation, and no indented code blocks,
+ * because inside a list four spaces of indentation is a continuation far more
+ * often than code.
+ */
+// Any indentation: a fence inside a nested list item is indented with the item.
+const FENCE = /^[ \t]*(`{3,}|~{3,})(.*)$/;
+const HEADING = /^ {0,3}(#{1,6})(?:[ \t]+|$)/;
+const TASK = /^([ \t]*)(?:[-*+]|\d{1,9}[.)])[ \t]+\[([ xX])\](?:[ \t]+(.*))?$/;
+const LIST_ITEM = /^[ \t]*(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)/;
+function blank(length) {
+    return ' '.repeat(length);
+}
+/**
+ * Scans `lines` from line `from`; earlier lines (front matter) are blanked in
+ * both masks and contribute nothing.
+ */
+export function scan(lines, from = 0) {
+    const prose = [];
+    const masked = [];
+    let fence = null;
+    let inComment = false;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (i < from) {
+            prose.push(blank(line.length));
+            masked.push(blank(line.length));
+            continue;
+        }
+        if (fence !== null) {
+            prose.push(line);
+            masked.push(blank(line.length));
+            const close = FENCE.exec(line);
+            if (close !== null) {
+                const [, run = '', rest = ''] = close;
+                if (run.charAt(0) === fence.char && run.length >= fence.length && rest.trim() === '')
+                    fence = null;
+            }
+            continue;
+        }
+        if (!inComment) {
+            const open = FENCE.exec(line);
+            const [, run = '', info = ''] = open ?? [];
+            if (open !== null && !(run.charAt(0) === '`' && info.includes('`'))) {
+                fence = { char: run.charAt(0), length: run.length };
+                prose.push(line);
+                masked.push(blank(line.length));
+                continue;
+            }
+        }
+        let proseLine = '';
+        let maskedLine = '';
+        let j = 0;
+        while (j < line.length) {
+            if (inComment) {
+                const close = line.indexOf('-->', j);
+                const stop = close < 0 ? line.length : close + 3;
+                proseLine += blank(stop - j);
+                maskedLine += blank(stop - j);
+                inComment = close < 0;
+                j = stop;
+                continue;
+            }
+            if (line.startsWith('<!--', j)) {
+                inComment = true;
+                proseLine += blank(4);
+                maskedLine += blank(4);
+                j += 4;
+                continue;
+            }
+            if (line.charAt(j) === '`') {
+                const run = backtickRun(line, j);
+                const close = closingRun(line, j + run, run);
+                if (close >= 0) {
+                    const span = line.slice(j, close + run);
+                    proseLine += span;
+                    maskedLine += blank(span.length);
+                    j = close + run;
+                    continue;
+                }
+                proseLine += line.slice(j, j + run);
+                maskedLine += line.slice(j, j + run);
+                j += run;
+                continue;
+            }
+            proseLine += line.charAt(j);
+            maskedLine += line.charAt(j);
+            j += 1;
+        }
+        prose.push(proseLine);
+        masked.push(maskedLine);
+    }
+    const headings = findHeadings(lines, masked);
+    return { lines, prose, masked, headings, tasks: findTasks(lines, masked, headings) };
+}
+function backtickRun(line, at) {
+    let end = at;
+    while (line.charAt(end) === '`')
+        end += 1;
+    return end - at;
+}
+/** The index of a run of exactly `length` backticks at or after `from`, or -1. */
+function closingRun(line, from, length) {
+    let i = from;
+    while (i < line.length) {
+        if (line.charAt(i) !== '`') {
+            i += 1;
+            continue;
+        }
+        const run = backtickRun(line, i);
+        if (run === length)
+            return i;
+        i += run;
+    }
+    return -1;
+}
+function findHeadings(lines, masked) {
+    const headings = [];
+    for (let i = 0; i < masked.length; i += 1) {
+        const match = HEADING.exec(masked[i]);
+        if (!match)
+            continue;
+        const level = match[1].length;
+        const original = lines[i];
+        const text = original
+            .replace(/^ {0,3}#{1,6}/, '')
+            .replace(/[ \t]+#+[ \t]*$/, '')
+            .trim();
+        headings.push({ line: i, level, text });
+    }
+    return headings;
+}
+function indentOf(line) {
+    return line.length - line.trimStart().length;
+}
+function findTasks(lines, masked, headings) {
+    const headingLines = new Set(headings.map((h) => h.line));
+    const tasks = [];
+    for (let i = 0; i < masked.length; i += 1) {
+        const match = TASK.exec(masked[i]);
+        if (!match)
+            continue;
+        const indent = match[1].length;
+        const original = TASK.exec(lines[i]);
+        const text = (original?.[3] ?? '').trim();
+        tasks.push({ line: i, end: itemEnd(lines, masked, headingLines, i, indent), checked: match[2] !== ' ', text });
+    }
+    return tasks;
+}
+/**
+ * Where the list item starting at `start` ends: after its last line indented
+ * past the marker, or its last lazy continuation line - text directly under
+ * the item with no blank line between, which CommonMark folds into the item's
+ * paragraph.
+ */
+function itemEnd(lines, masked, headingLines, start, indent) {
+    let last = start;
+    let previousBlank = false;
+    for (let k = start + 1; k < lines.length; k += 1) {
+        const line = lines[k];
+        if (headingLines.has(k))
+            break;
+        if (line.trim() === '') {
+            previousBlank = true;
+            continue;
+        }
+        const nested = indentOf(line) > indent;
+        const lazy = !previousBlank && !LIST_ITEM.test(masked[k]) && !FENCE.test(line) && !/^\s*>/.test(line);
+        if (!nested && !lazy)
+            break;
+        last = k;
+        previousBlank = false;
+    }
+    return last + 1;
+}
+/** Sections: every heading below the title, running to the next heading at its level or above. */
+export function sectionsOf(result) {
+    const sections = [];
+    const { headings } = result;
+    for (let h = 0; h < headings.length; h += 1) {
+        const heading = headings[h];
+        if (heading.level < 2)
+            continue;
+        let end = result.lines.length;
+        for (let k = h + 1; k < headings.length; k += 1) {
+            const next = headings[k];
+            if (next.level <= heading.level) {
+                end = next.line;
+                break;
+            }
+        }
+        sections.push({ heading, end });
+    }
+    return sections;
+}
+/** The first level-one heading, which is what a reader takes as the title. */
+export function titleOf(result) {
+    return result.headings.find((h) => h.level === 1);
+}
+const DEFINITION = /^ {0,3}\[(?!\^)[^\]]+\]:[ \t]*/;
+/** What may follow a definition's destination: nothing, or a title. */
+const TITLE = /^(?:"[^"]*"|'[^']*'|\([^)]*\))?$/;
+/**
+ * Link and image destinations outside code and comments: `[text](dest)`,
+ * `![alt](dest)`, and reference definitions `[label]: dest`.
+ */
+export function linksOf(result) {
+    const links = [];
+    result.masked.forEach((masked, line) => {
+        const original = result.lines[line];
+        const definition = DEFINITION.exec(masked);
+        if (definition) {
+            // `[Note]: this matters` is prose that looks like a definition; a real one
+            // has nothing after its destination but an optional title.
+            const found = readDestination(masked, original, definition[0].length);
+            if (found && TITLE.test(masked.slice(found.end + (masked.charAt(found.end) === '>' ? 1 : 0)).trim())) {
+                links.push({ line, ...found });
+            }
+        }
+        let from = 0;
+        for (;;) {
+            const at = masked.indexOf('](', from);
+            if (at < 0)
+                break;
+            let start = at + 2;
+            while (masked.charAt(start) === ' ' || masked.charAt(start) === '\t')
+                start += 1;
+            const found = readDestination(masked, original, start);
+            if (found)
+                links.push({ line, ...found });
+            from = at + 2;
+        }
+    });
+    return links;
+}
+function readDestination(masked, original, start) {
+    if (masked.charAt(start) === '<') {
+        const close = masked.indexOf('>', start + 1);
+        if (close < 0)
+            return undefined;
+        return { start: start + 1, end: close, target: original.slice(start + 1, close) };
+    }
+    let depth = 0;
+    let end = start;
+    while (end < masked.length) {
+        const ch = masked.charAt(end);
+        if (ch === ' ' || ch === '\t')
+            break;
+        if (ch === '(')
+            depth += 1;
+        if (ch === ')') {
+            if (depth === 0)
+                break;
+            depth -= 1;
+        }
+        end += 1;
+    }
+    if (end === start)
+        return undefined;
+    return { start, end, target: original.slice(start, end) };
+}
+/** Whether a line carries anything once comments are removed. */
+export function hasContent(proseLine) {
+    return proseLine.trim().length > 0;
+}
+//# sourceMappingURL=markdown.js.map

package/dist/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A structural Markdown scanner: code, comments, headings, task items and link\n * destinations, each with its line.\n *\n * Not a CommonMark parser, and it does not need to be. Nothing here renders.\n * What must be exactly right is knowing what is code or a comment, because a\n * heading inside a fenced block is not a section and a template hint inside\n * `<!-- -->` is not content. Everything else is deliberately simple: ATX\n * headings only (a setext underline and a front-matter delimiter are the same\n * three characters), fences at any indentation, and no indented code blocks,\n * because inside a list four spaces of indentation is a continuation far more\n * often than code.\n */\n\nexport interface Heading {\n  /** 0-based line. */\n  readonly line: number;\n  readonly level: number;\n  readonly text: string;\n}\n\nexport interface Section {\n  readonly heading: Heading;\n  /** 0-based line after the section's last line. The body starts on the line after the heading. */\n  readonly end: number;\n}\n\nexport interface TaskItem {\n  /** 0-based line of the box. */\n  readonly line: number;\n  /** 0-based line after the item's last continuation line. */\n  readonly end: number;\n  readonly checked: boolean;\n  readonly text: string;\n}\n\nexport interface LinkDestination {\n  /** 0-based line. */\n  readonly line: number;\n  /** Columns of the destination within the line, end exclusive. */\n  readonly start: number;\n  readonly end: number;\n  readonly target: string;\n}\n\nexport interface Scan {\n  readonly lines: readonly string[];\n  /** Lines with comments blanked and code kept: what counts as content. */\n  readonly prose: readonly string[];\n  /** Lines with comments, code spans and fenced blocks blanked: what counts as structure. */\n  readonly masked: readonly string[];\n  readonly headings: readonly Heading[];\n  readonly tasks: readonly TaskItem[];\n}\n\n// Any indentation: a fence inside a nested list item is indented with the item.\nconst FENCE = /^[ \\t]*(`{3,}|~{3,})(.*)$/;\nconst HEADING = /^ {0,3}(#{1,6})(?:[ \\t]+|$)/;\nconst TASK = /^([ \\t]*)(?:[-*+]|\\d{1,9}[.)])[ \\t]+\\[([ xX])\\](?:[ \\t]+(.*))?$/;\nconst LIST_ITEM = /^[ \\t]*(?:[-*+]|\\d{1,9}[.)])(?:[ \\t]|$)/;\n\nfunction blank(length: number): string {\n  return ' '.repeat(length);\n}\n\n/**\n * Scans `lines` from line `from`; earlier lines (front matter) are blanked in\n * both masks and contribute nothing.\n */\nexport function scan(lines: readonly string[], from = 0): Scan {\n  const prose: string[] = [];\n  const masked: string[] = [];\n  let fence: { readonly char: string; readonly length: number } | null = null;\n  let inComment = false;\n\n  for (let i = 0; i < lines.length; i += 1) {\n    const line = lines[i] as string;\n    if (i < from) {\n      prose.push(blank(line.length));\n      masked.push(blank(line.length));\n      continue;\n    }\n    if (fence !== null) {\n      prose.push(line);\n      masked.push(blank(line.length));\n      const close = FENCE.exec(line);\n      if (close !== null) {\n        const [, run = '', rest = ''] = close;\n        if (run.charAt(0) === fence.char && run.length >= fence.length && rest.trim() === '') fence = null;\n      }\n      continue;\n    }\n    if (!inComment) {\n      const open = FENCE.exec(line);\n      const [, run = '', info = ''] = open ?? [];\n      if (open !== null && !(run.charAt(0) === '`' && info.includes('`'))) {\n        fence = { char: run.charAt(0), length: run.length };\n        prose.push(line);\n        masked.push(blank(line.length));\n        continue;\n      }\n    }\n\n    let proseLine = '';\n    let maskedLine = '';\n    let j = 0;\n    while (j < line.length) {\n      if (inComment) {\n        const close = line.indexOf('-->', j);\n        const stop = close < 0 ? line.length : close + 3;\n        proseLine += blank(stop - j);\n        maskedLine += blank(stop - j);\n        inComment = close < 0;\n        j = stop;\n        continue;\n      }\n      if (line.startsWith('<!--', j)) {\n        inComment = true;\n        proseLine += blank(4);\n        maskedLine += blank(4);\n        j += 4;\n        continue;\n      }\n      if (line.charAt(j) === '`') {\n        const run = backtickRun(line, j);\n        const close = closingRun(line, j + run, run);\n        if (close >= 0) {\n          const span = line.slice(j, close + run);\n          proseLine += span;\n          maskedLine += blank(span.length);\n          j = close + run;\n          continue;\n        }\n        proseLine += line.slice(j, j + run);\n        maskedLine += line.slice(j, j + run);\n        j += run;\n        continue;\n      }\n      proseLine += line.charAt(j);\n      maskedLine += line.charAt(j);\n      j += 1;\n    }\n    prose.push(proseLine);\n    masked.push(maskedLine);\n  }\n\n  const headings = findHeadings(lines, masked);\n  return { lines, prose, masked, headings, tasks: findTasks(lines, masked, headings) };\n}\n\nfunction backtickRun(line: string, at: number): number {\n  let end = at;\n  while (line.charAt(end) === '`') end += 1;\n  return end - at;\n}\n\n/** The index of a run of exactly `length` backticks at or after `from`, or -1. */\nfunction closingRun(line: string, from: number, length: number): number {\n  let i = from;\n  while (i < line.length) {\n    if (line.charAt(i) !== '`') {\n      i += 1;\n      continue;\n    }\n    const run = backtickRun(line, i);\n    if (run === length) return i;\n    i += run;\n  }\n  return -1;\n}\n\nfunction findHeadings(lines: readonly string[], masked: readonly string[]): Heading[] {\n  const headings: Heading[] = [];\n  for (let i = 0; i < masked.length; i += 1) {\n    const match = HEADING.exec(masked[i] as string);\n    if (!match) continue;\n    const level = (match[1] as string).length;\n    const original = lines[i] as string;\n    const text = original\n      .replace(/^ {0,3}#{1,6}/, '')\n      .replace(/[ \\t]+#+[ \\t]*$/, '')\n      .trim();\n    headings.push({ line: i, level, text });\n  }\n  return headings;\n}\n\nfunction indentOf(line: string): number {\n  return line.length - line.trimStart().length;\n}\n\nfunction findTasks(lines: readonly string[], masked: readonly string[], headings: readonly Heading[]): TaskItem[] {\n  const headingLines = new Set(headings.map((h) => h.line));\n  const tasks: TaskItem[] = [];\n  for (let i = 0; i < masked.length; i += 1) {\n    const match = TASK.exec(masked[i] as string);\n    if (!match) continue;\n    const indent = (match[1] as string).length;\n    const original = TASK.exec(lines[i] as string);\n    const text = (original?.[3] ?? '').trim();\n    tasks.push({ line: i, end: itemEnd(lines, masked, headingLines, i, indent), checked: match[2] !== ' ', text });\n  }\n  return tasks;\n}\n\n/**\n * Where the list item starting at `start` ends: after its last line indented\n * past the marker, or its last lazy continuation line - text directly under\n * the item with no blank line between, which CommonMark folds into the item's\n * paragraph.\n */\nfunction itemEnd(\n  lines: readonly string[],\n  masked: readonly string[],\n  headingLines: ReadonlySet<number>,\n  start: number,\n  indent: number,\n): number {\n  let last = start;\n  let previousBlank = false;\n  for (let k = start + 1; k < lines.length; k += 1) {\n    const line = lines[k] as string;\n    if (headingLines.has(k)) break;\n    if (line.trim() === '') {\n      previousBlank = true;\n      continue;\n    }\n    const nested = indentOf(line) > indent;\n    const lazy = !previousBlank && !LIST_ITEM.test(masked[k] as string) && !FENCE.test(line) && !/^\\s*>/.test(line);\n    if (!nested && !lazy) break;\n    last = k;\n    previousBlank = false;\n  }\n  return last + 1;\n}\n\n/** Sections: every heading below the title, running to the next heading at its level or above. */\nexport function sectionsOf(result: Scan): Section[] {\n  const sections: Section[] = [];\n  const { headings } = result;\n  for (let h = 0; h < headings.length; h += 1) {\n    const heading = headings[h] as Heading;\n    if (heading.level < 2) continue;\n    let end = result.lines.length;\n    for (let k = h + 1; k < headings.length; k += 1) {\n      const next = headings[k] as Heading;\n      if (next.level <= heading.level) {\n        end = next.line;\n        break;\n      }\n    }\n    sections.push({ heading, end });\n  }\n  return sections;\n}\n\n/** The first level-one heading, which is what a reader takes as the title. */\nexport function titleOf(result: Scan): Heading | undefined {\n  return result.headings.find((h) => h.level === 1);\n}\n\nconst DEFINITION = /^ {0,3}\\[(?!\\^)[^\\]]+\\]:[ \\t]*/;\n/** What may follow a definition's destination: nothing, or a title. */\nconst TITLE = /^(?:\"[^\"]*\"|'[^']*'|\\([^)]*\\))?$/;\n\n/**\n * Link and image destinations outside code and comments: `[text](dest)`,\n * `![alt](dest)`, and reference definitions `[label]: dest`.\n */\nexport function linksOf(result: Scan): LinkDestination[] {\n  const links: LinkDestination[] = [];\n  result.masked.forEach((masked, line) => {\n    const original = result.lines[line] as string;\n    const definition = DEFINITION.exec(masked);\n    if (definition) {\n      // `[Note]: this matters` is prose that looks like a definition; a real one\n      // has nothing after its destination but an optional title.\n      const found = readDestination(masked, original, definition[0].length);\n      if (found && TITLE.test(masked.slice(found.end + (masked.charAt(found.end) === '>' ? 1 : 0)).trim())) {\n        links.push({ line, ...found });\n      }\n    }\n    let from = 0;\n    for (;;) {\n      const at = masked.indexOf('](', from);\n      if (at < 0) break;\n      let start = at + 2;\n      while (masked.charAt(start) === ' ' || masked.charAt(start) === '\\t') start += 1;\n      const found = readDestination(masked, original, start);\n      if (found) links.push({ line, ...found });\n      from = at + 2;\n    }\n  });\n  return links;\n}\n\nfunction readDestination(\n  masked: string,\n  original: string,\n  start: number,\n): { start: number; end: number; target: string } | undefined {\n  if (masked.charAt(start) === '<') {\n    const close = masked.indexOf('>', start + 1);\n    if (close < 0) return undefined;\n    return { start: start + 1, end: close, target: original.slice(start + 1, close) };\n  }\n  let depth = 0;\n  let end = start;\n  while (end < masked.length) {\n    const ch = masked.charAt(end);\n    if (ch === ' ' || ch === '\\t') break;\n    if (ch === '(') depth += 1;\n    if (ch === ')') {\n      if (depth === 0) break;\n      depth -= 1;\n    }\n    end += 1;\n  }\n  if (end === start) return undefined;\n  return { start, end, target: original.slice(start, end) };\n}\n\n/** Whether a line carries anything once comments are removed. */\nexport function hasContent(proseLine: string): boolean {\n  return proseLine.trim().length > 0;\n}\n"]}

package/dist/plugins.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Loading rule plugins named by the configuration.
+ *
+ * spec-brief does not know how another tool signs a departure, records a
+ * reproducer or measures a blast radius, and should not: the tool that
+ * defines a format is the one that can check it. A plugin is a module whose
+ * default export is a plugin object, or a function of the configured options
+ * that returns one. Loading one runs its code, exactly as loading an ESLint
+ * configuration does; the configuration belongs to the repository, and so
+ * does that trust.
+ */
+import type { PluginReference } from './config.js';
+import type { Plugin } from './lint.js';
+/** Checks the shape a module exported, since nothing typed it on the way in. */
+export declare function asPlugin(value: unknown, module: string, options: unknown): Plugin;
+export declare function loadPlugins(references: readonly PluginReference[], root: string): Promise<Plugin[]>;

package/dist/plugins.js

@@ -0,0 +1,77 @@
+/**
+ * Loading rule plugins named by the configuration.
+ *
+ * spec-brief does not know how another tool signs a departure, records a
+ * reproducer or measures a blast radius, and should not: the tool that
+ * defines a format is the one that can check it. A plugin is a module whose
+ * default export is a plugin object, or a function of the configured options
+ * that returns one. Loading one runs its code, exactly as loading an ESLint
+ * configuration does; the configuration belongs to the repository, and so
+ * does that trust.
+ */
+import { createRequire } from 'node:module';
+import { isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ConfigError } from './config.js';
+const SEVERITIES = new Set(['off', 'note', 'warning', 'error']);
+function specifierUrl(specifier, root) {
+    if (specifier.startsWith('.') || isAbsolute(specifier))
+        return pathToFileURL(resolve(root, specifier)).href;
+    const require = createRequire(join(root, 'package.json'));
+    return pathToFileURL(require.resolve(specifier)).href;
+}
+function isRule(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const rule = value;
+    return (typeof rule['id'] === 'string' &&
+        /^[a-z0-9][a-z0-9-]*$/.test(rule['id']) &&
+        typeof rule['description'] === 'string' &&
+        typeof rule['severity'] === 'string' &&
+        SEVERITIES.has(rule['severity']) &&
+        typeof rule['check'] === 'function');
+}
+/** Checks the shape a module exported, since nothing typed it on the way in. */
+export function asPlugin(value, module, options) {
+    const problems = [];
+    if (typeof value !== 'object' || value === null) {
+        throw new ConfigError(module, ['does not export a plugin: expected an object with "name" and "rules"']);
+    }
+    const candidate = value;
+    const name = candidate['name'];
+    const rules = candidate['rules'];
+    if (typeof name !== 'string' || !/^[a-z0-9@][a-z0-9@/._-]*$/i.test(name))
+        problems.push('"name" must be a plain identifier');
+    if (!Array.isArray(rules))
+        problems.push('"rules" must be a list');
+    else {
+        rules.forEach((rule, i) => {
+            if (!isRule(rule))
+                problems.push(`rules[${i}] needs a lower-case "id", a "description", a "severity" and a "check" function`);
+        });
+    }
+    if (problems.length > 0)
+        throw new ConfigError(module, problems);
+    return { name: name, rules: rules, options };
+}
+export async function loadPlugins(references, root) {
+    const plugins = [];
+    for (const reference of references) {
+        let loaded;
+        try {
+            loaded = (await import(specifierUrl(reference.module, root)));
+        }
+        catch (error) {
+            throw new ConfigError(reference.module, [`could not be loaded: ${error.message}`]);
+        }
+        const exported = loaded['default'] ?? loaded['plugin'];
+        const value = typeof exported === 'function' ? await exported(reference.options) : exported;
+        plugins.push(asPlugin(value, reference.module, reference.options));
+    }
+    const names = plugins.map((p) => p.name);
+    const repeated = names.filter((n, i) => names.indexOf(n) !== i);
+    if (repeated.length > 0)
+        throw new ConfigError('plugins', [`two plugins are named "${repeated[0]}"`]);
+    return plugins;
+}
+//# sourceMappingURL=plugins.js.map

package/dist/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Loading rule plugins named by the configuration.\n *\n * spec-brief does not know how another tool signs a departure, records a\n * reproducer or measures a blast radius, and should not: the tool that\n * defines a format is the one that can check it. A plugin is a module whose\n * default export is a plugin object, or a function of the configured options\n * that returns one. Loading one runs its code, exactly as loading an ESLint\n * configuration does; the configuration belongs to the repository, and so\n * does that trust.\n */\n\nimport { createRequire } from 'node:module';\nimport { isAbsolute, join, resolve } from 'node:path';\nimport { pathToFileURL } from 'node:url';\n\nimport type { PluginReference } from './config.js';\nimport { ConfigError } from './config.js';\nimport type { Plugin } from './lint.js';\nimport type { Rule } from './rules.js';\n\nconst SEVERITIES = new Set(['off', 'note', 'warning', 'error']);\n\nfunction specifierUrl(specifier: string, root: string): string {\n  if (specifier.startsWith('.') || isAbsolute(specifier)) return pathToFileURL(resolve(root, specifier)).href;\n  const require = createRequire(join(root, 'package.json'));\n  return pathToFileURL(require.resolve(specifier)).href;\n}\n\nfunction isRule(value: unknown): value is Rule {\n  if (typeof value !== 'object' || value === null) return false;\n  const rule = value as Record<string, unknown>;\n  return (\n    typeof rule['id'] === 'string' &&\n    /^[a-z0-9][a-z0-9-]*$/.test(rule['id']) &&\n    typeof rule['description'] === 'string' &&\n    typeof rule['severity'] === 'string' &&\n    SEVERITIES.has(rule['severity']) &&\n    typeof rule['check'] === 'function'\n  );\n}\n\n/** Checks the shape a module exported, since nothing typed it on the way in. */\nexport function asPlugin(value: unknown, module: string, options: unknown): Plugin {\n  const problems: string[] = [];\n  if (typeof value !== 'object' || value === null) {\n    throw new ConfigError(module, ['does not export a plugin: expected an object with \"name\" and \"rules\"']);\n  }\n  const candidate = value as Record<string, unknown>;\n  const name = candidate['name'];\n  const rules = candidate['rules'];\n  if (typeof name !== 'string' || !/^[a-z0-9@][a-z0-9@/._-]*$/i.test(name)) problems.push('\"name\" must be a plain identifier');\n  if (!Array.isArray(rules)) problems.push('\"rules\" must be a list');\n  else {\n    rules.forEach((rule, i) => {\n      if (!isRule(rule)) problems.push(`rules[${i}] needs a lower-case \"id\", a \"description\", a \"severity\" and a \"check\" function`);\n    });\n  }\n  if (problems.length > 0) throw new ConfigError(module, problems);\n  return { name: name as string, rules: rules as Rule[], options };\n}\n\nexport async function loadPlugins(references: readonly PluginReference[], root: string): Promise<Plugin[]> {\n  const plugins: Plugin[] = [];\n  for (const reference of references) {\n    let loaded: Record<string, unknown>;\n    try {\n      loaded = (await import(specifierUrl(reference.module, root))) as Record<string, unknown>;\n    } catch (error) {\n      throw new ConfigError(reference.module, [`could not be loaded: ${(error as Error).message}`]);\n    }\n    const exported = loaded['default'] ?? loaded['plugin'];\n    const value = typeof exported === 'function' ? await (exported as (o: unknown) => unknown)(reference.options) : exported;\n    plugins.push(asPlugin(value, reference.module, reference.options));\n  }\n  const names = plugins.map((p) => p.name);\n  const repeated = names.filter((n, i) => names.indexOf(n) !== i);\n  if (repeated.length > 0) throw new ConfigError('plugins', [`two plugins are named \"${repeated[0] as string}\"`]);\n  return plugins;\n}\n"]}

package/dist/report.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Rendering: findings, lists, the collision matrix and plans, for a person at
+ * a terminal or for the machine reading the job.
+ *
+ * `json` is a document with a version, for orchestrators. `sarif` is SARIF
+ * 2.1.0, for code-scanning upload. `github` is workflow commands, which put a
+ * finding on the line of the pull request with no upload and no permission.
+ */
+import type { Plan } from './archive.js';
+import type { Brief } from './brief.js';
+import type { CollisionReport } from './collisions.js';
+import type { Finding } from './types.js';
+export type Format = 'pretty' | 'json' | 'sarif' | 'github';
+export declare const FORMATS: readonly Format[];
+/** The version of the JSON documents this tool prints. Bumped when a field changes meaning. */
+export declare const JSON_SCHEMA_VERSION = 1;
+export interface Style {
+    readonly color: boolean;
+}
+declare const CODES: Readonly<Record<string, readonly [number, number]>>;
+export declare function paint(style: Style, color: keyof typeof CODES, text: string): string;
+export declare function summaryLine(findings: readonly Finding[]): string;
+export declare function prettyFindings(findings: readonly Finding[], style: Style): string;
+export declare function jsonDocument(command: string, version: string, body: Record<string, unknown>): string;
+export declare function findingJson(f: Finding): Record<string, unknown>;
+export declare function sarif(findings: readonly Finding[], version: string): string;
+export declare function githubCommands(findings: readonly Finding[]): string;
+export declare function briefJson(brief: Brief, extra?: Record<string, unknown>): Record<string, unknown>;
+export interface ListRow {
+    readonly brief: Brief;
+    readonly ready: boolean;
+    readonly waitingOn: readonly string[];
+}
+export declare function prettyList(rows: readonly ListRow[], style: Style): string;
+export declare function prettyMatrix(report: CollisionReport, style: Style): string;
+export declare function prettyPlan(plan: Plan, dryRun: boolean, style: Style): string;
+export declare function planJson(plan: Plan): Record<string, unknown>;
+export {};