@cplieger/deadset-ts 4.0.1 → 5.1.0

package/src/session.ts

@@ -1,8 +1,11 @@
 import { API, SymbolFlags } from "@typescript/native/unstable/sync";
 import type {
   APIRequestGenerator,
+  CreateSnapshotProgramParams,
   Diagnostic,
   DocumentIdentifier,
+  ModuleResolutionEntry,
+  ModuleResolver,
   NodeHandle,
   Project,
   Program,
@@ -11,7 +14,11 @@ import type {
   TimingInfo,
 } from "@typescript/native/unstable/sync";
 import type { Node, SourceFile } from "@typescript/native/unstable/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,
   UnansweredLog,
@@ -36,8 +43,34 @@ export interface Engine {
    * the compiler package returns here is not one of its exported names.
    */
   parseConfigFile(file: DocumentIdentifier): ReturnType<API["parseConfigFile"]>;
-  /** Opens one snapshot holding every project named. */
-  createSnapshot(openProjects: readonly string[]): Snapshot;
+  /** Resolves one configuration's JSON as if `configFile` held it, which no file need. */
+  parseConfigJson(json: unknown, configFile: string): ReturnType<API["parseConfigFile"]>;
+  /**
+   * Opens one snapshot holding every project named and every program described, the
+   * programs in the order given in the snapshot's operation. A project named in
+   * `configurations` is opened from that configuration text, which the snapshot alone
+   * holds.
+   */
+  createSnapshot(
+    openProjects: readonly string[],
+    createPrograms?: readonly CreateSnapshotProgramParams[],
+    configurations?: ReadonlyMap<string, string>,
+  ): Snapshot;
+  /**
+   * Whether the snapshots read component files. A described program reads none, because
+   * the compiler gives a program no content mapper.
+   */
+  readonly readsComponents: boolean;
+  /**
+   * A module resolver answering each entry's import with the entry's file, and every
+   * other import as the compiler resolves it.
+   */
+  createModuleResolver(
+    options: CreateSnapshotProgramParams["compilerOptions"],
+    entries: readonly ModuleResolutionEntry[],
+  ): ModuleResolver;
+  /** Parses one file's text outside every program. */
+  parseSourceFile(fileName: string, text: string): SourceFile;
   /** Sends many questions in one round trip and answers each, in order. */
   batch<T>(questions: readonly APIRequestGenerator<T>[]): T[];
   /**
@@ -56,6 +89,20 @@ export interface Engine {
 export interface EngineOptions {
   /** Collect per-request timing, which the calibration record reads. */
   readonly collectTiming: boolean;
+  /**
+   * The component files every snapshot reads. Present, every configuration a snapshot opens
+   * takes this analyzer's mapper in place of its own, or no mapper where no extension is
+   * listed, and with an extension the client runs that mapper from a temporary directory the
+   * close removes. Absent, the configurations are opened as they are and no mapper runs.
+   */
+  readonly components?: ComponentReading;
+}
+
+/** Which files a run reads as component files, and the host that runs their mapper. */
+export interface ComponentReading {
+  /** The file name extensions of component files, `ts.component_extensions`. */
+  readonly extensions: readonly string[];
+  readonly host: Host;
 }
 
 /**
@@ -66,11 +113,61 @@ export interface EngineOptions {
  * second call has nothing left to do.
  */
 export function openEngine(options: EngineOptions): Engine {
-  const api = new API({ collectTiming: options.collectTiming });
+  const { components } = options;
+  let mapper: TemporaryDirectory | undefined;
+  if (components !== undefined && components.extensions.length > 0) {
+    const made = components.host.temporaryDirectory();
+    try {
+      components.host.writeDocument(joinPath(made.path, "package.json"), [
+        mapperManifest(components.host.componentMapperCommand()),
+      ]);
+    } catch (error: unknown) {
+      made.remove();
+      throw error;
+    }
+    mapper = made;
+  }
+  const api = new API({
+    collectTiming: options.collectTiming,
+    ...(mapper === undefined ? {} : { runExternalCode: true }),
+  });
   let closed = false;
   return {
     parseConfigFile: (file) => api.parseConfigFile(file),
-    createSnapshot: (openProjects) => api.createSnapshot({ openProjects: [...openProjects] }),
+    parseConfigJson: (json, configFile) =>
+      api.parseJsonConfigFileContent(json, { configFileName: configFile }),
+    createSnapshot: (openProjects, createPrograms, configurations = new Map()) =>
+      api.createSnapshot({
+        openProjects: [...openProjects],
+        ...(createPrograms === undefined ? {} : { createPrograms: [...createPrograms] }),
+        ...(components === undefined
+          ? configurations.size === 0
+            ? {}
+            : { fileSystem: { kind: "layer", files: Object.fromEntries(configurations) } }
+          : {
+              fileSystem: componentLayer(
+                components.host,
+                openProjects,
+                mapper === undefined
+                  ? undefined
+                  : { extensions: components.extensions, packageDirectory: mapper.path },
+                configurations,
+              ),
+            }),
+      }),
+    readsComponents: mapper !== undefined,
+    createModuleResolver: (options, entries) =>
+      api.createModuleResolver(options, {
+        moduleResolutions: { fallback: "resolve", entries: [...entries] },
+      }),
+    parseSourceFile: (fileName, text) => {
+      const retained = api.createSourceFile(fileName, text);
+      try {
+        return retained.sourceFile;
+      } finally {
+        retained.dispose();
+      }
+    },
     batch: <T>(questions: readonly APIRequestGenerator<T>[]) =>
       api.batch<readonly APIRequestGenerator<T>[]>(...questions),
     ask: (_accessor, _locations, question) => question(),
@@ -80,7 +177,11 @@ export function openEngine(options: EngineOptions): Engine {
         return;
       }
       closed = true;
-      api.close();
+      try {
+        api.close();
+      } finally {
+        mapper?.remove();
+      }
     },
   };
 }
