@cplieger/deadset-ts 8.0.0-dev.1 → 8.0.0-dev.11

package/src/load/discover.ts

@@ -0,0 +1,455 @@
+import type { BuildConfiguration, ProjectConfiguration } from "../config.ts";
+import { LANGUAGE_ROWS } from "../contract/contract.generated.ts";
+import { filesBelow, filesIn } from "../fs/tree.ts";
+import type { Host } from "../host.ts";
+import { packageScope } from "../inventory.ts";
+import { dirnamePath, joinPath, relativePath, resolvePath } from "../paths.ts";
+import { LANGUAGE, message } from "../product.ts";
+import type { Module, Scope } from "../scope.ts";
+import type { Engine } from "../session.ts";
+import { globExpression } from "../text/glob.ts";
+import { failureExit, type FailureExit } from "../failure.ts";
+import { MANIFEST } from "../fs/manifest.ts";
+
+/** The names of the files a program of the language is read from. */
+export const MARKERS = LANGUAGE_ROWS[LANGUAGE].markers;
+const MARKER_EXPRESSIONS = MARKERS.map(globExpression);
+
+/** Whether one file name is a compiler configuration's: one of the language row's markers. */
+function isConfigFile(name: string): boolean {
+  return MARKER_EXPRESSIONS.some((marker) => marker.test(name));
+}
+
+/**
+ * Where one configuration of a run comes from, which decides what a failure to build it
+ * does: a guess discovery derived is dropped, any other ends the run.
+ */
+export type Origin = "declared" | "scope" | "derived" | "consumer";
+
+/** One consumer the run loads. */
+export interface LoadedConsumer {
+  /** The name the consumer publishes itself under, which every finding names it by. */
+  readonly id: string;
+  /** The consumer's directory, absolute. */
+  readonly path: string;
+}
+
+/** One compiler configuration a run opens. */
+export interface Configuration {
+  /**
+   * The name a run gives the project: the identifier the build matrix declares for it, or,
+   * for a derived one, its configuration file's path below the target root, else its
+   * absolute path. A consumer's is its configuration file's absolute path.
+   */
+  readonly id: string;
+  /** The compiler configuration file, absolute. */
+  readonly configFile: string;
+  readonly origin: Origin;
+  /** The compiler's parse of the configuration, which discovery could read and found not circular. */
+  readonly parsed: Parsed;
+  /** The consumer the configuration loads, for one whose origin is `consumer`. */
+  readonly consumer?: LoadedConsumer | undefined;
+  /**
+   * The configuration of a program the run forms for JavaScript files, which no file holds,
+   * so `configFile` is a free path the snapshot alone holds it at.
+   */
+  readonly written?: Readonly<Record<string, unknown>> | undefined;
+}
+
+/** Whether the run analyzes one configuration as the target's. */
+export function isTargetConfiguration(configuration: Configuration): boolean {
+  return configuration.origin !== "consumer";
+}
+
+/**
+ * One project discovery derived and the run could not build, with the first line of the
+ * error that dropped it.
+ */
+export interface NotBuilt {
+  /** The name the project would have carried, as {@link Configuration.id} spells it. */
+  readonly id: string;
+  /** The compiler configuration file, absolute. */
+  readonly configFile: string;
+  /** The error's first line, every path below the target root spelled relative to it. */
+  readonly error: string;
+}
+
+/**
+ * One entry of the target's matrix: a configuration discovery read, or a tree the plan forms
+ * programs over for the JavaScript files no configuration lists.
+ */
+type Target =
+  | { readonly kind: "configuration"; readonly configuration: Configuration }
+  /** The target tree of a derived matrix. */
+  | { readonly kind: "derived" }
+  /** The directory of a matrix entry naming its `package.json`, at the absolute `manifest`. */
+  | { readonly kind: "declared"; readonly id: string; readonly manifest: string };
+
+/** Every configuration file a run opens, the target's in discovery order, then each consumer's. */
+export interface Discovery {
+  /** Whether the matrix is the configuration document's or one discovery derived. */
+  readonly mode: "declared" | "derived";
+  /** The target's entries, in the order a declared matrix lists them, a derived tree last. */
+  readonly targets: readonly Target[];
+  /** Every configuration of {@link targets}, in its order, then each consumer's. */
+  readonly configurations: readonly Configuration[];
+  /** The derived configurations the compiler could not read, in discovery order. */
+  readonly notBuilt: readonly NotBuilt[];
+  /** Every declared consumer, in the scope's order. */
+  readonly consumers: readonly LoadedConsumer[];
+  /** The consumers holding no configuration, which the plan forms programs over. */
+  readonly unconfigured: readonly LoadedConsumer[];
+}
+
+/**
+ * The first line of one error about the target, every mention of the target root spelled
+ * relative to it: a path below the root loses the root and its separator, and the root
+ * itself is `.`.
+ */
+export function targetRelative(text: string, targetRoot: string): string {
+  const root = targetRoot.endsWith("/") ? targetRoot.slice(0, -1) : targetRoot;
+  const [first = ""] = text.split(/\r?\n/u);
+  const spelled = first.split(`${root}/`).join("").split(root).join(".").trim();
+  return spelled === "" ? "the configuration could not be built" : spelled;
+}
+
+/**
+ * Whether a derived matrix leaves one configuration file unopened: a `jsconfig.json` beside a
+ * `tsconfig.json`, because the compiler's editor host opens the directory's `tsconfig.json`
+ * first and so never its `jsconfig.json`.
+ */
+function shadowed(host: Host, configFile: string): boolean {
+  return (
+    configFile.endsWith("/jsconfig.json") &&
+    host.kindOf(joinPath(dirnamePath(configFile), "tsconfig.json")) === "file"
+  );
+}
+
+/** The configuration files directly in `dir` a derived matrix opens, by name. */
+export function configFilesIn(host: Host, dir: string): readonly string[] {
+  return filesIn(host, dir, isConfigFile).filter((name) => !shadowed(host, joinPath(dir, name)));
+}
+
+/** The configuration files below `root` a derived matrix opens, by absolute path in ascending order. */
+function configFilesUnder(host: Host, root: string): readonly string[] {
+  return filesBelow(host, root, isConfigFile)
+    .map((path) => joinPath(root, path))
+    .filter((path) => !shadowed(host, path));
+}
+
+export type Parsed = ReturnType<Engine["parseConfigFile"]>;
+
+/** The configuration files one parsed configuration's `references` name. */
+function referencesOf(parsed: Parsed): readonly string[] {
+  // The parse answers a directory reference as the directory; the compiler reads a
+  // path not ending `.json` as its `tsconfig.json`:
+  // https://github.com/microsoft/typescript-go/blob/89d5d5b2849a0db0957065889ca58536fa6d2e4a/internal/core/projectreference.go#L18
+  return (parsed.projectReferences ?? []).map(({ path }) =>
+    path.endsWith(".json") ? path : joinPath(path, "tsconfig.json"),
+  );
+}
+
+/**
+ * The code of a configuration whose `extends` chain returns to a configuration it already
+ * passed. A snapshot that opens two configurations whose `extends` chains reach one such
+ * cycle panics (`OwnerCache.AddOwner: entry not found`, typescript 7.1.0-dev.20261014.1),
+ * so the analysis refuses one before any snapshot is asked to open it.
+ */
+const CIRCULAR_EXTENDS = 18000;
+
+/** One configuration file's parse, or why it cannot be read. */
+function readConfiguration(
+  engine: Engine,
+  configFile: string,
+): { readonly parsed: Parsed } | { readonly reason: string } {
+  try {
+    const parsed = engine.parseConfigFile(configFile);
+    const circular = parsed.errors.find(({ code }) => code === CIRCULAR_EXTENDS);
+    // The compiler leaves the message's `{0}` unfilled:
+    // https://github.com/microsoft/TypeScript/pull/64755
+    return circular === undefined
+      ? { parsed }
+      : { reason: `TS${String(circular.code)}: ${circular.text.replace("{0}", () => configFile)}` };
+  } catch (error: unknown) {
+    return { reason: message(error) };
+  }
+}
+
+/** One configuration file the compiler parsed with no circular `extends`, and its parse. */
+interface Read {
+  readonly configFile: string;
+  readonly parsed: Parsed;
+}
+
+/**
+ * Every configuration file reached from `pending`, each once, each followed by the
+ * configurations it references that `follows` admits, transitively. `unreadable` is told
+ * each configuration the compiler cannot read, which the walk then goes on without.
+ */
+function derivedFrom(
+  engine: Engine,
+  host: Host,
+  pending: string[],
+  follows: (reference: string) => boolean,
+  unreadable: (configFile: string, reason: string) => void,
+): Read[] {
+  const seen = new Set<string>();
+  const found: Read[] = [];
+  for (let configFile = pending.shift(); configFile !== undefined; configFile = pending.shift()) {
+    const path = resolvePath(host.workingDirectory(), configFile);
+    if (seen.has(path)) {
+      continue;
+    }
+    seen.add(path);
+    const read = readConfiguration(engine, path);
+    if ("reason" in read) {
+      unreadable(path, read.reason);
+      continue;
+    }
+    found.push({ configFile: path, parsed: read.parsed });
+    pending.push(...referencesOf(read.parsed).filter(follows));
+  }
+  return found;
+}
+
+/** The name one module publishes itself under: the scope's, else its manifest's. */
+export function moduleIdentity(host: Host, module: Module): string {
+  return module.id === "" ? packageScope(host, module.path)("index.ts").package : module.id;
+}
+
+/**
+ * The compiler configurations one consumer is loaded through: every one under its root and
+ * each one those reference, transitively. A consumer that is absent, no directory or holds a
+ * configuration the compiler cannot read ends the run naming it, because a finding computed
+ * without a declared consumer would claim a reference set the run never read.
+ */
+function consumerProjects(engine: Engine, host: Host, root: string): readonly Configuration[] {
+  const kind = host.kindOf(root);
+  if (kind === "absent") {
+    throw failureExit(
+      "missing-consumer",
+      `the scope declares the consumer ${root}, and nothing is at that path: check the consumer out at ${root} and install its dependencies`,
+    );
+  }
+  if (kind !== "directory") {
+    throw failureExit(
+      "missing-consumer",
+      `the scope declares the consumer ${root}, which is not a directory: check the consumer out at ${root}`,
+    );
+  }
+  const found = derivedFrom(
+    engine,
+    host,
+    [...configFilesUnder(host, root)],
+    () => true,
+    (configFile, reason) => {
+      throw failureExit(
+        "missing-consumer",
+        `the consumer ${root} does not load, ${configFile} cannot be read as a compiler configuration: ${reason}`,
+      );
+    },
+  );
+  return found.map(({ configFile, parsed }) => ({
+    id: configFile,
+    configFile,
+    origin: "consumer" as const,
+    parsed,
+  }));
+}
+
+/** The failure of a consumer that holds no configuration and no JavaScript file a program is formed over. */
+export function consumerWithoutSources(root: string): FailureExit {
+  return failureExit(
+    "missing-consumer",
+    `the consumer ${root} holds no compiler configuration and no JavaScript file, so none of its references can be read: check the consumer out at ${root} with its ${MARKERS.join(", ")} or its JavaScript sources`,
+  );
+}
+
+/** The failure of a target that holds no configuration and no JavaScript file a program is formed over. */
+export function targetWithoutSources(target: string): FailureExit {
+  return failureExit(
+    "no-program",
+    `${target} holds no compiler configuration, no file named ${MARKERS.join(", ")}, and no JavaScript file: run from the directory that holds one, or name the languages to analyze`,
+  );
+}
+
+/** A target configuration a matrix or the invocation names that cannot be built, ending the run. */
+function unbuilt(named: string, reason: string): never {
+  throw failureExit(
+    "no-program",
+    `${named} ${reason}: correct the configuration, or name the configurations to analyze`,
+  );
+}
+
+/**
+ * The projects a build matrix declares, in its order, each a file below the target root, a
+ * `package.json` entry a tree for the plan to form in its place. An entry naming an absent file,
+ * a directory or a file the compiler cannot read ends the run naming it; one naming an earlier
+ * entry's file adds nothing. A reference below the root the matrix does not name ends the run
+ * naming both, because the compiler builds a referenced project's sources into the referencing
+ * program without reporting their diagnostics. A reference outside the root is an outside project.
+ */
+function declaredProjects(
+  engine: Engine,
+  host: Host,
+  targetRoot: string,
+  entries: readonly ProjectConfiguration[],
+): { readonly targets: readonly Target[]; readonly notBuilt: readonly NotBuilt[] } {
+  const targets: Target[] = [];
+  const projects: Configuration[] = [];
+  const references = new Map<string, readonly string[]>();
+  const manifests = new Set<string>();
+  for (const entry of entries) {
+    const configFile = joinPath(targetRoot, entry.project);
+    const named = `the project ${JSON.stringify(entry.id)} (${configFile})`;
+    const kind = host.kindOf(configFile);
+    if (kind !== "file") {
+      unbuilt(
+        named,
+        kind === "absent"
+          ? "does not exist"
+          : "is a directory, and a project names its compiler configuration file",
+      );
+    }
+    if (references.has(configFile) || manifests.has(configFile)) {
+      continue;
+    }
+    if (configFile.endsWith(`/${MANIFEST}`)) {
+      manifests.add(configFile);
+      targets.push({ kind: "declared", id: entry.id, manifest: configFile });
+      continue;
+    }
+    const read = readConfiguration(engine, configFile);
+    if ("reason" in read) {
+      unbuilt(named, `cannot be read as a compiler configuration: ${read.reason}`);
+    }
+    references.set(configFile, referencesOf(read.parsed));
+    const configuration: Configuration = {
+      id: entry.id,
+      configFile,
+      origin: "declared",
+      parsed: read.parsed,
+    };
+    projects.push(configuration);
+    targets.push({ kind: "configuration", configuration });
+  }
+  for (const project of projects) {
+    const unnamed = references
+      .get(project.configFile)
+      ?.find((path) => !references.has(path) && relativePath(targetRoot, path) !== undefined);
+    if (unnamed !== undefined) {
+      unbuilt(
+        `the project ${JSON.stringify(project.id)} (${project.configFile})`,
+        `references ${unnamed}, which the build matrix does not name. A referenced project is built into the program that references it, so the matrix names it too`,
+      );
+    }
+  }
+  return { targets, notBuilt: [] };
+}
+
+/**
+ * The projects a run derives where the matrix declares none: the configuration the scope
+ * names for the target where its path names one, every compiler configuration under the
+ * target root outside a skipped directory, then each configuration below the root those
+ * reference, transitively, each once. A configuration the scope names ends the run where it
+ * cannot be read; one the walk found is dropped and named. Where the scope names none, the
+ * plan forms programs over the target's JavaScript files no configuration lists.
+ */
+function derivedProjects(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+): { readonly targets: readonly Target[]; readonly notBuilt: readonly NotBuilt[] } {
+  const targetRoot = scope.target.path;
+  const fromScope = scope.target.path.endsWith(".json")
+    ? [resolvePath(host.workingDirectory(), scope.target.path)]
+    : [];
+  const absoluteRoot = resolvePath(host.workingDirectory(), targetRoot);
+  const rootDir = resolvePath(
+    host.workingDirectory(),
+    fromScope.length > 0 ? dirnamePath(targetRoot) : targetRoot,
+  );
+  const idOf = (configFile: string): string => relativePath(targetRoot, configFile) ?? configFile;
+  const notBuilt: NotBuilt[] = [];
+  const found = derivedFrom(
+    engine,
+    host,
+    [...fromScope, ...configFilesUnder(host, targetRoot)],
+    (reference) => relativePath(rootDir, reference) !== undefined,
+    (configFile, reason) => {
+      if (fromScope.includes(configFile)) {
+        unbuilt(configFile, `cannot be read as a compiler configuration: ${reason}`);
+      }
+      notBuilt.push({
+        id: idOf(configFile),
+        configFile,
+        error: targetRelative(reason, absoluteRoot),
+      });
+    },
+  );
+  const configurations = found.map(({ configFile, parsed }): Configuration => ({
+    id: idOf(configFile),
+    configFile,
+    origin: fromScope.includes(configFile) ? "scope" : "derived",
+    parsed,
+  }));
+  return {
+    targets: [
+      ...configurations.map((configuration) => ({ kind: "configuration" as const, configuration })),
+      ...(fromScope.length > 0 ? [] : [{ kind: "derived" as const }]),
+    ],
+    notBuilt,
+  };
+}
+
+/**
+ * Every configuration file one run opens: the build matrix's project entries in its order,
+ * or, where it holds none, those derived from the scope and the target tree, then each
+ * declared consumer's, a configuration the target or an earlier consumer opens being theirs
+ * alone. The consumers are read first, so one that cannot be read ends the run before any
+ * failure of the target: the Contract's failure-class table lists `missing-consumer` before
+ * `no-program`.
+ */
+export function discoverProjects(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  configurations: readonly BuildConfiguration[] = [],
+): Discovery {
+  const consumers = scope.consumers.map((module) => {
+    const projects = consumerProjects(engine, host, module.path);
+    return { consumer: { id: moduleIdentity(host, module), path: module.path }, projects };
+  });
+  const declared = configurations.filter(
+    (entry): entry is ProjectConfiguration => "project" in entry,
+  );
+  const target =
+    declared.length > 0
+      ? {
+          mode: "declared" as const,
+          ...declaredProjects(engine, host, scope.target.path, declared),
+        }
+      : { mode: "derived" as const, ...derivedProjects(engine, host, scope) };
+
+  const read = target.targets.flatMap((one) =>
+    one.kind === "configuration" ? [one.configuration] : [],
+  );
+  const opened = new Set(read.map((one) => one.configFile));
+  const consumed: Configuration[] = [];
+  for (const { consumer, projects } of consumers) {
+    for (const one of projects.filter(({ configFile }) => !opened.has(configFile))) {
+      opened.add(one.configFile);
+      consumed.push({ ...one, consumer });
+    }
+  }
+  return {
+    mode: target.mode,
+    targets: target.targets,
+    configurations: [...read, ...consumed],
+    notBuilt: target.notBuilt,
+    consumers: consumers.map(({ consumer }) => consumer),
+    unconfigured: consumers
+      .filter(({ projects }) => projects.length === 0)
+      .map(({ consumer }) => consumer),
+  };
+}

