@cplieger/deadset-ts 3.1.0 → 3.3.0

package/README.md

@@ -8,7 +8,7 @@ deadset-ts is a command-line analyzer for TypeScript and JavaScript projects. It
 
 deadset-ts is report-only. It never edits source, and it refuses any `--fix` flag.
 
-**Status: pre-release.** This version implements contract 2.2.0 and ships the analyzer's foundation: one compiler session per run over the projects `analysis.configurations` declares, in the order it lists them, each a compiler configuration file below the target, or, where it declares none, every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, the report-only guard, the symbol inventory of every declaration a project's own files hold down to its class and type members, the one-pass reference resolution over that inventory, which resolves each file's identifiers in batches ([batch-cap calibration](docs/batch-cap-calibration.md) is the measurement behind the batch size), and the root set `print-roots` prints. A root is a declaration the analysis keeps live without a reference: what a file exports when the manifest names it through `main`, `module`, `types`, `bin` or `exports`, or when `ts.entry_files` matches it; a library target's published API; the configuration, setup and test files of Vitest, Stryker and Playwright, the flat configuration of ESLint, and a worker or service worker a call addresses by a string literal; and every declaration a `roots.patterns` entry names. An entry that names nothing is reported as `DS1704` and fails the run. The entry-point conventions of other tools are not read, and `DECLINED_CONVENTIONS` lists each one with the reason. The analysis is reached through the command, and through `run()` for a caller that runs the command in-process; no other verb reports findings yet, so `analyze`, `explain`, `print-retained` and `describe` exit with a usage message. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share.
+**Status: pre-release.** This version implements contract 3.0.0 and ships the analyzer's foundation: one compiler session per run over the projects `analysis.configurations` declares, in the order it lists them, each a compiler configuration file below the target, or, where it declares none, every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, the report-only guard, the symbol inventory of every declaration a project's own files hold down to its class and type members, the one-pass reference resolution over that inventory, which resolves each file's identifiers in batches ([batch-cap calibration](docs/batch-cap-calibration.md) is the measurement behind the batch size), and the root set `print-roots` prints. A root is a declaration the analysis keeps live without a reference: what a file exports when the manifest names it through `main`, `module`, `types`, `bin` or `exports`, or when `ts.entry_files` matches it; a library target's published API; the configuration, setup and test files of Vitest, Stryker and Playwright, the flat configuration of ESLint, and a worker or service worker a call addresses by a string literal; and every declaration a `roots.patterns` entry names. An entry that names nothing is reported as `DS1704` and fails the run. The entry-point conventions of other tools are not read, and `DECLINED_CONVENTIONS` lists each one with the reason. Four exemption classes hold a declaration back from the sweep, and `print-retained` lists what each one held back: `interface-satisfaction`, a member an interface requires of a class whose value reaches that interface; `decorator`, a decorated member and every member of a decorated class; and, at the lowest confidence, `template-field`, a member an action of a template under `analysis.template_dirs` names, and `reflective-lookup`, a member a literal key of an element access or of `Reflect.get`, `Reflect.set` or `Reflect.has` names. None of them holds back a `#private` member. The analysis is reached through the command, and through `run()` for a caller that runs the command in-process; no other verb reports findings yet, so `analyze`, `explain` and `describe` exit with a usage message. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share.
 
 ## Install
 
