@cplieger/deadset-ts 3.7.0 → 3.9.0

package/dist/src/report.js

@@ -0,0 +1,237 @@
+/**
+ * The report one analysis writes: the Contract's report document, member for member and
+ * in the order its schema lists them, built from what one run answered. Every reporter
+ * renders this document, so no two renderings disagree about which findings exist.
+ */
+/** The version of the report schema this analyzer writes a report to. */
+export const SCHEMA_VERSION = "6.0.0";
+/** The name this analyzer writes every document under and mints every identifier with. */
+export const ANALYZER_NAME = "deadset-ts";
+/** The language this analyzer claims. */
+export const LANGUAGE = "ts";
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+function wirePosition(position) {
+    return {
+        path: position.path,
+        line: position.line,
+        column: position.column,
+        end_line: position.endLine,
+    };
+}
+function wireSymbol(symbol) {
+    return { ref: symbol.ref, name: symbol.name, position: wirePosition(symbol.position) };
+}
+/** The details one code carries, in the order the finding schema lists them. */
+function wireDetails(details) {
+    const { entry } = details;
+    return {
+        ...(details.narrowerVisibility === undefined
+            ? {}
+            : { narrower_visibility: details.narrowerVisibility }),
+        ...(details.implementations === undefined
+            ? {}
+            : { implementations: details.implementations.map(wireSymbol) }),
+        ...(details.writePositions === undefined
+            ? {}
+            : { write_positions: details.writePositions.map(wirePosition) }),
+        ...(details.dependencyClass === undefined ? {} : { dependency_class: details.dependencyClass }),
+        ...(details.mechanism === undefined ? {} : { mechanism: details.mechanism }),
+        ...(entry === undefined
+            ? {}
+            : {
+                entry: {
+                    code: entry.code,
+                    ...(entry.symbol === undefined ? {} : { symbol: entry.symbol }),
+                    ...(entry.path === undefined ? {} : { path: entry.path }),
+                    ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+                },
+            }),
+    };
+}
+/** One finding as the finding schema spells it, member for member in its order. */
+export function wireFinding(finding) {
+    return {
+        code: finding.code,
+        kind: finding.kind,
+        language: finding.language,
+        position: wirePosition(finding.position),
+        symbol: {
+            ref: finding.symbol.ref,
+            kind: finding.symbol.kind,
+            name: finding.symbol.name,
+            size_lines: finding.symbol.sizeLines,
+        },
+        reachability_class: finding.reachabilityClass,
+        confidence: finding.confidence,
+        ...(finding.livenessRelation === undefined
+            ? {}
+            : { liveness_relation: finding.livenessRelation }),
+        test_only: finding.testOnly,
+        generated: finding.generated,
+        component: {
+            id: finding.component.id,
+            root: finding.component.root,
+            symbol_count: finding.component.symbolCount,
+            deletable_lines: finding.component.deletableLines,
+        },
+        retained_by: finding.retainedBy,
+        configurations: finding.configurations,
+        consumers_loaded: finding.consumersLoaded,
+        fixability: finding.fixability,
+        severity: finding.severity,
+        message: finding.message,
+        details: wireDetails(finding.details),
+    };
+}
+function wireEvaluation(evaluation) {
+    return {
+        edge: evaluation.edge,
+        side: evaluation.side,
+        symbol: evaluation.symbol,
+        state: evaluation.state,
+        ...(evaluation.finding === undefined ? {} : { finding: wireFinding(evaluation.finding) }),
+    };
+}
+function wireStale(stale) {
+    return {
+        code: stale.code,
+        mechanism: stale.mechanism,
+        entry: {
+            code: stale.entry.code,
+            ...(stale.entry.symbol === undefined ? {} : { symbol: stale.entry.symbol }),
+            path: stale.entry.path,
+            reason: stale.entry.reason,
+        },
+        position: {
+            path: stale.position.path,
+            line: stale.position.line,
+            column: stale.position.column,
+        },
+        symbol: stale.symbol,
+        message: stale.message,
+    };
+}
+/** The canonical key over two findings: path, line, column, code, then the symbol reference. */
+function canonical(a, b) {
+    return (compare(a.position.path, b.position.path) ||
+        a.position.line - b.position.line ||
+        a.position.column - b.position.column ||
+        compare(a.code, b.code) ||
+        compare(a.symbol.ref, b.symbol.ref));
+}
+/** The canonical key over two stale suppressions, each component from the record's own member. */
+function canonicalStale(a, b) {
+    return (compare(a.position.path, b.position.path) ||
+        a.position.line - b.position.line ||
+        a.position.column - b.position.column ||
+        compare(a.code, b.code) ||
+        compare(a.symbol, b.symbol));
+}
+/** Edge evaluations by edge, then side, then their compact encodings. */
+function byEdge(a, b) {
+    return (compare(a.edge, b.edge) ||
+        compare(a.side, b.side) ||
+        compare(JSON.stringify(a), JSON.stringify(b)));
+}
+/**
+ * The lines a reader deletes by acting on every finding: each distinct component a root
+ * finding names, counted once however many of its roots the findings hold.
+ */
+function deletableLines(findings) {
+    const counted = new Map();
+    for (const finding of findings) {
+        if (finding.component.root) {
+            counted.set(finding.component.id, finding.component.deletable_lines);
+        }
+    }
+    let total = 0;
+    for (const lines of counted.values()) {
+        total += lines;
+    }
+    return total;
+}
+/** The totals of one finding set, counted over the whole set. */
+function totalsOf(findings, result) {
+    const bySeverity = { allow: 0, warn: 0, deny: 0 };
+    for (const finding of findings) {
+        bySeverity[finding.severity] += 1;
+    }
+    return {
+        findings: findings.length,
+        by_severity: bySeverity,
+        deletable_lines: deletableLines(findings),
+        suppressions_in_effect: result.totals.suppressionsInEffect,
+        reasons_recorded: result.totals.reasonsRecorded,
+        stale_suppressions: result.staleSuppressions.length,
+        pending: result.totals.pending,
+        omitted: 0,
+    };
+}
+/** Builds the report of one run, every array in the order the Contract fixes for it. */
+export function buildReport(input) {
+    const findings = input.result.findings.map(wireFinding).sort(canonical);
+    const unavailable = [...new Map(input.unavailable.map((one) => [one.id, one])).values()]
+        .sort((a, b) => compare(a.id, b.id))
+        .map((one) => ({ id: one.id, role: "consumer", reason: one.reason }));
+    return {
+        schema_version: SCHEMA_VERSION,
+        contract_version: input.contractVersion,
+        analyzer: {
+            name: ANALYZER_NAME,
+            version: input.version,
+            languages: [LANGUAGE],
+            schema_versions_accepted: [SCHEMA_VERSION],
+            conformance: {
+                corpus_version: input.conformance.corpusVersion,
+                result: input.conformance.result,
+                digest: input.conformance.digest,
+            },
+        },
+        target: { kind: input.target.kind, root: input.target.root, identity: input.target.identity },
+        configurations: [...input.configurations]
+            .sort((a, b) => compare(a.id, b.id))
+            .map((one) => ({ id: one.id, project: one.project })),
+        configurations_not_built: [],
+        consumers: { declared: unavailable.length, loaded: [], unavailable },
+        findings,
+        edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
+        stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),
+        declared_gaps: [],
+        excluded_by_cgo: [],
+        test_file_rules: [...input.testFileRules]
+            .sort((a, b) => compare(a.rule, b.rule) || a.matched - b.matched)
+            .map((one) => ({ rule: one.rule, matched: one.matched })),
+        totals: totalsOf(findings, input.result),
+    };
+}
+/**
+ * The report with its findings in the order a configuration asks for. By size, a finding
+ * whose component a deletion shrinks more comes first, then one whose subject is larger,
+ * then the canonical key, so the order stays total; by position it is the canonical key.
+ */
+export function sortFindings(report, by) {
+    const bySize = (a, b) => b.component.deletable_lines - a.component.deletable_lines ||
+        b.symbol.size_lines - a.symbol.size_lines ||
+        canonical(a, b);
+    return { ...report, findings: [...report.findings].sort(by === "size" ? bySize : canonical) };
+}
+/**
+ * The report holding the first `most` findings of its order, the rest counted as omitted.
+ * Every other total keeps describing the whole set. Zero keeps every finding.
+ */
+export function capFindings(report, most) {
+    if (most <= 0 || report.findings.length <= most) {
+        return report;
+    }
+    return {
+        ...report,
+        findings: report.findings.slice(0, most),
+        totals: { ...report.totals, omitted: report.findings.length - most },
+    };
+}