package/src/{emit-map.ts → load/emit-map.ts}

@@ -5,7 +5,7 @@
  * whether the path is the target's own or a workspace package's.
  */
 
-import { dirnamePath, joinPath, relativePath } from "./paths.ts";
+import { dirnamePath, joinPath, relativePath } from "../paths.ts";
 
 /** The source extensions the compiler emits each output extension from. */
 const EMITTED: readonly { readonly emitted: string; readonly sources: readonly string[] }[] = [

package/src/load/expected-module.ts

@@ -0,0 +1,188 @@
+import type { SourceFile } from "@typescript/native/ast";
+import {
+  isNoSubstitutionTemplateLiteral,
+  isStringLiteral,
+  type Node,
+} from "@typescript/native/ast";
+import { packageOfSpecifier } from "../dependencies.ts";
+import { MANIFEST } from "../fs/manifest.ts";
+import { entriesOf } from "../fs/tree.ts";
+import type { Host } from "../host.ts";
+import { dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath } from "../paths.ts";
+import { dependencySpecifiers, installedPackage, manifestsAbove } from "./module-lookup.ts";
+import type { CompilerOptions } from "./plan.ts";
+
+/** Where one project reads what its imports may name. */
+export interface ModuleContext {
+  readonly host: Host;
+  /** The root of the module the project is the target's or a consumer's, 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 {
+  for (const { dir: at, manifest } of manifestsAbove(host, dir, targetRoot)) {
+    if (dependencySpecifiers(manifest, name).length > 0) {
+      return joinPath(at, MANIFEST);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 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: ModuleContext,
+  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 && installedPackage(host, dirnamePath(importer), name) !== undefined) {
+    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 `paths` mapping of the configuration at `configFile` whose parse answered `options`. */
+export function pathsOf(configFile: string, options: CompilerOptions): PathsMapping {
+  // 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 : dirnamePath(configFile),
+    entries: Object.entries(options.paths ?? {}).map(([key, targets]) => ({ key, targets })),
+  };
+}
+
+/**
+ * Why one import the compiler cannot resolve, at `offset` of `file`, names a module the project
+ * expects and nothing provides, with the fix; undefined where the project does not expect it.
+ */
+export function missingModule(
+  context: ModuleContext,
+  file: SourceFile,
+  offset: number,
+): { readonly specifier: string; readonly reason: string } | undefined {
+  const specifier = literalAt(file, offset);
+  const reason =
+    specifier === undefined ? undefined : expectedModule(context, file.fileName, specifier);
+  return specifier === undefined || reason === undefined ? undefined : { specifier, reason };
+}