@cplieger/deadset-ts 3.8.0 → 3.9.1

package/dist/src/references.js

@@ -1,5 +1,6 @@
 import { isArrayLiteralExpression, isBinaryExpression, isCallExpression, isDecorator, isDeleteExpression, isElementAccessExpression, isExportDeclaration, isExternalModuleReference, isForInStatement, isForOfStatement, isImportDeclaration, isImportEqualsDeclaration, isNamespaceExport, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
 import { aliasChains } from "./alias-chain.js";
+import { destructuring, propertyReadsOf } from "./destructuring.js";
 import { globExpression } from "./glob.js";
 import { nodeKey } from "./inventory.js";
 import { byPosition, renderPosition } from "./position.js";
@@ -205,6 +206,7 @@ function linksOf(file, node, declarations, enclosing) {
  */
 function sitesOf(file, declarations, fileId) {
     const found = [];
+    const reads = [];
     const links = [];
     const evaluations = [];
     const decorated = [];
@@ -243,6 +245,9 @@ function sitesOf(file, declarations, fileId) {
         }
         markNames(node);
         markStores(node, writes);
+        for (const read of propertyReadsOf(node)) {
+            reads.push({ ...read, from: enclosing });
+        }
         links.push(...linksOf(file, node, declarations, enclosing));
         const evaluated = evaluatedBy(node);
         if (evaluated !== undefined) {
@@ -262,7 +267,7 @@ function sitesOf(file, declarations, fileId) {
         enclosing = outer;
     };
     file.forEachChild(visit);
-    return { uses: found, links, evaluations, decorated };
+    return { uses: found, reads, links, evaluations, decorated };
 }
 /**
  * The name one test-file rule takes. A rule's name is a word list the report's own
@@ -272,6 +277,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 +302,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,10 +318,10 @@ 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);
+    const destructured = destructuring(project, cap);
     let batched = 0;
     let fileBatches = 0;
     let residueFallbacks = 0;
@@ -332,17 +353,11 @@ 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);
         }
-        const { uses, links, evaluations, decorated } = sitesOf(file, declarations, declaredAt(file) ?? "");
+        const { uses, reads, links, evaluations, decorated } = sitesOf(file, declarations, declaredAt(file) ?? "");
         // A decorator is written inside the declaration it is attached to and receives it,
         // so the declaration is used where the decorator is written, whatever the
         // decorator does with it.
@@ -417,6 +432,25 @@ export function references(project, held, targetRoot, options) {
                 }
             }
         }
+        // A pattern names a property of the value it destructures, which no name node of
+        // the pattern resolves to: a shorthand's name is the local it binds.
+        destructured.resolve(reads).forEach((symbol, index) => {
+            const read = reads[index];
+            if (symbol === undefined || read === undefined) {
+                return;
+            }
+            const position = renderPosition(file, targetRoot, read.key.getStart());
+            for (const target of chains.chainOf(symbol)) {
+                found.push({
+                    from: read.from,
+                    to: target.id,
+                    position,
+                    use: "read",
+                    resolution: "destructured",
+                    test,
+                });
+            }
+        });
         for (const site of uses) {
             const direct = site.shorthand !== undefined
                 ? "shorthand"
@@ -449,10 +483,15 @@ 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 },
+        cost: {
+            batched,
+            fileBatches,
+            residueFallbacks,
+            shorthandLookups,
+            aliasSteps: chains.steps,
+            patternBatches: destructured.cost.patternBatches,
+            patternLookups: destructured.cost.patternLookups,
+        },
     };
 }

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/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;