@cplieger/deadset-ts 3.7.0 → 3.9.0

package/dist/src/findings/emitters.js

@@ -1,5 +1,7 @@
+import { evaluateEdges } from "../edges.js";
+import { ledgerOf } from "../suppress.js";
+import { completed, dialsOf, reportable } from "./completion.js";
 import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.js";
-import { completed, reportable } from "./completion.js";
 import { interfaces } from "./interfaces.js";
 import { intraFunction } from "./intra-function.js";
 import { nonCodeArtifacts } from "./non-code-artifacts.js";
@@ -18,12 +20,46 @@ export const EMITTERS = new Map([
     ["self-check", selfCheck],
     ["intra-function", intraFunction],
 ]);
+/** Every family's findings over one sweep, completed by one step. */
+function completedOver(input) {
+    return completed(input, [...EMITTERS.values()].flatMap((emit) => emit(input)));
+}
 /**
- * Every finding of the run the dials do not withhold, each family's in table order: every
- * family's findings completed by one step, then withheld by one step, so a root one
- * family reports withholds what another family reports in its component.
+ * The dials over the findings a record could name, each read against the sweep that
+ * produced it, so a component one sweep numbers withholds nothing of the other's.
  */
+function dialsOver(input, found, suppressed, unmarked) {
+    const marked = dialsOf(input, found);
+    const before = dialsOf(suppressed.unmarked, unmarked);
+    const fromUnmarked = new Set(unmarked);
+    return {
+        withholdsCode: marked.withholdsCode,
+        withholds: (finding) => fromUnmarked.has(finding) ? before.withholds(finding) : marked.withholds(finding),
+    };
+}
+/**
+ * Every finding of one run swept under its suppressions' marks, decided in one pass: every
+ * family's findings completed by one step, so every component number is minted once, a
+ * pending finding's among them; the finding each record claims withheld, whatever its
+ * kind; the rest withheld by the dials, so a root one family reports withholds what
+ * another family reports in its component; and every declared edge evaluated over what
+ * remains, so a finding it holds pending is in its evaluation and nowhere else.
+ */
+export function decidedFindings(input, suppressed = { unmarked: input, records: [] }) {
+    const found = completedOver(input);
+    const unmarked = suppressed.records.length === 0 ? [] : completedOver(suppressed.unmarked);
+    const would = [...unmarked, ...found];
+    const ledger = ledgerOf(suppressed.records, would, dialsOver(input, found, suppressed, unmarked));
+    const kept = reportable(input, found.filter((finding) => !ledger.withheld(finding)));
+    const evaluated = evaluateEdges(kept, input.boundary.edges, input.swept.matrix.union.symbols);
+    return {
+        findings: evaluated.findings,
+        evaluations: evaluated.evaluations,
+        ledger,
+        would,
+    };
+}
+/** Every finding the run reports, each family's in table order. */
 export function findingsOf(input) {
-    const found = [...EMITTERS.values()].flatMap((emit) => emit(input));
-    return reportable(completed(input, found), input.config.analysis.minConfidence);
+    return decidedFindings(input).findings;
 }

package/dist/src/findings/self-check.js

