@cplieger/deadset-ts 3.12.1 → 4.0.0

package/src/reporters/template.ts

@@ -7,6 +7,7 @@
  * and a member the document does not carry fails the rendering.
  */
 
+import { CHUNK_LENGTH } from "../json-chunks.ts";
 import { RenderError } from "./reporter.ts";
 import { utf8Bytes } from "./sha256.ts";
 
@@ -115,7 +116,11 @@ const ESCAPES: Readonly<Record<string, string>> = {
 const ESCAPE_WIDTHS: Readonly<Record<string, number>> = { x: 2, u: 4, U: 8 };
 
 const IDENTIFIER = /[A-Za-z_][A-Za-z0-9_]*/uy;
-const NUMBER = /[+-]?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/uy;
+/** A number as the lexer reads one, before the subset decides whether it is a decimal integer. */
+const NUMBER = /[+-]?[0-9][0-9A-Za-z_.]*/uy;
+
+/** The one number form the subset admits: a decimal integer with no leading zero. */
+const DECIMAL_INTEGER = /^[+-]?(?:0|[1-9][0-9]*)$/u;
 
 function lineOf(source: string, at: number): number {
   let line = 1;
@@ -224,6 +229,11 @@ function lexAction(
     NUMBER.lastIndex = i;
     const number = NUMBER.exec(source)?.[0];
     if (number !== undefined) {
+      if (!DECIMAL_INTEGER.test(number)) {
+        throw new TemplateError(
+          `line ${String(line)}: ${JSON.stringify(number)} is not a decimal integer`,
+        );
+      }
       tokens.push({ t: "lit", value: Number(number) });
       i += number.length;
       continue;
@@ -636,7 +646,61 @@ function compareBasic(name: string, a: Value, b: Value): number {
   if (kind === "boolean") {
     return Number.NaN;
   }
-  return (a as number | string) < (b as number | string) ? -1 : 1;
+  if (kind === "string") {
+    return byCodePoints(a as string, b as string);
+  }
+  return (a as number) < (b as number) ? -1 : 1;
+}
+
+/**
+ * Two strings ordered by the bytes of their UTF-8 encodings, which is the order of their
+ * code points: the order of their UTF-16 code units differs above U+FFFF.
+ */
+function byCodePoints(a: string, b: string): number {
+  let at = 0;
+  while (at < a.length && at < b.length) {
+    const x = a.codePointAt(at) ?? 0;
+    const y = b.codePointAt(at) ?? 0;
+    if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+    at += x > 0xffff ? 2 : 1;
+  }
+  return a.length - b.length;
+}
+
+/** The escapes `%q` writes for the control characters that have one of their own. */
+const QUOTED_ESCAPES: Readonly<Record<string, string>> = {
+  '"': '\\"',
+  "\\": "\\\\",
+  "\u0007": "\\a",
+  "\b": "\\b",
+  "\f": "\\f",
+  "\n": "\\n",
+  "\r": "\\r",
+  "\t": "\\t",
+  "\v": "\\v",
+};
+
+/**
+ * The text `%q` writes: double quotes around the text, a quote and a backslash escaped,
+ * each control character with an escape of its own written as it, every other character
+ * below U+0020 and U+007F written as `\x` and two lowercase hexadecimal digits, and every
+ * other character as itself.
+ */
+function goQuoted(text: string): string {
+  let out = '"';
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0;
+    if (Object.hasOwn(QUOTED_ESCAPES, char)) {
+      out += QUOTED_ESCAPES[char] ?? "";
+    } else if (code < 0x20 || code === 0x7f) {
+      out += `\\x${code.toString(16).padStart(2, "0")}`;
+    } else {
+      out += char;
+    }
+  }
+  return `${out}"`;
 }
 
 /** `printf`'s verbs, each over one operand. */
@@ -663,10 +727,10 @@ function printf(format: string, args: readonly Value[]): string {
     switch (verb) {
       case "v":
       case "s":
-        out += formatted(arg, false);
+        out += formatted(arg, true);
         break;
       case "q":
-        out += JSON.stringify(formatted(arg, false));
+        out += goQuoted(formatted(arg, true));
         break;
       case "d":
         if (typeof arg !== "number" || !Number.isInteger(arg)) {
@@ -768,11 +832,11 @@ function call(name: string, args: readonly Value[]): Value {
       return args
         .map((arg, i) => {
           const spaced = i > 0 && typeof arg !== "string" && typeof args[i - 1] !== "string";
-          return `${spaced ? " " : ""}${formatted(arg, false)}`;
+          return `${spaced ? " " : ""}${formatted(arg, true)}`;
         })
         .join("");
     case "println":
-      return `${args.map((arg) => formatted(arg, false)).join(" ")}\n`;
+      return `${args.map((arg) => formatted(arg, true)).join(" ")}\n`;
     case "printf":
       if (typeof first !== "string") {
         throw new RenderError("printf takes a format string first");
@@ -786,12 +850,24 @@ function call(name: string, args: readonly Value[]): Value {
 /** One execution of a template over a document. */
 class Execution {
   private readonly scopes: Map<string, Value>[];
-  out = "";
+  /** The rendering so far, in pieces of about {@link CHUNK_LENGTH}, the last still growing. */
+  readonly pieces: string[] = [""];
 
   constructor(root: Value) {
     this.scopes = [new Map([["$", root]])];
   }
 
+  private write(text: string): void {
+    const last = this.pieces.length - 1;
+    const held = (this.pieces[last] ?? "") + text;
+    if (held.length >= CHUNK_LENGTH) {
+      this.pieces[last] = held;
+      this.pieces.push("");
+    } else {
+      this.pieces[last] = held;
+    }
+  }
+
   private lookup(name: string): Value {
     for (let i = this.scopes.length - 1; i >= 0; i -= 1) {
       const scope = this.scopes[i];
@@ -900,12 +976,12 @@ class Execution {
     for (const node of nodes) {
       switch (node.k) {
         case "text":
-          this.out += node.text;
+          this.write(node.text);
           break;
         case "action": {
           const value = this.pipeline(node.pipe, dot, true);
           if (node.pipe.vars.length === 0) {
-            this.out += formatted(value, false);
+            this.write(formatted(value, false));
           }
           break;
         }
@@ -978,12 +1054,41 @@ class Execution {
 }
 
 /**
- * The template's rendering of one document. The rendering is built whole, so a template
- * that fails partway renders nothing, and the failure names what it could not evaluate.
+ * One document as the JSON value it encodes: what `JSON.stringify` would write for it,
+ * read back, without writing it. A member holding nothing is left out, and an array
+ * element holding nothing, like a number that is not finite, is null.
+ */
+function plainOf(value: unknown): Value | undefined {
+  if (Array.isArray(value)) {
+    return value.map((element: unknown) => plainOf(element) ?? null);
+  }
+  if (typeof value === "object" && value !== null) {
+    const held: Record<string, Value> = {};
+    for (const [key, member] of Object.entries(value)) {
+      const plain = plainOf(member);
+      if (plain !== undefined) {
+        held[key] = plain;
+      }
+    }
+    return held;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "string" || typeof value === "boolean" || value === null) {
+    return value;
+  }
+  return undefined;
+}
+
+/**
+ * The template's rendering of one document, in pieces of about {@link CHUNK_LENGTH}.
+ * The rendering is complete before it is answered, so a template that fails partway
+ * renders nothing, and the failure names what it could not evaluate.
  */
-export function renderTemplate(template: Template, document: unknown): string {
-  const root = JSON.parse(JSON.stringify(document)) as Value;
+export function renderTemplate(template: Template, document: unknown): readonly string[] {
+  const root = plainOf(document) ?? null;
   const execution = new Execution(root);
   execution.run(template.nodes, root);
-  return execution.out;
+  return execution.pieces.filter((piece) => piece !== "");
 }

package/src/reporters/text.ts

@@ -1,3 +1,4 @@
+import { coalesced } from "../json-chunks.ts";
 import type { Report, WireTotals } from "../report.ts";
 
 /** The kind token and the confidence a stale suppression is rendered with, both fixed. */
@@ -29,16 +30,15 @@ function summary(totals: WireTotals): string {
  * summary is deliberately not in that shape, so a filter for finding lines yields exactly
  * them. Nothing else is written: no timestamp, duration or host detail.
  */
-export const text = (report: Report): string => {
-  const lines = report.findings.map(
-    (found) =>
-      `${found.position.path}:${String(found.position.line)}:${String(found.position.column)}: ${found.symbol.kind} ${found.symbol.name}: ${found.message} [${found.confidence}] (${found.code})`,
+export const text = (report: Report): Iterable<string> =>
+  coalesced(
+    (function* lines(): Generator<string, void, undefined> {
+      for (const found of report.findings) {
+        yield `${found.position.path}:${String(found.position.line)}:${String(found.position.column)}: ${found.symbol.kind} ${found.symbol.name}: ${found.message} [${found.confidence}] (${found.code})\n`;
+      }
+      for (const stale of report.stale_suppressions) {
+        yield `${stale.position.path}:${String(stale.position.line)}:${String(stale.position.column)}: ${STALE_KIND} ${stale.symbol}: ${stale.message} [${STALE_CONFIDENCE}] (${stale.code})\n`;
+      }
+      yield `${summary(report.totals)}\n`;
+    })(),
   );
-  for (const stale of report.stale_suppressions) {
-    lines.push(
-      `${stale.position.path}:${String(stale.position.line)}:${String(stale.position.column)}: ${STALE_KIND} ${stale.symbol}: ${stale.message} [${STALE_CONFIDENCE}] (${stale.code})`,
-    );
-  }
-  lines.push(summary(report.totals));
-  return `${lines.join("\n")}\n`;
-};

package/src/roots.ts

@@ -15,6 +15,7 @@ import { globExpression } from "./glob.ts";
 import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
 import type { Manifest, ManifestEntry } from "./manifest.ts";
 import { byPosition } from "./position.ts";
+import { UNANSWERED } from "./query.ts";
 import type { ProjectView } from "./session.ts";
 import { sourceFilesOf } from "./source-files.ts";
 
@@ -70,6 +71,12 @@ export interface Roots {
    * {@link unmatchedEverywhere} is what turns one into the other.
    */
   readonly unmatched: readonly string[];
+  /**
+   * Every declaration of the project, where the checker left the module or export table
+   * of an entry or a published file unanswered, and none otherwise: which of them that
+   * file exports is unknown.
+   */
+  readonly unanswered: readonly string[];
 }
 
 /** What decides the roots beside the declarations themselves. */
@@ -225,7 +232,7 @@ export function roots<Brand>(
     enter(point.file, point.rule, point.source, point.exports);
   }
 
-  const exportsOf = exportTables(project, held, [
+  const { tables: exportsOf, answered } = exportTables(project, held, [
     ...entered.filter((entry) => entry.exports).map((entry) => entry.file),
     ...published,
   ]);
@@ -258,47 +265,62 @@ export function roots<Brand>(
     return site || compare(a.kind, b.kind) || compare(a.source, b.source);
   });
 
-  return { configFile: project.configFile, liveUnderReachability: ordered, unmatched };
+  return {
+    configFile: project.configFile,
+    liveUnderReachability: ordered,
+    unmatched,
+    unanswered: answered ? [] : held.symbols.map((symbol) => symbol.id),
+  };
 }
 
 /**
  * Every declaration each file's module exports, by the file's name: the declaration
  * each name of the export table is, and every link of a re-export's chain. A name
- * whose declaration is outside the project's own files belongs to another program
- * and names nothing here.
- *
- * One batch resolves every file to its module and one request per module reads
- * its export table, star re-exports resolved into it. A file that is no module
- * exports nothing.
+ * whose declaration is outside the project's own files names nothing here. One batch
+ * resolves every file to its module and one request per module reads its export
+ * table, star re-exports resolved into it. A file that is no module exports nothing.
+ * `answered` is false where the checker left a table or a link of a chain unanswered.
  */
 function exportTables<Brand>(
   project: ProjectView<Brand>,
   held: Inventory,
   wanted: readonly SourceFile[],
-): ReadonlyMap<string, readonly string[]> {
+): { readonly tables: ReadonlyMap<string, readonly string[]>; readonly answered: boolean } {
   const unique = [...new Map(wanted.map((file) => [file.fileName, file])).values()];
   const tables = new Map<string, readonly string[]>();
+  let answered = true;
   if (unique.length === 0) {
-    return tables;
+    return { tables, answered };
   }
   const modules = project.symbolsAt(unique.map((file) => project.handle(file)));
   const chains = aliasChains(project, held);
 
+  const topLevel = (file: SourceFile): readonly string[] => {
+    const fileId = held.declarations.get(nodeKey(file, file));
+    return held.symbols.filter((symbol) => symbol.parent === fileId).map((symbol) => symbol.id);
+  };
   unique.forEach((file, index) => {
     const module = modules[index];
     if (module === undefined) {
       tables.set(file.fileName, []);
       return;
     }
+    const table = module === UNANSWERED ? UNANSWERED : project.queries.exportsOfModule(module);
+    if (table === UNANSWERED) {
+      answered = false;
+      tables.set(file.fileName, topLevel(file));
+      return;
+    }
     const ids = new Set<string>();
-    for (const exported of project.checker.getExportsOfModule(module)) {
+    for (const exported of table) {
       for (const target of chains.chainOf(exported)) {
+        answered &&= !target.guessed;
         ids.add(target.id);
       }
     }
     tables.set(file.fileName, [...ids]);
   });
-  return tables;
+  return { tables, answered };
 }
 
 /** The kinds of container whose export table, not its members' visibility, says what it publishes. */

package/src/serialization-contract.ts

@@ -1,11 +1,12 @@
 /**
- * The serialization-contract class: the properties of a class whose values reach
- * `JSON.stringify` or a call `ts.serializers` names, and those and `toJSON` and
- * `toString` where a value 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 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.
  */
 
 import {
@@ -56,8 +57,9 @@ import {
 import type { DetectorInput, Evidence } from "./exempt.ts";
 import { nodeKey, type Inventory } from "./inventory.ts";
 import { renderPosition } from "./position.ts";
+import { must } from "./query.ts";
 import type { ProjectView } from "./session.ts";
-import { valueReach } from "./value-reach.ts";
+import { valueReach, type Reached } from "./value-reach.ts";
 
 /** The serializer every run reads, whatever the configuration names. */
 const JSON_STRINGIFY: DeclarationEntry = { shape: "global", global: "JSON.stringify" };
@@ -65,6 +67,9 @@ const JSON_STRINGIFY: DeclarationEntry = { shape: "global", global: "JSON.string
 /** The methods a serializer and a formatter resolve by name on a value that left the analysis. */
 const CONVERSIONS: ReadonlySet<string> = new Set(["toJSON", "toString"]);
 
+/** The method a serializer calls on a value that carries one, wherever the value goes. */
+const SERIALIZED_CONVERSION = "toJSON";
+
 /** The parameter types that keep nothing of the value they are given. */
 const ERASED = TypeFlags.Any | TypeFlags.Unknown;
 
@@ -312,12 +317,13 @@ function erasedParameters<Brand>(
     if (!parameter.rest) {
       return (type.flags & ERASED) !== 0;
     }
-    const [element] = type.isTypeReference() ? project.checker.getTypeArguments(type) : [];
+    const [element] = must(project.queries.typeArguments(type));
     return element !== undefined && (element.flags & ERASED) !== 0;
   });
   const bySymbol = new Map<number, Parameter>();
   project
     .symbolsAt(erased.map((parameter) => project.handle(parameter.name)))
+    .map(must)
     .forEach((symbol, index) => {
       const parameter = erased[index];
       if (symbol !== undefined && parameter !== undefined) {
@@ -343,11 +349,11 @@ function handedOn<Brand>(
     ),
   );
   const plain = candidates.filter((one) => !one.value.shorthand);
-  const resolved = project.symbolsAt(plain.map((one) => project.handle(one.value.name)));
+  const resolved = project.symbolsAt(plain.map((one) => project.handle(one.value.name))).map(must);
   const symbolOf = new Map(plain.map((one, index) => [one, resolved[index]]));
   return candidates.flatMap((one) => {
     const symbol = one.value.shorthand
-      ? project.shorthandValueAt(project.handle(one.value.name))
+      ? must(project.shorthandValueAt(project.handle(one.value.name)))
       : symbolOf.get(one);
     const parameter = symbol === undefined ? undefined : erased.get(symbol.id);
     return parameter === undefined ? [] : [{ parameter, site: one.site, argument: one.argument }];
@@ -378,8 +384,8 @@ function destinations<Brand>(
   walked: Walked,
 ): Destinations {
   const { project, held } = input;
-  const checker = project.checker;
-  const own = new Set(project.ownSourceFiles().map((file) => file.fileName));
+  const queries = project.queries;
+  const own = project.ownPaths();
   const named = resolveEntries(project, held, [JSON_STRINGIFY, ...input.ts.serializers]).filter(
     namesADeclaration,
   );
@@ -418,7 +424,7 @@ function destinations<Brand>(
       form !== undefined &&
       method !== undefined &&
       outside(method) &&
-      FUNCTION_INTERFACES.has(method.getParent()?.name ?? "")
+      FUNCTION_INTERFACES.has(must(project.queries.parentOf(method))?.name ?? "")
     ) {
       return form.invocation;
     }
@@ -435,16 +441,16 @@ function destinations<Brand>(
       const invoked = invocation(call);
       // Through a method of the prototype the resolved signature is the method's, so
       // the parameters are read off the callee's own signatures, any one erasing.
-      const type = invoked.indirect ? checker.getTypeAtLocation(invoked.callee) : undefined;
+      const type = invoked.indirect ? must(queries.typeAt(invoked.callee)) : undefined;
       const signatures = invoked.indirect
         ? type === undefined
           ? []
-          : checker.getSignaturesOfType(type, SignatureKind.Call)
-        : [checker.getResolvedSignature(call)].filter((one) => one !== undefined);
+          : must(queries.signaturesOf(type, SignatureKind.Call))
+        : [must(queries.resolvedSignature(call))].filter((one) => one !== undefined);
       indexes = new Set(
         invoked.arguments.flatMap((_unused, index) =>
           signatures.some((signature) => {
-            const parameter = checker.getParameterType(signature, index);
+            const parameter = must(queries.parameterType(signature, index));
             return parameter !== undefined && (parameter.flags & ERASED) !== 0;
           })
             ? [index]
@@ -521,10 +527,12 @@ function destinations<Brand>(
   return { invocation, at, mayReceive };
 }
 
-/** One argument whose value carries classes of the target into a destination. */
+/** One argument whose value 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;
 }
 
@@ -554,31 +562,34 @@ function flowsOf<Brand>(
   );
   return arguments_.flatMap((one) => {
     const type = typeOf.get(one.value);
-    let classes: ReadonlySet<string> = new Set<string>();
+    let reached: Reached = { classes: new Set<string>(), members: [] };
     if (one.value.kind === SyntaxKind.ThisKeyword) {
-      classes = new Set(one.site.self === undefined ? [] : [one.site.self]);
+      reached = {
+        classes: new Set(one.site.self === undefined ? [] : [one.site.self]),
+        members: [],
+      };
     } else if (type !== undefined) {
-      classes = reach.classesOf(type);
+      reached = reach.reachedFrom(type);
     }
-    const destination = classes.size === 0 ? undefined : to.at(one.site.call, one.argument);
-    return destination === undefined ? [] : [{ site: one.value, classes, to: destination }];
+    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 }];
   });
 }
 
 /**
- * The serialization-contract detector: each property of each class whose values reach
- * a destination, and the two conversion methods where the destination is outside the
- * analysis, recorded at the argument with the callee named.
+ * The serialization-contract detector: each data member and `toJSON` of each class,
+ * interface and object type a value that reaches a destination carries, and `toString`
+ * as well where the destination is outside the analysis, recorded at the argument with
+ * the callee named.
  */
 export function serializationContract<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
   const { project, held, targetRoot } = input;
   const walked = walkProject(project, held);
-  const flows = flowsOf(
-    project,
-    held,
-    walked.sites,
-    destinations(input, aliasChains(project, held), walked),
-  );
+  const chains = aliasChains(project, held);
+  const flows = flowsOf(project, held, walked.sites, destinations(input, chains, walked));
   if (flows.length === 0) {
     return [];
   }
@@ -589,22 +600,30 @@ export function serializationContract<Brand>(input: DetectorInput<Brand>): reado
     "instance",
   );
   const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+  // A destination holds back a data member and `toJSON`, and `toString` as well where
+  // the value left the analysis.
+  const holdsBack = (flags: SymbolFlags, name: string, to: Destination): boolean =>
+    (flags & SymbolFlags.Property) !== 0 ||
+    ((flags & SymbolFlags.Method) !== 0 &&
+      (name === SERIALIZED_CONVERSION || (to.reach === "conversions" && CONVERSIONS.has(name))));
   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}`;
     for (const member of [...flow.classes].flatMap((id) => members.get(id) ?? [])) {
       const symbol = byId.get(member.id);
-      const isProperty = (member.flags & SymbolFlags.Property) !== 0;
-      const converts =
-        flow.to.reach === "conversions" &&
-        (member.flags & SymbolFlags.Method) !== 0 &&
-        symbol !== undefined &&
-        CONVERSIONS.has(memberComponent(symbol, byId) ?? "");
-      if (isProperty || converts) {
+      const name = symbol === undefined ? "" : (memberComponent(symbol, byId) ?? "");
+      if (holdsBack(member.flags, name, flow.to)) {
         found.push({ id: member.id, detail, site });
       }
     }
+    for (const member of flow.members) {
+      if (holdsBack(member.flags, member.name, flow.to)) {
+        for (const id of chains.declarationsOf(member)) {
+          found.push({ id, detail, site });
+        }
+      }
+    }
   }
   return found;
 }