package/dist/src/reporters/json.js

@@ -0,0 +1,4 @@
+/** The indentation of the report document, which with the schema's member order fixes its bytes. */
+const INDENT = 2;
+/** The report document itself: the report, indented, with a closing newline. */
+export const json = (report) => `${JSON.stringify(report, null, INDENT)}\n`;

package/dist/src/reporters/reporter.js

@@ -0,0 +1 @@
+export {};

package/dist/src/reporters/reporters.js

@@ -0,0 +1,10 @@
+import { json } from "./json.js";
+import { text } from "./text.js";
+/**
+ * Every format this analyzer renders, each by its reporter and its file suffix. A format
+ * absent from the table is refused rather than silently not written.
+ */
+export const RENDERINGS = new Map([
+    ["text", { render: text, suffix: ".txt" }],
+    ["json", { render: json, suffix: ".json" }],
+]);

package/dist/src/reporters/text.js

@@ -0,0 +1,34 @@
+/** The kind token and the confidence a stale suppression is rendered with, both fixed. */
+const STALE_KIND = "suppression";
+const STALE_CONFIDENCE = "certain";
+/** A count with the word for it, so the summary reads as a sentence. */
+function counted(n, one, many) {
+    return `${String(n)} ${n === 1 ? one : many}`;
+}
+/** The report's totals in one line, in the order the report declares them. */
+function summary(totals) {
+    const { allow, warn, deny } = totals.by_severity;
+    return [
+        `summary: ${counted(totals.findings, "finding", "findings")} (${String(allow)} allow, ${String(warn)} warn, ${String(deny)} deny)`,
+        counted(totals.deletable_lines, "deletable line", "deletable lines"),
+        counted(totals.suppressions_in_effect, "suppression in effect", "suppressions in effect"),
+        counted(totals.reasons_recorded, "reason recorded", "reasons recorded"),
+        counted(totals.stale_suppressions, "stale suppression", "stale suppressions"),
+        `${String(totals.pending)} pending`,
+        `${String(totals.omitted)} omitted`,
+    ].join(", ");
+}
+/**
+ * One line per finding in the report's order, then one per stale suppression, then the
+ * summary. A finding line is `path:line:col: kind name: message [confidence] (CODE)`; the
+ * summary is deliberately not in that shape, so a filter for finding lines yields exactly
+ * them. Nothing else is written: no timestamp, duration or host detail.
+ */
+export const text = (report) => {
+    const lines = report.findings.map((found) => `${found.position.path}:${String(found.position.line)}:${String(found.position.column)}: ${found.symbol.kind} ${found.symbol.name}: ${found.message} [${found.confidence}] (${found.code})`);
+    for (const stale of report.stale_suppressions) {
+        lines.push(`${stale.position.path}:${String(stale.position.line)}:${String(stale.position.column)}: ${STALE_KIND} ${stale.symbol}: ${stale.message} [${STALE_CONFIDENCE}] (${stale.code})`);
+    }
+    lines.push(summary(report.totals));
+    return `${lines.join("\n")}\n`;
+};

