@cplieger/deadset-ts 5.0.0 → 5.1.1

package/dist/src/template-field.js

@@ -87,12 +87,69 @@ function stringEnd(text, from) {
     }
     return at + 1;
 }
-/** The identifiers one action's inner text writes outside a quoted string, with their offsets in it. */
-function identifiersOf(inner) {
+/** The end of the `${` substitution whose expression starts at `from`, past its closing brace. */
+function substitutionEnd(text, from) {
+    let depth = 1;
+    let at = from;
+    while (at < text.length) {
+        const char = text[at];
+        if (char === '"' || char === "'") {
+            at = stringEnd(text, at);
+            continue;
+        }
+        if (char === "`") {
+            at = templateEnd(text, at, () => undefined);
+            continue;
+        }
+        if (char === "{") {
+            depth += 1;
+        }
+        else if (char === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                return at + 1;
+            }
+        }
+        at += 1;
+    }
+    return at;
+}
+/** The end of the template literal at `from`; each `${…}` expression goes to `substitution`. */
+function templateEnd(text, from, substitution) {
+    let at = from + 1;
+    while (at < text.length && text[at] !== "`") {
+        if (text[at] === "\\") {
+            at += 2;
+            continue;
+        }
+        if (text[at] === "$" && text[at + 1] === "{") {
+            const start = at + 2;
+            const end = substitutionEnd(text, start);
+            substitution(text.slice(start, end - 1), start);
+            at = end;
+            continue;
+        }
+        at += 1;
+    }
+    return at + 1;
+}
+/**
+ * The identifiers one action's inner text writes outside a quoted string, with their offsets
+ * in it. In `script` text, a component's markup, a template literal's substitutions are code.
+ */
+function identifiersOf(inner, script = false) {
     const found = [];
     let at = 0;
     while (at < inner.length) {
         const char = inner[at] ?? "";
+        if (char === "`" && script) {
+            at = templateEnd(inner, at, (expression, offset) => {
+                for (const one of identifiersOf(expression, true)) {
+                    found.push({ name: one.name, offset: offset + one.offset });
+                }
+            });
+            continue;
+        }
         if (char === '"' || char === "'" || char === "`") {
             at = stringEnd(inner, at);
             continue;
@@ -142,7 +199,7 @@ function namesOf(text, delimiters) {
 }
 /** Every identifier the markup of one component file writes in an action. */
 function markupNamesOf(text) {
-    return readComponent(text).markup.flatMap((one) => identifiersOf(one.text).map(({ name, offset }) => ({
+    return readComponent(text).markup.flatMap((one) => identifiersOf(one.text, true).map(({ name, offset }) => ({
         name,
         offset: one.start + offset,
         action: one.action,

package/dist/src/value-flow.js

@@ -0,0 +1,74 @@
+/**
+ * The values a program hands to a position the checker types from its context: the
+ * initializer of a declaration whose type is written, an assignment's right side, an
+ * argument, a returned value, an arrow function's expression body, an array element, an
+ * object property, and the operand of `as` or `satisfies`.
+ */
+import { isArrayLiteralExpression, isArrowFunction, isAsExpression, isBinaryExpression, isCallExpression, isConditionalExpression, isIdentifier, isNewExpression, isParameterDeclaration, isParenthesizedExpression, isPropertyAssignment, isPropertyDeclaration, isReturnStatement, isSatisfiesExpression, isShorthandPropertyAssignment, isSpreadElement, isVariableDeclaration, SyntaxKind, } from "@typescript/native/unstable/ast";
+/** The operators of an assignment whose right side is stored into the left side's type. */
+const STORES = new Set([
+    SyntaxKind.EqualsToken,
+    SyntaxKind.QuestionQuestionEqualsToken,
+    SyntaxKind.BarBarEqualsToken,
+    SyntaxKind.AmpersandAmpersandEqualsToken,
+]);
+/** Whether a declaration writes its type, so its initializer is read in that type's context. */
+function writesType(node) {
+    return node.type !== undefined;
+}
+/**
+ * The values one written expression hands on: the expression itself, or what it
+ * evaluates to through parentheses, a conditional and the operators whose result is
+ * one of their operands.
+ */
+export function valuesOf(expression) {
+    if (isParenthesizedExpression(expression)) {
+        return valuesOf(expression.expression);
+    }
+    if (isConditionalExpression(expression)) {
+        return [...valuesOf(expression.whenTrue), ...valuesOf(expression.whenFalse)];
+    }
+    if (isBinaryExpression(expression)) {
+        const operator = expression.operatorToken.kind;
+        if (operator === SyntaxKind.QuestionQuestionToken || operator === SyntaxKind.BarBarToken) {
+            return [...valuesOf(expression.left), ...valuesOf(expression.right)];
+        }
+        if (operator === SyntaxKind.AmpersandAmpersandToken || operator === SyntaxKind.CommaToken) {
+            return valuesOf(expression.right);
+        }
+    }
+    return [expression];
+}
+/** The expressions one node hands to a position typed by its context. */
+export function handedOn(node) {
+    if ((isVariableDeclaration(node) || isPropertyDeclaration(node) || isParameterDeclaration(node)) &&
+        node.initializer !== undefined &&
+        writesType(node)) {
+        return [node.initializer];
+    }
+    if (isBinaryExpression(node) && STORES.has(node.operatorToken.kind)) {
+        return [node.right];
+    }
+    if (isCallExpression(node) || isNewExpression(node)) {
+        return (node.arguments ?? []).filter((argument) => !isSpreadElement(argument));
+    }
+    if (isReturnStatement(node)) {
+        return node.expression === undefined ? [] : [node.expression];
+    }
+    if (isArrowFunction(node)) {
+        return node.body.kind === SyntaxKind.Block ? [] : [node.body];
+    }
+    if (isArrayLiteralExpression(node)) {
+        return node.elements.filter((element) => !isSpreadElement(element) && element.kind !== SyntaxKind.OmittedExpression);
+    }
+    if (isPropertyAssignment(node)) {
+        return [node.initializer];
+    }
+    if (isShorthandPropertyAssignment(node)) {
+        return isIdentifier(node.name) ? [node.name] : [];
+    }
+    if (isAsExpression(node) || isSatisfiesExpression(node)) {
+        return [node.expression];
+    }
+    return [];
+}

package/dist/src/version.js

@@ -4,4 +4,4 @@
  * independently of the analyzer's own version, which is the one the host answers
  * from the package the analyzer was installed from.
  */
-export const CONTRACT_VERSION = "5.1.0";
+export const CONTRACT_VERSION = "5.2.0";

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",
@@ -33,7 +33,7 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "24.19.0",
+    "@types/node": "24.19.1",
     "eslint": "10.11.0",
     "fast-check": "4.10.2",
     "prettier": "3.9.9",

package/src/analysis.ts

@@ -36,14 +36,18 @@ import {
 } from "./discover.ts";
 import {
   conventionFailuresFor,
+  generatedFiles,
   readConventions,
   type AppliedConvention,
   type ConventionManifest,
 } from "./conventions.ts";
 import { readEdgeSides } from "./edges.ts";
 import { enumGroup } from "./enum-group.ts";
+import { generatedFile } from "./generated-file.ts";
+import { sourceFilesOf } from "./source-files.ts";
 import {
-  computeExemptions,
+  evidenceRecords,
+  heldRecords,
   disabledClasses,
   exemptionsOf,
   holdingWhile,
@@ -53,7 +57,8 @@ import {
   type Detectors,
 } from "./exempt.ts";
 import type { TSExemptionClass } from "./exempt-classes.ts";
-import { heldByInclusion, sourceTree } from "./file-facts.ts";
+import { heldByInclusion, sourcePaths, sourceTree } from "./file-facts.ts";
+import { globExpression } from "./glob.ts";
 import type { Finding } from "./finding.ts";
 import { findingsPass, recordedFindings, rowKey, type PassResult } from "./findings-pass.ts";
 import type { EmitterInput } from "./findings/emitter.ts";
@@ -69,7 +74,7 @@ import { injectionContainer } from "./injection-container.ts";
 import { interfaceSatisfaction } from "./interface-satisfaction.ts";
 import { intraFunctionFacts, projectParts, type ProjectParts } from "./intra-function-parts.ts";
 import { inventory, type Inventory, type InventorySymbol } from "./inventory.ts";
-import { readManifest } from "./manifest.ts";
+import { packageEntries, readManifest } from "./manifest.ts";
 import {
   liveFilesAt,
   matrixOf,
@@ -79,7 +84,7 @@ import {
   type Matrix,
   type SweepResult,
 } from "./matrix.ts";
-import { joinPath, relativePath, resolvePath } from "./paths.ts";
+import { joinPath, normalizePath, relativePath, resolvePath } from "./paths.ts";
 import type { UnansweredQuestion } from "./query.ts";
 import { byPosition, isComponentFile, type Position } from "./position.ts";
 import type { TypeErrorSkip, UnansweredCount } from "./report.ts";
@@ -96,6 +101,7 @@ import { references, testFileRulesOf, type Reference, type TestFileRule } from "
 import { roots, unmatchedEverywhere, type RootKind, type Roots } from "./roots.ts";
 import type { Scope } from "./scope.ts";
 import { serializationContract } from "./serialization-contract.ts";
+import { outsideTestReferences, testFilesAt, type OutsideTest } from "./outside-tests.ts";
 import { supportReferences, testSupportFiles } from "./test-support.ts";
 import { diagnosticsOf, ownedAs, runSession, type Engine, type ProjectView } from "./session.ts";
 import { accessorsOf, storesOf } from "./stores.ts";
@@ -185,6 +191,8 @@ interface ProjectRead {
   readonly typeErrorSkips: readonly TypeErrorSkip[];
   /** The lines each of those skips withholds every finding on. */
   readonly skipped: readonly SkippedUnit[];
+  /** The project's generated files, by path below the target root, each with the row naming it. */
+  readonly generated: ReadonlyMap<string, string>;
 }
 
 /** One target project the run analyzes, as its stage is handed it. */
@@ -214,6 +222,8 @@ interface ReadProjects<Answer> {
   readonly componentsUnread: readonly ComponentsUnread[];
   /** The convention rows the run applied. */
   readonly conventionsApplied: readonly AppliedConvention[];
+  /** The test files below the target root no project the run reads holds, parsed. */
+  readonly outsideTests: readonly OutsideTest[];
 }
 
 /**
@@ -279,11 +289,20 @@ function readProjects<Answer>(
   const options = {
     host,
     manifest: workspace?.manifest ?? readManifest(host, targetRoot),
-    workspaceEntries: workspace?.entries,
+    otherPackages: [
+      ...(workspace?.entries ?? []),
+      ...packageEntries(
+        host,
+        normalizePath(absoluteRoot),
+        discovered.configFiles,
+        new Set(workspace?.memberDirs ?? []),
+      ),
+    ],
     patterns: config.rootPatterns,
     entryFiles: config.ts.entryFiles,
     conventions,
     testFiles: config.ts.testFiles,
+    parse: (fileName: string, text: string) => engine.parseSourceFile(fileName, text),
     publishedAPI: config.targetKind === "library",
   };
   const notBuilt: NotBuilt[] = [...discovered.notBuilt];
@@ -298,6 +317,8 @@ function readProjects<Answer>(
   const unbuildable: SetupFailure[] = [];
   const setupDropped: SetupFailure[] = [];
   const consumed = new Map<string, Reference>();
+  const heldFiles = new Set<string>();
+  let outsideTests: readonly OutsideTest[] = [];
   const setupMet = (configFile: string, met: readonly SetupFailure[]): void => {
     const [first] = met;
     if (first !== undefined && isGuess(discovered, configFile)) {
@@ -425,12 +446,27 @@ function readProjects<Answer>(
             .ownSourceFiles()
             .filter((file) => referenceOnly(file.fileName))
             .flatMap((file) => relativePath(absoluteRoot, file.fileName) ?? []),
+          generated: generatedFiles(conventions, sourceFilesOf(project, targetRoot)),
         };
       };
+      for (const file of project.ownSourceFiles()) {
+        heldFiles.add(relativePath(absoluteRoot, file.fileName) ?? file.fileName);
+      }
       return stage(project, { configuration, read });
     },
     discovered.derived ? "record" : "refuse",
     workspace?.programs,
+    () => {
+      const patterns = config.ts.testFiles.map(globExpression);
+      outsideTests = testFilesAt(
+        host,
+        targetRoot,
+        sourcePaths(host, targetRoot).filter(
+          (path) => !heldFiles.has(path) && patterns.some((pattern) => pattern.test(path)),
+        ),
+        options.parse,
+      );
+    },
   );
   for (const configFile of session.unopened) {
     if (consumerOf.has(configFile) || !isGuess(discovered, configFile)) {
@@ -468,6 +504,7 @@ function readProjects<Answer>(
     unanswered: session.unanswered,
     componentsUnread: workspace?.componentsUnread ?? [],
     conventionsApplied: conventions.applied,
+    outsideTests,
   };
 }
 
@@ -599,6 +636,7 @@ export interface ComponentWarning {
 const DETECTORS: Detectors = new Map<TSExemptionClass, Detector>([
   ["interface-satisfaction", interfaceSatisfaction],
   ["enum-group", enumGroup],
+  ["generated-file", generatedFile],
   ["template-field", templateField],
   ["reflective-lookup", reflectiveLookup],
   ["decorator", decorator],
@@ -622,6 +660,17 @@ interface SweptProject<Extra> {
   readonly extra: Extra;
 }
 
+/** What one project's stage reads while its view is open, before the run's test-support code is known. */
+interface ReadProject<Extra> {
+  readonly projectRead: ProjectRead;
+  readonly references: readonly Reference[];
+  readonly testFiles: readonly string[];
+  readonly evidence: readonly Exemption[];
+  readonly componentFiles: readonly string[];
+  readonly componentWarnings: readonly ComponentWarning[];
+  readonly extra: Extra;
+}
+
 /** What a run read of its projects before any sweep: the matrix, its exemptions, and each project's answers. */
 interface ReadRun<Extra> {
   readonly matrix: Matrix;
@@ -666,56 +715,34 @@ function readRun<Extra>(
     ? { delimiters: config.analysis.templateDelimiters, files: [] }
     : readTemplates(host, targetRoot, config.analysis);
   const consumers = scope.consumers.map((consumer) => consumer.path);
-  const read = readProjects<SweptProject<Extra>>(engine, host, scope, config, (project, opened) => {
+  const read = readProjects<ReadProject<Extra>>(engine, host, scope, config, (project, opened) => {
     const projectRead = opened.read();
     const resolved = references(project, projectRead.held, targetRoot, {
       testFiles: config.ts.testFiles,
     });
-    const support = testSupportFiles(
-      projectRead.held.symbols,
-      resolved.references,
-      projectRead.rooted.liveUnderReachability,
-      resolved.testFilePaths,
-    );
-    const made = supportReferences(resolved.references, support);
-    const configured: Configured = {
-      configuration: projectRead.configuration,
-      symbols: projectRead.held.symbols,
-      references: made,
-      roots: projectRead.rooted.liveUnderReachability,
-      testFiles: resolved.testFilePaths,
-      ...(support.size === 0 ? {} : { supportFiles: [...support].sort() }),
-      ...(projectRead.referenceOnly.length === 0
-        ? {}
-        : { referenceOnly: projectRead.referenceOnly }),
-    };
-    const exempt = computeExemptions(
-      { project, held: projectRead.held, targetRoot, templates, ts: config.ts, consumers },
-      detectors,
+    const evidence = evidenceRecords(
       {
-        disabled,
-        mode,
-        testFiles: new Set([...resolved.testFilePaths, ...support]),
+        project,
+        held: projectRead.held,
+        targetRoot,
+        templates,
+        ts: config.ts,
+        consumers,
+        ...(config.analysis.generatedFiles === "include"
+          ? {}
+          : { generated: projectRead.generated }),
       },
+      detectors,
+      disabled,
     );
-    const unanswered = [
-      ...projectRead.held.unanswered,
-      ...projectRead.rooted.unanswered,
-      ...made
-        .filter((reference) => reference.resolution === "by-name")
-        .map((reference) => reference.to),
-      ...exempt.filter(isUnansweredRecord).map((record) => record.id),
-    ];
     const components = project.ownSourceFiles().filter(isComponentFile);
     const pathOf = (file: (typeof components)[number]): string =>
       relativePath(targetRoot, file.fileName) ?? file.fileName;
     return {
-      configFile: projectRead.configFile,
-      configured,
-      exempt,
-      unanswered,
-      typeErrorSkips: projectRead.typeErrorSkips,
-      skipped: projectRead.skipped,
+      projectRead,
+      references: resolved.references,
+      testFiles: resolved.testFilePaths,
+      evidence,
       componentFiles: components.map(pathOf),
       componentWarnings: components.flatMap((file) =>
         readComponent(file.originalText).warnings.map((warning) => ({
@@ -724,11 +751,69 @@ function readRun<Extra>(
           reason: warning.reason,
         })),
       ),
-      extra: extra(project, projectRead, made),
+      extra: extra(project, projectRead, resolved.references),
+    };
+  });
+  const outsidePaths = read.outsideTests.map((one) => one.path);
+  const withOutside = read.answers.map((one) => ({
+    ...one,
+    references: [
+      ...one.references,
+      ...outsideTestReferences(read.outsideTests, one.projectRead.held, targetRoot),
+    ],
+    testFiles: [...one.testFiles, ...outsidePaths],
+  }));
+  // Test-support code is code only test code imports in any configuration of the run: a
+  // configuration that holds no test file says nothing about what the tests import.
+  const support = testSupportFiles(
+    withOutside.flatMap((one) => one.projectRead.held.symbols),
+    withOutside.flatMap((one) => one.references),
+    withOutside.flatMap((one) => one.projectRead.rooted.liveUnderReachability),
+    withOutside.flatMap((one) => one.testFiles),
+  );
+  const answers = withOutside.map((one): SweptProject<Extra> => {
+    const { projectRead } = one;
+    const detected = heldRecords(one.evidence, {
+      disabled,
+      mode,
+      testFiles: new Set([...one.testFiles, ...support]),
+    });
+    const exempt = detected.records;
+    const made = supportReferences(one.references, support);
+    const held = new Set(projectRead.held.symbols.map((symbol) => symbol.position.path));
+    const supportFiles = [...support].filter((path) => held.has(path)).sort();
+    const configured: Configured = {
+      configuration: projectRead.configuration,
+      symbols: projectRead.held.symbols,
+      references: [...made, ...evidenceReferences(projectRead.held.symbols, detected.inTestFiles)],
+      roots: projectRead.rooted.liveUnderReachability,
+      testFiles: one.testFiles,
+      ...(supportFiles.length === 0 ? {} : { supportFiles }),
+      ...(projectRead.referenceOnly.length === 0
+        ? {}
+        : { referenceOnly: projectRead.referenceOnly }),
+    };
+    return {
+      configFile: projectRead.configFile,
+      configured,
+      exempt,
+      unanswered: [
+        ...projectRead.held.unanswered,
+        ...projectRead.rooted.unanswered,
+        ...made
+          .filter((reference) => reference.resolution === "by-name")
+          .map((reference) => reference.to),
+        ...exempt.filter(isUnansweredRecord).map((record) => record.id),
+      ],
+      typeErrorSkips: projectRead.typeErrorSkips,
+      skipped: projectRead.skipped,
+      componentFiles: one.componentFiles,
+      componentWarnings: one.componentWarnings,
+      extra: one.extra,
     };
   });
   const consumed = read.consumers.references;
-  const projects = read.answers.map((one) =>
+  const projects = answers.map((one) =>
     consumed.length === 0
       ? one
       : {
@@ -744,7 +829,7 @@ function readRun<Extra>(
     exempt: exemptionsOf(projects.flatMap((one) => one.exempt)),
     unansweredHeld: [
       ...new Set([
-        ...read.answers.flatMap((one) => one.unanswered),
+        ...answers.flatMap((one) => one.unanswered),
         ...consumed.filter((one) => one.resolution === "by-name").map((one) => one.to),
       ]),
     ],
@@ -784,6 +869,61 @@ function holdingSweep<Extra>(
   }
 }
 
+/**
+ * The test references exemption evidence written in a test file makes: each is a read of
+ * the declaration it would retain, made by the test file at the evidence's site.
+ */
+function evidenceReferences(
+  symbols: readonly InventorySymbol[],
+  inTestFiles: readonly Exemption[],
+): readonly Reference[] {
+  if (inTestFiles.length === 0) {
+    return [];
+  }
+  const files = new Map(
+    symbols
+      .filter((symbol) => symbol.kind === "file")
+      .map((symbol) => [symbol.position.path, symbol.id]),
+  );
+  return inTestFiles.flatMap((record) => {
+    const from = files.get(record.site.path);
+    return from === undefined
+      ? []
+      : [
+          {
+            from,
+            to: record.id,
+            position: record.site,
+            use: "read",
+            resolution: "syntax",
+            test: true,
+          },
+        ];
+  });
+}
+
+/**
+ * The declarations every reference the mode counts stores into, a loaded consumer's
+ * reference counting as a read: what the write-only kind would report but for a record.
+ */
+function writtenOnly<Extra>(read: ReadRun<Extra>, mode: Mode): ReadonlySet<string> {
+  const written = new Set<string>();
+  const readSome = new Set<string>();
+  for (const { configured } of read.projects) {
+    for (const reference of configured.references) {
+      if (mode.production && reference.test) {
+        continue;
+      }
+      if (reference.use === "write" && reference.consumer === undefined) {
+        written.add(reference.to);
+      } else {
+        readSome.add(reference.to);
+      }
+    }
+  }
+  return new Set([...written].filter((id) => !readSome.has(id)));
+}
+
 /**
  * The sweep of a run read once, under one set of marks. Where a question went unanswered,
  * the run is swept once more without what that question could have kept live and without
@@ -834,7 +974,7 @@ function sweptOf<Extra>(
     matrix: read.matrix,
     sweep: result,
     exempt,
-    retained: retainedIn(read.matrix, swept),
+    retained: retainedIn(read.matrix, swept, writtenOnly(read, input.mode)),
     notBuilt: read.notBuilt,
     unanswered: read.unanswered,
     heldByUnanswered: [...held],
@@ -874,6 +1014,7 @@ interface EmitterExtra {
   readonly needs: ReturnType<typeof projectNeeds>;
   readonly implementations: ReturnType<typeof implementations>;
   readonly heldByInclusion: readonly string[];
+  readonly generated: readonly string[];
   readonly rooted: Roots;
   readonly directives: readonly InlineDirective[];
   readonly declarationsNamed: readonly boolean[];
@@ -900,9 +1041,12 @@ function readEmitterRun(
     (project, read, references) => ({
       deprecation: deprecatedDeclarations(project, read.held),
       accessors: accessorsOf(project, read.held),
-      needs: projectNeeds(project, read.held, host, targetRoot),
+      needs: projectNeeds(project, read.held, host, targetRoot, (fileName, text) =>
+        engine.parseSourceFile(fileName, text),
+      ),
       implementations: implementations(project, read.held),
       heldByInclusion: heldByInclusion(project, targetRoot),
+      generated: [...read.generated.keys()],
       rooted: read.rooted,
       directives: inlineDirectives(project, read.held, targetRoot).filter(
         (directive) => !read.referenceOnly.includes(directive.site.path),
@@ -956,6 +1100,7 @@ function emitterInputOver(
     files: {
       tree: sourceTree(host, targetRoot),
       heldByInclusion: new Set(projects.flatMap((one) => one.extra.heldByInclusion)),
+      generated: new Set(projects.flatMap((one) => one.extra.generated)),
     },
     boundary: {
       consumers: {