@cplieger/deadset-ts 3.1.0 → 3.3.0

package/src/member-names.ts

@@ -0,0 +1,89 @@
+/**
+ * The members of one project's inventory by the name each is written with, for the
+ * classes whose evidence is a name rather than a type relation: a template and a
+ * string key both hold a name and nothing else, so each holds back every member of
+ * that name its own mechanism can reach.
+ */
+
+import {
+  isIdentifier,
+  isNumericLiteral,
+  isPrivateIdentifier,
+  isStringLiteral,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+import { nodeKey, type Inventory, type InventorySymbol, type SymbolKind } from "./inventory.ts";
+
+/** The kinds of declaration a member name can name. */
+const MEMBER_KINDS: ReadonlySet<SymbolKind> = new Set([
+  "method",
+  "class-member",
+  "interface-method",
+  "type-member",
+  "enum-member",
+]);
+
+/**
+ * The name a member declaration is written with: an identifier's text, a private
+ * name's text without its `#`, a string key's value and a numeric key's text. A
+ * private name is indexed under the name a template or a string would spell, so the
+ * rule that no such evidence holds it back is the framework's alone. A computed key
+ * names nothing a string can be equal to before the program runs.
+ */
+function writtenName(name: Node | undefined): string | undefined {
+  if (name === undefined) {
+    return undefined;
+  }
+  if (isPrivateIdentifier(name)) {
+    return name.text.replace(/^#/u, "");
+  }
+  if (isIdentifier(name)) {
+    return name.text;
+  }
+  if (isStringLiteral(name) || isNumericLiteral(name)) {
+    return name.text;
+  }
+  return undefined;
+}
+
+/**
+ * Every member the inventory holds, keyed by the name it is written with, each
+ * member once and in inventory order. A getter and a setter of one name are one
+ * member.
+ */
+export function memberNames(
+  files: readonly SourceFile[],
+  held: Inventory,
+): ReadonlyMap<string, readonly InventorySymbol[]> {
+  const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+  const named = new Map<string, string>();
+  for (const file of files) {
+    const visit = (node: Node): void => {
+      const id = held.declarations.get(nodeKey(file, node));
+      const symbol = id === undefined ? undefined : byId.get(id);
+      if (symbol !== undefined && MEMBER_KINDS.has(symbol.kind)) {
+        const name = writtenName((node as { readonly name?: Node }).name);
+        if (name !== undefined) {
+          named.set(symbol.id, name);
+        }
+      }
+      node.forEachChild(visit);
+    };
+    visit(file);
+  }
+  const index = new Map<string, InventorySymbol[]>();
+  for (const symbol of held.symbols) {
+    const name = named.get(symbol.id);
+    if (name === undefined) {
+      continue;
+    }
+    const members = index.get(name);
+    if (members === undefined) {
+      index.set(name, [symbol]);
+    } else {
+      members.push(symbol);
+    }
+  }
+  return index;
+}

package/src/references.ts

@@ -2,6 +2,7 @@ import {
   isArrayLiteralExpression,
   isBinaryExpression,
   isCallExpression,
+  isDecorator,
   isDeleteExpression,
   isElementAccessExpression,
   isExportDeclaration,
@@ -53,9 +54,11 @@ import type { ProjectView } from "./session.ts";
 /**
  * How one reference uses the declaration it names. An `evaluation` names a file: the
  * place it is written imports the module, which runs the module's top level and reads
- * none of what it exports. A `read` of a file reads the module's namespace.
+ * none of what it exports. A `read` of a file reads the module's namespace. A
+ * `decorator` names the declaration a decorator expression is attached to, which the
+ * decorator receives when the class is defined.
  */
-export type Use = "read" | "write" | "evaluation";
+export type Use = "read" | "write" | "evaluation" | "decorator";
 
 /**
  * Which accessor answered for one reference, so that the cost of a run is attributable
@@ -67,8 +70,9 @@ export type Use = "read" | "write" | "evaluation";
  * - `shorthand` is the per-node lookup for `{ a }`, whose name resolves to the property
  *   the literal declares rather than to the declaration that name reads.
  * - `alias` is a step along an import or export chain, from one link to what it names.
+ * - `syntax` is the tree alone, which says what a decorator is attached to.
  */
-export type Resolution = "batch" | "resolved-symbol" | "shorthand" | "alias";
+export type Resolution = "batch" | "resolved-symbol" | "shorthand" | "alias" | "syntax";
 
 /** One use of one declaration by one declaration. */
 export interface Reference {
@@ -318,11 +322,18 @@ interface Evaluation {
   readonly from: string;
 }
 
-/** Everything one file's walk found to resolve. */
+/** One decorator expression, and the declaration it is attached to. */
+interface Decorated {
+  readonly decorator: Node;
+  readonly declaration: string;
+}
+
+/** Everything one file's walk found to resolve, and the decorators it needs no resolution for. */
 interface FileSites {
   readonly uses: readonly Site[];
   readonly links: readonly Link[];
   readonly evaluations: readonly Evaluation[];
+  readonly decorated: readonly Decorated[];
 }
 
 /** Whether one node is a string literal or a template literal with no substitution. */
@@ -418,6 +429,7 @@ function sitesOf(
   const found: Site[] = [];
   const links: Link[] = [];
   const evaluations: Evaluation[] = [];
+  const decorated: Decorated[] = [];
   const writes = new Set<number>();
   const declared = new Set<number>();
   const shorthands = new Map<number, Node>();
@@ -464,13 +476,18 @@ function sitesOf(
     const outer = enclosing;
     if (held !== undefined) {
       enclosing = held;
+      for (const modifier of (node as { readonly modifiers?: readonly Node[] }).modifiers ?? []) {
+        if (isDecorator(modifier)) {
+          decorated.push({ decorator: modifier, declaration: held });
+        }
+      }
     }
     node.forEachChild(visit);
     enclosing = outer;
   };
 
   file.forEachChild(visit);
-  return { uses: found, links, evaluations };
+  return { uses: found, links, evaluations, decorated };
 }
 
 /**
@@ -567,7 +584,25 @@ export function references<Brand>(
     if (test) {
       tests.push(path);
     }
-    const { uses, links, evaluations } = sitesOf(file, declarations, declaredAt(file) ?? "");
+    const { uses, 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.
+    for (const { decorator, declaration } of decorated) {
+      found.push({
+        from: declaration,
+        to: declaration,
+        position: renderPosition(file, targetRoot, decorator.getStart()),
+        use: "decorator",
+        resolution: "syntax",
+        test,
+      });
+    }
 
     // One batch per capped run of the file's name nodes, the re-exports' nodes after
     // the uses and the evaluated modules' specifiers last, each node once: a bare star

package/src/reflective-lookup.ts

@@ -0,0 +1,127 @@
+/**
+ * The reflective-lookup class: a member is held back, at the lowest confidence, when
+ * a string literal equal to its name is the key of an element access or the property
+ * key of a `Reflect.get`, `Reflect.set` or `Reflect.has` call, because the member is
+ * then read by a name the program computes nowhere the reference pass can follow.
+ *
+ * The evidence is a string beside a lookup rather than a type relation, so the
+ * string reaches every member of that name on any type, static members included,
+ * and every record names the string's own position. A key that is not literal text
+ * holds nothing back: a computed name is the case no exact rule serves. `Reflect` is
+ * the global one only: a local declaration of that name is a different object.
+ */
+
+import {
+  isCallExpression,
+  isElementAccessExpression,
+  isIdentifier,
+  isNoSubstitutionTemplateLiteral,
+  isPropertyAccessExpression,
+  isStringLiteral,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+import type { DetectorInput, Evidence } from "./exempt.ts";
+import { memberNames } from "./member-names.ts";
+import { renderPosition } from "./position.ts";
+
+/** The `Reflect` methods whose second argument is a property key. */
+const REFLECT_KEYED: ReadonlySet<string> = new Set(["get", "set", "has"]);
+
+/** One literal key at one lookup, and how the lookup is spelled in a record. */
+interface Lookup {
+  readonly key: Node;
+  readonly name: string;
+  readonly callee: string;
+  /** The `Reflect` the call names, where the lookup is a `Reflect` call. */
+  readonly reflect: Node | undefined;
+}
+
+/** The text one key denotes, where it is literal text. */
+function literalText(node: Node | undefined): string | undefined {
+  if (node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node))) {
+    return node.text;
+  }
+  return undefined;
+}
+
+/** Every lookup one file writes with a literal key, in source order. */
+function lookupsOf(file: SourceFile): readonly Lookup[] {
+  const found: Lookup[] = [];
+  const visit = (node: Node): void => {
+    if (isElementAccessExpression(node)) {
+      const name = literalText(node.argumentExpression);
+      if (name !== undefined) {
+        found.push({
+          key: node.argumentExpression,
+          name,
+          callee: `[${JSON.stringify(name)}]`,
+          reflect: undefined,
+        });
+      }
+    } else if (isCallExpression(node) && isPropertyAccessExpression(node.expression)) {
+      const target = node.expression.expression;
+      const method = node.expression.name;
+      const key = node.arguments[1];
+      const name = literalText(key);
+      if (
+        isIdentifier(target) &&
+        target.text === "Reflect" &&
+        isIdentifier(method) &&
+        REFLECT_KEYED.has(method.text) &&
+        key !== undefined &&
+        name !== undefined
+      ) {
+        found.push({ key, name, callee: `Reflect.${method.text}`, reflect: target });
+      }
+    }
+    node.forEachChild(visit);
+  };
+  file.forEachChild(visit);
+  return found;
+}
+
+/**
+ * The reflective-lookup detector: every member whose name a literal key of a lookup
+ * spells, recorded at the key.
+ */
+export function reflectiveLookup<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
+  const { project, held, targetRoot } = input;
+  const files = project.ownSourceFiles();
+  const lookups = files.flatMap(lookupsOf);
+  if (lookups.length === 0) {
+    return [];
+  }
+
+  // Whether each written `Reflect` is the global one, asked in one batch: a
+  // declaration of that name in one of the project's own files shadows it.
+  const ownFiles = new Set(files.map((file) => file.fileName));
+  const reflects = lookups.flatMap((lookup) =>
+    lookup.reflect === undefined ? [] : [lookup.reflect],
+  );
+  const global = new Set<Node>();
+  if (reflects.length > 0) {
+    project.symbolsAt(reflects.map((node) => project.handle(node))).forEach((symbol, index) => {
+      const node = reflects[index];
+      const declaredHere = symbol?.declarations.some((declaration) =>
+        ownFiles.has(declaration.path),
+      );
+      if (node !== undefined && declaredHere === false) {
+        global.add(node);
+      }
+    });
+  }
+
+  const members = memberNames(files, held);
+  const found: Evidence[] = [];
+  for (const lookup of lookups) {
+    if (lookup.reflect !== undefined && !global.has(lookup.reflect)) {
+      continue;
+    }
+    const site = renderPosition(lookup.key.getSourceFile(), targetRoot, lookup.key.getStart());
+    for (const member of members.get(lookup.name) ?? []) {
+      found.push({ id: member.id, detail: `looked up by ${lookup.callee}`, site });
+    }
+  }
+  return found;
+}

package/src/run.ts

@@ -1,4 +1,4 @@
-import { runRoots, type RunRoot } from "./analysis.ts";
+import { runRoots, runSweep, type RunRoot } from "./analysis.ts";
 import { ConfigError, REPOSITORY_DOCUMENT, type Inputs } from "./config.ts";
 import {
   diagnosticErrors,
@@ -6,6 +6,7 @@ import {
   DiscoveryError,
   renderDiagnostic,
 } from "./discover.ts";
+import { retainedLines } from "./exempt.ts";
 import type { Host } from "./host.ts";
 import { joinPath, resolvePath } from "./paths.ts";
 import { printConfig } from "./print.ts";
@@ -221,6 +222,9 @@ export function run(
   if (verb === "print-roots") {
     return printRootsVerb(args.slice(1), out, err, host, openClient);
   }
+  if (verb === "print-retained") {
+    return printRetainedVerb(args.slice(1), out, err, host, openClient);
+  }
   if (verb !== undefined && (VERBS as readonly string[]).includes(verb)) {
     err.write(`deadset-ts: ${verb} is not implemented\n`);
     return EXIT_USAGE;
@@ -337,6 +341,40 @@ function printRootsVerb(
   }
 }
 
+/**
+ * Writes every declaration an exemption held back in the production sweep a report is
+ * built from, one per line, and nothing where no exemption held one back. One fact
+ * several configurations found is one record, so the line names no configuration. The
+ * line shape is this command's own rather than a Contract format, so that sort and cut
+ * read it.
+ */
+function printRetainedVerb(
+  args: readonly string[],
+  out: Writer,
+  err: Writer,
+  host: Host,
+  openClient: (collectTiming: boolean) => Engine,
+): number {
+  let engine: Engine | undefined;
+  try {
+    const options = readOptions(args);
+    const { config } = resolve(inputsOf(host, options));
+    const scope = scopeOf(host, options);
+    engine = openClient(false);
+    const swept = runSweep(engine, host, scope, config, {
+      marked: [],
+      mode: { production: true },
+    });
+    for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
+      out.write(`${line}\n`);
+    }
+    return EXIT_CLEAN;
+  } catch (error: unknown) {
+    engine?.close();
+    return refuse(error, err);
+  }
+}
+
 /** Turns one refusal into the exit code the Contract's table gives it. */
 function refuse(error: unknown, err: Writer): number {
   if (error instanceof ConfigError) {

package/src/sweep.ts

@@ -6,11 +6,24 @@
  * declaration only unreachable ones reference is live under the first, dead under the second.
  */
 
+import type { TSExemptionClass } from "./exempt-classes.ts";
 import { namesACaller, OUTSIDE, type Graph } from "./graph.ts";
+import type { Position } from "./position.ts";
 
 /** The liveness relation that decided a declaration, as a finding spells it. */
 export type Relation = "reference-counting" | "reachability";
 
+/** One declaration an exemption class holds back, and the evidence it was found by. */
+export interface Exemption {
+  /** The identifier of the declaration held back. */
+  readonly id: string;
+  readonly class: TSExemptionClass;
+  /** One clause naming the relation, then the thing it relates to: `passed to JSON.stringify`. */
+  readonly detail: string;
+  /** Where the evidence is written. */
+  readonly site: Position;
+}
+
 /**
  * The run's reference mode, decided once by the composition and read by every stage
  * that counts references.
@@ -31,6 +44,13 @@ export interface SweepInput {
    * nothing only a marked declaration references is dead.
    */
   readonly marked: readonly string[];
+  /**
+   * The exemptions the run computed. An exempt declaration is never a candidate, and it
+   * seeds reachability as a mark does, so nothing it references is dead; it is live
+   * under reference counting only where something references it. Absent, the sweep
+   * holds nothing back.
+   */
+  readonly exempt?: readonly Exemption[];
   readonly mode: Mode;
 }
 
@@ -69,19 +89,19 @@ export interface Liveness {
  *
  * The order is the order the answers depend on: the callers and the marks are live
  * before either relation runs, the candidate set is every judged declaration at least
- * one relation does not hold live, and the tests of dead code join it.
+ * one relation does not hold live and no exemption holds back, and the tests of dead
+ * code join it.
  */
 export function sweep(graph: Graph, input: SweepInput): Liveness {
-  const marked = graph.symbols.map(() => false);
-  for (const id of input.marked) {
-    const at = graph.at(id);
-    if (at !== OUTSIDE) {
-      marked[at] = true;
-    }
-  }
-  // Every root and every mark seeds reachability. A root of a kind that names a caller,
-  // and a mark, are live under reference counting as well; a root that only supposes a
-  // caller is not.
+  const marked = flagged(graph, input.marked);
+  const exempt = flagged(
+    graph,
+    (input.exempt ?? []).map((record) => record.id),
+  );
+  const held = marked.map((mark, at) => mark || exempt[at] === true);
+  // Every root, every mark and every exemption seeds reachability. A root of a kind that
+  // names a caller, and a mark, are live under reference counting as well; a root that
+  // only supposes a caller is not, and neither is an exemption.
   const called = graph.symbols.map(() => false);
   for (const root of graph.rooted) {
     if (namesACaller(root.kind)) {
@@ -96,7 +116,7 @@ export function sweep(graph: Graph, input: SweepInput): Liveness {
     }
     return input.mode.production ? made.production : made.production + made.test;
   };
-  const reached = reachable(graph, marked, input.mode);
+  const reached = reachable(graph, held, input.mode);
   const liveUnder = graph.symbols.map((_symbol, at): readonly Relation[] => {
     const relations: Relation[] = [];
     if (marked[at] === true || called[at] === true || counted(at) > 0) {
@@ -109,9 +129,10 @@ export function sweep(graph: Graph, input: SweepInput): Liveness {
   });
 
   const dead = graph.symbols.map(
-    (_symbol, at) => graph.subject[at] === true && (liveUnder[at]?.length ?? 0) < 2,
+    (_symbol, at) =>
+      graph.subject[at] === true && exempt[at] !== true && (liveUnder[at]?.length ?? 0) < 2,
   );
-  const testOfDeadCode = admitTestsOfDeadCode(graph, dead, marked);
+  const testOfDeadCode = admitTestsOfDeadCode(graph, dead, held);
 
   const candidates: Candidate[] = [];
   const live = new Map<string, readonly Relation[]>();
@@ -135,13 +156,26 @@ export function sweep(graph: Graph, input: SweepInput): Liveness {
   return { liveUnder: live, candidates };
 }
 
+/** Per declaration of the graph, whether one of the identifiers names it. */
+function flagged(graph: Graph, ids: readonly string[]): boolean[] {
+  const flags = graph.symbols.map(() => false);
+  for (const id of ids) {
+    const at = graph.at(id);
+    if (at !== OUTSIDE) {
+      flags[at] = true;
+    }
+  }
+  return flags;
+}
+
 /**
  * Per declaration, whether a seed reaches it. The two seeds reach through different
- * reference sets: a marked declaration is live by a mechanism the analysis cannot see, so
- * no mode withholds a reference it makes, while a root reaches through the references the
- * mode counts. The marks run first, so what they reach is expanded under the wider rule.
+ * reference sets: a held declaration, marked or exempt, is live by a mechanism the
+ * analysis cannot see, so no mode withholds a reference it makes, a test declaration's
+ * included, while a root reaches through the references the mode counts. The held seed
+ * runs first, so what it reaches is expanded under the wider rule.
  */
-function reachable(graph: Graph, marked: readonly boolean[], mode: Mode): readonly boolean[] {
+function reachable(graph: Graph, held: readonly boolean[], mode: Mode): readonly boolean[] {
   const reached = graph.symbols.map(() => false);
   const expanded = graph.symbols.map(() => false);
   const queue: number[] = [];
@@ -164,10 +198,10 @@ function reachable(graph: Graph, marked: readonly boolean[], mode: Mode): readon
       enter(exported, false);
     }
   };
-  const walk = (held: boolean): void => {
+  const walk = (holding: boolean): void => {
     for (let at = queue.pop(); at !== undefined; at = queue.pop()) {
       for (const edge of graph.out[at] ?? []) {
-        if (!held && mode.production && edge.test) {
+        if (!holding && mode.production && edge.test) {
           continue;
         }
         enter(edge.to, !edge.evaluation);
@@ -175,8 +209,8 @@ function reachable(graph: Graph, marked: readonly boolean[], mode: Mode): readon
     }
   };
 
-  marked.forEach((mark, at) => {
-    if (mark) {
+  held.forEach((hold, at) => {
+    if (hold) {
       enter(at, false);
     }
   });
@@ -192,16 +226,17 @@ function reachable(graph: Graph, marked: readonly boolean[], mode: Mode): readon
  * Admits every test declaration whose set of referenced production declarations is
  * non-empty and wholly dead, and returns which it admitted. The set is read from every
  * reference the test makes, not the ones the mode counts: a production sweep counts none,
- * which is what makes the targets dead. A test referencing one live target is never admitted.
+ * which is what makes the targets dead. A test referencing one live target is never
+ * admitted, and neither is a marked or exempt test.
  */
 function admitTestsOfDeadCode(
   graph: Graph,
   dead: boolean[],
-  marked: readonly boolean[],
+  held: readonly boolean[],
 ): readonly boolean[] {
   const admitted = graph.symbols.map(() => false);
   graph.symbols.forEach((_symbol, at) => {
-    if (graph.test[at] !== true || graph.subject[at] !== true || marked[at] === true) {
+    if (graph.test[at] !== true || graph.subject[at] !== true || held[at] === true) {
       return;
     }
     let targets = 0;