@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.21

package/src/scope.ts

@@ -1,11 +1,12 @@
-import { ConfigError } from "./config.ts";
+import { SCOPE_SCHEMA } from "./contract/config.generated.ts";
 import type { Host } from "./host.ts";
+import { dotted, locatedFault, placeIn, readStrict, StrictJSONError } from "./json-document.ts";
 import { dirnamePath, isAbsolutePath, joinPath, resolvePath } from "./paths.ts";
-import { checkDocument, type KeyNode } from "./schema.ts";
-
-/** The roles a scope document declares for a module. */
-const ROLE_TARGET = "target";
-const ROLE_CONSUMER = "consumer";
+import { MARKERS } from "./load/discover.ts";
+import { failureExit } from "./failure.ts";
+import { message } from "./product.ts";
+import { firstRefusal } from "./schema.ts";
+import { UsageError } from "./usage.ts";
 
 /**
  * A scope document above this length is refused rather than decoded. It names one
@@ -14,23 +15,14 @@ const ROLE_CONSUMER = "consumer";
 const MAX_DOCUMENT_LENGTH = 1 << 20;
 
 /**
- * A scope document that cannot be read as one. It ends the run with the failure
- * code: the run could not learn what to analyze, so it produced no answer.
+ * The bytes read of a scope document. A UTF-16 unit decodes from at most three bytes,
+ * so a document past the bound is past it within these.
  */
