@cplieger/deadset-ts 3.7.0 → 3.8.0

package/dist/src/findings/visibility-narrowing.js

@@ -164,49 +164,29 @@ function unreachable(facts, at, symbol, candidate, input) {
         : "has no reference in the target";
     return findingOf(symbol, UNREACHABLE_EXPORT, `exported ${wordOf(symbol)} ${found}, and nothing outside can import the file that declares it`);
 }
-/** Two strings ordered bytewise. */
-function compare(a, b) {
-    if (a === b) {
-        return 0;
-    }
-    return a < b ? -1 : 1;
-}
 /**
- * The visibility-narrowing family over one run: `DS1101`, `DS1103` and `DS1104`.
- *
- * A finding about a symbol a declared cross-language edge names is pending instead of
- * reported, once per side naming it: the edge counts as a reference from outside the
- * file and the package, and whether it is a use is decided on the side in the other
- * language.
+ * The visibility-narrowing family over one run: `DS1101`, `DS1103` and `DS1104`. A finding
+ * about a symbol a declared cross-language edge names is reported here like any other, and
+ * the edge's evaluation then holds it pending, because the edge stands for a reference from
+ * outside the file and the package whose use is decided in the other language.
  */
 export function narrowings(input) {
-    const { boundary } = input;
     const facts = factsOf(input.swept.matrix.union);
-    const { declared, loaded } = boundary.consumers;
+    const { declared, loaded } = input.boundary.consumers;
     const closed = input.config.consumersComplete && declared.every((id) => loaded.includes(id));
     const world = { closed, writeOnly: writeOnlyDeclarations(input) };
     const candidates = new Map(input.swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
     const findings = [];
-    const pending = [];
     facts.graph.symbols.forEach((symbol, at) => {
         const candidate = candidates.get(symbol.id);
         const found = candidate === undefined
             ? narrowing(facts, at, symbol, world)
             : unreachable(facts, at, symbol, candidate, input);
-        if (found === undefined) {
-            return;
-        }
-        const named = boundary.edges.filter((side) => side.symbol === symbol.ref);
-        if (named.length === 0) {
+        if (found !== undefined) {
             findings.push(found);
-            return;
-        }
-        for (const side of named) {
-            pending.push({ ...side, finding: found });
         }
     });
-    pending.sort((a, b) => compare(a.edge, b.edge) || compare(a.side, b.side));
-    return { findings, pending };
+    return findings;
 }
 /**
  * The declarations the unreachable-export kind reports, whether or not a declared edge
@@ -224,16 +204,5 @@ export function unreachableExports(input) {
     }
     return found;
 }
-/**
- * The findings of the visibility-narrowing family, `DS1100` to `DS1199`. A finding a
- * declared edge holds pending belongs in that edge's evaluation, which this analyzer
- * does not publish yet, so a run that holds one is refused rather than reported
- * without it.
- */
-export const visibilityNarrowing = (input) => {
-    const { findings, pending } = narrowings(input);
-    if (pending.length > 0) {
-        throw new Error(`${String(pending.length)} finding(s) a declared edge holds pending, and no edge evaluation is published`);
-    }
-    return findings;
-};
+/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
+export const visibilityNarrowing = narrowings;

package/dist/src/findings-pass.js

@@ -0,0 +1,97 @@
+/**
+ * The findings pass over one run: the emitter table's findings with the suppressions
+ * applied and the declared edges evaluated, and the stale suppressions, the totals and the
+ * verdict a report carries beside them.
+ */
+import { decidedFindings } from "./findings/emitters.js";
+import { fileRefsOf, staleSuppressions, } from "./findings/self-check.js";
+import { isRowSubject, pairs, suppressionCounts } from "./suppress.js";
+import { EXIT_CLEAN, EXIT_FINDINGS } from "./verbs/verb.js";
+/** The exit code of a report holding at least one pending finding. */
+export const EXIT_PENDING = 4;
+/** The severities ranked, the strongest highest. */
+const SEVERITY_RANK = { allow: 0, warn: 1, deny: 2 };
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/** The canonical order: 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 pass over one run. The emitter table decides every record against every finding the
+ * run would produce with no record there, withholds what the records claim, and evaluates
+ * the declared edges; a stale record then names the codes its declaration reports instead.
+ */
+export function findingsPass(inputs) {
+    const { marked, unmarked, suppressions } = inputs;
+    const decided = decidedFindings(marked, { unmarked, records: suppressions.records });
+    const { ledger, would } = decided;
+    const stale = [];
+    suppressions.records.forEach((record, at) => {
+        if (ledger.verdicts[at] !== "stale") {
+            return;
+        }
+        const reports = would
+            .filter((finding) => finding.code !== record.code && pairs({ ...record, code: finding.code }, finding))
+            .map((finding) => finding.code);
+        stale.push({ record, reports });
+    });
+    const records = staleSuppressions(stale, fileRefsOf(marked.swept.matrix.union.symbols));
+    const counts = suppressionCounts(suppressions.records, ledger);
+    return {
+        findings: [...decided.findings].sort(canonical),
+        staleSuppressions: records,
+        edgeEvaluations: decided.evaluations,
+        totals: {
+            suppressionsInEffect: counts.inEffect,
+            reasonsRecorded: counts.reasonsRecorded,
+            staleSuppressions: records.length,
+            pending: decided.evaluations.filter((one) => one.finding !== undefined).length,
+        },
+        ledger,
+    };
+}
+/**
+ * The exit code of a report the pass answered: pending when an evaluation holds a finding,
+ * which outranks the rest because an unmerged report is not an answer; findings when a
+ * suppression is stale or a finding's severity reaches the configured failing severity;
+ * clean otherwise.
+ */
+export function verdictOf(result, config) {
+    if (result.totals.pending > 0) {
+        return EXIT_PENDING;
+    }
+    if (result.totals.staleSuppressions > 0) {
+        return EXIT_FINDINGS;
+    }
+    const failing = SEVERITY_RANK[config.reporters.failOn];
+    const fails = result.findings.some((finding) => SEVERITY_RANK[finding.severity] >= failing);
+    return fails ? EXIT_FINDINGS : EXIT_CLEAN;
+}
+/**
+ * The findings of a report as a baseline records them, in report order. A finding about a
+ * row of a document is not recorded: no record withholds one, so a row recording it would
+ * be stale on the first read back.
+ */
+export function recordedFindings(result) {
+    return result.findings
+        .filter((finding) => !isRowSubject(finding.symbol.kind))
+        .map((finding) => ({
+        code: finding.code,
+        symbol: finding.symbol.ref,
+        path: finding.position.path,
+    }));
+}
+/** The analyzer identity a baseline this analyzer writes names as its rows' provenance. */
+export function analyzerProvenance(version) {
+    return { analyzer: "deadset-ts", version };
+}

package/dist/src/json-document.js

@@ -0,0 +1,113 @@
+/**
+ * A read of a strict JSON document beside its parse: what a parse into a value cannot
+ * report, the offset of each record of one array and a member written twice.
+ */
+/** The token walk over a document `JSON.parse` accepted, so every token is well formed. */
+class Walk {
+    opened = [];
+    /** The member written twice, where one is, as the offset of its name. */
+    twice;
+    text;
+    array;
+    at = 0;
+    constructor(text, array) {
+        this.text = text;
+        this.array = array;
+    }
+    run() {
+        this.value("document");
+    }
+    skip() {
+        while (/[ \t\r\n]/u.test(this.text[this.at] ?? "")) {
+            this.at += 1;
+        }
+    }
+    string() {
+        const start = this.at;
+        this.at += 1;
+        while (this.text[this.at] !== '"') {
+            this.at += this.text[this.at] === "\\" ? 2 : 1;
+        }
+        this.at += 1;
+        return JSON.parse(this.text.slice(start, this.at));
+    }
+    value(role) {
+        this.skip();
+        const char = this.text[this.at];
+        if (char === "{") {
+            if (role === "record") {
+                this.opened.push(this.at);
+            }
+            this.object(role);
+        }
+        else if (char === "[") {
+            this.list(role === "array" ? "record" : "other");
+        }
+        else if (char === '"') {
+            this.string();
+        }
+        else {
+            while (this.at < this.text.length && !/[,\]} \t\r\n]/u.test(this.text[this.at] ?? "")) {
+                this.at += 1;
+            }
+        }
+    }
+    object(role) {
+        const seen = new Set();
+        this.at += 1;
+        for (;;) {
+            this.skip();
+            if (this.text[this.at] === "}") {
+                this.at += 1;
+                return;
+            }
+            if (this.text[this.at] === ",") {
+                this.at += 1;
+                this.skip();
+            }
+            const offset = this.at;
+            const name = this.string();
+            if (seen.has(name) && this.twice === undefined) {
+                this.twice = { name, offset };
+            }
+            seen.add(name);
+            this.skip();
+            this.at += 1;
+            this.value(role === "document" && name === this.array ? "array" : "other");
+        }
+    }
+    list(element) {
+        this.at += 1;
+        for (;;) {
+            this.skip();
+            if (this.text[this.at] === "]") {
+                this.at += 1;
+                return;
+            }
+            if (this.text[this.at] === ",") {
+                this.at += 1;
+            }
+            this.value(element);
+        }
+    }
+}
+/**
+ * Walks a document `JSON.parse` accepted, whose top-level member `array` holds the
+ * records. A member one object writes twice reads as though it were written once, its
+ * later value silently replacing the earlier one, so a document holding one is one a
+ * reader names rather than reads.
+ */
+export function walkDocument(text, array) {
+    const walk = new Walk(text, array);
+    walk.run();
+    return { opened: walk.opened, twice: walk.twice };
+}
+/**
+ * One offset of a document as a finding carries it: the line counted from one, and the
+ * column counted from one in UTF-16 code units.
+ */
+export function positionAt(text, file, offset) {
+    const before = text.slice(0, offset);
+    const lineStart = before.lastIndexOf("\n") + 1;
+    return { path: file, line: before.split("\n").length, column: offset - lineStart + 1 };
+}

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/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`;
+}