@descent-vtt/spec-guard 0.11.0 → 0.12.1

package/dist/reporter.js

@@ -158,6 +158,47 @@ function formatError(error, paint, glyphs) {
         lines.push(`    ${paint(error.raw.split('\n')[0], 'dim')}`);
     return lines;
 }
+/**
+ * What changed how a document was read, on the line it happened. Yellow, as a
+ * note is: nothing failed, but a rule may not have run where it was written.
+ */
+function formatSpecWarnings(warnings, paint, glyphs) {
+    const lines = (warnings ?? []).map((warning) => `${paint(glyphs.warn, 'yellow')} ${paint(`${warning.location.relativeFile}:${warning.location.line}  ${warning.message}`, 'yellow')}`);
+    return lines.length === 0 ? [] : [...lines, ''];
+}
+/** How many locations the line about masked directives names before it counts the rest. */
+const MASKED_SHOWN = 5;
+/**
+ * The one line that counts the directive-shaped comments no rule was read
+ * from, and says where: dim, as a withheld document is, since most are
+ * examples shown on purpose. The first few are named, and every one under
+ * `--verbose`; JSON names them all.
+ */
+function formatMasked(masked, paint, glyphs, verbose) {
+    const all = masked ?? [];
+    if (all.length === 0)
+        return [];
+    const shown = verbose ? all : all.slice(0, MASKED_SHOWN);
+    const places = shown.map(({ location }) => `${location.relativeFile}:${location.line}`).join(', ');
+    const rest = all.length - shown.length;
+    const was = all.length === 1 ? 'was' : 'were';
+    return [
+        paint(`${glyphs.skip} ${countLabel(all.length, 'directive-shaped comment')} in code, raw HTML or front matter ${was} not run: ${places}${rest > 0 ? ` and ${rest} more` : ''}`, 'dim'),
+        '',
+    ];
+}
+/** Directive-shaped comments as a script reads them, each with what hid it. */
+function maskedJson(masked) {
+    return (masked ?? []).map(({ location, inside }) => ({ spec: { file: location.relativeFile, line: location.line, column: location.column }, inside }));
+}
+/** A document's warnings as a script reads them, placed as errors are. */
+function specWarningsJson(warnings) {
+    return (warnings ?? []).map((warning) => ({
+        spec: { file: warning.location.relativeFile, line: warning.location.line, column: warning.location.column },
+        kind: warning.kind,
+        message: warning.message,
+    }));
+}
 /**
  * The line that says which options came from a project's configuration.
  *
@@ -221,6 +262,7 @@ export function formatReport(report, options, maxSnippets = 5) {
     }
     if (report.warnings.length > 0)
         lines.push('');
+    lines.push(...formatSpecWarnings(report.specWarnings, paint, glyphs));
     // A passing assertion's own warnings - references that could not be resolved,
     // files no layer constrains, a target that is not there - print whether or not
     // --verbose was passed. Nobody passes --verbose to a green run, which is when
@@ -264,6 +306,7 @@ export function formatReport(report, options, maxSnippets = 5) {
     }
     if (report.inactiveSpecs.length > 0)
         lines.push('');
+    lines.push(...formatMasked(report.maskedDirectives, paint, glyphs, options.verbose));
     const optionLines = formatOptionLines(report.config, report.exclude);
     if (optionLines.length > 0)
         lines.push(...optionLines, '');
@@ -320,9 +363,18 @@ export function formatBaselines(report) {
         return '# nothing to baseline: no failing assertion had a match to exempt';
     return lines.join('\n').trimEnd();
 }
+/**
+ * The version of a run's `--json` document. A field removed or renamed moves
+ * it; a field added does not. The family contract (spec-core's ADR-0005) asks
+ * it of every machine-readable output. The run's document went without one
+ * for eleven releases, and got it at 1, since nothing had been removed or
+ * renamed in them.
+ */
+export const RUN_FORMAT_VERSION = 1;
 /** Machine-readable output for CI consumers. */
 export function formatJson(report) {
     return JSON.stringify({
+        formatVersion: RUN_FORMAT_VERSION,
         ok: report.ok,
         root: report.root,
         engine: report.engine,
@@ -367,6 +419,8 @@ export function formatJson(report) {
             raw: error.raw,
         })),
         warnings: report.warnings,
+        specWarnings: specWarningsJson(report.specWarnings),
+        maskedDirectives: maskedJson(report.maskedDirectives),
         inactiveSpecs: report.inactiveSpecs,
         // Always present, as every other list is: an audit records "no project
         // exclusions" as surely as it records which.
@@ -386,6 +440,24 @@ export function formatJson(report) {
 function fingerprint(parts) {
     return createHash('sha256').update(parts.join('\u0000')).digest('hex').slice(0, 32);
 }
+/**
+ * What an assertion is, whatever it found: its document, its kind, what it is
+ * about and where it looks. Never a count or a line, so an alert stays one
+ * alert while the code it counts changes and the document it sits in grows.
+ */
+function assertionIdentity(result) {
+    return [
+        result.location.relativeFile,
+        result.kind,
+        // The description only where there is nothing else to tell two
+        // assertions apart. A cycle or layer rule names no symbol and no
+        // file, so two on one target - `types="ignore"` beside the default -
+        // would share an identity and be merged into one alert. Every kind
+        // that has a symbol or a file list keeps the fingerprint it had.
+        result.symbol ?? (result.files.length > 0 ? result.files.join(',') : result.description),
+        result.targets.join(','),
+    ];
+}
 /** SARIF severity for anything spec-guard reports. */
 const SARIF_LEVEL = 'error';
 /** One rule per directive kind, plus the one for a directive that will not parse. */
@@ -410,13 +482,21 @@ const SARIF_RULES = [
  * which GitHub surfaces as run information rather than as an alert.
  */
 function inactiveNotifications(report) {
-    return report.inactiveSpecs.map((spec) => ({
-        level: 'note',
-        message: {
-            text: `${spec.file} is ${spec.label}, so ` +
-                `${spec.directives === 1 ? 'its 1 assertion was' : `its ${spec.directives} assertions were`} not executed.`,
-        },
-    }));
+    return [
+        ...report.inactiveSpecs.map((spec) => ({
+            level: 'note',
+            message: {
+                text: `${spec.file} is ${spec.label}, so ` +
+                    `${spec.directives === 1 ? 'its 1 assertion was' : `its ${spec.directives} assertions were`} not executed.`,
+            },
+        })),
+        // A document read differently from how it was written runs different
+        // rules, and the page a reviewer reads would otherwise not say so.
+        ...(report.specWarnings ?? []).map((warning) => ({
+            level: 'warning',
+            message: { text: `${warning.location.relativeFile}:${warning.location.line} ${warning.message}` },
+        })),
+    ];
 }
 function sarifLocation(uri, line, column, text) {
     const location = {
@@ -466,19 +546,7 @@ export function formatSarif(report, options = {}) {
             // baseline - is anchored on the directive, which is where its fix goes.
             locations: [matches[0] ?? spec],
             relatedLocations: matches[0] ? [...matches.slice(1), spec] : [],
-            partialFingerprints: {
-                specGuardAssertion: fingerprint([
-                    result.location.relativeFile,
-                    result.kind,
-                    // The description only where there is nothing else to tell two
-                    // assertions apart. A cycle or layer rule names no symbol and no
-                    // file, so two on one target - `types="ignore"` beside the default -
-                    // would share an identity and be merged into one alert. Every kind
-                    // that has a symbol or a file list keeps the fingerprint it had.
-                    result.symbol ?? (result.files.length > 0 ? result.files.join(',') : result.description),
-                    result.targets.join(','),
-                ]),
-            },
+            partialFingerprints: { specGuardAssertion: fingerprint(assertionIdentity(result)) },
         });
     }
     for (const error of report.errors) {
@@ -502,7 +570,7 @@ export function formatSarif(report, options = {}) {
             {
                 // Present only when there is something to say. An empty invocations
                 // block is noise in every consumer that renders one.
-                ...(report.inactiveSpecs.length > 0
+                ...(report.inactiveSpecs.length + (report.specWarnings?.length ?? 0) > 0
                     ? {
                         invocations: [
                             { executionSuccessful: report.ok, toolExecutionNotifications: inactiveNotifications(report) },
@@ -526,4 +594,508 @@ export function formatSarif(report, options = {}) {
         ],
     }, null, 2);
 }
+/* -------------------------------------------------------------------- prove */
+/** What each outcome is called where a person reads it. */
+const PROVE_WORDS = {
+    killed: 'seen to fail',
+    survived: 'passed with a violation in place',
+    unprovable: 'no violation could be made',
+};
+/** The claim a probe crossed, as a report names it. */
+const CLAIM_WORDS = { max: 'maximum', min: 'minimum', present: 'presence' };
+function formatProveResult(result, paint, glyphs) {
+    const glyph = result.outcome === 'killed'
+        ? paint(glyphs.pass, 'green')
+        : result.outcome === 'survived'
+            ? paint(glyphs.fail, 'red', 'bold')
+            : paint(glyphs.skip, 'yellow');
+    const lines = [
+        `${glyph} ${paint(formatLocation(result), 'bold')}  ${paint(`@${result.kind}`, 'magenta')}  ${PROVE_WORDS[result.outcome]}`,
+        `    ${result.description}`,
+    ];
+    for (const probe of result.probes) {
+        const verdict = probe.outcome === 'killed' ? paint('and it failed', 'green') : paint('and it still passed', 'red', 'bold');
+        lines.push(`    ${CLAIM_WORDS[probe.claim]}: ${probe.violation}, ${verdict}: ${paint(probe.message, 'dim')}`);
+    }
+    if (result.unprovable !== undefined)
+        lines.push(`    ${paint(result.unprovable, 'yellow')}`);
+    if (result.reason !== undefined)
+        lines.push(`    ${paint(`reason: ${result.reason}`, 'dim')}`);
+    return lines;
+}
+/**
+ * Renders what `spec-guard prove` found, for a person.
+ *
+ * A rule that survived is the finding, and is printed whatever the options;
+ * so is one no violation could be made for, since a rule nobody can show
+ * failing is not yet one anybody should trust. A rule seen to fail is printed
+ * under `--verbose`, with the violation that failed it. Survivors come first.
+ */
+export function formatProve(report, options) {
+    const paint = createPainter(options.color);
+    const glyphs = symbols(options.ascii ?? false);
+    const { summary } = report;
+    const lines = [
+        `${paint('spec-guard prove', 'bold', 'blue')} ${paint(`${countLabel(summary.specs, 'spec')} · ${countLabel(summary.total, 'rule')}`, 'dim')}`,
+        '',
+    ];
+    for (const outcome of ['survived', 'unprovable', 'killed']) {
+        if (outcome === 'killed' && !options.verbose)
+            continue;
+        for (const result of report.results.filter((entry) => entry.outcome === outcome)) {
+            lines.push(...formatProveResult(result, paint, glyphs), '');
+        }
+    }
+    for (const error of report.errors)
+        lines.push(...formatError(error, paint, glyphs), '');
+    lines.push(...formatSpecWarnings(report.specWarnings, paint, glyphs));
+    for (const spec of report.inactiveSpecs) {
+        lines.push(paint(`${glyphs.skip} ${spec.file} is ${spec.label} - ${countLabel(spec.directives, 'rule')} not proved`, 'dim'));
+    }
+    if (report.inactiveSpecs.length > 0)
+        lines.push('');
+    lines.push(...formatMasked(report.maskedDirectives, paint, glyphs, options.verbose));
+    const optionLines = formatOptionLines(report.config, report.exclude);
+    if (optionLines.length > 0)
+        lines.push(...optionLines, '');
+    const parts = [
+        paint(`${summary.killed} seen to fail`, 'green'),
+        summary.survived > 0 ? paint(`${summary.survived} survived`, 'red', 'bold') : null,
+        summary.unprovable > 0 ? paint(`${summary.unprovable} unprovable`, 'yellow') : null,
+        report.errors.length > 0 ? paint(`${report.errors.length} invalid`, 'yellow') : null,
+        summary.inactive > 0 ? paint(`${summary.inactive} not in force`, 'dim') : null,
+        paint(formatDuration(report.durationMs), 'dim'),
+    ].filter((part) => part !== null);
+    lines.push(parts.join(paint(' · ', 'dim')));
+    if (summary.survived > 0) {
+        const them = summary.survived === 1 ? 'itself' : 'themselves';
+        lines.push(paint(`${glyphs.fail} ${countLabel(summary.survived, 'rule')} passed with a violation of ${them} in place`, 'red', 'bold'));
+    }
+    else if (summary.total === 0) {
+        lines.push(paint(`${glyphs.warn} no rule was proved, so nothing was shown`, 'yellow'));
+    }
+    else if (summary.killed === summary.total) {
+        lines.push(paint(`${glyphs.pass} every rule in force was seen to fail`, 'green'));
+    }
+    return lines.join('\n');
+}
+/**
+ * The version of `spec-guard prove --json`'s document. A field removed or
+ * renamed moves it; a field added does not.
+ */
+export const PROVE_FORMAT_VERSION = 1;
+/** What `spec-guard prove` found, for a script. */
+export function formatProveJson(report) {
+    return JSON.stringify({
+        formatVersion: PROVE_FORMAT_VERSION,
+        ok: report.ok,
+        root: report.root,
+        durationMs: Math.round(report.durationMs * 1000) / 1000,
+        summary: report.summary,
+        specFiles: report.specFiles,
+        results: report.results.map((result) => ({
+            outcome: result.outcome,
+            kind: result.kind,
+            spec: { file: result.location.relativeFile, line: result.location.line, column: result.location.column },
+            description: result.description,
+            reason: result.reason,
+            unprovable: result.unprovable,
+            probes: result.probes,
+            durationMs: Math.round(result.durationMs * 1000) / 1000,
+        })),
+        errors: report.errors.map((error) => ({
+            spec: { file: error.location.relativeFile, line: error.location.line, column: error.location.column },
+            message: error.message,
+            raw: error.raw,
+        })),
+        specWarnings: specWarningsJson(report.specWarnings),
+        maskedDirectives: maskedJson(report.maskedDirectives),
+        inactiveSpecs: report.inactiveSpecs,
+        exclude: report.exclude,
+        config: report.config,
+    }, null, 2);
+}
+/** One rule per finding `spec-guard prove` makes. */
+const PROVE_RULES = [
+    { id: 'rule-cannot-fail', text: 'A rule that passed with a violation of itself in place.' },
+    { id: 'rule-unprovable', text: 'A rule no violation could be made for.' },
+    { id: 'invalid-directive', text: 'A directive that could not be parsed, so nothing was checked.' },
+];
+/**
+ * What `spec-guard prove` found, for code scanning.
+ *
+ * A rule that survived is an error on its directive, which is where the fix
+ * goes: a target that reaches the code, a glob that names its kind, a bound
+ * that can be crossed. A rule no violation could be made for is a note there,
+ * which GitHub shows without failing anything. A rule seen to fail is not a
+ * finding and is not a result.
+ */
+export function formatProveSarif(report, options = {}) {
+    const results = report.results
+        .filter((result) => result.outcome !== 'killed')
+        .map((result) => {
+        const survived = result.outcome === 'survived';
+        const detail = survived
+            ? result.probes
+                .filter((probe) => probe.outcome === 'survived')
+                .map((probe) => `${probe.violation}, and it still passed: ${probe.message}`)
+                .join('; ')
+            : result.unprovable;
+        return {
+            ruleId: survived ? 'rule-cannot-fail' : 'rule-unprovable',
+            level: survived ? SARIF_LEVEL : 'note',
+            message: { text: `${result.description}: ${detail}` },
+            locations: [sarifLocation(result.location.relativeFile, result.location.line, result.location.column)],
+            partialFingerprints: {
+                specGuardAssertion: fingerprint([result.location.relativeFile, result.kind, result.description]),
+            },
+        };
+    });
+    for (const error of report.errors) {
+        results.push({
+            ruleId: 'invalid-directive',
+            level: SARIF_LEVEL,
+            message: { text: error.message },
+            locations: [sarifLocation(error.location.relativeFile, error.location.line, error.location.column)],
+            partialFingerprints: { specGuardAssertion: fingerprint([error.location.relativeFile, 'invalid', error.message]) },
+        });
+    }
+    return JSON.stringify({
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'spec-guard prove',
+                        informationUri: 'https://github.com/DescentVTT/spec-guard',
+                        version: options.version ?? '0.0.0',
+                        rules: PROVE_RULES.map((rule) => ({ id: rule.id, name: rule.id, shortDescription: { text: rule.text } })),
+                    },
+                },
+                results,
+            },
+        ],
+    }, null, 2);
+}
+/**
+ * A finding as GitLab Code Quality reads it.
+ *
+ * The fingerprint is what GitLab compares between a merge request and its
+ * target to tell a finding that is new from one that was already there. It is
+ * the SHA-256 of the annotation's identity - the rule, the document or file,
+ * the subject - and never of its message: a message holds the count of
+ * matches and the directive's line, so one more match, or a line added above
+ * the directive, made every open issue look fixed and a new one appear. Two
+ * findings with one identity, one ghost cited on two lines, are told apart by
+ * the order they come in, each a finding of its own.
+ */
+export function formatGitlab(annotations) {
+    const seen = new Map();
+    const issues = [];
+    for (const annotation of annotations) {
+        const identity = annotation.identity.join('\u0000');
+        const repeat = seen.get(identity) ?? 0;
+        seen.set(identity, repeat + 1);
+        const fingerprint = createHash('sha256')
+            .update(repeat === 0 ? identity : `${identity}\u0000${repeat}`)
+            .digest('hex');
+        issues.push({
+            description: annotation.message,
+            check_name: annotation.rule,
+            fingerprint,
+            severity: annotation.severity,
+            location: { path: annotation.file, lines: { begin: Math.max(annotation.line, 1) } },
+        });
+    }
+    return JSON.stringify(issues, null, 2);
+}
+/** A workflow command's message: `%`, and the line breaks that would end the command. */
+function escapeData(text) {
+    return text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+/** A workflow command's property: as a message, and the `:` and `,` that would end the property. */
+function escapeProperty(text) {
+    return escapeData(text).replace(/:/g, '%3A').replace(/,/g, '%2C');
+}
+/**
+ * Findings as GitHub Actions workflow commands, one line each, which a job's log
+ * turns into annotations on the pull request's diff without an upload step.
+ * Nothing at all when there is nothing to annotate.
+ */
+export function formatGithub(annotations) {
+    return annotations
+        .map((annotation) => `::${annotation.level} file=${escapeProperty(annotation.file)},line=${Math.max(annotation.line, 1)},title=${escapeProperty(annotation.rule)}::${escapeData(annotation.message)}`)
+        .join('\n');
+}
+/** Where a document that is not in force is named, in a format with no room for a note beside the findings. */
+function inactiveAnnotations(inactive, what, done) {
+    return inactive.map((spec) => ({
+        rule: 'not-in-force',
+        identity: ['not-in-force', spec.file],
+        level: 'notice',
+        severity: 'info',
+        file: spec.file,
+        line: 1,
+        message: `${spec.file} is ${spec.label}, so ${spec.directives === 1 ? `its 1 ${what} was` : `its ${spec.directives} ${what}s were`} not ${done}.`,
+    }));
+}
+/** What changed how a document was read, on the line it happened: a warning, which fails nothing. */
+function warningAnnotations(warnings) {
+    return (warnings ?? []).map((warning) => ({
+        rule: 'spec-warning',
+        identity: ['spec-warning', warning.location.relativeFile, warning.kind],
+        level: 'warning',
+        severity: 'minor',
+        file: warning.location.relativeFile,
+        line: warning.location.line,
+        message: warning.message,
+    }));
+}
+/** A directive that could not be read: nothing it states was checked. */
+function errorAnnotations(errors) {
+    return errors.map((error) => ({
+        rule: 'invalid-directive',
+        identity: ['invalid-directive', error.location.relativeFile, error.message],
+        level: 'error',
+        severity: 'major',
+        file: error.location.relativeFile,
+        line: error.location.line,
+        message: error.message,
+    }));
+}
+/**
+ * A run's findings, placed as SARIF places them.
+ *
+ * Each failing assertion is one finding, on its first offending line, since the
+ * thing that broke is the rule; one with no match - a missing target, an empty
+ * scope, a directory missing an entry - sits on its directive. `critical`,
+ * because it fails the run. A directive that could not be read fails the run
+ * too, and is `major`: it is the rule, not the code, that needs the fix. A
+ * document not in force is `info`, named rather than left out, for ADR-0010's
+ * reason.
+ */
+export function runAnnotations(report) {
+    const failed = report.results
+        .filter((result) => !result.ok)
+        .map((result) => {
+        const match = result.claim === 'required' ? undefined : result.matches[0];
+        return {
+            rule: result.kind,
+            identity: assertionIdentity(result),
+            level: 'error',
+            severity: 'critical',
+            file: match?.file ?? result.location.relativeFile,
+            line: match?.line ?? result.location.line,
+            message: `${result.description}: ${result.message} (${result.location.relativeFile}:${result.location.line})`,
+        };
+    });
+    return [
+        ...failed,
+        ...errorAnnotations(report.errors),
+        ...warningAnnotations(report.specWarnings),
+        ...inactiveAnnotations(report.inactiveSpecs, 'assertion', 'executed'),
+    ];
+}
+/**
+ * What `spec-guard prove` found, placed on each rule's directive.
+ *
+ * A rule that survived is `critical`: it passed with a violation of itself in
+ * place, and fails the proof. One no violation could be made for is `minor`, a
+ * notice, as it is a note in SARIF. A rule seen to fail is not a finding.
+ */
+export function proveAnnotations(report) {
+    const results = report.results
+        .filter((result) => result.outcome !== 'killed')
+        .map((result) => {
+        const survived = result.outcome === 'survived';
+        const detail = survived
+            ? result.probes
+                .filter((probe) => probe.outcome === 'survived')
+                .map((probe) => `${probe.violation}, and it still passed: ${probe.message}`)
+                .join('; ')
+            : result.unprovable;
+        return {
+            rule: survived ? 'rule-cannot-fail' : 'rule-unprovable',
+            identity: [survived ? 'rule-cannot-fail' : 'rule-unprovable', result.location.relativeFile, result.kind, result.description],
+            level: survived ? 'error' : 'notice',
+            severity: survived ? 'critical' : 'minor',
+            file: result.location.relativeFile,
+            line: result.location.line,
+            message: `${result.description}: ${detail}`,
+        };
+    });
+    return [
+        ...results,
+        ...errorAnnotations(report.errors),
+        ...warningAnnotations(report.specWarnings),
+        ...inactiveAnnotations(report.inactiveSpecs, 'rule', 'proved'),
+    ];
+}
+/* -------------------------------------------------------------------- cites */
+/** How a family is introduced: its id, its documents, and where it came from. */
+function familyLine(family) {
+    const from = family.source === 'derived' ? ", read off the specs' titles" : '';
+    return `${family.id} (${countLabel(family.documents, 'document')} matching ${family.files}${from})`;
+}
+/**
+ * Renders what `spec-guard cites` found, for a person.
+ *
+ * Each ghost and each stale citation is printed with the hint that says what
+ * to do. So are the files whose comments could not all be read, and the files
+ * no comment syntax is known for, counted by extension: a citation in either
+ * was not looked at, and a report that stayed quiet about them would read as
+ * though it had been.
+ */
+export function formatCites(report, options) {
+    const paint = createPainter(options.color);
+    const glyphs = symbols(options.ascii ?? false);
+    const { summary } = report;
+    const families = report.families.length === 0 ? 'no families' : report.families.map(familyLine).join('; ');
+    const lines = [`${paint('spec-guard cites', 'bold', 'blue')} ${paint(families, 'dim')}`, ''];
+    for (const finding of report.findings) {
+        const glyph = finding.severity === 'error' ? paint(glyphs.fail, 'red', 'bold') : paint(glyphs.warn, 'yellow', 'bold');
+        lines.push(`${glyph} ${finding.message}  ${paint(finding.rule, 'dim')}`, `    ${paint(`hint: ${finding.hint}`, 'dim')}`);
+    }
+    if (report.findings.length > 0)
+        lines.push('');
+    if (report.gaps.length > 0) {
+        const them = report.gaps.length === 1 ? 'it' : 'them';
+        lines.push(paint(`${glyphs.skip} ${countLabel(report.gaps.length, 'file')} could not be read in full, so a citation in ${them} may have been missed:`, 'yellow'));
+        for (const gap of report.gaps)
+            lines.push(`    ${gap.file} ${gap.detail}`);
+        lines.push('');
+    }
+    if (summary.unclassified > 0) {
+        const kinds = report.unclassified.map(({ extension, files }) => `${extension} ${files}`).join(', ');
+        lines.push(paint(`${glyphs.skip} ${countLabel(summary.unclassified, 'file')} in no language spec-guard knows the comments of, and not read: ${kinds}`, 'dim'), '');
+    }
+    if (summary.qualified > 0) {
+        const verb = summary.qualified === 1 ? 'names' : 'name';
+        const were = summary.qualified === 1 ? 'was' : 'were';
+        lines.push(paint(`${glyphs.skip} ${countLabel(summary.qualified, 'id')} ${verb} another project's document, as spec-core's ADR-0005 does, and ${were} not checked`, 'dim'), '');
+    }
+    for (const note of report.notes)
+        lines.push(paint(`${glyphs.skip} ${note}`, 'dim'));
+    if (report.notes.length > 0)
+        lines.push('');
+    const optionLines = formatOptionLines(report.config, report.exclude);
+    if (optionLines.length > 0)
+        lines.push(...optionLines, '');
+    const parts = [
+        `${countLabel(summary.citations, 'citation')} in ${countLabel(summary.files, 'file')}`,
+        summary.ghosts > 0 ? paint(countLabel(summary.ghosts, 'ghost'), 'red', 'bold') : null,
+        summary.stale > 0 ? paint(`${summary.stale} stale`, 'yellow') : null,
+        paint(formatDuration(report.durationMs), 'dim'),
+    ].filter((part) => part !== null);
+    lines.push(parts.join(paint(' · ', 'dim')));
+    const names = (count) => `${countLabel(count, 'citation')} ${count === 1 ? 'names' : 'name'}`;
+    if (summary.ghosts > 0) {
+        lines.push(paint(`${glyphs.fail} ${names(summary.ghosts)} a document that does not exist`, 'red', 'bold'));
+    }
+    else if (report.families.length === 0) {
+        lines.push(paint(`${glyphs.warn} no citation was looked for, so nothing was checked`, 'yellow'));
+    }
+    else if (summary.files === 0) {
+        lines.push(paint(`${glyphs.warn} no source file was read, so nothing was checked`, 'yellow'));
+    }
+    else if (summary.stale > 0) {
+        lines.push(paint(`${report.ok ? glyphs.warn : glyphs.fail} ${names(summary.stale)} a document no longer in force`, 'yellow', 'bold'));
+    }
+    else {
+        lines.push(paint(`${glyphs.pass} every citation names a document in force`, 'green'));
+    }
+    return lines.join('\n');
+}
+/**
+ * The version of `spec-guard cites --json`'s document. A field removed or
+ * renamed moves it; a field added does not.
+ */
+export const CITES_FORMAT_VERSION = 1;
+/** What `spec-guard cites` found, for a script. */
+export function formatCitesJson(report) {
+    return JSON.stringify({
+        formatVersion: CITES_FORMAT_VERSION,
+        ok: report.ok,
+        root: report.root,
+        durationMs: Math.round(report.durationMs * 1000) / 1000,
+        families: report.families,
+        summary: report.summary,
+        findings: report.findings,
+        gaps: report.gaps,
+        unclassified: report.unclassified,
+        notes: report.notes,
+        exclude: report.exclude,
+        config: report.config,
+    }, null, 2);
+}
+const CITE_SARIF_RULES = [
+    { id: 'ghost-citation', text: 'A comment cites a document that does not exist.' },
+    { id: 'stale-citation', text: 'A comment cites a document that is no longer in force.' },
+];
+/**
+ * What `spec-guard cites` found, for code scanning: each finding on the line
+ * of the comment, with its hint beneath. The fingerprint is the file, the rule
+ * and the id as written, which survives the comment moving. A file whose
+ * comments could not all be read, and every note, is a notification.
+ */
+export function formatCitesSarif(report, options = {}) {
+    const notifications = [
+        ...report.gaps.map((gap) => ({ level: 'warning', message: { text: `${gap.file} ${gap.detail}` } })),
+        ...report.notes.map((note) => ({ level: 'note', message: { text: note } })),
+    ];
+    return JSON.stringify({
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                ...(notifications.length > 0 ? { invocations: [{ executionSuccessful: report.ok, toolExecutionNotifications: notifications }] } : {}),
+                tool: {
+                    driver: {
+                        name: 'spec-guard cites',
+                        informationUri: 'https://github.com/DescentVTT/spec-guard',
+                        version: options.version ?? '0.0.0',
+                        rules: CITE_SARIF_RULES.map((rule) => ({ id: rule.id, name: rule.id, shortDescription: { text: rule.text } })),
+                    },
+                },
+                results: report.findings.map((finding) => ({
+                    ruleId: finding.rule,
+                    level: finding.severity,
+                    message: { text: `${finding.message}\n${finding.hint}` },
+                    locations: [sarifLocation(finding.file, finding.line, finding.column)],
+                    partialFingerprints: { specGuardCitation: fingerprint([finding.file, finding.rule, finding.cited]) },
+                })),
+            },
+        ],
+    }, null, 2);
+}
+/**
+ * What `spec-guard cites` found, placed for GitLab and GitHub.
+ *
+ * A ghost is `critical`, an error. A stale citation is a warning and `minor`,
+ * and under `--strict`, where it fails the check, an error and `critical`. A
+ * file whose comments could not all be read is a notice on its first line.
+ */
+export function citesAnnotations(report) {
+    return [
+        ...report.findings.map((finding) => ({
+            rule: finding.rule,
+            identity: [finding.rule, finding.file, finding.family, finding.cited],
+            level: finding.severity === 'error' ? 'error' : 'warning',
+            severity: finding.severity === 'error' ? 'critical' : 'minor',
+            file: finding.file,
+            line: finding.line,
+            message: `${finding.message}. ${finding.hint}`,
+        })),
+        ...report.gaps.map((gap) => ({
+            rule: 'unread-comments',
+            identity: ['unread-comments', gap.file, gap.reason],
+            level: 'notice',
+            severity: 'info',
+            file: gap.file,
+            line: 1,
+            message: `${gap.file} ${gap.detail}, so a citation in it may have been missed`,
+        })),
+    ];
+}
 //# sourceMappingURL=reporter.js.map