@cplieger/deadset-ts 3.0.0 → 3.2.0

package/src/alias-chain.ts

@@ -0,0 +1,135 @@
+/**
+ * Where an import or export chain leads in one project: from one symbol to each
+ * declaration of the target it is, and along the chain of aliases it heads to each
+ * declaration every link of that chain is.
+ */
+
+import { SymbolFlags, type Symbol as TSSymbol } from "@typescript/native/unstable/sync";
+import { nodeKey, type Inventory } from "./inventory.ts";
+import type { ProjectView } from "./session.ts";
+
+/** One declaration a chain reaches, and whether a step along an alias reached it. */
+export interface ChainTarget {
+  readonly id: string;
+  /** False for a declaration the head symbol itself is, true for one a link stands for. */
+  readonly stepped: boolean;
+}
+
+/** The chain walks over one project's aliases, each step asked of the compiler once. */
+export interface AliasChains {
+  /**
+   * The declarations of the inventory one symbol is, each once. A declaration outside
+   * the project's own files belongs to another program and is not one of them.
+   */
+  declarationsOf(symbol: TSSymbol): readonly string[];
+  /**
+   * The declarations one symbol is, and those of every link of the alias chain it
+   * stands at the head of, each once and in chain order. A link the inventory does
+   * not declare is stepped over rather than named.
+   */
+  chainOf(symbol: TSSymbol): readonly ChainTarget[];
+  /**
+   * The declarations of the first link after `symbol` along its chain that the
+   * inventory declares, stepping over the links it does not, or none where no later
+   * link is declared.
+   */
+  nextDeclared(symbol: TSSymbol): readonly string[];
+  /** How many steps the compiler was asked for: one per alias, whatever the chains it heads. */
+  readonly steps: number;
+}
+
+/**
+ * The chain walks over one project, against the declarations of `held`, the same
+ * project's inventory.
+ *
+ * A declaration handle carries the file it is in, so whether it is one of the
+ * project's own files is answered before the handle is resolved: a declaration of a
+ * library file is never fetched to find out that the inventory does not hold it.
+ */
+export function aliasChains<Brand>(project: ProjectView<Brand>, held: Inventory): AliasChains {
+  const ownFiles = new Set(project.ownSourceFiles().map((file) => file.fileName));
+  const steps = new Map<number, TSSymbol | undefined>();
+  const chains = new Map<number, readonly ChainTarget[]>();
+  let asked = 0;
+
+  const declarationsOf = (symbol: TSSymbol): string[] => {
+    const ids: string[] = [];
+    for (const handle of symbol.declarations) {
+      if (!ownFiles.has(handle.path)) {
+        continue;
+      }
+      const node = project.declarationAt(handle)?.node;
+      const id =
+        node === undefined ? undefined : held.declarations.get(nodeKey(node.getSourceFile(), node));
+      if (id !== undefined && !ids.includes(id)) {
+        ids.push(id);
+      }
+    }
+    return ids;
+  };
+
+  /**
+   * What one alias names, one link along. Only a symbol the binder flagged an alias is
+   * asked, which is the condition the step asserts on: a default export of an
+   * expression is written in an alias form and names nothing declared elsewhere, so its
+   * chain ends at itself.
+   */
+  const stepOf = (symbol: TSSymbol): TSSymbol | undefined => {
+    if ((symbol.flags & SymbolFlags.Alias) === 0) {
+      return undefined;
+    }
+    if (steps.has(symbol.id)) {
+      return steps.get(symbol.id);
+    }
+    const next = project.aliasStepOf(symbol);
+    asked += 1;
+    steps.set(symbol.id, next);
+    return next;
+  };
+
+  const chainOf = (symbol: TSSymbol): readonly ChainTarget[] => {
+    const cached = chains.get(symbol.id);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const targets: ChainTarget[] = [];
+    const walked = new Set<number>();
+    let at: TSSymbol | undefined = symbol;
+    let stepped = false;
+    while (at !== undefined && !walked.has(at.id)) {
+      walked.add(at.id);
+      for (const id of declarationsOf(at)) {
+        if (!targets.some((target) => target.id === id)) {
+          targets.push({ id, stepped });
+        }
+      }
+      at = stepOf(at);
+      stepped = true;
+    }
+    chains.set(symbol.id, targets);
+    return targets;
+  };
+
+  const nextDeclared = (symbol: TSSymbol): readonly string[] => {
+    const walked = new Set<number>([symbol.id]);
+    let at = stepOf(symbol);
+    while (at !== undefined && !walked.has(at.id)) {
+      walked.add(at.id);
+      const ids = declarationsOf(at);
+      if (ids.length > 0) {
+        return ids;
+      }
+      at = stepOf(at);
+    }
+    return [];
+  };
+
+  return {
+    declarationsOf,
+    chainOf,
+    nextDeclared,
+    get steps() {
+      return asked;
+    },
+  };
+}