@@ -1,2 +1,139 @@
-/** The findings of the self-check family, `DS1700` to `DS1799`. */
-export const selfCheck = () => [];
+import { REPOSITORY_DOCUMENT } from "../config.js";
+import { STALE_SUPPRESSION, SUPPRESSION_WITHOUT_REASON, } from "../suppress.js";
+/** The code a configured root that matches nothing is reported under. */
+const UNMATCHED_ROOT = "DS1704";
+/** The subject kind of a finding about a suppression record. */
+const SUPPRESSION_SUBJECT = "suppression";
+/** The subject kind of a finding about a configured root. */
+const ROOT_SUBJECT = "root";
+/** The fixed position of a finding about a document rather than about a line of one. */
+const DOCUMENT_POSITION = 1;
+/** A run with nothing for the self-check family to report. */
+export const NO_SELF_CHECK = {
+    refusals: [],
+    unmatchedRoots: [],
+    rootsDocument: "",
+};
+/** The words a message names a mechanism by. */
+const WRITTEN = {
+    inline: "inline directive",
+    ignore: "ignore entry",
+    baseline: "baseline row",
+};
+/** The file references of a run's declarations, by path. */
+export function fileRefsOf(symbols) {
+    const byPath = new Map(symbols
+        .filter((symbol) => symbol.kind === "file")
+        .map((symbol) => [symbol.position.path, symbol.ref]));
+    return (path) => byPath.get(path);
+}
+/** A list of codes as a sentence names them. */
+function spelled(codes) {
+    if (codes.length < 2) {
+        return codes.join("");
+    }
+    return `${codes.slice(0, -1).join(", ")} and ${codes.at(-1) ?? ""}`;
+}
+/** A finding about one suppression, at the suppression's own site. */
+function aboutSuppression(code, ref, site, message, details) {
+    return {
+        code,
+        position: { ...site, endLine: site.line },
+        symbol: { ref, kind: SUPPRESSION_SUBJECT, name: ref, sizeLines: 1 },
+        message,
+        details,
+    };
+}
+/** Whether a reason holds a character other than whitespace. */
+const STATED = /[^ \t\r\n]/u;
+/** A refused suppression as written: a member it lacks is absent. */
+function writtenEntry(refused) {
+    return {
+        code: refused.code,
+        ...(refused.symbol === "" ? {} : { symbol: refused.symbol }),
+        ...(refused.path === "" ? {} : { path: refused.path }),
+        ...(STATED.test(refused.reason) ? { reason: refused.reason } : {}),
+    };
+}
+/**
+ * The reference a finding about a suppression names: the symbol it names or bound, else
+ * the file form of the document that holds it, else that document's path.
+ */
+function suppressionRef(symbol, path, files) {
+    return symbol === "" ? (files(path) ?? path) : symbol;
+}
+/** One finding per refused suppression: the grammar's reason refusal and its scope refusal. */
+export function refusedSuppressions(refusals, files) {
+    return refusals.map((refused) => aboutSuppression(refused.reported, suppressionRef(refused.symbol, refused.path, files), refused.site, `${WRITTEN[refused.mechanism]} for ${refused.code} ${refused.reported === SUPPRESSION_WITHOUT_REASON
+        ? "carries no reason"
+        : "names a symbol and no path"}`, { mechanism: refused.mechanism, entry: writtenEntry(refused) }));
+}
+/**
+ * One record per site at which a suppression matched nothing, whatever the number of
+ * codes or declarations written there: the first record names the entry, and the message
+ * names every code the site's records named and every code the declaration reports
+ * instead, so the maintainer corrects the code rather than hunting for it.
+ */
+export function staleSuppressions(stale, files) {
+    const bySite = new Map();
+    for (const one of stale) {
+        const { site, mechanism } = one.record;
+        const key = `${mechanism}\u0000${site.path}\u0000${String(site.line)}\u0000${String(site.column)}`;
+        const held = bySite.get(key) ?? { first: one.record, records: [] };
+        held.records.push(one);
+        bySite.set(key, held);
+    }
+    return [...bySite.values()].map(({ first, records }) => {
+        const codes = [...new Set(records.map((one) => one.record.code))].sort();
+        const reports = [...new Set(records.flatMap((one) => one.reports))]
+            .filter((code) => !codes.includes(code))
+            .sort();
+        const instead = reports.length === 0 ? "" : `, and its declaration reports ${spelled(reports)}`;
+        return {
+            code: STALE_SUPPRESSION,
+            mechanism: first.mechanism,
+            entry: {
+                code: first.code,
+                ...(first.symbol === "" ? {} : { symbol: first.symbol }),
+                path: first.path,
+                reason: first.reason,
+            },
+            position: first.site,
+            symbol: suppressionRef(first.symbol, first.path, files),
+            message: `${WRITTEN[first.mechanism]} for ${spelled(codes)} matches no current finding${instead}`,
+        };
+    });
+}
+/**
+ * One finding per configured root or pattern that named nothing in any project. A finding
+ * names the document that declared the roots, or the conventional repository configuration
+ * where no document of the target did, and every finding of one run sits at that
+ * document's first position: the roots are an array whose members carry no line of their
+ * own, so the string each finding names tells one from another.
+ */
+export function unmatchedRootFindings(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,
+        position,
+        symbol: { ref: source, kind: ROOT_SUBJECT, name: source, sizeLines: 1 },
+        message: source.includes("*") || source.includes("?")
+            ? "configured root pattern matches no symbol of the inventory"
+            : "configured root matches no symbol of the inventory",
+    }));
+}
+/**
+ * The findings of the self-check family, `DS1700` to `DS1799`: a suppression refused for
+ * carrying no reason or naming no path, and a configured root that named nothing. A
+ * suppression that matched nothing is a record of the report's stale suppressions, which
+ * {@link staleSuppressions} builds, and a stale cross-language edge is the merge's to report.
+ */
+export const selfCheck = ({ selfCheck: facts, swept }) => [
+    ...refusedSuppressions(facts.refusals, fileRefsOf(swept.matrix.union.symbols)),
+    ...unmatchedRootFindings(facts.unmatchedRoots, facts.rootsDocument),
+];

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/references.js

