@cplieger/deadset-ts 5.0.0 → 5.1.0

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.0",
   "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.0",
   "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,17 @@ 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,
+  detectExemptions,
   disabledClasses,
   exemptionsOf,
   holdingWhile,
@@ -185,6 +188,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. */
@@ -284,6 +289,7 @@ function readProjects<Answer>(
     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];
@@ -425,6 +431,7 @@ function readProjects<Answer>(
             .ownSourceFiles()
             .filter((file) => referenceOnly(file.fileName))
             .flatMap((file) => relativePath(absoluteRoot, file.fileName) ?? []),
+          generated: generatedFiles(conventions, sourceFilesOf(project, targetRoot)),
         };
       };
       return stage(project, { configuration, read });
@@ -599,6 +606,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],
@@ -677,11 +685,31 @@ function readRun<Extra>(
       projectRead.rooted.liveUnderReachability,
       resolved.testFilePaths,
     );
+    const detected = detectExemptions(
+      {
+        project,
+        held: projectRead.held,
+        targetRoot,
+        templates,
+        ts: config.ts,
+        consumers,
+        ...(config.analysis.generatedFiles === "include"
+          ? {}
+          : { generated: projectRead.generated }),
+      },
+      detectors,
+      {
+        disabled,
+        mode,
+        testFiles: new Set([...resolved.testFilePaths, ...support]),
+      },
+    );
+    const exempt = detected.records;
     const made = supportReferences(resolved.references, support);
     const configured: Configured = {
       configuration: projectRead.configuration,
       symbols: projectRead.held.symbols,
-      references: made,
+      references: [...made, ...evidenceReferences(projectRead.held.symbols, detected.inTestFiles)],
       roots: projectRead.rooted.liveUnderReachability,
       testFiles: resolved.testFilePaths,
       ...(support.size === 0 ? {} : { supportFiles: [...support].sort() }),
@@ -689,15 +717,6 @@ function readRun<Extra>(
         ? {}
         : { referenceOnly: projectRead.referenceOnly }),
     };