@@ -28,7 +28,7 @@ The npm package carries the command and the library as JavaScript that the compi
 npx deadset-ts version
 ```
 
-`version` prints the analyzer version and the Contract version it implements, and exits 0. `print-config`, `print-projects` and `print-roots` print what their row of the table says and exit 0, or 1 when `print-roots` reports a `DS1704`. `analyze`, `explain`, `print-retained`, `describe`, any other invocation and no arguments print the usage line and exit 2.
+`version` prints the analyzer version and the Contract version it implements, and exits 0. `print-config`, `print-projects`, `print-roots` and `print-retained` print what their row of the table says and exit 0, or 1 when `print-roots` reports a `DS1704`, and `print-retained` exits 2 when an `exemptions.disabled` entry is not an exemption class or an `analysis.template_dirs` entry is not a directory below the target root. `analyze`, `explain`, `describe`, any other invocation and no arguments print the usage line and exit 2.
 
 | Verb             | Job                                                                             |
 | ---------------- | ------------------------------------------------------------------------------- |
@@ -37,7 +37,7 @@ npx deadset-ts version
 | `print-config`   | Print the resolved configuration and where each setting came from               |
 | `print-projects` | Print the identifier of every project a run analyzes                            |
 | `print-roots`    | Print every declaration the analysis keeps live without a reference, and why    |
-| `print-retained` | Print every symbol an exemption class held back, with the class                 |
+| `print-retained` | Print every declaration an exemption held back: each class, its site and detail |
 | `describe`       | Describe the analyzer: version, Contract version, supported issue kinds         |
 | `version`        | Print the analyzer and Contract versions                                        |
 

package/dist/src/analysis.js

@@ -7,15 +7,20 @@
  * carries a project's identity in its type so a handle cannot cross to another
  * project's checker, and that holds only for views the session itself hands out.
  */
+import { decorator } from "./decorator.js";
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.js";
+import { computeExemptions, disabledClasses, exemptionsOf, retainedIn, } from "./exempt.js";
+import { interfaceSatisfaction } from "./interface-satisfaction.js";
 import { inventory } from "./inventory.js";
 import { readManifest } from "./manifest.js";
 import { matrixOf, sweepMatrix } from "./matrix.js";
 import { relativePath, resolvePath } from "./paths.js";
 import { byPosition } from "./position.js";
+import { reflectiveLookup } from "./reflective-lookup.js";
 import { references } from "./references.js";
 import { roots, unmatchedEverywhere, unmatchedRoots } from "./roots.js";
 import { diagnosticsOf, runSession } from "./session.js";
+import { readTemplates, templateField } from "./template-field.js";
 /** The setting whose source decides where a finding about a configured root sits. */
 const ROOTS_SETTING = "roots.patterns";
 /**
@@ -117,27 +122,48 @@ export function runRoots(engine, host, scope, config, provenance) {
         findings: unmatchedRoots(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
     };
 }
+/** The exemption classes this analyzer detects, each by its detector; any other retains nothing. */
+const DETECTORS = new Map([
+    ["interface-satisfaction", interfaceSatisfaction],
+    ["template-field", templateField],
+    ["reflective-lookup", reflectiveLookup],
+    ["decorator", decorator],
+]);
 /**
  * Sweeps the run the scope and the configuration describe. Each project's references
- * are read against its own inventory with the configured test-file patterns while its
- * view is open; the projects then merge into one matrix in discovery order, which is
- * swept under the input the caller decided once for the run. A project that carries
- * an error ends the run before any project is swept.
+ * and exemptions are read against its own inventory while its view is open; the
+ * projects then merge into one matrix in the run's order, which is swept under the
+ * caller's marks and mode with the exemptions every project found. A record found in
+ * one configuration holds in every configuration that holds its declaration, because
+ * an exemption is evidence of a use the analysis cannot see and a use in one
+ * configuration is a use. A project that carries an error ends the run before any
+ * project is swept.
  */
-export function runSweep(engine, host, scope, config, input) {
+export function runSweep(engine, host, scope, config, input, detectors = DETECTORS) {
     const targetRoot = scope.target.path;
-    const configured = readProjects(engine, host, scope, config, (project, read) => {
-        const resolved = references(project, read.held, targetRoot, {
+    const disabled = disabledClasses(config);
+    const templates = disabled.has("template-field")
+        ? { delimiters: config.analysis.templateDelimiters, files: [] }
+        : readTemplates(host, targetRoot, config.analysis);
+    const read = readProjects(engine, host, scope, config, (project, projectRead) => {
+        const resolved = references(project, projectRead.held, targetRoot, {
             testFiles: config.ts.testFiles,
         });
-        return {
-            configuration: read.configuration,
-            symbols: read.held.symbols,
+        const configured = {
+            configuration: projectRead.configuration,
+            symbols: projectRead.held.symbols,
             references: resolved.references,
-            roots: read.rooted.liveUnderReachability,
+            roots: projectRead.rooted.liveUnderReachability,
             testFiles: resolved.testFilePaths,
         };
+        const exempt = computeExemptions({ project, held: projectRead.held, targetRoot, templates }, detectors, {
+            disabled,
+            mode: input.mode,
+            testFiles: new Set(resolved.testFilePaths),
+        });
+        return { configured, exempt };
     });
-    const matrix = matrixOf(configured);
-    return { matrix, sweep: sweepMatrix(matrix, input) };
+    const matrix = matrixOf(read.map((one) => one.configured));
+    const swept = { ...input, exempt: exemptionsOf(read.flatMap((one) => one.exempt)) };
+    return { matrix, sweep: sweepMatrix(matrix, swept), retained: retainedIn(matrix, swept) };
 }

package/dist/src/decorator.js

@@ -0,0 +1,64 @@
+/**
+ * The decorator class: a member a decorator expression is attached to, and every
+ * member of a class a decorator expression is attached to, is held back, because the
+ * decorator receives the member or the class when the class is defined and may reach
+ * the member by its name.
+ *
+ * The rule is read from the tree alone: a decorator is attached where it is written.
+ * The use the decorator itself makes of what it decorates is the reference pass's,
+ * which records it as a `decorator` reference; this class records only that the
+ * declaration is held back, and the member set of a decorated class is every member
+ * the inventory holds for the class, static members included.
+ */
+import { isCallExpression, isDecorator, } from "@typescript/native/unstable/ast";
+import { nodeKey } from "./inventory.js";
+import { renderPosition } from "./position.js";
+/** The kinds of declaration a decorator is attached to and holds back. */
+const DECORATED = new Set(["class", "method", "class-member"]);
+/** How one decorator is spelled in a record: its expression, without a call's arguments. */
+function spelled(decorator) {
+    const expression = decorator.expression;
+    const named = isCallExpression(expression) ? expression.expression : expression;
+    return `@${named.getText().replace(/\s+/gu, "")}`;
+}
+/**
+ * The decorator detector: each decorated member, and each member of a decorated
+ * class, recorded at the decorator.
+ */
+export function decorator(input) {
+    const { project, held, targetRoot } = input;
+    const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+    const membersOf = new Map();
+    for (const symbol of held.symbols) {
+        if (symbol.kind === "method" || symbol.kind === "class-member") {
+            const members = membersOf.get(symbol.parent);
+            if (members === undefined) {
+                membersOf.set(symbol.parent, [symbol]);
+            }
+            else {
+                members.push(symbol);
+            }
+        }
+    }
+    const found = [];
+    for (const file of project.ownSourceFiles()) {
+        const visit = (node) => {
+            const id = held.declarations.get(nodeKey(file, node));
+            const symbol = id === undefined ? undefined : byId.get(id);
+            if (symbol !== undefined && DECORATED.has(symbol.kind)) {
+                const modifiers = node.modifiers ?? [];
+                for (const attached of modifiers.filter(isDecorator)) {
+                    const detail = `decorated by ${spelled(attached)}`;
+                    const site = renderPosition(file, targetRoot, attached.getStart());
+                    const reached = symbol.kind === "class" ? (membersOf.get(symbol.id) ?? []) : [symbol];
+                    for (const member of reached) {
+                        found.push({ id: member.id, detail, site });
+                    }
+                }
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    return found;
+}

package/dist/src/exempt-classes.js

@@ -0,0 +1,83 @@
+/**
+ * The exemption classes of the Contract's vocabulary, in its order: each class's name,
+ * the languages it runs on, the confidence it is recorded at and, for a class that runs
+ * on TypeScript, which private members it may retain.
+ *
+ * The rows are written out rather than read from the Contract at run time, for the
+ * reason the fixed severity codes are, and a test holds them equal to the Contract
+ * release this analyzer implements. A class name is a type, so a detector table or a
+ * record naming a class the vocabulary does not hold, or one that runs on another
+ * language only, does not compile.
+ */
+/** Every class of the vocabulary, in the order the Contract lists them. */
+export const EXEMPTION_CLASSES = [
+    {
+        class: "interface-satisfaction",
+        languages: ["go", "ts"],
+        confidence: "certain",
+        typescriptVisibility: { private: false, privateName: false },
+    },
+    { class: "encoding-reflection", languages: ["go"], confidence: "certain" },
+    { class: "format-verb-contract", languages: ["go"], confidence: "certain" },
+    { class: "errors-duck-typing", languages: ["go"], confidence: "certain" },
+    {
+        class: "enum-group",
+        languages: ["go", "ts"],
+        confidence: "certain",
+        typescriptVisibility: { private: false, privateName: false },
+    },
+    { class: "generated-file", languages: ["go"], confidence: "certain" },
+    { class: "linkname-cgo-asm-plugin", languages: ["go"], confidence: "certain" },
+    {
+        class: "template-field",
+        languages: ["go", "ts"],
+        confidence: "possible",
+        typescriptVisibility: { private: true, privateName: false },
+    },
+    {
+        class: "reflective-lookup",
+        languages: ["go", "ts"],
+        confidence: "possible",
+        typescriptVisibility: { private: true, privateName: false },
+    },
+    {
+        class: "decorator",
+        languages: ["ts"],
+        confidence: "certain",
+        typescriptVisibility: { private: true, privateName: false },
+    },
+    {
+        class: "injection-container",
+        languages: ["ts"],
+        confidence: "certain",
+        typescriptVisibility: { private: true, privateName: false },
+    },
+    {
+        class: "framework-lifecycle",
+        languages: ["ts"],
+        confidence: "certain",
+        typescriptVisibility: { private: true, privateName: false },
+    },
+    {
+        class: "serialization-contract",
+        languages: ["ts"],
+        confidence: "certain",
+        typescriptVisibility: { private: true, privateName: false },
+    },
+];
+function runsOnTS(row) {
+    const languages = row.languages;
+    return languages.includes("ts");
+}
+const TS_ROWS = EXEMPTION_CLASSES.filter(runsOnTS);
+/** The classes that run on TypeScript, in the vocabulary's order. */
+export const TS_EXEMPTION_CLASSES = TS_ROWS.map((row) => row.class);
+const VISIBILITY = new Map(TS_ROWS.map((row) => [row.class, row.typescriptVisibility]));
+/** Which private members one class that runs on TypeScript may retain. */
+export function typescriptVisibilityOf(exemptionClass) {
+    return VISIBILITY.get(exemptionClass) ?? { private: false, privateName: false };
+}
+/** Whether one name is a class of the vocabulary, whichever language it runs on. */
+export function isExemptionClass(name) {
+    return EXEMPTION_CLASSES.some((row) => row.class === name);
+}

package/dist/src/exempt.js

@@ -0,0 +1,152 @@
+/**
+ * The exemption framework: the classes of reason for which a declaration the reference
+ * graph alone would report is live all the same. A class is policy over what one
+ * project's checker answers, and its detector names the declarations it holds back;
+ * this module runs the detectors, decides which of their records stand, and answers
+ * which records held something back. It names no class's detector: the composition
+ * hands it the table of the classes it has.
+ */
+import { ConfigError } from "./config.js";
+import { EXEMPTION_CLASSES, isExemptionClass, TS_EXEMPTION_CLASSES, typescriptVisibilityOf, } from "./exempt-classes.js";
+import { byPosition, positionKey } from "./position.js";
+import { sweep } from "./sweep.js";
+/**
+ * The classes `exemptions.disabled` switches off. A name is refused unless the
+ * vocabulary holds it; a class that runs on another language only is admitted and
+ * switches nothing off here, so one configuration serves every analyzer.
+ */
+export function disabledClasses(config) {
+    const disabled = new Set();
+    for (const name of config.exemptionsDisabled) {
+        if (!isExemptionClass(name)) {
+            const known = EXEMPTION_CLASSES.map((row) => row.class).join(", ");
+            throw new ConfigError("malformed", "exemptions.disabled", `exemptions.disabled: ${JSON.stringify(name)} is not an exemption class: the classes are ${known}`);
+        }
+        disabled.add(name);
+    }
+    return disabled;
+}
+/**
+ * Whether a class whose row states `allowed` may retain a member of one visibility. A
+ * declaration the inventory does not hold has no visibility to refuse it by.
+ */
+function retainable(allowed, visibility) {
+    if (visibility === "private") {
+        return allowed.private;
+    }
+    if (visibility === "private-name") {
+        return allowed.privateName;
+    }
+    return true;
+}
+/**
+ * The records one project's detectors found, each class in the vocabulary's order and
+ * none of a switched-off class. Evidence on a private member the class's row says it
+ * cannot retain is dropped first, whatever the detector found. Under a production mode
+ * a record whose evidence is written in a test file holds nothing, as a reference a
+ * test file makes is none there.
+ */
+export function computeExemptions(input, detectors, holding) {
+    const visibility = new Map(input.held.symbols.map((symbol) => [symbol.id, symbol.visibility]));
+    const found = [];
+    for (const exemptionClass of TS_EXEMPTION_CLASSES) {
+        const detect = detectors.get(exemptionClass);
+        if (detect === undefined || holding.disabled.has(exemptionClass)) {
+            continue;
+        }
+        const allowed = typescriptVisibilityOf(exemptionClass);
+        for (const evidence of detect(input)) {
+            if (!retainable(allowed, visibility.get(evidence.id))) {
+                continue;
+            }
+            if (holding.mode.production && holding.testFiles.has(evidence.site.path)) {
+                continue;
+            }
+            found.push({
+                id: evidence.id,
+                class: exemptionClass,
+                detail: evidence.detail,
+                site: evidence.site,
+            });
+        }
+    }
+    return exemptionsOf(found);
+}
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/**
+ * Records as a run holds them: ordered by site, then class, then declaration, and one
+ * per declaration, class and detail, the one at the first site. A fact found at many
+ * sites, or by several projects, is one record.
+ */
+export function exemptionsOf(found) {
+    const ordered = [...found].sort((a, b) => byPosition(a.site, b.site) || compare(a.class, b.class) || compare(a.id, b.id));
+    const seen = new Set();
+    return ordered.filter((record) => {
+        const fact = [record.id, record.class, record.detail].join("\u0000");
+        if (seen.has(fact)) {
+            return false;
+        }
+        seen.add(fact);
+        return true;
+    });
+}
+/** The records per declaration, each declaration's in the order given. */
+function byDeclaration(records) {
+    const grouped = new Map();
+    for (const record of records) {
+        const held = grouped.get(record.id);
+        if (held === undefined) {
+            grouped.set(record.id, [record]);
+        }
+        else {
+            held.push(record);
+        }
+    }
+    return grouped;
+}
+/**
+ * The records that held back a declaration some configuration of the run would
+ * otherwise judge dead: each configuration's graph is swept once more with no
+ * exemption and the marks it was given, and a record is retained when one of those
+ * sweeps judged its declaration a candidate. A record that holds a declaration back in
+ * one configuration is retained whatever another configuration answers about it, as a
+ * run of that configuration alone would report the declaration without it. A record
+ * on a declaration that a relation or a mark holds live in every configuration held
+ * nothing back. The order is the declarations' site order, and for one declaration
+ * the input's.
+ */
+export function retainedIn(matrix, input) {
+    const exempt = input.exempt ?? [];
+    if (exempt.length === 0) {
+        return [];
+    }
+    const bare = { marked: input.marked, mode: input.mode };
+    const dead = new Set(matrix.graphs.flatMap((graph) => sweep(graph, bare).candidates.map((candidate) => candidate.id)));
+    const held = byDeclaration(exempt.filter((record) => dead.has(record.id)));
+    return matrix.union.symbols.flatMap((symbol) => held.get(symbol.id) ?? []);
+}
+/**
+ * One line per held-back declaration, in site order: its reference, then each record's
+ * class, site and detail, all separated by tabs.
+ */
+export function retainedLines(symbols, retained) {
+    const held = byDeclaration(retained);
+    return symbols.flatMap((symbol) => {
+        const records = held.get(symbol.id);
+        if (records === undefined) {
+            return [];
+        }
+        const fields = records.flatMap((record) => [
+            record.class,
+            positionKey(record.site),
+            record.detail,
+        ]);
+        return [[symbol.ref, ...fields].join("\t")];
+    });
+}