@cplieger/deadset-ts 8.0.0-dev.8 → 8.0.0-dev.9

package/src/scope.ts

@@ -2,6 +2,8 @@ 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 { 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";
@@ -18,17 +20,6 @@ const MAX_DOCUMENT_LENGTH = 1 << 20;
  */
 const MAX_DOCUMENT_BYTES = 3 * (MAX_DOCUMENT_LENGTH + 1);
 
-/**
- * A scope 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.
- */
-export class ScopeError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "ScopeError";
-  }
-}
-
 /**
  * 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.
@@ -51,14 +42,14 @@ interface DeclaredModule {
   readonly path: string;
 }
 
-function refusal(file: string, place: string, reason: string): ScopeError {
-  return new ScopeError(`scope: ${file}: ${place === "" ? "" : `${place}: `}${reason}`);
+function refusal(file: string, place: string, reason: string): UsageError {
+  return new UsageError(`scope: ${file}: ${place === "" ? "" : `${place}: `}${reason}`);
 }
 
 /**
  * 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 is
- * a usage error, one that is refused a scope error. `workspace` is read by Go consumers
+ * 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 {
@@ -70,7 +61,7 @@ export function readScope(host: Host, file: string): Scope {
     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 {
@@ -94,15 +85,18 @@ export function readScope(host: Host, file: string): Scope {
   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

@@ -15,9 +15,7 @@ import type {
 } from "@typescript/native/sync";
 import type { Node, SourceFile } 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,
@@ -37,8 +35,8 @@ import { MANIFEST } from "./fs/manifest.ts";
 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. */
@@ -272,13 +270,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.
@@ -472,19 +463,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
@@ -513,22 +515,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[] = [];
@@ -553,32 +551,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();
     }
@@ -586,3 +565,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,7 +5,7 @@
  */
 
 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";
 

package/src/type-errors.ts

@@ -1,58 +1,22 @@
 /**
- * What the errors a project's own files carry do to the run. An import of a module the
- * project expects and nothing provides is a setup failure. Any other error in an own file
- * is a type error: the function, method or file-level statement holding it is skipped,
- * which only ever withholds a finding. `projectErrors` decides, before any of these, which
- * errors the compiler places in no file leave the project unloaded.
+ * What a type error in a project's own file does: the function, method or file-level statement
+ * holding it is skipped, which only ever withholds a finding.
  */
 
 import {
   isClassDeclaration,
   isFunctionLikeDeclaration,
-  isNoSubstitutionTemplateLiteral,
   isPropertyAccessExpression,
-  isStringLiteral,
   type Node,
   type PropertyAccessExpression,
   type SourceFile,
 } from "@typescript/native/ast";
 import type { Symbol as TSSymbol, Type } from "@typescript/native/sync";
-import { packageOfSpecifier } from "./dependencies.ts";
-import type { LocatedDiagnostic } from "./discover.ts";
-import type { Host } from "./host.ts";
 import { nodeKey, type Inventory } from "./inventory.ts";
-import {
-  ancestors,
-  dirnamePath,
-  isAbsolutePath,
-  joinPath,
-  relativePath,
-  resolvePath,
-} from "./paths.ts";
+import { relativePath } from "./paths.ts";
 import { isAnswered } from "./query.ts";
 import type { TypeErrorSkip } from "./report.ts";
