@cplieger/deadset-ts 7.0.0-dev.1 → 7.0.0-dev.3

package/src/serialization-contract.ts

@@ -1,12 +1,10 @@
 /**
- * The serialization-contract class: the data members and `toJSON` of every class,
- * interface and object type a value's static type names, and of every such type its
- * data members' types reach, where the value reaches `JSON.stringify` or a call
- * `ts.serializers` names, and those and `toString` where it is passed to an `unknown`
- * or `any` parameter of a function outside the analysis. A function of the project
- * handing such a parameter of its own to a destination is one, holding back what that
- * destination does, to a fixpoint. A function invoked through `Function.prototype.call`,
- * `apply` or `bind` is the callee, given the arguments those methods pass it.
+ * The serialization-contract class: the data members and `toJSON` of every type a value's
+ * static type reaches, where the value reaches `JSON.stringify` or a call `ts.serializers`
+ * names, and `toString` too where it reaches an `unknown` or `any` parameter of a function
+ * outside the analysis or an erased property of a type the program does not declare. A
+ * function of the project handing such a parameter to a destination is one, to a fixpoint,
+ * and a function invoked through `call`, `apply` or `bind` is the callee.
  */
 
 import {
@@ -59,6 +57,7 @@ import { nodeKey, type Inventory } from "./inventory.ts";
 import { renderPosition } from "./position.ts";
 import { must } from "./query.ts";
 import type { ProjectView } from "./session.ts";
+import { erasedStores, type ErasedStores } from "./erased-stores.ts";
 import { valueReach, type Reached } from "./value-reach.ts";
 
 /** The serializer every run reads, whatever the configuration names. */
@@ -527,13 +526,20 @@ function destinations<Brand>(
   return { invocation, at, mayReceive };
 }
 
-/** One argument whose value carries classes and object types of the target into a destination. */
+/** One value that carries classes and object types of the target into a destination. */
 interface Flow {
   readonly site: Node;
   readonly classes: ReadonlySet<string>;
   /** The members of the interfaces and object types the value carries. */
   readonly members: readonly TSSymbol[];
   readonly to: Destination;
+  /** What a retention names the destination by. */
+  readonly detail: string;
+}
+
+/** What two reaches carry together. */
+function joined(a: Reached, b: Reached): Reached {
+  return { classes: new Set([...a.classes, ...b.classes]), members: [...a.members, ...b.members] };
 }
 
 /** Each argument of a call that can receive one whose value carries a class of the target. */
@@ -542,8 +548,9 @@ function flowsOf<Brand>(
   held: Inventory,
   sites: readonly Site[],
   to: Destinations,
+  stores: ErasedStores,
 ): readonly Flow[] {
-  const reach = valueReach(project, held);
+  const reach = valueReach(project, held, stores.inside);
   const arguments_ = sites.flatMap((site) =>
     to.mayReceive(site.call)
       ? to.invocation(site.call).arguments.flatMap((argument, index) => {
@@ -560,7 +567,7 @@ function flowsOf<Brand>(
   const typeOf = new Map<Expression, Type | undefined>(
     asked.map((one, index) => [one.value, types[index]]),
   );
-  return arguments_.flatMap((one) => {
+  const passed = arguments_.flatMap((one) => {
     const type = typeOf.get(one.value);
     let reached: Reached = { classes: new Set<string>(), members: [] };
     if (one.value.kind === SyntaxKind.ThisKeyword) {
@@ -571,12 +578,38 @@ function flowsOf<Brand>(
     } else if (type !== undefined) {
       reached = reach.reachedFrom(type);
     }
+    for (const stored of stores.ofVariable(one.value) ?? []) {
+      reached = joined(reached, reach.reachedFrom(stored));
+    }
     const carries = reached.classes.size > 0 || reached.members.length > 0;
     const destination = carries ? to.at(one.site.call, one.argument) : undefined;
     return destination === undefined
       ? []
-      : [{ site: one.value, classes: reached.classes, members: reached.members, to: destination }];
+      : [
+          {
+            site: one.value,
+            classes: reached.classes,
+            members: reached.members,
+            to: destination,
+            detail: `passed to ${destination.callee}`,
+          },
+        ];
+  });
+  const left = stores.outside.flatMap((store) => {
+    const reached = reach.reachedFrom(store.type);
+    return reached.classes.size === 0 && reached.members.length === 0
+      ? []
+      : [
+          {
+            site: store.value,
+            classes: reached.classes,
+            members: reached.members,
+            to: { reach: "conversions" as const, callee: store.property },
+            detail: `stored in the property ${store.property} of a type the program does not declare`,
+          },
+        ];
   });
+  return [...passed, ...left];
 }
 
 /**
@@ -589,7 +622,13 @@ export function serializationContract<Brand>(input: DetectorInput<Brand>): reado
   const { project, held, targetRoot } = input;
   const walked = walkProject(project, held);
   const chains = aliasChains(project, held);
-  const flows = flowsOf(project, held, walked.sites, destinations(input, chains, walked));
+  const flows = flowsOf(
+    project,
+    held,
+    walked.sites,
+    destinations(input, chains, walked),
+    erasedStores(project),
+  );
   if (flows.length === 0) {
     return [];
   }
@@ -609,7 +648,7 @@ export function serializationContract<Brand>(input: DetectorInput<Brand>): reado
   const found: Evidence[] = [];
   for (const flow of flows) {
     const site = renderPosition(flow.site.getSourceFile(), targetRoot, flow.site.getStart());
-    const detail = `passed to ${flow.to.callee}`;
+    const { detail } = flow;
     for (const member of [...flow.classes].flatMap((id) => members.get(id) ?? [])) {
       const symbol = byId.get(member.id);
       const name = symbol === undefined ? "" : (memberComponent(symbol, byId) ?? "");

package/src/session.ts

@@ -28,13 +28,10 @@ import {
 } from "./query.ts";
 
 /**
- * The compiler the analysis reads through. It is a client over a protocol to a
- * separate process, so every accessor call is a round trip and a run holds one
- * client and one snapshot.
- *
- * It is an interface because the run's own accounting for that lifetime is not on
- * the client's surface: a snapshot reports whether it is disposed and not how many
- * a client opened, so the count is observed at this seam.
+ * The compiler the analysis reads through: a client over a protocol to a separate
+ * process, so every accessor call is a round trip and a run holds one client and one
+ * snapshot. It is an interface because a snapshot reports whether it is disposed and not
+ * how many a client opened, so the run's count of them is observed at this seam.
  */
 export interface Engine {
   /**
@@ -187,14 +184,10 @@ export function openEngine(options: EngineOptions): Engine {
 }
 
 /**
- * A node of one project's program, carried with that project's identity.
- *
- * `Brand` is a type parameter and never a value: a view is handed to a visitor
- * that introduces its own `Brand`, so two projects' views have handle types the
- * compiler will not exchange and a handle cannot reach another project's checker.
- * Handles are only meaningful inside the program that produced them, and the
- * cross-project step of the analysis compares rendered positions rather than
- * handles.
+ * A node of one project's program, carried with that project's identity. `Brand` is a
+ * type parameter and never a value: each visitor introduces its own, so two projects'
+ * handle types do not exchange and a handle cannot reach another project's checker. The
+ * cross-project step compares rendered positions, never handles.
  */
 export interface Handle<Brand> {
   readonly node: Node;
@@ -253,14 +246,11 @@ export interface ProjectView<Brand> {
    */
   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.
-   *
-   * A symbol is shared by every project of the snapshot and remembers the project it
-   * was first seen in, so resolving its handle without saying which program to read
-   * would answer out of whichever project reached the symbol first. The project is
-   * named here instead, and the answer becomes a handle of this project like any
-   * other. The read is local once the file has been fetched.
+   * The node one symbol's declaration handle names, read in this project's program, or
+   * `undefined` where this program does not hold that file. A symbol is shared by every
+   * project of the snapshot and remembers the one it was first seen in, so the project is
+   * named here, or the answer would come from whichever project reached the symbol first.
+   * The read is local once the file has been fetched.
    */
   declarationAt(handle: NodeHandle): Handle<Brand> | undefined;
 }
@@ -272,6 +262,13 @@ export interface ProjectView<Brand> {
  */
 export type ProjectVisitor<Result> = <Brand>(project: ProjectView<Brand>) => Result;
 
+/** One project a session opened: its configuration and the files of its own program. */
+export interface OpenedFiles {
+  readonly configFile: string;
+  /** The program's source files no default library and no external library holds. */
+  readonly fileNames: () => readonly string[];
+}
+
 /**
  * The source files of one program that `own` admits, in the program's order, none of
  * them one of the compiler's default libraries.
@@ -417,7 +414,6 @@ export function ownedAs<Brand>(
 
 /** Every diagnostic set a project is refused for carrying an error in. */
 export interface ProjectDiagnostics {
-  readonly configFile: string;
   readonly syntactic: readonly Diagnostic[];
   readonly semantic: readonly Diagnostic[];
   readonly configParsing: readonly Diagnostic[];
@@ -431,7 +427,6 @@ export interface ProjectDiagnostics {
 /** The three diagnostic sets one project carries, read before any analysis. */
 export function diagnosticsOf<Brand>(project: ProjectView<Brand>): ProjectDiagnostics {
   return {
-    configFile: project.configFile,
     syntactic: project.program.getSyntacticDiagnostics(),
     semantic: project.program.getSemanticDiagnostics(),
     configParsing: project.program.getConfigFileParsingDiagnostics(),
@@ -489,10 +484,10 @@ function projectsOf(
 /**
  * Runs `visit` over every project the compiler configurations name, inside one never updated
  * snapshot of one client, and answers in their order. A configuration `programs` describes is
- * built as that program, or opened from the configuration it writes, instead of as a project.
- * One the snapshot holds nothing for ends the run under `"refuse"` and is named in the result
- * under `"record"`. `last` runs after the last visit while the client still answers; the
- * snapshot is disposed and the client released after it, whether the visit completed or threw.
+ * built as that program, or opened from the configuration it writes. One the snapshot holds
+ * nothing for ends the run under `"refuse"` and is named in the result under `"record"`.
+ * `first` runs over every opened project before the first visit and `last` after the last,
+ * both while the client answers; the snapshot and the client are then released.
  */
 export function runSession<Result>(
   engine: Engine,
@@ -501,6 +496,7 @@ export function runSession<Result>(
   unopened: Unopened = "refuse",
   programs: ReadonlyMap<string, WorkspaceProgram> = new Map(),
   last: () => void = () => undefined,
+  first: (opened: readonly OpenedFiles[]) => void = () => undefined,
 ): SessionResult<Result> {
   try {
     const built: string[] = [];
@@ -525,7 +521,7 @@ export function runSession<Result>(
     try {
       const opened = projectsOf(snapshot, built, written);
       const log = new UnansweredLog();
-      const projects: Result[] = [];
+      const views: ProjectView<unknown>[] = [];
       const missing: string[] = [];
       for (const configFile of configFiles) {
         const project = opened.get(configFile);
@@ -536,8 +532,15 @@ export function runSession<Result>(
           missing.push(configFile);
           continue;
         }
-        projects.push(visit(viewOf(project, configFile, engine, log)));
+        views.push(viewOf(project, configFile, engine, log));
       }
+      first(
+        views.map((view) => ({
+          configFile: view.configFile,
+          fileNames: () => view.ownSourceFiles().map((file) => file.fileName),
+        })),
+      );
+      const projects = views.map((view) => visit(view));
       last();
       return {
         projects,

package/src/stores.ts

@@ -37,7 +37,7 @@ export interface Stores {
 }
 
 /** What one configuration contributes to the run's stores. */
-export interface ConfigurationStores {
+interface ConfigurationStores {
   readonly references: readonly Reference[];
   readonly accessors: readonly string[];
 }

package/src/suppress-file.ts

@@ -59,6 +59,13 @@ const BASELINE_SHAPE: Shape = {
   recordWant: "a row naming code, symbol, path and reason, each a string",
 };
 
+/**
+ * The reference scheme of this analyzer's language. A record of the other scheme is
+ * form-checked and then left to the analyzer of its language: it binds nothing here, counts
+ * in neither total and is reported under no code.
+ */
+const OWN_SCHEME = "ts://";
+
 /** The closed key list of one entry or row. */
 const RECORD_KEYS: ReadonlySet<string> = new Set(["code", "symbol", "path", "reason"]);
 
@@ -126,6 +133,9 @@ function readRecord(value: unknown, site: Position, byReference: ByReference, sh
   if (path !== undefined && path !== "" && !isEntryPath(path)) {
     return refuse(JSON.stringify(path), PATH_WANT);
   }
+  if (!symbol.startsWith(OWN_SCHEME)) {
+    return { records: [], refusals: [] };
+  }
 
   const written = {
     code,
@@ -284,15 +294,68 @@ export function rowReason(provenance: Provenance): string {
   return `recorded by ${provenance.analyzer} ${provenance.version}`;
 }
 
+/** A row of the other language's scheme a write keeps: the members the document held, and no other. */
+interface KeptRow {
+  readonly code: string;
+  readonly symbol: string;
+  readonly path?: string;
+  readonly reason?: string;
+}
+
+/**
+ * The rows of the other language's scheme that the baseline document `text` holds, in
+ * document order and as written, which a write keeps. A document that is not a baseline,
+ * or a row in a shape no record takes, is refused rather than dropped.
+ */
+export function otherSchemeRows(text: string): readonly KeptRow[] {
+  const refuse = (detail: string): never => {
+    throw new Error(
+      `${BASELINE_FILE} cannot be rewritten keeping the other language's rows: ${detail}`,
+    );
+  };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error: unknown) {
+    return refuse(error instanceof Error ? error.message : String(error));
+  }
+  const held = isObject(parsed) ? parsed[BASELINE_SHAPE.array] : undefined;
+  if (!Array.isArray(held)) {
+    return refuse(BASELINE_SHAPE.documentWant);
+  }
+  return (held as readonly unknown[]).flatMap((value): KeptRow[] => {
+    try {
+      readRecord(value, documentSite(BASELINE_SHAPE), new Map(), BASELINE_SHAPE);
+    } catch (error: unknown) {
+      return refuse(error instanceof Error ? error.message : String(error));
+    }
+    // readRecord has checked every member is a string and the code and symbol are present.
+    const { code, symbol, path, reason } = value as Readonly<Record<string, string>>;
+    if (code === undefined || symbol === undefined || symbol.startsWith(OWN_SCHEME)) {
+      return [];
+    }
+    return [
+      {
+        code,
+        symbol,
+        ...(path === undefined ? {} : { path }),
+        ...(reason === undefined ? {} : { reason }),
+      },
+    ];
+  });
+}
+
 /**
- * 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.
+ * A baseline holding one row per finding, in the order given, which is the report's, after
+ * the other language's rows `kept`, so two analyzers writing one document in either order
+ * write the same bytes. Every recorded 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,
+  kept: readonly KeptRow[] = [],
 ): Iterable<string> {
   if (provenance.analyzer === "" || provenance.version === "") {
     throw new Error(
@@ -308,5 +371,5 @@ export function writeBaseline(
     }
     return { code: found.code, symbol: found.symbol, path: found.path, reason };
   });
-  return jsonChunks({ description: BASELINE_DESCRIPTION, baseline }, 2);
+  return jsonChunks({ description: BASELINE_DESCRIPTION, baseline: [...kept, ...baseline] }, 2);
 }

package/src/suppress-inline.ts

@@ -1,7 +1,7 @@
 /**
  * The inline directive: `deadset:ignore`, the first token of a `//` line comment, naming
  * one or more codes and a reason, and binding to every declaration that begins on the line
- * below it.
+ * below it, or on its own line where it trails a token there.
  */
 
 import { SyntaxKind, type Node, type SourceFile } from "@typescript/native/unstable/ast";
@@ -37,7 +37,7 @@ const NO_REASON = new RegExp(DIRECTIVE_EXPRESSIONS.noReason);
 const DIRECTIVE_FORM = "// deadset:ignore DS0000[,DS0000...] -- <reason>";
 
 /** What the grammar's decision procedure makes of one comment. */
-export type Directive =
+type Directive =
   | { readonly is: "none" }
   | { readonly is: "directive"; readonly codes: readonly string[]; readonly reason: string }
   | { readonly is: "no-reason"; readonly codes: readonly string[] }
@@ -64,7 +64,7 @@ export function classifyComment(text: string): Directive {
 }
 
 /** One `//` line comment: the offset of its first solidus, and its text to the end of its line. */
-export interface LineComment {
+interface LineComment {
   readonly offset: number;
   readonly text: string;
 }
@@ -123,7 +123,7 @@ export function tokenStart(text: string, from: number): number {
  * syntax tree holds are skipped, so a `//` inside a string, a template or a regular
  * expression starts nothing.
  */
-export function lineComments(file: SourceFile): readonly LineComment[] {
+function lineComments(file: SourceFile): readonly LineComment[] {
   const text = file.text;
   const spans: { readonly start: number; readonly end: number }[] = [];
   const visit = (node: Node): void => {
@@ -211,6 +211,15 @@ function declarationLines(
   return below;
 }
 
+/**
+ * Whether the comment at `offset` follows a token on its own line, so it binds the
+ * declarations that begin on that line rather than on the next.
+ */
+function trails(file: SourceFile, offset: number): boolean {
+  const { line } = file.getLineAndCharacterOfPosition(offset);
+  return tokenStart(file.text, file.getPositionOfLineAndCharacter(line, 0)) < offset;
+}
+
 /** One comment in the namespace, what the grammar made of it, and what it bound. */
 export interface InlineDirective {
   readonly site: Position;
@@ -242,11 +251,12 @@ export function inlineDirectives<Brand>(
     const below = declarationLines(file, held, symbols);
     for (const comment of comments) {
       const site = renderPosition(file, targetRoot, comment.offset);
+      const target = trails(file, comment.offset) ? site.line : site.line + 1;
       found.push({
         site,
         text: comment.text,
         directive: classifyComment(comment.text),
-        bound: [...(below.get(site.line + 1) ?? [])],
+        bound: [...(below.get(target) ?? [])],
       });
     }
   }
@@ -254,8 +264,8 @@ export function inlineDirectives<Brand>(
 }
 
 /**
- * The inline directives of a run's projects, each bound to the declarations that begin on
- * the line below it, one directive binding the union of what each project holding its file
+ * The inline directives of a run's projects, each bound to the declarations the placement
+ * rule gives it, one directive binding the union of what each project holding its file
  * declares there. A directive that lacks only its reason is one {@link Refusal} per code;
  * any other malformed comment in the namespace ends the read with a
  * {@link SuppressionError} naming the first one written.