package/src/analysis.ts

@@ -11,18 +11,25 @@
 import type { Diagnostic } from "@typescript/native/unstable/sync";
 import type { Config, Provenance } from "./config.ts";
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.ts";
+import {
+  computeExemptions,
+  disabledClasses,
+  exemptionsOf,
+  retainedIn,
+  type Detectors,
+} from "./exempt.ts";
 import type { Finding } from "./finding.ts";
-import { graphOf } from "./graph.ts";
 import type { Host } from "./host.ts";
-import { inventory, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { inventory, type Inventory } from "./inventory.ts";
 import { readManifest } from "./manifest.ts";
+import { matrixOf, sweepMatrix, type Configured, type Matrix, type SweepResult } from "./matrix.ts";
 import { relativePath, resolvePath } from "./paths.ts";
 import { byPosition, type Position } from "./position.ts";
 import { references } from "./references.ts";
 import { roots, unmatchedEverywhere, unmatchedRoots, type RootKind, type Roots } from "./roots.ts";
 import type { Scope } from "./scope.ts";
 import { diagnosticsOf, runSession, type Engine, type ProjectView } from "./session.ts";
-import { sweep, type SweepInput, type SweepResult } from "./sweep.ts";
+import type { Exemption, SweepInput } from "./sweep.ts";
 
 /** The setting whose source decides where a finding about a configured root sits. */
 const ROOTS_SETTING = "roots.patterns";
@@ -43,7 +50,7 @@ export interface RunRoot {
 export interface RunRoots {
   /**
    * The configurations the run analyzed, each by the name discovery gives its
-   * project, in discovery order.
+   * project, in discovery order: the order a declared matrix lists them in.
    */
   readonly configurations: readonly string[];
   /**
@@ -122,10 +129,7 @@ function readProjects<Answer>(
     }
     const held = inventory(project, host, targetRoot);
     const rooted = roots(project, held, targetRoot, options);
-    const configuration =
-      ids.get(project.configFile) ??
-      relativePath(targetRoot, project.configFile) ??
-      project.configFile;
+    const configuration = ids.get(project.configFile) ?? project.configFile;
     return stage(project, { configuration, held, rooted });
   });
   if (failures.length > 0) {
@@ -195,42 +199,59 @@ export function runRoots(
   };
 }
 
-/** One configuration's sweep, beside the declarations it judged. */
-export interface ConfigurationSweep {
-  /** The name discovery gives the configuration's project. */
-  readonly configuration: string;
-  readonly symbols: readonly InventorySymbol[];
+/** The run's sweep, beside the matrix it judged. */
+export interface RunSweep {
+  readonly matrix: Matrix;
   readonly sweep: SweepResult;
+  /**
+   * The exemption records that held back a declaration some configuration of the run
+   * would otherwise judge dead, in the declarations' site order.
+   */
+  readonly retained: readonly Exemption[];
 }
 
+/** The exemption classes this analyzer detects, each by its detector; any other retains nothing. */
+const DETECTORS: Detectors = new Map();
+
 /**
- * Sweeps every project of the run the scope and the configuration describe, one
- * configuration at a time, in discovery order. Each project's references are read
- * against its own inventory with the configured test-file patterns, and its graph is
- * swept under the input the caller decided once for the run.
+ * Sweeps the run the scope and the configuration describe. Each project's references
+ * 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 runSweeps(
+export function runSweep(
   engine: Engine,
   host: Host,
   scope: Scope,
   config: Config,
-  input: SweepInput,
-): readonly ConfigurationSweep[] {
+  input: Pick<SweepInput, "marked" | "mode">,
+  detectors: Detectors = DETECTORS,
+): RunSweep {
   const targetRoot = scope.target.path;
-  return readProjects(engine, host, scope, config, (project, read) => {
-    const resolved = references(project, read.held, targetRoot, {
+  const disabled = disabledClasses(config);
+  const read = readProjects(engine, host, scope, config, (project, projectRead) => {
+    const resolved = references(project, projectRead.held, targetRoot, {
       testFiles: config.ts.testFiles,
     });
-    const graph = graphOf(
-      read.held.symbols,
-      resolved.references,
-      read.rooted.liveUnderReachability,
-      resolved.testFilePaths,
-    );
-    return {
-      configuration: read.configuration,
-      symbols: read.held.symbols,
-      sweep: sweep(graph, input),
+    const configured: Configured = {
+      configuration: projectRead.configuration,
+      symbols: projectRead.held.symbols,
+      references: resolved.references,
+      roots: projectRead.rooted.liveUnderReachability,
+      testFiles: resolved.testFilePaths,
     };
+    const exempt = computeExemptions({ project, held: projectRead.held, targetRoot }, detectors, {
+      disabled,
+      mode: input.mode,
+      testFiles: new Set(resolved.testFilePaths),
+    });
+    return { configured, exempt };
   });
+  const matrix = matrixOf(read.map((one) => one.configured));
+  const swept: SweepInput = { ...input, exempt: exemptionsOf(read.flatMap((one) => one.exempt)) };
+  return { matrix, sweep: sweepMatrix(matrix, swept), retained: retainedIn(matrix, swept) };
 }

package/src/components.ts

@@ -35,7 +35,7 @@ export interface Component {
    * neither and is counted by its own component.
    */
   readonly falls: readonly string[];
-  /** The source lines the deletion removes, summed over {@link Component.falls}. */
+  /** The source lines the deletion removes: the distinct lines {@link Component.falls} spans. */
   readonly deletableLines: number;
 }
 

package/src/exempt-classes.ts

@@ -0,0 +1,69 @@
+/**
+ * The exemption classes of the Contract's vocabulary, in its order: each class's name,
+ * the languages it runs on and the confidence it is recorded at.
+ *
+ * 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.
+ */
+
+import type { Confidence, Language } from "./config.ts";
+
+/** One class of the vocabulary. */
+interface ExemptionClassRow {
+  readonly class: string;
+  readonly languages: readonly Language[];
+  readonly confidence: Confidence;
+}
+
+/** Every class of the vocabulary, in the order the Contract lists them. */
+export const EXEMPTION_CLASSES = [
+  { class: "interface-satisfaction", languages: ["go", "ts"], confidence: "certain" },
+  { 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" },
+  { class: "generated-file", languages: ["go"], confidence: "certain" },
+  { class: "linkname-cgo-asm-plugin", languages: ["go"], confidence: "certain" },
+  { class: "template-field", languages: ["go", "ts"], confidence: "possible" },
+  { class: "reflective-lookup", languages: ["go", "ts"], confidence: "possible" },
+  { class: "decorator", languages: ["ts"], confidence: "certain" },
+  { class: "injection-container", languages: ["ts"], confidence: "certain" },
+  { class: "framework-lifecycle", languages: ["ts"], confidence: "certain" },
+  { class: "serialization-contract", languages: ["ts"], confidence: "certain" },
+] as const satisfies readonly ExemptionClassRow[];
+
+type Row = (typeof EXEMPTION_CLASSES)[number];
+
+/** The name of a class of the vocabulary. */
+export type ExemptionClass = Row["class"];
+
+/** The classes of the rows that list one language. */
+type ClassesOf<R, L extends Language> = R extends {
+  readonly class: infer C;
+  readonly languages: readonly (infer Listed)[];
+}
+  ? L extends Listed
+    ? C
+    : never
+  : never;
+
+/** The name of a class that runs on TypeScript, the only classes this analyzer records. */
+export type TSExemptionClass = ClassesOf<Row, "ts">;
+
+function runsOnTS(row: Row): row is Extract<Row, { readonly class: TSExemptionClass }> {
+  const languages: readonly Language[] = row.languages;
+  return languages.includes("ts");
+}
+
+/** The classes that run on TypeScript, in the vocabulary's order. */
+export const TS_EXEMPTION_CLASSES: readonly TSExemptionClass[] = EXEMPTION_CLASSES.filter(
+  runsOnTS,
+).map((row) => row.class);
+
+/** Whether one name is a class of the vocabulary, whichever language it runs on. */
+export function isExemptionClass(name: string): name is ExemptionClass {
+  return EXEMPTION_CLASSES.some((row) => row.class === name);
+}

package/src/exempt.ts

@@ -0,0 +1,200 @@
+/**
+ * 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 type { Config } from "./config.ts";
+import { ConfigError } from "./config.ts";
+import {
+  EXEMPTION_CLASSES,
+  isExemptionClass,
+  TS_EXEMPTION_CLASSES,
+  type ExemptionClass,
+  type TSExemptionClass,
+} from "./exempt-classes.ts";
+import type { Inventory, InventorySymbol } from "./inventory.ts";
+import type { Matrix } from "./matrix.ts";
+import { byPosition, positionKey, type Position } from "./position.ts";
+import type { ProjectView } from "./session.ts";
+import { sweep, type Exemption, type Mode, type SweepInput } from "./sweep.ts";
+
+/** One declaration a detector holds back, and where and why. */
+export interface Evidence {
+  /** The identifier of the declaration held back. */
+  readonly id: string;
+  /** One clause naming the relation, then the thing it relates to. */
+  readonly detail: string;
+  readonly site: Position;
+}
+
+/** What a detector reads of one project, while the project's view is open. */
+export interface DetectorInput<Brand> {
+  readonly project: ProjectView<Brand>;
+  readonly held: Inventory;
+  readonly targetRoot: string;
+}
+
+/**
+ * One class's detection over one project. The framework records each piece of evidence
+ * under the class the table names the detector by, so a detector names no class.
+ */
+export type Detector = <Brand>(input: DetectorInput<Brand>) => readonly Evidence[];
+
+/** The detector of each class one composition implements. */
+export type Detectors = ReadonlyMap<TSExemptionClass, Detector>;
+
+/** What decides which records of one project stand. */
+export interface Holding {
+  /** The classes the configuration switches off, whose detectors do not run. */
+  readonly disabled: ReadonlySet<ExemptionClass>;
+  readonly mode: Mode;
+  /** The paths the reference pass classified as test files. */
+  readonly testFiles: ReadonlySet<string>;
+}
+
+/**
+ * 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: Config): ReadonlySet<ExemptionClass> {
+  const disabled = new Set<ExemptionClass>();
+  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;
+}
+
+/**
+ * The records one project's detectors found, each class in the vocabulary's order and
+ * none of a switched-off class. 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<Brand>(
+  input: DetectorInput<Brand>,
+  detectors: Detectors,
+  holding: Holding,
+): readonly Exemption[] {
+  const found: Exemption[] = [];
+  for (const exemptionClass of TS_EXEMPTION_CLASSES) {
+    const detect = detectors.get(exemptionClass);
+    if (detect === undefined || holding.disabled.has(exemptionClass)) {
+      continue;
+    }
+    for (const evidence of detect(input)) {
+      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: string, b: string): number {
+  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: readonly Exemption[]): readonly Exemption[] {
+  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<string>();
+  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: readonly Exemption[]): ReadonlyMap<string, readonly Exemption[]> {
+  const grouped = new Map<string, Exemption[]>();
+  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: Matrix, input: SweepInput): readonly Exemption[] {
+  const exempt = input.exempt ?? [];
+  if (exempt.length === 0) {
+    return [];
+  }
+  const bare: SweepInput = { 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: readonly InventorySymbol[],
+  retained: readonly Exemption[],
+): readonly string[] {
+  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")];
+  });
+}

package/src/graph.ts

@@ -72,6 +72,11 @@ export function namesACaller(kind: RootKind): boolean {
 export interface Edge {
   readonly to: number;
   readonly test: boolean;
+  /**
+   * Whether the reference evaluates the module whose file it names, which reaches the
+   * module's top level and none of what it exports.
+   */
+  readonly evaluation: boolean;
 }
 
 /** How many references one declaration carries, split by the classification of the file that made each. */
@@ -102,8 +107,8 @@ export interface Graph {
   readonly subject: readonly boolean[];
   /**
    * Per declaration, the declarations its export table names where it is a file, and
-   * nothing for any other declaration. A reference to a file is a reference to the
-   * module's namespace, which reaches everything the module exports.
+   * nothing for any other declaration. A reference that reads a file reads the module's
+   * namespace, which reaches everything the module exports.
    */
   readonly exportsOf: readonly (readonly number[])[];
   /** Every root naming a declaration the inventory holds, in the order the root set gives them. */
@@ -144,7 +149,11 @@ export function graphOf(
         counts.production += 1;
       }
     }
-    out[at(reference.from)]?.push({ to, test: reference.test });
+    out[at(reference.from)]?.push({
+      to,
+      test: reference.test,
+      evaluation: reference.use === "evaluation",
+    });
   }
 
   const parent = symbols.map((symbol) => at(symbol.parent));