-import type { Engine, ProjectView } from "./session.ts";
-import type { SetupFailure } from "./setup-failure.ts";
-import { findWorkspace, type Workspace } from "./workspace.ts";
-import { entriesOf } from "./fs/tree.ts";
-import { INSTALLED_PACKAGES, MANIFEST, manifestAt } from "./fs/manifest.ts";
-
-/** The compiler's codes for an import whose module it cannot find. */
-const MODULE_NOT_FOUND: ReadonlySet<number> = new Set([2307, 2792]);
-
-/**
- * The compiler's codes for where the configuration places a file, which leave every type
- * the file's statements carry as it is: an output that would overwrite an input (5055,
- * 5056), a file outside `rootDir` (6059), one a composite project does not list (6307).
- */
-const CONFIGURATION_LEVEL: ReadonlySet<number> = new Set([5055, 5056, 6059, 6307]);
-
-const MANIFEST_SECTIONS = [
-  "dependencies",
-  "devDependencies",
-  "peerDependencies",
-  "optionalDependencies",
-] as const;
+import type { ProjectView } from "./session.ts";
 
 /** The lines of one file a skip withholds every finding on. */
 export interface SkippedUnit {
@@ -74,184 +38,12 @@ export function insideSkipped(
 }
 
 /** One type error of an own file, with the unit it skips. */
-interface Skip {
+export interface Skip {
   readonly record: TypeErrorSkip;
   readonly file: SourceFile;
   readonly unit: Node;
 }
 
-/** What the errors of one project's own files are. */
-interface ProjectErrorReading {
-  /** The imports of a module the project expects that nothing provides, one failure each. */
-  readonly missing: readonly SetupFailure[];
-  /** The type errors, each with the unit it skips. */
-  readonly skips: readonly Skip[];
-}
-
-/** Where one project reads what its imports may name. */
-interface ErrorContext {
-  readonly host: Host;
-  /** The target root, absolute. */
-  readonly targetRoot: string;
-  /** The project configuration's `paths` mapping. */
-  readonly paths: PathsMapping;
-  /** Whether one manifest is a workspace member's, whose dependencies the workspace installs. */
-  readonly member: (manifest: string) => boolean;
-}
-
-/** One configuration's `paths` mapping, its targets read against `base`. */
-interface PathsMapping {
-  readonly base: string;
-  readonly entries: readonly { readonly key: string; readonly targets: readonly string[] }[];
-}
-
-/** The string literal holding one offset, innermost first, a doc comment's included. */
-function literalAt(file: SourceFile, offset: number): string | undefined {
-  let found: string | undefined;
-  const visit = (node: Node): void => {
-    if (offset < node.pos || offset >= node.end) {
-      return;
-    }
-    if (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node)) {
-      found = node.text;
-    }
-    // `forEachChild` does not enter a doc comment, where a JavaScript file imports types.
-    for (const doc of (node as { readonly jsDoc?: readonly Node[] }).jsDoc ?? []) {
-      visit(doc);
-    }
-    node.forEachChild(visit);
-  };
-  file.forEachChild(visit);
-  return found;
-}
-
-/**
- * What one `paths` key's `*` matches in one specifier, `""` for a key with no `*` that
- * is the specifier, or `undefined` where the key does not match it.
- */
-function mappedBy(key: string, specifier: string): string | undefined {
-  const star = key.indexOf("*");
-  if (star < 0) {
-    return key === specifier ? "" : undefined;
-  }
-  const prefix = key.slice(0, star);
-  const suffix = key.slice(star + 1);
-  return specifier.length >= prefix.length + suffix.length &&
-    specifier.startsWith(prefix) &&
-    specifier.endsWith(suffix)
-    ? specifier.slice(prefix.length, specifier.length - suffix.length)
-    : undefined;
-}
-
-/**
- * One `paths` target, its first `*` replaced by `star` taken literally, as the compiler does:
- * https://github.com/microsoft/typescript-go/blob/89d5d5b2849a0db0957065889ca58536fa6d2e4a/internal/module/resolver.go#L1282
- */
-function substituted(target: string, star: string): string {
-  const at = target.indexOf("*");
-  return at < 0 ? target : target.slice(0, at) + star + target.slice(at + 1);
-}
-
-/**
- * Whether a path names something on disk, as written or with any extension; under
- * `fileOnly`, only a file counts.
- */
-function provided(host: Host, path: string, fileOnly: boolean): boolean {
-  const counts = (at: string): boolean =>
-    fileOnly ? host.kindOf(at) === "file" : host.kindOf(at) !== "absent";
-  if (counts(path)) {
-    return true;
-  }
-  const dir = dirnamePath(path);
-  const stem = `${path.slice(dir.length + 1)}.`;
-  return entriesOf(host, dir).some(
-    (entry) => entry.name.startsWith(stem) && counts(joinPath(dir, entry.name)),
-  );
-}
-
-/** The manifest at or above `dir`, no higher than the target root, that declares `name`. */
-function declaringManifest(
-  host: Host,
-  dir: string,
-  targetRoot: string,
-  name: string,
-): string | undefined {
-  const chain = ancestors(dir, targetRoot);
-  // A directory outside the target root reads its own manifest alone.
-  for (const at of chain.length > 0 ? chain : [dir]) {
-    const manifest = manifestAt(host, at);
-    for (const section of MANIFEST_SECTIONS) {
-      const declared = manifest?.[section];
-      if (typeof declared === "object" && declared !== null && Object.hasOwn(declared, name)) {
-        return joinPath(at, MANIFEST);
-      }
-    }
-  }
-  return undefined;
-}
-
-/**
- * Whether a package is installed for an importer in `dir`: in the `node_modules` of
- * `dir` or of any ancestor, above the target root too, as Node and the compiler look.
- */
-function installed(host: Host, dir: string, name: string): boolean {
-  return ancestors(dir).some(
-    (at) => host.kindOf(joinPath(at, INSTALLED_PACKAGES, name)) === "directory",
-  );
-}
-
-/**
- * Why one import that the compiler cannot resolve names a module the project expects,
- * with the fix, or undefined where the module is one the project does not expect.
- */
-function expectedModule(
-  context: ErrorContext,
-  importer: string,
-  specifier: string,
-): string | undefined {
-  const { host, targetRoot } = context;
-  const fix = "run the generator or the build that writes it";
-  if (specifier.startsWith(".") || isAbsolutePath(specifier)) {
-    return provided(host, resolvePath(dirnamePath(importer), specifier), false)
-      ? undefined
-      : `which names no file of the target: ${fix}`;
-  }
-  if (specifier.startsWith("#")) {
-    return `which the manifest's imports map to no file: ${fix}`;
-  }
-  const mapped = context.paths.entries.flatMap(({ key, targets }) => {
-    const star = mappedBy(key, specifier);
-    return star === undefined
-      ? []
-      : targets.map((target) => resolvePath(context.paths.base, substituted(target, star)));
-  });
-  const name = packageOfSpecifier(specifier);
-  // The compiler looks up in `node_modules` what `paths` does not resolve, so the error
-  // of an installed package's import is the import's own, a subpath its exports omit:
-  // https://github.com/microsoft/typescript-go/blob/89d5d5b2849a0db0957065889ca58536fa6d2e4a/internal/module/resolver.go#L548-L575
-  if (name !== undefined && installed(host, dirnamePath(importer), name)) {
-    return undefined;
-  }
-  if (mapped.length > 0) {
-    return mapped.some((path) => provided(host, path, true))
-      ? undefined
-      : `which the compiler configuration's paths map to no file: ${fix}`;
-  }
-  const manifest =
-    name === undefined
-      ? undefined
-      : declaringManifest(host, dirnamePath(importer), targetRoot, name);
-  // No run requires a nested package that is no workspace member to be installed.
-  if (
-    manifest === undefined ||
-    (dirnamePath(manifest) !== targetRoot && !context.member(manifest))
-  ) {
-    return undefined;
-  }
-  const where = relativePath(targetRoot, manifest) ?? manifest;
-  return `a dependency ${where} declares that is not installed: run the package manager's install`;
-}
-
 /**
  * The unit a type error at one offset skips: the innermost function holding it, else the
  * class member holding it where a top-level class does, else the top-level statement.
@@ -284,62 +76,19 @@ function messageOf(text: string, targetRoot: string): string {
   return line === "" ? "a type error" : line;
 }
 
-/**
- * Reads the errors one project's own files carry. A diagnostic marking unnecessary code
- * or about where the configuration places a file is no error here, and one in a file that
- * is not the project's own is that file's package's to answer for.
- */
-export function readErrors<Brand>(
-  project: ProjectView<Brand>,
-  errors: readonly LocatedDiagnostic[],
-  where: Omit<ErrorContext, "member">,
-): ProjectErrorReading {
-  let workspace: Workspace | undefined | null = null;
-  const context: ErrorContext = {
-    ...where,
-    member: (manifest) => {
-      if (workspace === null) {
-        workspace = findWorkspace(where.host, where.targetRoot, () => undefined);
-      }
-      return workspace?.memberOf(manifest) !== undefined;
-    },
-  };
-  const files = new Map(project.ownSourceFiles().map((file) => [file.fileName, file]));
-  const missing: SetupFailure[] = [];
-  const skips: Skip[] = [];
-  for (const { diagnostic, at } of errors) {
-    const file = diagnostic.fileName === undefined ? undefined : files.get(diagnostic.fileName);
-    if (
-      file === undefined ||
-      diagnostic.reportsUnnecessary === true ||
-      CONFIGURATION_LEVEL.has(diagnostic.code)
-    ) {
-      continue;
-    }
-    const path = relativePath(context.targetRoot, file.fileName) ?? file.fileName;
-    const line = at?.line ?? 1;
-    const specifier = MODULE_NOT_FOUND.has(diagnostic.code)
-      ? literalAt(file, diagnostic.pos)
-      : undefined;
-    const expected =
-      specifier === undefined ? undefined : expectedModule(context, file.fileName, specifier);
-    if (specifier !== undefined && expected !== undefined) {
-      missing.push({
-        setupClass: "missing-module",
-        detail: `${path}:${String(line)}: ${path} imports ${JSON.stringify(specifier)}, ${expected}`,
-      });
-      continue;
-    }
-    const unit = unitAt(file, diagnostic.pos);
-    if (unit !== undefined) {
-      skips.push({
-        record: { path, line, message: messageOf(diagnostic.text, context.targetRoot) },
-        file,
-        unit,
-      });
-    }
-  }
-  return { missing, skips };
+/** The skip one type error at `offset` of an own file makes, the root spelled relative to itself. */
+export function skipAt(
+  file: SourceFile,
+  offset: number,
+  line: number,
+  text: string,
+  targetRoot: string,
+): Skip | undefined {
+  const unit = unitAt(file, offset);
+  const path = relativePath(targetRoot, file.fileName) ?? file.fileName;
+  return unit === undefined
+    ? undefined
+    : { record: { path, line, message: messageOf(text, targetRoot) }, file, unit };
 }
 
 /** The lines each skip withholds, below the target root. */
@@ -411,22 +160,3 @@ export function skippedRoots<Brand>(
   }
   return [...kept];
 }
-
-/** One compiler configuration's `paths` mapping, empty where it cannot be read. */
-export function pathsOf(engine: Engine, configFile: string): PathsMapping {
-  const base = dirnamePath(configFile);
-  try {
-    const { options } = engine.parseConfigFile(configFile);
-    const { paths } = options;
-    // The parse answers `pathsBasePath`, the directory of the configuration that writes
-    // `paths` (an extended one included), though the client's option type omits it:
-    // https://github.com/microsoft/typescript-go/blob/89d5d5b2849a0db0957065889ca58536fa6d2e4a/internal/tsoptions/tsconfigparsing.go#L1120
-    const declaredAt = (options as { readonly pathsBasePath?: unknown }).pathsBasePath;
-    return {
-      base: typeof declaredAt === "string" ? declaredAt : base,
-      entries: Object.entries(paths ?? {}).map(([key, targets]) => ({ key, targets })),
-    };
-  } catch {
-    return { base, entries: [] };
-  }
-}