package/dist/src/roots.js

@@ -9,18 +9,11 @@
  * candidate under reference counting.
  */
 import { aliasChains } from "./alias-chain.js";
-import { REPOSITORY_DOCUMENT } from "./config.js";
 import { entryPoints } from "./entry-points.js";
 import { globExpression } from "./glob.js";
 import { nodeKey } from "./inventory.js";
 import { byPosition } from "./position.js";
 import { sourceFilesOf } from "./source-files.js";
-/** The code the Contract gives a configured root that matches nothing. */
-const UNMATCHED_ROOT_CODE = "DS1704";
-/** The subject kind a finding under that code carries, from the Contract's vocabulary. */
-const UNMATCHED_ROOT_SUBJECT = "root";
-/** The fixed position of a finding about a document rather than about a line of one. */
-const DOCUMENT_POSITION = 1;
 /** Whether a configured string carries either special character. */
 function isPattern(text) {
     return text.includes("*") || text.includes("?");
@@ -293,30 +286,3 @@ function configured(held, patterns, add) {
 export function unmatchedEverywhere(patterns, perProject) {
     return [...new Set(patterns)].filter((pattern) => perProject.every((project) => project.unmatched.includes(pattern)));
 }
-/**
- * The findings a run reports for the configured strings that named nothing.
- *
- * `document` is the path of the document that declared the roots, below the target
- * root; where the run read them from no document of the target it is empty and the
- * finding names the conventional repository configuration, which is the document a
- * maintainer writes a configured root in. Every finding of one run sits at that
- * document's first position: the roots are written as an array whose members carry
- * no line of their own, so the string each finding names is what tells one from
- * another.
- */
-export function unmatchedRoots(sources, document) {
-    const position = {
-        path: document === "" ? REPOSITORY_DOCUMENT : document,
-        line: DOCUMENT_POSITION,
-        column: DOCUMENT_POSITION,
-        endLine: DOCUMENT_POSITION,
-    };
-    return sources.map((source) => ({
-        code: UNMATCHED_ROOT_CODE,
-        position,
-        symbol: { ref: source, kind: UNMATCHED_ROOT_SUBJECT, name: source, sizeLines: 1 },
-        message: isPattern(source)
-            ? "configured root pattern matches no symbol of the inventory"
-            : "configured root matches no symbol of the inventory",
-    }));
-}

package/dist/src/run.js

@@ -8,6 +8,8 @@ import { printConfigVerb } from "./verbs/print-config.js";
 import { printProjectsVerb } from "./verbs/print-projects.js";
 import { printRetainedVerb } from "./verbs/print-retained.js";
 import { printRootsVerb } from "./verbs/print-roots.js";
+import { ANALYZE_OPTIONS, analyzeVerb } from "./verbs/analyze.js";
+import { describeVerb } from "./verbs/describe.js";
 import { EXIT_FAILURE, EXIT_USAGE } from "./verbs/verb.js";
 import { versionVerb } from "./verbs/version.js";
 /**
@@ -15,13 +17,13 @@ import { versionVerb } from "./verbs/version.js";
  * with no `run` is listed, and invoking it is a usage error.
  */
 const VERBS = [
-    { name: "analyze" },
+    { name: "analyze", run: analyzeVerb, options: ANALYZE_OPTIONS },
     { name: "explain" },
     { name: "print-config", run: printConfigVerb },
     { name: "print-projects", run: printProjectsVerb },
     { name: "print-roots", run: printRootsVerb },
     { name: "print-retained", run: printRetainedVerb },
-    { name: "describe" },
+    { name: "describe", run: describeVerb },
     { name: "version", run: versionVerb },
 ];
 const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.map((verb) => verb.name).join(", ")}\n`;
@@ -55,6 +57,8 @@ const PLAIN_OPTIONS = new Set(["target", "config", "central", "scope"]);
 const INTEGER_OPTIONS = new Set(["max-findings"]);
 /** An integer as an option writes it: an optional minus sign and digits alone. */
 const INTEGER_TEXT = /^-?[0-9]+$/u;
+/** No option beyond the ones every verb takes. */
+const NO_OPTIONS = { plain: [], repeatable: [] };
 /**
  * The first option whose name carries a source-edit token, because every verb
  * reports and never edits. The match is on the name alone, so an option whose
@@ -73,24 +77,30 @@ function sourceEditOption(args) {
     }
     return undefined;
 }
-/** Reads one verb's options, refusing a name this command does not offer. */
-function readOptions(args) {
+/** Reads one verb's options, refusing a name neither this command nor the verb offers. */
+function readOptions(args, own) {
     const named = new Map();
+    const repeated = new Map();
     for (const arg of args) {
         if (!arg.startsWith("-")) {
             throw new ConfigError("malformed", "", `unexpected argument ${JSON.stringify(arg)}`);
         }
         const [spelled, ...rest] = arg.split("=");
         const name = (spelled ?? "").replace(/^-+/u, "");
-        if (!PLAIN_OPTIONS.has(name) && !SETTING_OPTIONS.has(name)) {
+        if (!PLAIN_OPTIONS.has(name) &&
+            !SETTING_OPTIONS.has(name) &&
+            !own.plain.includes(name) &&
+            !own.repeatable.includes(name)) {
             throw new ConfigError("malformed", "", `unknown option ${JSON.stringify(spelled ?? arg)}`);
         }
         if (rest.length === 0) {
             throw new ConfigError("malformed", "", `option ${JSON.stringify(spelled ?? arg)} takes a value`);
         }
-        named.set(name, rest.join("="));
+        const value = rest.join("=");
+        named.set(name, value);
+        repeated.set(name, [...(repeated.get(name) ?? []), value]);
     }
-    return { named };
+    return { named, repeated };
 }
 function readFileOr(host, path, orUndefined) {
     try {
@@ -160,7 +170,7 @@ export function run(args, out, err, host, openClient = (collectTiming) => openEn
     const name = args[0];
     const verb = VERBS.find((listed) => listed.name === name);
     if (verb?.run !== undefined) {
-        return invoke(verb.run, args.slice(1), { out, err, host }, openClient);
+        return invoke(verb.run, verb.options ?? NO_OPTIONS, args.slice(1), { out, err, host }, openClient);
     }
     if (verb !== undefined) {
         err.write(`deadset-ts: ${verb.name} is not implemented\n`);
@@ -177,15 +187,18 @@ export function run(args, out, err, host, openClient = (collectTiming) => openEn
  * time the verb asks for what they name, and a refusal the verb throws is written
  * and turned into its exit code once the client the verb opened is closed.
  */
-function invoke(verb, args, streams, openClient) {
+function invoke(verb, own, args, streams, openClient) {
     let options;
-    const read = () => (options ??= readOptions(args));
+    const read = () => (options ??= readOptions(args, own));
     let opened;
     try {
         return verb({
             ...streams,
+            args,
             inputs: () => inputsOf(streams.host, read()),
             scope: () => scopeOf(streams.host, read()),
+            option: (name) => read().named.get(name),
+            repeated: (name) => read().repeated.get(name) ?? [],
             openClient: (collectTiming) => {
                 opened = openClient(collectTiming);
                 return opened;

package/dist/src/suppress-file.js

@@ -0,0 +1,196 @@
+/**
+ * The two file-backed suppression documents at the target root: the ignore file, whose
+ * entries a maintainer writes, and the baseline, whose rows an analyzer writes. They share
+ * one record shape, so one decoder and one matcher serve both, and a row moves into the
+ * ignore file by gaining a maintainer's reason.
+ */
+import { joinPath } from "./paths.js";
+import { positionAt, walkDocument } from "./json-document.js";
+import { CODE_FORM, SUPPRESSION_WITHOUT_REASON, SuppressionError, UNSCOPED_ENTRY, blankReason, isEntryPath, isSymbolRef, siteText, } from "./suppress.js";
+/** The name and the location the grammar fixes for the ignore file. */
+export const IGNORE_FILE = "deadset-ignore.json";
+/** The name and the location the grammar fixes for the baseline. */
+export const BASELINE_FILE = "deadset-baseline.json";
+const IGNORE_SHAPE = {
+    file: IGNORE_FILE,
+    array: "ignore",
+    mechanism: "ignore",
+    documentWant: "an object carrying the ignore array, and an optional description",
+    recordWant: "an entry naming code, symbol, path and reason, each a string",
+};
+const BASELINE_SHAPE = {
+    file: BASELINE_FILE,
+    array: "baseline",
+    mechanism: "baseline",
+    documentWant: "an object carrying the baseline array, and an optional description",
+    recordWant: "a row naming code, symbol, path and reason, each a string",
+};
+/** The closed key list of one entry or row. */
+const RECORD_KEYS = new Set(["code", "symbol", "path", "reason"]);
+const CODE_WANT = "DS followed by four digits";
+const SYMBOL_WANT = "a stable symbol reference, go://<import-path>#<fragment> or ts://<package>/<source-path>#<fragment>";
+const PATH_WANT = "a path relative to the target root, with the solidus as separator";
+/** The document itself, for a defect no record position describes. */
+function documentSite(shape) {
+    return { path: shape.file, line: 0, column: 0 };
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function referenceKey(ref, path) {
+    return `${ref}\u0000${path}`;
+}
+/**
+ * Reads one entry or row: the records it binds, the refusals it carries, or the
+ * malformed value that ends the run.
+ */
+function readRecord(value, site, byReference, shape) {
+    const refuse = (text, want) => {
+        throw new SuppressionError(shape.mechanism, `${shape.file} ${siteText(site)}`, text, want);
+    };
+    if (!isObject(value)) {
+        return refuse(JSON.stringify(value), shape.recordWant);
+    }
+    for (const [key, held] of Object.entries(value)) {
+        if (!RECORD_KEYS.has(key)) {
+            refuse(`the member ${JSON.stringify(key)} is not one the grammar declares`, shape.recordWant);
+        }
+        if (typeof held !== "string") {
+            refuse(`the member ${JSON.stringify(key)} holds ${JSON.stringify(held)}`, shape.recordWant);
+        }
+    }
+    const entry = value;
+    const { code, symbol, path, reason } = {
+        code: entry["code"],
+        symbol: entry["symbol"],
+        path: entry["path"],
+        reason: entry["reason"],
+    };
+    if (code === undefined) {
+        return refuse("a record naming no code", shape.recordWant);
+    }
+    if (symbol === undefined) {
+        return refuse("a record naming no symbol", shape.recordWant);
+    }
+    if (!CODE_FORM.test(code)) {
+        return refuse(JSON.stringify(code), CODE_WANT);
+    }
+    if (!isSymbolRef(symbol)) {
+        return refuse(JSON.stringify(symbol), SYMBOL_WANT);
+    }
+    if (path !== undefined && path !== "" && !isEntryPath(path)) {
+        return refuse(JSON.stringify(path), PATH_WANT);
+    }
+    const written = {
+        code,
+        symbol,
+        path: path ?? "",
+        reason: reason ?? "",
+        site,
+        mechanism: shape.mechanism,
+    };
+    const refusals = [];
+    if (blankReason(reason)) {
+        refusals.push({ ...written, reported: SUPPRESSION_WITHOUT_REASON });
+    }
+    if (written.path === "") {
+        refusals.push({ ...written, reported: UNSCOPED_ENTRY });
+    }
+    if (refusals.length > 0) {
+        return { records: [], refusals };
+    }
+    const named = byReference.get(referenceKey(symbol, written.path)) ?? [];
+    if (named.length === 0) {
+        return { records: [{ ...written, bound: "" }], refusals: [] };
+    }
+    return { records: named.map((one) => ({ ...written, bound: one.id })), refusals: [] };
+}
+/** Reads one document at the target root, binding each record against the run's declarations. */
+function readDocument(host, targetRoot, symbols, shape) {
+    const file = joinPath(targetRoot, shape.file);
+    if (host.kindOf(file) === "absent") {
+        return { records: [], refusals: [] };
+    }
+    const text = host.readFile(file);
+    const malformed = (detail, site = documentSite(shape)) => {
+        throw new SuppressionError(shape.mechanism, siteText(site), detail, shape.documentWant);
+    };
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return malformed(`${shape.file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isObject(parsed)) {
+        return malformed(shape.file);
+    }
+    const walk = walkDocument(text, shape.array);
+    if (walk.twice !== undefined) {
+        malformed(`the member ${JSON.stringify(walk.twice.name)} is written twice, so neither value is chosen`, positionAt(text, shape.file, walk.twice.offset));
+    }
+    for (const key of Object.keys(parsed)) {
+        if (key !== "description" && key !== shape.array) {
+            malformed(`the member ${JSON.stringify(key)} is not one the grammar declares`);
+        }
+    }
+    const description = parsed["description"];
+    const held = parsed[shape.array];
+    if ((description !== undefined && typeof description !== "string") || !Array.isArray(held)) {
+        return malformed(shape.file);
+    }
+    const byReference = new Map();
+    for (const symbol of symbols) {
+        const key = referenceKey(symbol.ref, symbol.position.path);
+        byReference.set(key, [...(byReference.get(key) ?? []), symbol]);
+    }
+    const records = [];
+    const refusals = [];
+    held.forEach((value, index) => {
+        const offset = walk.opened[index];
+        const site = offset === undefined ? documentSite(shape) : positionAt(text, shape.file, offset);
+        const read = readRecord(value, site, byReference, shape);
+        records.push(...read.records);
+        refusals.push(...read.refusals);
+    });
+    return { records, refusals };
+}
+/**
+ * The ignore file at the target root, each entry bound to the declaration whose reference
+ * and file both equal the ones it names, and never by glob, pattern or substring. An
+ * absent file is an empty one.
+ */
+export function readIgnoreFile(host, targetRoot, symbols) {
+    return readDocument(host, targetRoot, symbols, IGNORE_SHAPE);
+}
+/**
+ * The baseline at the target root, each row matched exactly as an ignore entry is. A row's
+ * reason is the provenance an analyzer wrote, never a maintainer's judgement: the finding
+ * it records is real, and the row says only that it was there when the baseline was
+ * written. An absent file is an empty one.
+ */
+export function readBaseline(host, targetRoot, symbols) {
+    return readDocument(host, targetRoot, symbols, BASELINE_SHAPE);
+}
+/** What a written document says about itself, so the same report writes the same bytes. */
+const BASELINE_DESCRIPTION = "Recorded findings: a run fails only on a finding this document does not hold. " +
+    "Every reason is the analyzer that recorded the row, never an adjudication.";
+/**
+ * A baseline holding one row per finding, in the order given, which is the report's. Every
+ * row carries the provenance as its reason. A finding missing a value a row needs, and an
+ * identity missing its name or version, are refused rather than written, because the
+ * grammar requires a reason on every row.
+ */
+export function writeBaseline(findings, provenance) {
+    if (provenance.analyzer === "" || provenance.version === "") {
+        throw new Error(`a baseline row would carry no reason: the analyzer identity names ${JSON.stringify(provenance.analyzer)} at version ${JSON.stringify(provenance.version)}`);
+    }
+    const reason = `recorded by ${provenance.analyzer} ${provenance.version}`;
+    const baseline = findings.map((found) => {
+        if (found.code === "" || found.symbol === "" || found.path === "") {
+            throw new Error(`a baseline row would carry no reason: a finding names code ${JSON.stringify(found.code)}, symbol ${JSON.stringify(found.symbol)} and path ${JSON.stringify(found.path)}`);
+        }
+        return { code: found.code, symbol: found.symbol, path: found.path, reason };
+    });
+    return `${JSON.stringify({ description: BASELINE_DESCRIPTION, baseline }, null, 2)}\n`;
+}