@@ -272,6 +272,22 @@ function sitesOf(file, declarations, fileId) {
 function patternRule(index) {
     return `test-file-pattern-${String(index + 1)}`;
 }
+/**
+ * The rules over the test files of several projects at once, ordered by rule: a file two
+ * projects hold is one file, so each rule counts the distinct paths it matches.
+ */
+export function testFileRulesOf(testFiles, paths) {
+    const distinct = [...new Set(paths)];
+    return testFiles
+        .map((pattern, index) => {
+        const expression = globExpression(pattern);
+        return {
+            rule: patternRule(index),
+            matched: distinct.filter((path) => expression.test(path)).length,
+        };
+    })
+        .sort((a, b) => compare(a.rule, b.rule));
+}
 /** Two strings ordered bytewise, which is the order every set of a run is read in. */
 function compare(a, b) {
     if (a === b) {
@@ -281,7 +297,7 @@ function compare(a, b) {
 }
 /**
  * Every reference one project's own files make to the project's own declarations, in
- * position order, and the test-file rules that classified those files.
+ * position order, and the files the test-file rules classified.
  *
  * `held` is the inventory of the same project, whose declaration map is what a resolved
  * symbol is looked up in; `targetRoot` is the absolute path every position is rendered
@@ -297,7 +313,6 @@ export function references(project, held, targetRoot, options) {
     const cap = options.batchCap ?? DEFAULT_BATCH_CAP;
     const declarations = held.declarations;
     const patterns = options.testFiles.map(globExpression);
-    const matched = options.testFiles.map(() => 0);
     const found = [];
     const tests = [];
     const chains = aliasChains(project, held);
@@ -332,13 +347,7 @@ export function references(project, held, targetRoot, options) {
     };
     for (const file of files) {
         const path = renderPosition(file, targetRoot, 0).path;
-        const hits = patterns.map((pattern) => pattern.test(path));
-        hits.forEach((hit, index) => {
-            if (hit) {
-                matched[index] = (matched[index] ?? 0) + 1;
-            }
-        });
-        const test = hits.includes(true);
+        const test = patterns.some((pattern) => pattern.test(path));
         if (test) {
             tests.push(path);
         }
@@ -449,9 +458,6 @@ export function references(project, held, targetRoot, options) {
     return {
         configFile: project.configFile,
         references: found,
-        testFileRules: options.testFiles
-            .map((_pattern, index) => ({ rule: patternRule(index), matched: matched[index] ?? 0 }))
-            .sort((a, b) => compare(a.rule, b.rule)),
         testFilePaths: tests.sort(compare),
         cost: { batched, fileBatches, residueFallbacks, shorthandLookups, aliasSteps: chains.steps },
     };