@cplieger/deadset-ts 8.0.0-dev.16 → 8.0.0-dev.17

package/dist/src/verbs/explain.js

@@ -1,11 +1,12 @@
 import { EXIT_CLEAN, EXIT_USAGE } from "../contract/contract.generated.js";
-import { runAnalysis } from "../analysis.js";
+import { productionMode, runAnalysis } from "../analysis.js";
 import { listing } from "../components.js";
 import { OUTSIDE, swept as judged } from "../graph.js";
 import { referenceKey } from "../matrix.js";
 import { partialNotes } from "../partial.js";
 import { resolvePath } from "../paths.js";
 import { positionKey } from "../position.js";
+import { madeByTestCode, withheldBy } from "../tests/file-class.js";
 import { resolve } from "../resolve.js";
 import {} from "./verb.js";
 import { UsageError } from "../usage.js";
@@ -107,24 +108,32 @@ function rootsOf(configured) {
     });
 }
 /**
- * The shortest path from a root or a loaded consumer to one declaration, walked breadth first
- * from every root at once in the order the run names them, a consumer's reference being the
- * first hop of a path of its own, and following the references the sweep follows: a
+ * The shortest path from a root, a loaded consumer or a test file no project holds to one
+ * declaration, walked breadth first from every root at once in the order the run names them,
+ * a reference of a consumer or of such a file being the first hop of a path of its own, as
+ * the sweep seeds them, and following the references the sweep follows: a
  * reference that reads a module reaches what the module exports, and an evaluation or a root
  * reaches the module alone. Under `production` no reference a test file made is followed,
  * which is the set the report's sweep counts.
  */