-    const exempt = computeExemptions(
-      { project, held: projectRead.held, targetRoot, templates, ts: config.ts, consumers },
-      detectors,
-      {
-        disabled,
-        mode,
-        testFiles: new Set([...resolved.testFilePaths, ...support]),
-      },
-    );
     const unanswered = [
       ...projectRead.held.unanswered,
       ...projectRead.rooted.unanswered,
@@ -784,6 +803,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 +908,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 +948,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 +975,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 +1034,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: {

package/src/configuration-files.ts

@@ -8,6 +8,8 @@
  */
 
 import {
+  isExportDeclaration,
+  isImportDeclaration,
   isNoSubstitutionTemplateLiteral,
   isStringLiteral,
   type Node,
@@ -43,6 +45,17 @@ const DEPENDENCY_MEMBERS = [
 /** The prefixes a string names a file with, relative to the file that writes it. */
 const RELATIVE_PREFIXES = ["./", "../"] as const;
 
+/** The JavaScript extensions a relative specifier from a configuration file stands for TypeScript under. */
+const COUNTERPARTS: readonly (readonly [string, readonly string[]])[] = [
+  [".js", [".ts", ".tsx"]],
+  [".jsx", [".tsx", ".ts"]],
+  [".mjs", [".mts"]],
+  [".cjs", [".cts"]],
+];
+
+/** The extensions appended to a relative specifier from a configuration file, in order. */
+const APPENDED = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"] as const;
+
 /** The extensions the program's module resolution appends to a specifier written without one. */
 const RESOLVED_EXTENSIONS = [
   ".ts",
@@ -83,10 +96,27 @@ interface ConfigurationDocument {
   readonly strings: readonly string[];
 }
 
+/** Parses one file the program does not hold, with no type information. */
+export type ParseFile = (fileName: string, text: string) => SourceFile;
+
+/** One file no program holds that a configuration module outside the program leads to. */
+export interface OutsideModule {
+  /** The file, parsed alone. */
+  readonly file: SourceFile;
+  /** The directory of the configuration module the file was reached from, which holds its manifest. */
+  readonly manifestDir: string;
+}
+
 /** The configuration files one project holds and sits beside. */
 interface ConfigurationFiles {
   /** Every own file that is a configuration module, with the form its name has. */
   readonly modules: readonly { readonly file: SourceFile; readonly form: string }[];
+  /**
+   * Every configuration module in a directory of the project that the program does not
+   * hold, and every file such a file imports or re-exports by a relative specifier that
+   * the program does not hold either, read where a parser is given.
+   */
+  readonly outside: readonly OutsideModule[];
   /** Every JSON configuration file in a directory of the project's files or above one. */
   readonly documents: readonly ConfigurationDocument[];
 }
@@ -128,6 +158,7 @@ export function configurationFiles(
   host: Host,
   targetRoot: string,
   files: SourceFiles,
+  parse?: ParseFile,
 ): ConfigurationFiles {
   const root = resolvePath(host.workingDirectory(), targetRoot);
   const manifests = new Map<string, boolean>();
@@ -182,7 +213,111 @@ export function configurationFiles(
       documents.push({ path, strings: documentStrings(value) });
     }
   }
-  return { modules, documents };
+  return {
+    modules,
+    documents,
+    outside:
+      parse === undefined ? [] : outsideModules(host, [...dirs], files, holdsManifest, parse),
+  };
+}
+
+/** The relative specifiers one file's imports and re-exports name. */
+function relativeSpecifiers(file: SourceFile): readonly string[] {
+  return file.statements.flatMap((statement) => {
+    const specifier =
+      isImportDeclaration(statement) || isExportDeclaration(statement)
+        ? statement.moduleSpecifier
+        : undefined;
+    return specifier !== undefined &&
+      isStringLiteral(specifier) &&
+      RELATIVE_PREFIXES.some((prefix) => specifier.text.startsWith(prefix))
+      ? [specifier.text]
+      : [];
+  });
+}
+
+/**
+ * The module one relative specifier from a configuration file reaches: the path it names,
+ * that path with its JavaScript extension replaced by the TypeScript counterparts, that
+ * path with an extension appended, and a directory's `index` with one appended.
+ */
+function reachedBy(host: Host, dir: string, specifier: string): string | undefined {
+  const path = resolvePath(dir, specifier);
+  const isFile = (candidate: string): boolean => host.kindOf(candidate) === "file";
+  // A data file such as `./package.json` is no module, so its strings use no dependency.
+  if (isFile(path) && APPENDED.some((extension) => path.endsWith(extension))) {
+    return path;
+  }
+  for (const [extension, counterparts] of COUNTERPARTS) {
+    if (path.endsWith(extension)) {
+      const stem = path.slice(0, -extension.length);
+      const found = counterparts.map((one) => stem + one).find(isFile);
+      if (found !== undefined) {
+        return found;
+      }
+    }
+  }
+  const appended = APPENDED.map((extension) => path + extension).find(isFile);
+  if (appended !== undefined) {
+    return appended;
+  }
+  return host.kindOf(path) === "directory"
+    ? APPENDED.map((extension) => joinPath(path, `index${extension}`)).find(isFile)
+    : undefined;
+}
+
+/**
+ * The configuration modules of the directories that hold a manifest which the program
+ * does not hold, and the files they import by a relative specifier, until no further
+ * file joins. A file that cannot be read is skipped.
+ */
+function outsideModules(
+  host: Host,
+  dirs: readonly string[],
+  files: SourceFiles,
+  holdsManifest: (dir: string) => boolean,
+  parse: ParseFile,
+): readonly OutsideModule[] {
+  const pending: { path: string; manifestDir: string }[] = [];
+  for (const dir of [...dirs].sort()) {
+    if (!holdsManifest(dir)) {
+      continue;
+    }
+    let names: readonly string[];
+    try {
+      names = host
+        .readDirectory(dir)
+        .filter((entry) => !entry.directory && configurationModuleForm(entry.name) !== undefined)
+        .map((entry) => entry.name)
+        .sort();
+    } catch {
+      continue;
+    }
+    pending.push(...names.map((name) => ({ path: joinPath(dir, name), manifestDir: dir })));
+  }
+  const found: OutsideModule[] = [];
+  const seen = new Set<string>();
+  for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
+    if (seen.has(next.path) || files.byName.has(next.path)) {
+      continue;
+    }
+    seen.add(next.path);
+    let text: string;
+    try {
+      text = host.readFile(next.path);
+    } catch {
+      continue;
+    }
+    const file = parse(next.path, text);
+    found.push({ file, manifestDir: next.manifestDir });
+    for (const specifier of relativeSpecifiers(file)) {
+      const reached = reachedBy(host, dirnamePath(next.path), specifier);
+      if (reached !== undefined) {
+        pending.push({ path: reached, manifestDir: next.manifestDir });
+      }
+    }
+  }
+  return found;
 }
 
 /** Every dependency the manifest in one directory declares, or none where it holds none to read. */

package/src/conformance-record.ts

@@ -2,16 +2,9 @@
 // Regenerate it with `UPDATE_GOLDEN=1 npx vitest --run src/conformance.corpus.test.ts`.
 export const RECORD = {
   conformance: {
-    corpusVersion: "2.1.1",
+    corpusVersion: "2.2.0",
     result: "pass",
-    digest: "sha256:e5e456bf3a706f1fa9f906ae71e10ea98a78da52d7d99a5ed59dca8a72bbe927",
+    digest: "sha256:ce7c9087ed7b2baf3de9fa2df436b500706f4f9e94fd9e0fed633054305f06a4",
   },
-  gaps: [
-    {
-      fixture: "private-member-unread",
-      capability: "reflective-lookup",
-      reason:
-        "The reference pass resolves a string-literal element access to the member it names, so the member is live by that reference and the retained listing names no class for it.",
-    },
-  ],
+  gaps: [],
 } as const;