@cplieger/deadset-ts 3.12.1 → 4.0.0

package/src/session.ts

@@ -1,6 +1,6 @@
 import { API, SymbolFlags } from "@typescript/native/unstable/sync";
 import type {
-  Checker,
+  APIRequestGenerator,
   Diagnostic,
   DocumentIdentifier,
   NodeHandle,
@@ -10,9 +10,15 @@ import type {
   Symbol as TSSymbol,
   TimingInfo,
 } from "@typescript/native/unstable/sync";
-import { isIdentifier } from "@typescript/native/unstable/ast";
 import type { Node, SourceFile } from "@typescript/native/unstable/ast";
 import { DiscoveryError } from "./discover.ts";
+import {
+  queriesOf,
+  UnansweredLog,
+  type Answer,
+  type Queries,
+  type UnansweredQuestion,
+} from "./query.ts";
 
 /**
  * The compiler the analysis reads through. It is a client over a protocol to a
@@ -31,7 +37,15 @@ export interface Engine {
    */
   parseConfigFile(file: DocumentIdentifier): ReturnType<API["parseConfigFile"]>;
   /** Opens one snapshot holding every project named. */
-  updateSnapshot(openProjects: readonly string[]): Snapshot;
+  createSnapshot(openProjects: readonly string[]): Snapshot;
+  /** Sends many questions in one round trip and answers each, in order. */
+  batch<T>(questions: readonly APIRequestGenerator<T>[]): T[];
+  /**
+   * Puts one question to a project's checker, by the accessor's name and the locations
+   * it asks about. Every guarded question passes through here, so a caller that
+   * observes or fails questions does it at this seam.
+   */
+  ask<T>(accessor: string, locations: () => readonly string[], question: () => T): T;
   /** Round-trip latency, bytes transferred and server time, when collection is on. */
   getTimingInfo(): TimingInfo;
   /** Releases the client and the process behind it. */
@@ -56,7 +70,10 @@ export function openEngine(options: EngineOptions): Engine {
   let closed = false;
   return {
     parseConfigFile: (file) => api.parseConfigFile(file),
-    updateSnapshot: (openProjects) => api.updateSnapshot({ openProjects: [...openProjects] }),
+    createSnapshot: (openProjects) => api.createSnapshot({ openProjects: [...openProjects] }),
+    batch: <T>(questions: readonly APIRequestGenerator<T>[]) =>
+      api.batch<readonly APIRequestGenerator<T>[]>(...questions),
+    ask: (_accessor, _locations, question) => question(),
     getTimingInfo: () => api.getTimingInfo(),
     close: () => {
       if (closed) {
@@ -90,38 +107,45 @@ export interface ProjectView<Brand> {
   readonly configFile: string;
   /** The project's program, whose walk is local to this process. */
   readonly program: Program;
-  /** The project's checker. Every call on it is a round trip. */
-  readonly checker: Checker;
+  /**
+   * The questions the project's checker answers, each guarded. Every one is a round
+   * trip, and one may go unanswered.
+   */
+  readonly queries: Queries;
   /** The source files the program holds that are the target's own. */
   ownSourceFiles(): readonly SourceFile[];
+  /**
+   * The keys of the target's own files, which is how a declaration handle names the
+   * file it is in.
+   */
+  ownPaths(): ReadonlySet<string>;
   /** A handle to one node of this project's program. */
   handle(node: Node): Handle<Brand>;
   /**
-   * The symbols a batch of this project's nodes resolve to, one round trip for
-   * the batch, in the order the handles were given. The batch is how a file's
-   * identifiers reach the checker, and `undefined` marks a node the batch did not
-   * resolve.
+   * The symbols a batch of this project's nodes resolve to, in the order the handles
+   * were given, in runs of at most `cap`. The batch is how a file's identifiers reach
+   * the checker, and `undefined` marks a node the batch did not resolve.
    */
-  symbolsAt(handles: readonly Handle<Brand>[]): readonly (TSSymbol | undefined)[];
+  symbolsAt(handles: readonly Handle<Brand>[], cap?: number): Answer<TSSymbol | undefined>[];
   /**
    * The symbol one node resolves to, asked for that node alone. The accessor behind
-   * it takes one identifier and offers no array overload, so it is one round trip per
-   * node and it answers only for the residue a batch left unresolved. A node that is
-   * not an identifier has no such answer.
+   * it takes one identifier and offers no array form, so it answers only for the
+   * residue a batch left unresolved. A node that is not an identifier has no such
+   * answer.
    */
-  resolvedSymbolAt(handle: Handle<Brand>): TSSymbol | undefined;
+  resolvedSymbolAt(handle: Handle<Brand>): Answer<TSSymbol | undefined>;
   /**
    * The symbol the value of one shorthand property assignment names, which is the
    * declaration `{ a }` reads; the symbol the property's own name resolves to is the
    * property the literal declares. The handle names the assignment, not its name.
    */
-  shorthandValueAt(handle: Handle<Brand>): TSSymbol | undefined;
+  shorthandValueAt(handle: Handle<Brand>): Answer<TSSymbol | undefined>;
   /**
    * The symbol one alias names, one link along: an import or export specifier
    * resolves to the declaration it carries forward, or to the next alias of a chain.
    * `undefined` where the symbol is no alias, or where the alias resolves to nothing.
    */
-  aliasStepOf(symbol: TSSymbol): TSSymbol | undefined;
+  aliasStepOf(symbol: TSSymbol): Answer<TSSymbol | undefined>;
   /**
    * The node one symbol's declaration handle names, read in this project's program,
    * or `undefined` where this project's program does not hold that file.
@@ -142,49 +166,70 @@ export interface ProjectView<Brand> {
  */
 export type ProjectVisitor<Result> = <Brand>(project: ProjectView<Brand>) => Result;
 
-function viewOf<Brand>(project: Project): ProjectView<Brand> {
+function viewOf<Brand>(
+  project: Project,
+  configFile: string,
+  engine: Engine,
+  log: UnansweredLog,
+): ProjectView<Brand> {
+  const queries = queriesOf(
+    project.checker,
+    configFile,
+    (questions) => engine.batch(questions),
+    log,
+    (accessor, locations, question) => engine.ask(accessor, locations, question),
+  );
   // The snapshot is never updated, so a project's own file set is the same answer
   // every time it is asked for. It is read once because the question is not free:
   // deciding it consults the metadata of every file the program holds, the compiler's
   // own library files included, and a run asks for the set once per pass.
   let ownFiles: readonly SourceFile[] | undefined;
+  let ownKeys: ReadonlySet<string> | undefined;
+  const ownSourceFiles = (): readonly SourceFile[] => {
+    ownFiles ??= project.program
+      .getSourceFileNames()
+      // The metadata decides which files belong to the target, and it is read by
+      // name. Fetching each file first and filtering afterwards costs one round
+      // trip per library file the answer then discards, and a program holds far
+      // more library files than target files.
+      .filter((name) => {
+        const metadata = project.program.getSourceFileMetadata(name);
+        return (
+          metadata !== undefined && !metadata.isDefaultLibrary && !metadata.isFromExternalLibrary
+        );
+      })
+      .map((name) => project.program.getSourceFile(name))
+      .filter((file): file is SourceFile => file !== undefined);
+    return ownFiles;
+  };
   return {
-    configFile: project.configFileName,
+    configFile,
     program: project.program,
-    checker: project.checker,
-    ownSourceFiles: () => {
-      ownFiles ??= project.program
-        .getSourceFileNames()
-        // The metadata decides which files belong to the target, and it is read by
-        // name. Fetching each file first and filtering afterwards costs one round
-        // trip per library file the answer then discards, and a program holds far
-        // more library files than target files.
-        .filter((name) => {
-          const metadata = project.program.getSourceFileMetadata(name);
-          return (
-            metadata !== undefined && !metadata.isDefaultLibrary && !metadata.isFromExternalLibrary
-          );
-        })
-        .map((name) => project.program.getSourceFile(name))
-        .filter((file): file is SourceFile => file !== undefined);
-      return ownFiles;
+    queries,
+    ownSourceFiles,
+    ownPaths: () => {
+      ownKeys ??= new Set(ownSourceFiles().map((file) => file.path));
+      return ownKeys;
     },
     handle: (node) => ({ node }),
-    symbolsAt: (handles) => project.checker.getSymbolAtLocation(handles.map(({ node }) => node)),
-    resolvedSymbolAt: ({ node }) =>
-      isIdentifier(node) ? project.checker.getResolvedSymbol(node) : undefined,
-    shorthandValueAt: ({ node }) => project.checker.getShorthandAssignmentValueSymbol(node),
+    symbolsAt: (handles, cap) =>
+      queries.symbolsAt(
+        handles.map(({ node }) => node),
+        cap,
+      ),
+    resolvedSymbolAt: ({ node }) => queries.resolvedSymbol(node),
+    shorthandValueAt: ({ node }) => queries.shorthandValue(node),
     aliasStepOf: (symbol) => {
       // The step is asked of an alias only: asked of any other symbol, the compiler
       // fails an assertion and the session ends.
       if ((symbol.flags & SymbolFlags.Alias) === 0) {
         return undefined;
       }
-      const held = project.checker.getImmediateAliasedSymbol(symbol);
+      const held = queries.immediateAliased(symbol);
       // An alias that resolves to nothing answers with the checker's own unknown
       // symbol, which declares nothing; a symbol that is no alias answers with
       // nothing at all.
-      return held === undefined || held.declarations.length === 0 ? undefined : held;
+      return typeof held === "object" && held.declarations.length === 0 ? undefined : held;
     },
     declarationAt: (handle) => {
       const node = handle.resolve(project);
@@ -203,11 +248,17 @@ export function narrowedTo<Brand>(
   keep: (file: SourceFile) => boolean,
 ): ProjectView<Brand> {
   let kept: readonly SourceFile[] | undefined;
+  let keys: ReadonlySet<string> | undefined;
+  const ownSourceFiles = (): readonly SourceFile[] => {
+    kept ??= project.ownSourceFiles().filter(keep);
+    return kept;
+  };
   return {
     ...project,
-    ownSourceFiles: () => {
-      kept ??= project.ownSourceFiles().filter(keep);
-      return kept;
+    ownSourceFiles,
+    ownPaths: () => {
+      keys ??= new Set(ownSourceFiles().map((file) => file.path));
+      return keys;
     },
   };
 }
@@ -218,6 +269,11 @@ export interface ProjectDiagnostics {
   readonly syntactic: readonly Diagnostic[];
   readonly semantic: readonly Diagnostic[];
   readonly configParsing: readonly Diagnostic[];
+  /** The line and column of one offset into one of the program's files, counted from one. */
+  readonly locate: (
+    fileName: string,
+    offset: number,
+  ) => { line: number; column: number } | undefined;
 }
 
 /** The three diagnostic sets one project carries, read before any analysis. */
@@ -227,15 +283,31 @@ export function diagnosticsOf<Brand>(project: ProjectView<Brand>): ProjectDiagno
     syntactic: project.program.getSyntacticDiagnostics(),
     semantic: project.program.getSemanticDiagnostics(),
     configParsing: project.program.getConfigFileParsingDiagnostics(),
+    locate: (fileName, offset) => {
+      const file = project.program.getSourceFile(fileName);
+      if (file === undefined || offset < 0 || offset > file.text.length) {
+        return undefined;
+      }
+      const { line, character } = file.getLineAndCharacterOfPosition(offset);
+      return { line: line + 1, column: character + 1 };
+    },
   };
 }
 
 /** One run's result: what the visitor answered for each project, and what it cost. */
 export interface SessionResult<Result> {
+  /** One answer per configuration the snapshot opened a project for, in the order named. */
   readonly projects: readonly Result[];
+  /** The configurations the snapshot opened no project for, in the order named. */
+  readonly unopened: readonly string[];
   readonly timing: TimingInfo;
+  /** Every question the checker could not answer, each once, in the order first asked. */
+  readonly unanswered: readonly UnansweredQuestion[];
 }
 
+/** What a run does about a configuration the snapshot opened no project for. */
+type Unopened = "refuse" | "record";
+
 /**
  * Runs `visit` over every project the compiler configurations name, inside one
  * snapshot of one client, in the order they are named, and answers in that order.
@@ -244,30 +316,46 @@ export interface SessionResult<Result> {
  * with its own program and checker; it is never updated, because the analysis
  * reads and the tree does not change under it. The order the snapshot lists its
  * projects in is the compiler's own, so each named configuration is looked up in it
- * instead, and a configuration the snapshot opened no project for ends the run: the
- * run would otherwise answer for fewer projects than it was asked to analyze. The
- * snapshot is disposed once when the last project has been visited, and the client
- * is released after it, whether the visit completed or threw.
+ * instead. A configuration the snapshot opened no project for ends the run under
+ * `"refuse"` and is named in the result under `"record"`. The snapshot is disposed once
+ * the last project has been visited, and the client is released after it, whether the
+ * visit completed or threw.
  */
 export function runSession<Result>(
   engine: Engine,
   configFiles: readonly string[],
   visit: ProjectVisitor<Result>,
+  unopened: Unopened = "refuse",
 ): SessionResult<Result> {
   try {
-    const snapshot = engine.updateSnapshot(configFiles);
+    const snapshot = engine.createSnapshot(configFiles);
     try {
-      const opened = new Map(
-        snapshot.getProjects().map((project) => [project.configFileName, project]),
-      );
-      const projects = configFiles.map((configFile) => {
+      const opened = new Map<string, Project>();
+      for (const project of snapshot.getProjects()) {
+        if (project.configFileName !== undefined) {
+          opened.set(project.configFileName, project);
+        }
+      }
+      const log = new UnansweredLog();
+      const projects: Result[] = [];
+      const missing: string[] = [];
+      for (const configFile of configFiles) {
         const project = opened.get(configFile);
         if (project === undefined) {
-          throw new DiscoveryError(`${configFile} opened no project`, []);
+          if (unopened === "refuse") {
+            throw new DiscoveryError(`${configFile} opened no project`, []);
+          }
+          missing.push(configFile);
+          continue;
         }
-        return visit(viewOf(project));
-      });
-      return { projects, timing: engine.getTimingInfo() };
+        projects.push(visit(viewOf(project, configFile, engine, log)));
+      }
+      return {
+        projects,
+        unopened: missing,
+        timing: engine.getTimingInfo(),
+        unanswered: log.questions,
+      };
     } finally {
       snapshot.dispose();
     }

package/src/signatures.ts

@@ -0,0 +1,55 @@
+/**
+ * The function a declaration of the inventory declares, where it declares one: the node
+ * whose parameters, body and result are the declaration's own parts.
+ */
+
+import {
+  isArrowFunction,
+  isClassDeclaration,
+  isClassExpression,
+  isFunctionDeclaration,
+  isFunctionExpression,
+  isMethodDeclaration,
+  isPropertyDeclaration,
+  isVariableDeclaration,
+  type ArrowFunction,
+  type FunctionDeclaration,
+  type FunctionExpression,
+  type MethodDeclaration,
+  type Node,
+} from "@typescript/native/unstable/ast";
+
+/** A function-like node that carries a body of its own. */
+export type SignatureNode =
+  FunctionDeclaration | MethodDeclaration | ArrowFunction | FunctionExpression;
+
+/** Whether one node is a function value written in place: an arrow or a function expression. */
+function isFunctionValue(node: Node | undefined): node is ArrowFunction | FunctionExpression {
+  return node !== undefined && (isArrowFunction(node) || isFunctionExpression(node));
+}
+
+/**
+ * The function one declaration declares: a function declaration and a class method with
+ * a body are their own; a variable and a class property whose initializer is an arrow or
+ * a function expression declare that function. Any other declaration declares none, an
+ * overload signature and an abstract or ambient method among them, because no body is
+ * there to read its parts.
+ */
+export function signatureOf(node: Node): SignatureNode | undefined {
+  if (isFunctionDeclaration(node)) {
+    return node.body === undefined ? undefined : node;
+  }
+  if (isMethodDeclaration(node)) {
+    const owner = node.parent;
+    return node.body !== undefined && (isClassDeclaration(owner) || isClassExpression(owner))
+      ? node
+      : undefined;
+  }
+  if (
+    (isVariableDeclaration(node) || isPropertyDeclaration(node)) &&
+    isFunctionValue(node.initializer)
+  ) {
+    return node.initializer;
+  }
+  return undefined;
+}

package/src/suppress-file.ts

@@ -7,6 +7,7 @@
 
 import type { Host } from "./host.ts";
 import type { InventorySymbol } from "./inventory.ts";
+import { jsonChunks } from "./json-chunks.ts";
 import { joinPath } from "./paths.ts";
 import { positionAt, walkDocument } from "./json-document.ts";
 import type { Position } from "./position.ts";
@@ -154,6 +155,15 @@ function readRecord(value: unknown, site: Position, byReference: ByReference, sh
   return { records: named.map((one) => ({ ...written, bound: one.id })), refusals: [] };
 }
 
+function byReferenceOf(symbols: readonly InventorySymbol[]): ByReference {
+  const byReference = new Map<string, InventorySymbol[]>();
+  for (const symbol of symbols) {
+    const key = referenceKey(symbol.ref, symbol.position.path);
+    byReference.set(key, [...(byReference.get(key) ?? []), symbol]);
+  }
+  return byReference;
+}
+
 /** Reads one document at the target root, binding each record against the run's declarations. */
 function readDocument(
   host: Host,
@@ -196,11 +206,7 @@ function readDocument(
     return malformed(shape.file);
   }
 
-  const byReference = new Map<string, InventorySymbol[]>();
-  for (const symbol of symbols) {
-    const key = referenceKey(symbol.ref, symbol.position.path);
-    byReference.set(key, [...(byReference.get(key) ?? []), symbol]);
-  }
+  const byReference = byReferenceOf(symbols);
   const records: SuppressionRecord[] = [];
   const refusals: Refusal[] = [];
   (held as readonly unknown[]).forEach((value, index) => {
@@ -247,6 +253,24 @@ export interface Recorded {
   readonly path: string;
 }
 
+/**
+ * Rows a baseline write holds in memory, bound against the run's declarations as the same
+ * rows read back from the document would be, each carrying the reason given.
+ */
+export function bindRows(
+  rows: readonly Recorded[],
+  reason: string,
+  symbols: readonly InventorySymbol[],
+): Suppressions {
+  const byReference = byReferenceOf(symbols);
+  const site = documentSite(BASELINE_SHAPE);
+  const read = rows.map((row) => readRecord({ ...row, reason }, site, byReference, BASELINE_SHAPE));
+  return {
+    records: read.flatMap((one) => one.records),
+    refusals: read.flatMap((one) => one.refusals),
+  };
+}
+
 /** The analyzer a written row names as its provenance, as the same run's report names it. */
 export interface Provenance {
   readonly analyzer: string;
@@ -258,19 +282,27 @@ const BASELINE_DESCRIPTION =
   "Recorded findings: a run fails only on a finding this document does not hold. " +
   "Every reason is the analyzer that recorded the row, never an adjudication.";
 
+/** The reason every row a baseline write records carries. */
+export function rowReason(provenance: Provenance): string {
+  return `recorded by ${provenance.analyzer} ${provenance.version}`;
+}
+
 /**
  * A baseline holding one row per finding, in the order given, which is the report's. Every
  * row carries the provenance as its reason. A finding missing a value a row needs, and an
  * identity missing its name or version, are refused rather than written, because the
  * grammar requires a reason on every row.
  */
-export function writeBaseline(findings: readonly Recorded[], provenance: Provenance): string {
+export function writeBaseline(
+  findings: readonly Recorded[],
+  provenance: Provenance,
+): Iterable<string> {
   if (provenance.analyzer === "" || provenance.version === "") {
     throw new Error(
       `a baseline row would carry no reason: the analyzer identity names ${JSON.stringify(provenance.analyzer)} at version ${JSON.stringify(provenance.version)}`,
     );
   }
-  const reason = `recorded by ${provenance.analyzer} ${provenance.version}`;
+  const reason = rowReason(provenance);
   const baseline = findings.map((found) => {
     if (found.code === "" || found.symbol === "" || found.path === "") {
       throw new Error(
@@ -279,5 +311,5 @@ export function writeBaseline(findings: readonly Recorded[], provenance: Provena
     }
     return { code: found.code, symbol: found.symbol, path: found.path, reason };
   });
-  return `${JSON.stringify({ description: BASELINE_DESCRIPTION, baseline }, null, 2)}\n`;
+  return jsonChunks({ description: BASELINE_DESCRIPTION, baseline }, 2);
 }

package/src/suppress-inline.ts

@@ -8,6 +8,7 @@ import { SyntaxKind, type Node, type SourceFile } from "@typescript/native/unsta
 import { nodeKey, type Inventory } from "./inventory.ts";
 import { byPosition, positionKey, renderPosition, type Position } from "./position.ts";
 import type { ProjectView } from "./session.ts";
+import { signatureOf } from "./signatures.ts";
 import {
   SUPPRESSION_WITHOUT_REASON,
   SuppressionError,
@@ -168,7 +169,8 @@ interface Declared {
 /**
  * The declarations of one file by the line each begins on, the line of its first token: a
  * decorator, a modifier or the keyword. A variable's first token is its statement's
- * keyword, and a variable written on a later line of the statement also begins there.
+ * keyword, and a variable written on a later line of the statement also begins there. A
+ * function also begins, for a directive, on the line of each of its parameters.
  */
 function declarationLines(
   file: SourceFile,
@@ -189,6 +191,11 @@ function declarationLines(
     const one = id === undefined ? undefined : symbols.get(id);
     if (one !== undefined) {
       add(node.pos, one);
+      // A parameter on a later line of a wrapped signature takes its directive on the
+      // line above it, inside the parameter list, and the directive binds the function.
+      for (const parameter of signatureOf(node)?.parameters ?? []) {
+        add(parameter.pos, one);
+      }
       const list = node.parent;
       if (
         node.kind === SyntaxKind.VariableDeclaration &&

package/src/suppress.ts

@@ -169,6 +169,7 @@ const ROW_SUBJECTS: ReadonlySet<string> = new Set([
   "dependency",
   "module-directive",
   "root",
+  "configured-declaration",
   "suppression",
   "edge",
 ]);
@@ -178,6 +179,36 @@ export function isRowSubject(kind: string): boolean {
   return ROW_SUBJECTS.has(kind);
 }
 
+/**
+ * The subject kinds that are a part of a declaration rather than a declaration: a part
+ * has no reference of its own, so a finding about one names the declaration that holds
+ * it, and the part is decided inside that declaration whatever uses it.
+ */
+const PART_SUBJECTS: ReadonlySet<string> = new Set([
+  "parameter",
+  "receiver",
+  "result",
+  "statement",
+  "case",
+  "store",
+]);
+
+/** Whether a finding's subject is a part of the declaration its reference names. */
+export function isPartSubject(kind: string): boolean {
+  return PART_SUBJECTS.has(kind);
+}
+
+/** The prefix of the codes of the part kinds, the intra-function range. */
+const PART_KIND_PREFIX = "DS18";
+
+/**
+ * Whether a code is a part kind, whose record withholds its finding and marks nothing:
+ * the record says the part is wanted, not that the declaration holding it is.
+ */
+export function isPartKind(code: string): boolean {
+  return code.startsWith(PART_KIND_PREFIX);
+}
+
 /** One finding's identity: its code and the position of the thing it names. */
 function claimKey(finding: Finding): string {
   return `${finding.code}\u0000${positionKey(finding.position)}`;

package/src/sweep.ts

@@ -51,6 +51,11 @@ export interface SweepInput {
    * holds nothing back.
    */
   readonly exempt?: readonly Exemption[];
+  /**
+   * The declarations a question the checker did not answer could have kept live. Each
+   * is held as an exempt declaration is. Absent, the sweep holds nothing back for one.
+   */
+  readonly unanswered?: readonly string[];
   readonly mode: Mode;
 }
 
@@ -94,10 +99,10 @@ export interface Liveness {
  */
 export function sweep(graph: Graph, input: SweepInput): Liveness {
   const marked = flagged(graph, input.marked);
-  const exempt = flagged(
-    graph,
-    (input.exempt ?? []).map((record) => record.id),
-  );
+  const exempt = flagged(graph, [
+    ...(input.exempt ?? []).map((record) => record.id),
+    ...(input.unanswered ?? []),
+  ]);
   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