-function shortestPath(analysis, to, production) {
+function shortestPath(analysis, to, mode, support) {
     const graph = analysis.swept.matrix.union;
     const out = new Map();
     const consumed = [];
     for (const reference of referencesOf(analysis.configured)) {
-        if (production && reference.test) {
+        if (withheldBy(mode, reference, support)) {
             continue;
         }
         const { consumer } = reference;
         if (consumer !== undefined) {
-            consumed.push({ ...reference, consumer });
+            consumed.push({ reference, origin: { k: "consumer", consumer } });
+            continue;
+        }
+        if (reference.unheld === true) {
+            consumed.push({
+                reference,
+                origin: { k: "unheld", file: reference.from.replace(/#$/u, "") },
+            });
             continue;
         }
         const held = out.get(reference.from);
@@ -161,13 +170,12 @@ function shortestPath(analysis, to, production) {
     for (const root of rootsOf(analysis.configured)) {
         enter({ at: root.id, hop: undefined, previous: -1, origin: { k: "root", root } });
     }
-    // A consumer's reference is one hop long, so it joins the walk where the roots' first
-    // hops do.
+    // A consumed reference is one hop long, so it joins the walk where the roots' first hops do.
     const firstHops = steps.length;
     for (let head = 0;; head += 1) {
         if (head === firstHops) {
-            for (const reference of consumed) {
-                follow(reference, -1, { k: "consumer", consumer: reference.consumer });
+            for (const { reference, origin } of consumed) {
+                follow(reference, -1, origin);
             }
         }
         const step = steps[head];
@@ -187,15 +195,27 @@ function shortestPath(analysis, to, production) {
     }
     return undefined;
 }
+/** Where a path starts, as a line names it. */
+function originText(origin) {
+    switch (origin.k) {
+        case "root":
+            return `root ${origin.root.kind} ${origin.root.id}`;
+        case "consumer":
+            return `consumer ${origin.consumer}`;
+        case "unheld":
+            return `test file no project holds ${origin.file}`;
+    }
+}
 /** What made a reference: a declaration of the target, or a loaded consumer. */
 function madeBy(reference) {
     return reference.consumer === undefined ? reference.from : `consumer ${reference.consumer}`;
 }
-function referenceLine(reference, tail) {
-    return `  reference: ${positionKey(reference.position)}\t${reference.use}\t${tail}${reference.test ? "\tfrom a test file" : ""}\n`;
+/** One reference of an answer, marked where test code made it, a test-support file's included. */
+function referenceLine(reference, tail, support) {
+    return `  reference: ${positionKey(reference.position)}\t${reference.use}\t${tail}${madeByTestCode(reference, support) ? "\tfrom a test file" : ""}\n`;
 }
 /** Why a declaration no finding names and no exemption held back is live, or how it fell. */
-function liveness(analysis, subject, cascade) {
+function liveness(analysis, subject, cascade, mode) {
     const { sweep } = analysis.swept;
     const candidate = sweep.candidates.find((one) => one.id === subject.id);
     if (candidate === undefined && !judged(subject.kind)) {
@@ -206,12 +226,14 @@ function liveness(analysis, subject, cascade) {
     for (const root of rootsOf(analysis.configured).filter((one) => one.id === subject.id)) {
         text += `  root: ${root.kind}${root.source === "" ? "" : `\tnamed by ${root.source}`}\n`;
     }
-    const found = shortestPath(analysis, subject.id, true) ?? shortestPath(analysis, subject.id, false);
+    const support = new Set(analysis.configured.flatMap((one) => one.supportFiles ?? []));
+    const found = shortestPath(analysis, subject.id, mode, support) ??
+        shortestPath(analysis, subject.id, { production: false }, support);
     if (found !== undefined && found.path.length > 0) {
         const { origin } = found;
-        text += `  reached from: ${origin.k === "root" ? `root ${origin.root.kind} ${origin.root.id}` : `consumer ${origin.consumer}`}\n`;
+        text += `  reached from: ${originText(origin)}\n`;
         for (const hop of found.path) {
-            text += referenceLine(hop.reference, `${madeBy(hop.reference)} -> ${hop.reference.to}`);
+            text += referenceLine(hop.reference, `${madeBy(hop.reference)} -> ${hop.reference.to}`, support);
             if (hop.k === "export") {
                 text += `  export: ${hop.reference.to} -> ${hop.to}\n`;
             }
@@ -219,10 +241,11 @@ function liveness(analysis, subject, cascade) {
     }
     else if (found === undefined) {
         const references = referencesOf(analysis.configured).filter((one) => one.to === subject.id);
-        text += "  unreachable: no path of references reaches it from a root or a loaded consumer\n";
+        text +=
+            "  unreachable: no path of references reaches it from a root, a loaded consumer or a test file no project holds\n";
         text += `  references: ${String(references.length)}\n`;
         for (const reference of references) {
-            text += referenceLine(reference, `from ${madeBy(reference)}`);
+            text += referenceLine(reference, `from ${madeBy(reference)}`, support);
         }
     }
     if (candidate !== undefined) {
@@ -271,7 +294,7 @@ function namedElsewhere(findings, subject) {
         .join("");
 }
 /** The one explanation that applies to a declaration, built whole before it is written. */
-function explanation(analysis, subject, cascade) {
+function explanation(analysis, subject, cascade, mode) {
     const graph = analysis.swept.matrix.union;
     const at = graph.at(subject.id);
     let text = `symbol: ${subject.ref}\n`;
@@ -294,7 +317,7 @@ function explanation(analysis, subject, cascade) {
             "answer: held\n  held by: a question the checker did not answer, which could have kept it live, so no finding names it\n";
     }
     else {
-        text += liveness(analysis, subject, cascade);
+        text += liveness(analysis, subject, cascade, mode);
     }
     return text + namedElsewhere(analysis.result.findings, subject);
 }
@@ -302,17 +325,16 @@ function explanation(analysis, subject, cascade) {
  * Explains one symbol from the analysis the report is built from: why a reported symbol is
  * reported, which exemption classes held a retained one back, that an unanswered question held
  * a held one, and for any other declaration the relations that hold it live and the shortest
- * path from a root or a loaded consumer, or the references it has where no path reaches it. A
- * request naming no one declaration exits with the usage code and names what partially
- * matches it. Where the analysis was partial, the error stream says so.
+ * path from a root, a loaded consumer or a test file no project holds, or the references it
+ * has where no path reaches it. A request naming no one declaration exits with the usage
+ * code and names what partially matches it. Where the analysis was partial, the error stream says so.
  */
 export const explainVerb = ({ out, err, host, inputs, scope, openClient, option }) => {
     const named = namedSymbol(option);
     const { config, provenance } = resolve(inputs());
     const scoped = scope();
-    const analysis = runAnalysis(openClient(config), host, scoped, config, provenance, {
-        production: true,
-    });
+    const mode = productionMode(config);
+    const analysis = runAnalysis(openClient(config), host, scoped, config, provenance, mode);
     const { subject, candidates } = subjectOf(analysis.swept.matrix.union.symbols, named);
     const notes = partialNotes({
         notBuilt: analysis.run.notBuilt,
@@ -329,7 +351,7 @@ export const explainVerb = ({ out, err, host, inputs, scope, openClient, option
         }
     }
     else {
-        out.write(explanation(analysis, subject, config.reporters.cascade));
+        out.write(explanation(analysis, subject, config.reporters.cascade, mode));
     }
     for (const note of notes) {
         diagnose(err, note);

package/dist/src/verbs/print-retained.js

@@ -1,5 +1,5 @@
 import { EXIT_CLEAN } from "../contract/contract.generated.js";
-import { runSweep } from "../analysis.js";
+import { productionMode, runSweep } from "../analysis.js";
 import { retainedLines } from "../exempt.js";
 import { partialNotes } from "../partial.js";
 import { resolvePath } from "../paths.js";
@@ -18,7 +18,7 @@ export const printRetainedVerb = ({ out, err, host, inputs, scope, openClient })
     const scoped = scope();
     const swept = runSweep(openClient(config), host, scoped, config, {
         marked: [],
-        mode: { production: true },
+        mode: productionMode(config),
     });
     for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
         out.write(`${line}\n`);

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "8.0.0-dev.16",
+  "version": "8.0.0-dev.17",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",
@@ -48,7 +48,7 @@
     "prettier": "3.9.10",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.72.1",
-    "vitest": "5.0.5"
+    "vitest": "5.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/alias-chain.ts

@@ -49,8 +49,6 @@ export interface AliasChains {
    * link is declared.
    */
   nextDeclared(symbol: TSSymbol): readonly ChainTarget[];
-  /** How many steps the compiler was asked for: one per alias, whatever the chains it heads. */
-  readonly steps: number;
 }
 
 /**
@@ -65,7 +63,6 @@ export function aliasChains<Brand>(project: ProjectView<Brand>, held: Inventory)
   const ownFiles = project.ownPaths();
   const steps = new Map<number, Answer<TSSymbol | undefined>>();
   const chains = new Map<number, readonly ChainTarget[]>();
-  let asked = 0;
 
   const declarationsOf = (symbol: TSSymbol): string[] => {
     const ids: string[] = [];
@@ -102,7 +99,6 @@ export function aliasChains<Brand>(project: ProjectView<Brand>, held: Inventory)
       return steps.get(symbol.id);
     }
     const next = project.aliasStepOf(symbol);
-    asked += 1;
     steps.set(symbol.id, next);
     return next;
   };
@@ -197,8 +193,5 @@ export function aliasChains<Brand>(project: ProjectView<Brand>, held: Inventory)
     declarationsOf,
     chainOf,
     nextDeclared,
-    get steps() {
-      return asked;
-    },
   };
 }

package/src/amd.ts

@@ -0,0 +1,130 @@
+/**
+ * AMD's module forms (references-ts.37), read from the syntax because the binder declares
+ * none of them: `define([<ids>], factory)`, `define("<name>", [<ids>], factory)` and
+ * `require([<ids>], callback)` (https://github.com/amdjs/amdjs-api/blob/master/AMD.md).
+ */
+
+import {
+  isArrayLiteralExpression,
+  isArrowFunction,
+  isFunctionExpression,
+  isCallExpression,
+  isIdentifier,
+  isNoSubstitutionTemplateLiteral,
+  isStringLiteral,
+  type Identifier,
+  type Node,
+  type StringLiteralLikeNode,
+} from "@typescript/native/ast";
+import { hasURLScheme, isAbsolutePath, resolvePath, startsRelativePath } from "./paths.ts";
+import { parenthesesRemoved } from "./unwrap.ts";
+
+/** The platform function an AMD call is written as. */
+type AmdPlatform = "define" | "require";
+
+/** One AMD call's dependency list. */
+export interface AmdLoad {
+  /** The name the call is written with; {@link callsPlatform} owns whether it is AMD's. */
+  readonly callee: Identifier;
+  /** Each dependency id written as literal text, AMD's own `require`, `exports` and `module` left out. */
+  readonly ids: readonly AmdDependency[];
+  /** Whether the list, or an element of it, is computed, so the call may load any module. */
+  readonly computed: boolean;
+}
+
+/** One dependency id of an AMD call. */
+interface AmdDependency {
+  readonly id: StringLiteralLikeNode;
+  /**
+   * Whether the factory may receive the module's value: it declares a parameter at the id's
+   * place, a rest parameter included, or it is written as anything but a function.
+   */
+  readonly received: boolean;
+}
+
+/** The ids AMD binds to the factory's CommonJS parameters, which load no module. */
+const FREE_VARIABLES: ReadonlySet<string> = new Set(["require", "exports", "module"]);
+
+/** The platform function `callee` is written as. */
+export function amdPlatform(callee: Identifier): AmdPlatform {
+  return callee.text === "define" ? "define" : "require";
+}
+
+/**
+ * The dependency list one call writes, where it is a call of a bare `define` or `require` in
+ * one of AMD's forms. A `define` with no list, of a factory or a value alone, loads nothing;
+ * a `require` whose first argument is no array literal is CommonJS's.
+ */
+export function amdLoadOf(node: Node): AmdLoad | undefined {
+  if (!isCallExpression(node)) {
+    return undefined;
+  }
+  const callee = parenthesesRemoved(node.expression);
+  if (!isIdentifier(callee) || (callee.text !== "define" && callee.text !== "require")) {
+    return undefined;
+  }
+  const written = node.arguments.map((one) => parenthesesRemoved(one));
+  const [first] = written;
+  if (first === undefined) {
+    return undefined;
+  }
+  const define = callee.text === "define";
+  const named = define && isLiteralText(first);
+  const list = written[named ? 1 : 0];
+  if (list !== undefined && isArrayLiteralExpression(list)) {
+    const elements = list.elements.map((one) => parenthesesRemoved(one));
+    const factory = written[named ? 2 : 1];
+    const ids = elements.flatMap((one, at) =>
+      isLiteralText(one) && !FREE_VARIABLES.has(one.text)
+        ? [{ id: one, received: receives(factory, at) }]
+        : [],
+    );
+    return { callee, ids, computed: elements.some((one) => !isLiteralText(one)) };
+  }
+  if (!define) {
+    return undefined;
+  }
+  // A factory after the list's place makes what stands there a list, here a computed one.
+  return { callee, ids: [], computed: written.length > (named ? 2 : 1) };
+}
+
+function isLiteralText(node: Node): node is StringLiteralLikeNode {
+  return isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node);
+}
+
+/** Whether a factory may receive the dependency at place `at` of its list. */
+function receives(factory: Node | undefined, at: number): boolean {
+  if (factory === undefined) {
+    return false;
+  }
+  if (!isFunctionExpression(factory) && !isArrowFunction(factory)) {
+    return true;
+  }
+  const { parameters } = factory;
+  return at < parameters.length || parameters.some((one) => one.dotDotDotToken !== undefined);
+}
+
+/**
+ * The path a dependency id names against the calling file's directory: a relative module id,
+ * `./` or `../` with no `.js` ending, with `.js` appended. RequireJS reads any other id
+ * through its configuration or as a URL against the page, which the analysis does not know.
+ */
+export function amdPath(dir: string, id: string): string | undefined {
+  return startsRelativePath(id) && !id.endsWith(".js") ? resolvePath(dir, `${id}.js`) : undefined;
+}
+
+/**
+ * Whether one call may load a file the analysis cannot name: a computed list, or an id that
+ * RequireJS reads as a URL, one ending in `.js`, starting with `/` or carrying a scheme. Any
+ * other id {@link amdPath} reads no path from is a package's.
+ */
+export function amdUnresolved(load: AmdLoad): boolean {
+  return (
+    load.computed ||
+    load.ids.some(
+      ({ id }) =>
+        amdPath("/", id.text) === undefined &&
+        (id.text.endsWith(".js") || isAbsolutePath(id.text) || hasURLScheme(id.text)),
+    )
+  );
+}