-export class ScopeError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "ScopeError";
-  }
-}
+const MAX_DOCUMENT_BYTES = 3 * (MAX_DOCUMENT_LENGTH + 1);
 
 /**
- * One module the run reads: the target or a declared consumer.
- *
- * The role a document declares is not carried here, because the resolved scope
- * holds exactly one target and a list of consumers, so a module's role is where it
- * sits. What a document declares is read and refused where it contradicts that
- * position, which is the only place the declaration can be wrong.
+ * One module the run reads: the target or a declared consumer. The role a document
+ * declares is not carried, because a module's role is where the scope holds it.
  */
 export interface Module {
   /** The package name. A document may state it; otherwise it is empty. */
@@ -45,150 +37,66 @@ export interface Scope {
   readonly consumers: readonly Module[];
 }
 
-const MODULE: KeyNode = {
-  kind: "section",
-  members: { id: { kind: "leaf" }, role: { kind: "leaf" }, path: { kind: "leaf" } },
-};
-
-/** The closed key list of the scope document, compared as bytes. */
-const SCOPE_ROOT: KeyNode = {
-  kind: "section",
-  members: {
-    target: MODULE,
-    workspace: { kind: "leaf" },
-    consumers: { kind: "list", members: MODULE.members ?? {} },
-  },
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/**
- * One string member, or undefined where the document omits it. A member the
- * document writes is a string holding at least one character, so `null` and `""`
- * are refused rather than read as absent.
- */
-function stringMember(
-  parent: Record<string, unknown>,
-  name: string,
-  at: string,
-): string | undefined {
-  if (!Object.hasOwn(parent, name)) {
-    return undefined;
-  }
-  const value = parent[name];
-  if (typeof value !== "string") {
-    throw new ScopeError(`scope: ${at === "" ? name : `${at}.${name}`} is not a string`);
-  }
-  if (value === "") {
-    throw new ScopeError(`scope: ${at === "" ? name : `${at}.${name}`} names nothing`);
-  }
-  return value;
-}
-
-function readModule(value: unknown, at: string, role: string, documentDir: string): Module {
-  if (!isRecord(value)) {
-    throw new ScopeError(`scope: ${at} is not an object`);
-  }
-  const declared = stringMember(value, "role", at);
-  if (declared !== undefined && declared !== role) {
-    throw new ScopeError(
-      `scope: ${at}.role is ${JSON.stringify(declared)}, want ${JSON.stringify(role)}`,
-    );
-  }
-  const path = stringMember(value, "path", at);
-  if (path === undefined) {
-    throw new ScopeError(`scope: ${at}.path names nothing`);
-  }
-  return {
-    id: stringMember(value, "id", at) ?? "",
-    path: isAbsolutePath(path) ? path : joinPath(documentDir, path),
-  };
+interface DeclaredModule {
+  readonly id?: string;
+  readonly path: string;
 }
 
-/**
- * Walks the document's text against the closed key list, refusing a key the list
- * does not declare, compared as bytes, and a key one object writes twice, which a
- * parse cannot report because it keeps the last value.
- */
-function checkKeys(text: string, file: string): void {
-  try {
-    checkDocument(text, SCOPE_ROOT, `scope: ${file}`);
-  } catch (error: unknown) {
-    if (error instanceof ConfigError) {
-      // The configuration's refusal names the nearest configuration key, which a
-      // scope document does not have.
-      throw new ScopeError(
-        error.kind === "unimplemented-key"
-          ? `scope: ${file}: ${error.key} is not a declared key`
-          : error.message,
-      );
-    }
-    throw error;
-  }
+function refusal(file: string, place: string, reason: string): UsageError {
+  return new UsageError(`scope: ${file}: ${place === "" ? "" : `${place}: `}${reason}`);
 }
 
 /**
- * Decodes the scope document at `file`. Decoding is strict: an undeclared key, a
- * key written twice in one object, and a value of a type the document does not
- * admit, `null` included, are errors, and a relative path inside the document
- * resolves against the document's own directory.
- *
- * The `workspace` key the format declares is checked and carries nothing here: it
- * names the file a Go consumer resolves the target through, and a TypeScript
- * project resolves one through its own compiler configuration.
+ * Decodes the scope document at `file`, held to the Contract's scope schema, a relative
+ * path resolved against the document's own directory. A document that cannot be read or is
+ * refused is a usage error, as any document the invocation names. `workspace` is read by Go consumers
+ * alone: a TypeScript project resolves the target through its own compiler configuration.
  */
 export function readScope(host: Host, file: string): Scope {
   const absolute = resolvePath(host.workingDirectory(), file);
   let text: string;
   try {
-    text = host.readFile(absolute);
+    text = host.readFile(absolute, MAX_DOCUMENT_BYTES);
   } catch (error: unknown) {
-    throw new ScopeError(
-      `scope: ${file}: ${error instanceof Error ? error.message : String(error)}`,
-    );
+    throw new UsageError(`scope: ${file}: ${message(error)}`);
   }
   if (text.length > MAX_DOCUMENT_LENGTH) {
-    throw new ScopeError(`scope: ${file} is longer than ${String(MAX_DOCUMENT_LENGTH)} characters`);
+    throw new UsageError(`scope: ${file} is longer than ${String(MAX_DOCUMENT_LENGTH)} characters`);
   }
   let value: unknown;
   try {
-    value = JSON.parse(text);
+    value = readStrict(text).value;
   } catch (error: unknown) {
-    throw new ScopeError(
-      `scope: ${file}: ${error instanceof Error ? error.message : String(error)}`,
-    );
+    if (!(error instanceof StrictJSONError)) {
+      throw error;
+    }
+    throw refusal(file, dotted(error.place), locatedFault(text, error));
   }
-  if (!isRecord(value)) {
-    throw new ScopeError(`scope: ${file} is not one JSON object`);
+  const refused = firstRefusal(SCOPE_SCHEMA, value);
+  if (refused !== undefined) {
+    throw refusal(file, dotted(placeIn(value, refused.pointer, refused.member)), refused.reason);
   }
-  checkKeys(text, file);
-  stringMember(value, "workspace", "");
+  const declared = value as { target: DeclaredModule; consumers?: readonly DeclaredModule[] };
   const documentDir = dirnamePath(absolute);
-  if (!Object.hasOwn(value, "target")) {
-    throw new ScopeError(`scope: ${file} names no target`);
-  }
-  const target = readModule(value["target"], "target", ROLE_TARGET, documentDir);
-  const listed = Object.hasOwn(value, "consumers") ? value["consumers"] : [];
-  if (!Array.isArray(listed)) {
-    throw new ScopeError(`scope: ${file}: consumers is not an array`);
-  }
-  const consumers = (listed as unknown[]).map((entry, index) =>
-    readModule(entry, `consumers[${String(index)}]`, ROLE_CONSUMER, documentDir),
-  );
-  return { target, consumers };
+  const moduleOf = (module: DeclaredModule): Module => ({
+    id: module.id ?? "",
+    path: isAbsolutePath(module.path) ? module.path : joinPath(documentDir, module.path),
+  });
+  return { target: moduleOf(declared.target), consumers: (declared.consumers ?? []).map(moduleOf) };
 }
 
-/** The single-package scope one directory is, when no scope document is given. */
+/**
+ * The single-package scope one directory is, when no scope document is given. A target that is
+ * no directory holds no program.
+ */
 export function scopeForDir(host: Host, dir: string): Scope {
   const path = resolvePath(host.workingDirectory(), dir);
   const kind = host.kindOf(path);
-  if (kind === "absent") {
-    throw new ScopeError(`scope: ${path} does not exist`);
-  }
   if (kind !== "directory") {
-    throw new ScopeError(`scope: ${path} is not a directory`);
+    throw failureExit(
+      "no-program",
+      `the target ${path} ${kind === "absent" ? "does not exist" : "is not a directory"}, so it holds no compiler configuration, no file named ${MARKERS.join(", ")}: name the directory that holds one`,
+    );
   }
   return { target: { id: "", path }, consumers: [] };
 }

package/src/session.ts

@@ -13,11 +13,9 @@ import type {
   Symbol as TSSymbol,
   TimingInfo,
 } from "@typescript/native/sync";
-import type { Node, SourceFile } from "@typescript/native/ast";
+import type { Node, SourceFile, StringLiteralLikeNode } from "@typescript/native/ast";
 import { componentLayer, mapperManifest } from "./component-layer.ts";
-import { DiscoveryError } from "./discover.ts";
 import type { Host, TemporaryDirectory } from "./host.ts";
-import type { WorkspaceProgram } from "./workspace-programs.ts";
 import { joinPath } from "./paths.ts";
 import {
   queriesOf,
@@ -26,6 +24,7 @@ import {
   type Queries,
   type UnansweredQuestion,
 } from "./query.ts";
+import { MANIFEST } from "./fs/manifest.ts";
 
 /**
  * The compiler the analysis reads through: a client over a protocol to a separate
@@ -36,8 +35,8 @@ import {
 export interface Engine {
   /**
    * Resolves one compiler configuration file, or throws with the reason it cannot
-   * be read. The result is spelled through the client's own signature: the type
-   * the compiler package returns here is not one of its exported names.
+   * be read. The result is spelled through the client's own signature: the type the
+   * compiler package returns here is not one of its exported names.
    */
   parseConfigFile(file: DocumentIdentifier): ReturnType<API["parseConfigFile"]>;
   /** Resolves one configuration's JSON as if `configFile` held it, which no file need. */
@@ -82,6 +81,22 @@ export interface Engine {
   close(): void;
 }
 
+/** The most questions one round trip carries. */
+const BATCH = 2048;
+
+/** Asks one question of every item, in round trips of at most {@link BATCH}, answers in order. */
+export function batched<T, A>(
+  engine: Engine,
+  items: readonly T[],
+  question: (item: T) => APIRequestGenerator<A>,
+): A[] {
+  const answers: A[] = [];
+  for (let at = 0; at < items.length; at += BATCH) {
+    answers.push(...engine.batch(items.slice(at, at + BATCH).map(question)));
+  }
+  return answers;
+}
+
 /** How a run opens its compiler client. */
 export interface EngineOptions {
   /** Collect per-request timing, which the calibration record reads. */
@@ -115,7 +130,7 @@ export function openEngine(options: EngineOptions): Engine {
   if (components !== undefined && components.extensions.length > 0) {
     const made = components.host.temporaryDirectory();
     try {
-      components.host.writeDocument(joinPath(made.path, "package.json"), [
+      components.host.writeDocument(joinPath(made.path, MANIFEST), [
         mapperManifest(components.host.componentMapperCommand()),
       ]);
     } catch (error: unknown) {
@@ -227,6 +242,11 @@ export interface ProjectView<Brand> {
    * file it is in.
    */
   ownPaths(): ReadonlySet<string>;
+  /**
+   * The file the compiler's module resolution names for each module specifier of this
+   * project's files, in order, or `undefined` where it names none.
+   */
+  resolvedFileNames(specifiers: readonly StringLiteralLikeNode[]): (string | undefined)[];
   /** A handle to one node of this project's program. */
   handle(node: Node): Handle<Brand>;
   /**
@@ -271,13 +291,6 @@ 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.
@@ -339,6 +352,17 @@ function viewOf<Brand>(
       ownKeys ??= new Set(ownSourceFiles().map((file) => file.path));
       return ownKeys;
     },
+    resolvedFileNames: (specifiers) =>
+      batched(engine, specifiers, (node) =>
+        project.program.getResolvedModuleFromModuleSpecifier.gen(
+          node,
+          node.getSourceFile().fileName,
+        ),
+      ).map((resolved) =>
+        resolved === undefined || resolved.resolvedFileName === ""
+          ? undefined
+          : resolved.resolvedFileName,
+      ),
     handle: (node) => ({ node }),
     symbolsAt: (handles, cap) =>
       queries.symbolsAt(
@@ -471,19 +495,30 @@ export function diagnosticsOf<Brand>(project: ProjectView<Brand>): ProjectDiagno
   };
 }
 
+/** How a snapshot builds one configuration other than by opening the project it names. */
+export type ProgramBuild =
+  | { readonly kind: "program"; readonly params: CreateSnapshotProgramParams }
+  /** A configuration only the snapshot holds, at a path no file has. */
+  | { readonly kind: "configuration"; readonly file: string; readonly text: string };
+
 /** 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. */
+  /** One answer per configuration, 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";
+/** One open snapshot's projects, valid only while the session that handed it out runs. */
+export interface OpenedSession {
+  /** One view per configuration the snapshot opened a project for, in the order named. */
+  readonly views: readonly ProjectView<unknown>[];
+}
+
+/** How one session opens its configurations. */
+export interface SessionOptions {
+  /** How the snapshot builds each configuration it does not open as its project. */
+  readonly programs?: ReadonlyMap<string, ProgramBuild> | undefined;
+}
 
 /**
  * The projects one snapshot holds for the configurations named, by configuration file. A
@@ -512,22 +547,18 @@ 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. 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.
+ * Opens every project the compiler configurations name in one never updated snapshot of one
+ * client, and hands them to `use` while the client answers; the snapshot and the client are
+ * then released. A configuration `options.programs` describes is built as that program, or
+ * opened from the configuration it writes. One the snapshot holds nothing for has no view.
  */
-export function runSession<Result>(
+export function openSession<Result>(
   engine: Engine,
   configFiles: readonly string[],
-  visit: ProjectVisitor<Result>,
-  unopened: Unopened = "refuse",
-  programs: ReadonlyMap<string, WorkspaceProgram> = new Map(),
-  last: () => void = () => undefined,
-  first: (opened: readonly OpenedFiles[]) => void = () => undefined,
-): SessionResult<Result> {
+  options: SessionOptions,
+  use: (opened: OpenedSession, unanswered: () => readonly UnansweredQuestion[]) => Result,
+): Result {
+  const programs = options.programs ?? new Map<string, ProgramBuild>();
   try {
     const built: string[] = [];
     const params: CreateSnapshotProgramParams[] = [];
@@ -552,32 +583,13 @@ export function runSession<Result>(
       const opened = projectsOf(snapshot, built, written);
       const log = new UnansweredLog();
       const views: ProjectView<unknown>[] = [];
-      const missing: string[] = [];
       for (const configFile of configFiles) {
         const project = opened.get(configFile);
-        if (project === undefined) {
-          if (unopened === "refuse") {
-            throw new DiscoveryError(`${configFile} opened no project`, []);
-          }
-          missing.push(configFile);
-          continue;
+        if (project !== undefined) {
+          views.push(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,
-        unopened: missing,
-        timing: engine.getTimingInfo(),
-        unanswered: log.questions,
-      };
+      return use({ views }, () => log.questions);
     } finally {
       snapshot.dispose();
     }
@@ -585,3 +597,23 @@ export function runSession<Result>(
     engine.close();
   }
 }
+
+/**
+ * Runs `visit` over the project {@link openSession} opens for each configuration, and answers
+ * in their order; a configuration the snapshot opens nothing for throws before any visit.
+ */
+export function runSession<Result>(
+  engine: Engine,
+  configFiles: readonly string[],
+  visit: ProjectVisitor<Result>,
+): SessionResult<Result> {
+  return openSession(engine, configFiles, {}, (opened) => {
+    const unopened = configFiles.find(
+      (configFile) => !opened.views.some((view) => view.configFile === configFile),
+    );
+    if (unopened !== undefined) {
+      throw new Error(`${unopened} opened no project`);
+    }
+    return { projects: opened.views.map((view) => visit(view)), timing: engine.getTimingInfo() };
+  });
+}

package/src/source-files.ts

@@ -5,9 +5,10 @@
  */
 
 import type { SourceFile } from "@typescript/native/ast";
-import { commonDirectory, emittedFrom } from "./emit-map.ts";
+import { commonDirectory, emittedFrom } from "./load/emit-map.ts";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import type { ProjectView } from "./session.ts";
+import { OUTPUT_EXTENSIONS } from "./extensions.ts";
 
 /** The one character a subpath pattern of a manifest's `exports` holds. */
 const SUBPATH_WILDCARD = "*";
@@ -15,9 +16,6 @@ const SUBPATH_WILDCARD = "*";
 /** The extension a source file's name drops when the project writes it out. */
 const SOURCE_EXTENSION = /\.[cm]?[jt]sx?$/u;
 
-/** The extensions the project may write a source file's output under. */
-const OUTPUT_EXTENSIONS = [".js", ".mjs", ".cjs", ".jsx", ".d.ts", ".d.mts", ".d.cts"] as const;
-
 /**
  * Whether one path is what a subpath pattern stands for: the text before the
  * wildcard, any run of characters including the solidus, then the text after it.
@@ -90,13 +88,10 @@ function layoutOf<Brand>(
 }
 
 /**
- * The lookups over one project's own files.
- *
- * A path that names an emitted file is read back to the source the project would
- * emit it from through the project's own emit mapping and nothing else: the
- * extension is one the compiler emits from a source extension, and a path below the
- * output directory is read below the directory the compiler emits from, which the
- * configuration declares or which is the directory every input file shares.
+ * The lookups over one project's own files. A path naming an emitted file is read back to its
+ * source through the project's own emit mapping alone: the extension is one the compiler emits
+ * from a source extension, and a path below the output directory is read below the directory
+ * the compiler emits from, which the configuration declares or every input file shares.
  */
 export function sourceFilesOf<Brand>(project: ProjectView<Brand>, targetRoot: string): SourceFiles {
   const byName = new Map<string, SourceFile>();

package/src/stores.ts

@@ -12,7 +12,9 @@ import {
 import { nodeKey, type Inventory } from "./inventory.ts";
 import type { Reference } from "./references.ts";
 import type { ProjectView } from "./session.ts";
-import type { Exemption, Mode } from "./sweep.ts";
+import type { Exemption } from "./exemptions/lifecycle.ts";
+import type { Mode } from "./tests/file-class.ts";
+import { classedAsTest, madeByTestCode, withheldBy } from "./tests/file-class.ts";
 
 /** One run's stores and reads, over every configuration. */
 export interface Stores {
@@ -39,6 +41,8 @@ export interface Stores {
 /** What one configuration contributes to the run's stores. */
 interface ConfigurationStores {
   readonly references: readonly Reference[];
+  /** The configuration's test-support files, whose references are test code's. */
+  readonly support: ReadonlySet<string>;
   readonly accessors: readonly string[];
 }
 
@@ -71,12 +75,20 @@ export function storesOf(
 ): Stores {
   return {
     references: per.flatMap((one) =>
-      one.references.filter((reference) => !mode.production || !reference.test),
+      one.references.filter((reference) => !withheldBy(mode, reference, one.support)),
     ),
     readInTests: new Set(
       per.flatMap((one) =>
         one.references
-          .filter((reference) => reference.test && reference.use !== "write")
+          .filter(
+            (reference) =>
+              reference.use !== "write" &&
+              classedAsTest(
+                madeByTestCode(reference, one.support),
+                reference.consumer !== undefined,
+                mode,
+              ),
+          )
           .map((reference) => reference.to),
       ),
     ),