@@ -112,6 +213,11 @@ export interface ProjectView<Brand> {
    * trip, and one may go unanswered.
    */
   readonly queries: Queries;
+  /**
+   * The files the project's configuration names, as the project reads them, so a
+   * component file a mapper reads is among them.
+   */
+  readonly rootFiles: readonly string[];
   /** The source files the program holds that are the target's own. */
   ownSourceFiles(): readonly SourceFile[];
   /**
@@ -166,6 +272,34 @@ export interface ProjectView<Brand> {
  */
 export type ProjectVisitor<Result> = <Brand>(project: ProjectView<Brand>) => Result;
 
+/**
+ * The source files of one program that `own` admits, in the program's order, none of
+ * them one of the compiler's default libraries.
+ */
+function filesOwned(
+  program: Program,
+  own: (fileName: string, fromExternalLibrary: boolean) => boolean,
+): readonly SourceFile[] {
+  return (
+    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 = program.getSourceFileMetadata(name);
+        return (
+          metadata !== undefined &&
+          !metadata.isDefaultLibrary &&
+          own(name, metadata.isFromExternalLibrary)
+        );
+      })
+      .map((name) => program.getSourceFile(name))
+      .filter((file): file is SourceFile => file !== undefined)
+  );
+}
+
 function viewOf<Brand>(
   project: Project,
   configFile: string,
@@ -186,25 +320,13 @@ function viewOf<Brand>(
   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);
+    ownFiles ??= filesOwned(project.program, (_name, fromExternalLibrary) => !fromExternalLibrary);
     return ownFiles;
   };
   return {
     configFile,
     program: project.program,
+    rootFiles: project.parsedCommandLine.fileNames,
     queries,
     ownSourceFiles,
     ownPaths: () => {
@@ -263,6 +385,30 @@ export function narrowedTo<Brand>(
   };
 }
 
+/**
+ * The same project, its own source files the ones `own` admits among every file its
+ * program holds, given whether the compiler reached the file as a library's.
+ */
+export function ownedAs<Brand>(
+  project: ProjectView<Brand>,
+  own: (fileName: string, fromExternalLibrary: boolean) => boolean,
+): ProjectView<Brand> {
+  let owned: readonly SourceFile[] | undefined;
+  let keys: ReadonlySet<string> | undefined;
+  const ownSourceFiles = (): readonly SourceFile[] => {
+    owned ??= filesOwned(project.program, own);
+    return owned;
+  };
+  return {
+    ...project,
+    ownSourceFiles,
+    ownPaths: () => {
+      keys ??= new Set(ownSourceFiles().map((file) => file.path));
+      return keys;
+    },
+  };
+}
+
 /** Every diagnostic set a project is refused for carrying an error in. */
 export interface ProjectDiagnostics {
   readonly configFile: string;
@@ -309,33 +455,68 @@ export interface SessionResult<Result> {
 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.
- *
- * The snapshot is opened once with every configuration, so each becomes a project
- * 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. 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.
+ * The projects one snapshot holds for the configurations named, by configuration file. A
+ * project opened from a written configuration is the project of the configuration
+ * `written` maps it to.
+ */
+function projectsOf(
+  snapshot: Snapshot,
+  built: readonly string[],
+  written: ReadonlyMap<string, string>,
+): ReadonlyMap<string, Project> {
+  const opened = new Map<string, Project>();
+  for (const project of snapshot.getProjects()) {
+    if (project.configFileName !== undefined) {
+      opened.set(written.get(project.configFileName) ?? project.configFileName, project);
+    }
+  }
+  (snapshot.operation.createdPrograms ?? []).forEach((program, at) => {
+    const project = snapshot.getProject(program.id);
+    const configFile = built[at];
+    if (project !== undefined && configFile !== undefined) {
+      opened.set(configFile, project);
+    }
+  });
+  return opened;
+}
+
+/**
+ * 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"`. The snapshot is disposed after the last visit and the client released
+ * after it, whether the visit completed or threw.
  */
 export function runSession<Result>(
   engine: Engine,
   configFiles: readonly string[],
   visit: ProjectVisitor<Result>,
   unopened: Unopened = "refuse",
+  programs: ReadonlyMap<string, WorkspaceProgram> = new Map(),
 ): SessionResult<Result> {
   try {
-    const snapshot = engine.createSnapshot(configFiles);
-    try {
-      const opened = new Map<string, Project>();
-      for (const project of snapshot.getProjects()) {
-        if (project.configFileName !== undefined) {
-          opened.set(project.configFileName, project);
-        }
+    const built: string[] = [];
+    const params: CreateSnapshotProgramParams[] = [];
+    const written = new Map<string, string>();
+    const texts = new Map<string, string>();
+    for (const configFile of configFiles) {
+      const program = programs.get(configFile);
+      if (program?.kind === "program") {
+        built.push(configFile);
+        params.push(program.params);
+      } else if (program?.kind === "configuration") {
+        written.set(program.file, configFile);
+        texts.set(program.file, program.text);
       }
+    }
+    const snapshot = engine.createSnapshot(
+      [...configFiles.filter((configFile) => !programs.has(configFile)), ...written.keys()],
+      params.length === 0 ? undefined : params,
+      texts,
+    );
+    try {
+      const opened = projectsOf(snapshot, built, written);
       const log = new UnansweredLog();
       const projects: Result[] = [];
       const missing: string[] = [];

package/src/setup-failure.ts

@@ -0,0 +1,39 @@
+/**
+ * A setup failure: a file or a component the analysis needs and the project does not
+ * provide. Each one names what is missing and the fix, on one line of the error stream
+ * that starts with its class.
+ */
+
+/** The classes of setup failure this analyzer meets. */
+type SetupClass =
+  | "missing-module"
+  | "missing-consumer"
+  | "workspace-member-without-source"
+  | "convention-not-literal";
+
+export interface SetupFailure {
+  readonly setupClass: SetupClass;
+  /** What is missing and the fix, on one line. */
+  readonly detail: string;
+}
+
+/** The failure as the one line of the error stream that names it. */
+export function setupLine(failure: SetupFailure): string {
+  return `setup failure: ${failure.setupClass}: ${failure.detail}`;
+}
+
+/**
+ * A run that met a setup failure where none may be dropped: in a configuration the
+ * configuration document or the scope declares, in a declared consumer, or in every
+ * configuration discovery derived. It ends the run with the failure code and no finding
+ * list.
+ */
+export class SetupError extends Error {
+  readonly failures: readonly SetupFailure[];
+
+  constructor(failures: readonly SetupFailure[]) {
+    super(failures.map(setupLine).join("\n"));
+    this.name = "SetupError";
+    this.failures = failures;
+  }
+}

package/src/source-files.ts

@@ -5,53 +5,13 @@
  */
 
 import type { SourceFile } from "@typescript/native/unstable/ast";
-import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
+import { commonDirectory, emittedFrom } from "./emit-map.ts";
+import { dirnamePath, relativePath, resolvePath } from "./paths.ts";
 import type { ProjectView } from "./session.ts";
 
-/** The source extensions the compiler emits each output extension from. */
-const EMITTED: readonly { readonly emitted: string; readonly sources: readonly string[] }[] = [
-  { emitted: ".d.ts", sources: [".ts", ".tsx"] },
-  { emitted: ".d.mts", sources: [".mts"] },
-  { emitted: ".d.cts", sources: [".cts"] },
-  { emitted: ".js", sources: [".ts", ".tsx"] },
-  { emitted: ".jsx", sources: [".tsx"] },
-  { emitted: ".mjs", sources: [".mts"] },
-  { emitted: ".cjs", sources: [".cts"] },
-];
-
 /** The one character a subpath pattern of a manifest's `exports` holds. */
 const SUBPATH_WILDCARD = "*";
 
-/** One path with its extension replaced, where it carries the one named. */
-function reExtended(path: string, emitted: string, source: string): string | undefined {
-  return path.endsWith(emitted) ? path.slice(0, path.length - emitted.length) + source : undefined;
-}
-
-/**
- * The longest directory every path shares, which is the directory the compiler
- * emits from where the configuration declares no root directory.
- */
-function commonDirectory(paths: readonly string[]): string {
-  const first = paths[0];
-  if (first === undefined) {
-    return "";
-  }
-  let common = dirnamePath(first).split("/");
-  for (const path of paths.slice(1)) {
-    const segments = dirnamePath(path).split("/");
-    let shared = 0;
-    while (
-      shared < common.length &&
-      shared < segments.length &&
-      common[shared] === segments[shared]
-    ) {
-      shared += 1;
-    }
-    common = common.slice(0, shared);
-  }
-  return common.join("/");
-}
-
 /**
  * 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.
@@ -108,32 +68,10 @@ export function sourceFilesOf<Brand>(project: ProjectView<Brand>, targetRoot: st
   const declarationDir = at(options.declarationDir);
   const sourceDir = at(options.rootDir) ?? commonDirectory([...byName.keys()]);
 
-  /** One path read below the directory the compiler emits from, where it is below the one it emits to. */
-  const fromEmit = (path: string, emitted: string): string | undefined => {
-    const emitDir = emitted.startsWith(".d.") ? (declarationDir ?? outDir) : outDir;
-    if (emitDir === undefined) {
-      return undefined;
-    }
-    const below = relativePath(emitDir, path);
-    return below === undefined ? undefined : joinPath(sourceDir, below);
-  };
+  const layout = { outDir, declarationDir, sourceDirs: [sourceDir] };
 
   /** The source paths one written path may stand for, the path itself first. */
-  const candidates = (path: string): readonly string[] => {
-    const found = [path];
-    for (const { emitted, sources } of EMITTED) {
-      const mapped = fromEmit(path, emitted);
-      for (const source of sources) {
-        for (const from of [path, mapped]) {
-          const candidate = from === undefined ? undefined : reExtended(from, emitted, source);
-          if (candidate !== undefined) {
-            found.push(candidate);
-          }
-        }
-      }
-    }
-    return found;
-  };
+  const candidates = (path: string): readonly string[] => [path, ...emittedFrom(path, layout)];
 
   return {
     byPath,

package/src/stores.ts

@@ -22,6 +22,8 @@ export interface Stores {
    * configuration. A production mode counts none a test file made.
    */
   readonly references: readonly Reference[];
+  /** The declarations a test file reads, which a production mode counts no read of. */
+  readonly readInTests: ReadonlySet<string>;
   /**
    * The class members declared by a getter or a setter. A store into one runs the
    * setter, which is code rather than state.
@@ -71,6 +73,13 @@ export function storesOf(
     references: per.flatMap((one) =>
       one.references.filter((reference) => !mode.production || !reference.test),
     ),
+    readInTests: new Set(
+      per.flatMap((one) =>
+        one.references
+          .filter((reference) => reference.test && reference.use !== "write")
+          .map((reference) => reference.to),
+      ),
+    ),
     accessors: new Set(per.flatMap((one) => one.accessors)),
     exempt: new Set(exempt.map((record) => record.id)),
   };

package/src/sweep.ts

@@ -22,6 +22,11 @@ export interface Exemption {
   readonly detail: string;
   /** Where the evidence is written. */
   readonly site: Position;
+  /**
+   * The component file, below the target root, whose markup holds the evidence. The
+   * record holds only while that file is live.
+   */
+  readonly whileLive?: string;
 }
 
 /**
@@ -253,13 +258,15 @@ function admitTestsOfDeadCode(
 ): readonly boolean[] {
   const admitted = graph.symbols.map(() => false);
   graph.symbols.forEach((_symbol, at) => {
-    if (graph.test[at] !== true || graph.subject[at] !== true || held[at] === true) {
+    const testCode = graph.test[at] === true || graph.support[at] === true;
+    if (!testCode || graph.subject[at] !== true || held[at] === true) {
       return;
     }
     let targets = 0;
     let live = 0;
     for (const edge of graph.out[at] ?? []) {
-      if (graph.test[edge.to] === true || graph.subject[edge.to] !== true) {
+      const target = graph.test[edge.to] === true || graph.support[edge.to] === true;
+      if (target || graph.subject[edge.to] !== true) {
         continue;
       }
       targets += 1;

package/src/template-field.ts

@@ -12,13 +12,14 @@
  * type, because nothing ties the name to a type.
  */
 
+import { readComponent } from "./component-files.ts";
 import { ConfigError, type Analysis, type TemplateDelimiters } from "./config.ts";
 import type { DetectorInput, Evidence } from "./exempt.ts";
 import type { Host } from "./host.ts";
 import type { SymbolKind } from "./inventory.ts";
 import { memberNames } from "./member-names.ts";
-import { isAbsolutePath, joinPath, normalizePath } from "./paths.ts";
-import type { Position } from "./position.ts";
+import { isAbsolutePath, joinPath, normalizePath, relativePath } from "./paths.ts";
+import { isComponentFile, type Position } from "./position.ts";
 
 /** One template, by its path below the target root. */
 export interface TemplateFile {
@@ -40,6 +41,12 @@ const READ_BY_A_TEMPLATE: ReadonlySet<SymbolKind> = new Set([
   "type-member",
 ]);
 
+/**
+ * The kinds of declaration a component file's markup can name. Its expressions are the
+ * language's own, so a static member and an enum member are reachable by name too.
+ */
+const READ_BY_MARKUP: ReadonlySet<SymbolKind> = new Set([...READ_BY_A_TEMPLATE, "enum-member"]);
+
 /** One identifier, as the grammar of the analyzed language spells one. */
 const IDENTIFIER = /[\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*/uy;
 
@@ -173,6 +180,17 @@ function namesOf(text: string, delimiters: TemplateDelimiters): readonly Named[]
   }
 }
 
+/** Every identifier the markup of one component file writes in an action. */
+function markupNamesOf(text: string): readonly Named[] {
+  return readComponent(text).markup.flatMap((one) =>
+    identifiersOf(one.text).map(({ name, offset }) => ({
+      name,
+      offset: one.start + offset,
+      action: one.action,
+    })),
+  );
+}
+
 /** Where one offset of a template is, its column counted in UTF-16 code units. */
 function positionIn(file: TemplateFile, offset: number): Position {
   const before = file.text.slice(0, offset);
@@ -187,25 +205,42 @@ function positionIn(file: TemplateFile, offset: number): Position {
 /**
  * The template-field detector: every instance member of a class and every member of
  * an interface or an object type whose name an action of a configured template
- * writes, recorded at the identifier.
+ * writes, and every member of those and of an enum whose name a component file's
+ * markup writes, recorded at the identifier and held while that file is live.
  */
 export function templateField<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
   const { templates } = input;
-  if (templates.files.length === 0) {
+  const components = input.project.ownSourceFiles().flatMap((file) => {
+    const path = isComponentFile(file) ? relativePath(input.targetRoot, file.fileName) : undefined;
+    return path === undefined ? [] : [{ path, text: file.originalText }];
+  });
+  if (templates.files.length === 0 && components.length === 0) {
     return [];
   }
   const members = memberNames(input.project.ownSourceFiles(), input.held);
   const found: Evidence[] = [];
-  for (const file of templates.files) {
-    for (const named of namesOf(file.text, templates.delimiters)) {
+  const scanned = [
+    ...templates.files.map((file) => ({
+      file,
+      names: namesOf(file.text, templates.delimiters),
+      markup: false,
+    })),
+    ...components.map((file) => ({ file, names: markupNamesOf(file.text), markup: true })),
+  ];
+  for (const { file, names, markup } of scanned) {
+    for (const named of names) {
       for (const member of members.get(named.name) ?? []) {
-        if (!READ_BY_A_TEMPLATE.has(member.kind) || member.static) {
+        const readable = markup
+          ? READ_BY_MARKUP.has(member.kind)
+          : READ_BY_A_TEMPLATE.has(member.kind) && !member.static;
+        if (!readable) {
           continue;
         }
         found.push({
           id: member.id,
           detail: `named by ${named.action}`,
           site: positionIn(file, named.offset),
+          ...(markup ? { whileLive: file.path } : {}),
         });
       }
     }