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

package/dist/src/failure.js

@@ -0,0 +1,36 @@
+import { FAILURE_CLASSES, FAILURE_PREFIXES } from "./contract/contract.generated.js";
+import { PRODUCT } from "./product.js";
+/** The failure as a class line of the error stream, opened by its group's prefix. */
+export function failureLine(failure) {
+    return `${FAILURE_PREFIXES[FAILURE_CLASSES[failure.failureClass]]}${failure.failureClass}: ${failure.detail}`;
+}
+/**
+ * The lines of the error stream that name the failures: the first one's class line, the run's
+ * only one, then each further failure as its class and detail with no group prefix.
+ */
+export function failureLines([first, ...further]) {
+    return [failureLine(first), ...further.map((one) => `${one.failureClass}: ${one.detail}`)];
+}
+/**
+ * A run the analysis cannot answer. It ends the run with the failure code and no finding
+ * list, printing the compiler's located errors and then the failures' lines.
+ */
+export class FailureExit extends Error {
+    failures;
+    /** The compiler's errors behind the failures, in the order it reported them. */
+    diagnostics;
+    constructor(failures, diagnostics = []) {
+        super(failureLines(failures).join("\n"));
+        this.name = "FailureExit";
+        this.failures = failures;
+        this.diagnostics = diagnostics;
+    }
+}
+/** A failure exit of one failure. */
+export function failureExit(failureClass, detail, diagnostics = []) {
+    return new FailureExit([{ failureClass, detail }], diagnostics);
+}
+/** A fault of this analyzer itself, `fault` saying what it cannot do. */
+export function productFault(fault) {
+    return failureExit("product-fault", `${PRODUCT} ${fault}: reinstall ${PRODUCT}, and report the fault to its maintainers if a reinstalled ${PRODUCT} fails the same way`);
+}

package/dist/src/fs/document.js

@@ -5,20 +5,13 @@
  * more of it than the Contract's document bound.
  */
 import { CONFIG_MAX_BYTES } from "../contract/config.generated.js";
+import { failureExit } from "../failure.js";
 import { joinPath, relativePath } from "../paths.js";
 import { message } from "../product.js";
 import { utf8Bytes } from "../reporters/sha256.js";
 import { UsageError } from "../usage.js";
-/**
- * A document at the target root that is not one to read: its name resolves outside the
- * target root or to anything but a regular file, or the read fails. Nothing is read from
- * it, and the run ends with the failure code.
- */
-export class TargetDocumentError extends Error {
-    constructor(label, reason) {
-        super(`${label}: ${reason}`);
-        this.name = "TargetDocumentError";
-    }
+function unreadable(label, reason) {
+    return failureExit("unreadable-document", `${label}: ${reason}: make it a regular file inside the target root that the run can read, or remove it`);
 }
 /** Refuses a document past the Contract's bound with the usage code, naming it `label`. */
 export function refuseOverBound(label, text) {
@@ -26,34 +19,34 @@ export function refuseOverBound(label, text) {
         throw new UsageError(`${label}: holds more than ${String(CONFIG_MAX_BYTES)} bytes`);
     }
 }
-/** What `read` returns, or its throw as the document's {@link TargetDocumentError}. */
-function attempt(label, read) {
-    try {
-        return read();
-    }
-    catch (error) {
-        throw new TargetDocumentError(label, message(error));
-    }
-}
 /**
  * The text of the document `name` at the absolute `targetRoot`, undefined where nothing is
- * there, each refusal naming it `label`. A document past the bound is read one byte past
- * it and refused as {@link refuseOverBound} refuses it.
+ * there. One whose name resolves outside the target root or to anything but a regular file,
+ * or whose read fails, is refused by `refuse` naming it `label`, nothing read from it. A
+ * document past the bound is read one byte past it and refused as {@link refuseOverBound} does.
  */
-export function readTargetDocument(host, targetRoot, name, label = name) {
+export function readTargetDocument(host, targetRoot, name, label = name, refuse = unreadable) {
+    const attempt = (read) => {
+        try {
+            return read();
+        }
+        catch (error) {
+            throw refuse(label, message(error));
+        }
+    };
     const path = joinPath(targetRoot, name);
-    const kind = attempt(label, () => host.kindOf(path));
+    const kind = attempt(() => host.kindOf(path));
     if (kind === "absent") {
         return undefined;
     }
-    const real = attempt(label, () => host.realPath(path));
-    if (relativePath(attempt(label, () => host.realPath(targetRoot)), real) === undefined) {
-        throw new TargetDocumentError(label, `resolves to ${real}, outside the target root`);
+    const real = attempt(() => host.realPath(path));
+    if (relativePath(attempt(() => host.realPath(targetRoot)), real) === undefined) {
+        throw refuse(label, `resolves to ${real}, outside the target root`);
     }
     if (kind !== "file") {
-        throw new TargetDocumentError(label, "is not a regular file");
+        throw refuse(label, "is not a regular file");
     }
-    const text = attempt(label, () => host.readFile(real, CONFIG_MAX_BYTES + 1));
+    const text = attempt(() => host.readFile(real, CONFIG_MAX_BYTES + 1));
     refuseOverBound(label, text);
     return text;
 }

package/dist/src/fs/manifest.js

@@ -4,6 +4,13 @@ import { joinPath } from "../paths.js";
 export const MANIFEST = "package.json";
 /** The directory a package manager installs packages into, whose files are no project's own. */
 export const INSTALLED_PACKAGES = "node_modules";
+/** The manifest members a package declares the packages it depends on under. */
+export const DEPENDENCY_SECTIONS = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+];
 /** Whether one path passes through an installed-packages directory. */
 export function inInstalledPackages(path) {
     return path.split("/").includes(INSTALLED_PACKAGES);

package/dist/src/load/classify.js

@@ -0,0 +1,236 @@
+import { conventionFailuresFor } from "../conventions.js";
+import { relativePath, resolvePath } from "../paths.js";
+import { diagnosticsOf, ownedAs } from "../session.js";
+import { skipAt } from "../type-errors.js";
+import { classOf, MISSING_GLOBAL_TYPE, projectErrors, renderDiagnostic, } from "./diagnostics.js";
+import { targetRelative } from "./discover.js";
+import { missingModule, pathsOf } from "./expected-module.js";
+import { FailureExit, failureLine } from "../failure.js";
+import { ownErrors } from "./workspace-run.js";
+/** What a failure ends or drops, by where the configuration comes from. */
+const POLICY = {
+    declared: { load: "end", setup: "end", unopened: "end" },
+    scope: { load: "end", setup: "end", unopened: "end" },
+    derived: { load: "drop", setup: "drop", unopened: "drop" },
+    consumer: { load: "end", setup: "end", unopened: "end" },
+};
+/**
+ * The errors of one project's own files: an import of a module the project expects and
+ * nothing provides is a setup failure, every other error a type error skipping its unit.
+ */
+function readErrors(project, errors, context) {
+    const files = new Map(project.ownSourceFiles().map((file) => [file.fileName, file]));
+    const missing = [];
+    const skips = [];
+    for (const { diagnostic, at } of errors) {
+        const file = diagnostic.fileName === undefined ? undefined : files.get(diagnostic.fileName);
+        const kind = classOf(diagnostic, true);
+        if (file === undefined || kind === "ignored") {
+            continue;
+        }
+        const line = at?.line ?? 1;
+        const path = relativePath(context.targetRoot, file.fileName) ?? file.fileName;
+        const expected = kind === "module-not-found" ? missingModule(context, file, diagnostic.pos) : undefined;
+        if (expected !== undefined) {
+            missing.push({
+                failureClass: "missing-module",
+                detail: `${path}:${String(line)}: ${path} imports ${JSON.stringify(expected.specifier)}, ${expected.reason}`,
+            });
+            continue;
+        }
+        const skip = skipAt(file, diagnostic.pos, line, diagnostic.text, context.targetRoot);
+        if (skip !== undefined) {
+            skips.push(skip);
+        }
+    }
+    return { missing, skips };
+}
+function nonEmpty(items) {
+    const [first, ...rest] = items;
+    return first === undefined ? undefined : [first, ...rest];
+}
+/** One target project read for what keeps it from being analyzed, or the skips it is analyzed with. */
+function classifyTarget(host, run, plan, view, unfound) {
+    const { workspace, root } = run;
+    const unbuildable = workspace?.unbuildable(plan.configFile);
+    if (unbuildable !== undefined) {
+        return {
+            kind: "setup",
+            failures: [{ failureClass: "workspace-member-without-source", detail: unbuildable }],
+        };
+    }
+    const referenceOnly = workspace === undefined
+        ? () => false
+        : workspace.referenceOnly(plan.configFile, view.rootFiles);
+    const project = workspace === undefined
+        ? view
+        : ownedAs(view, (file, external) => workspace.ownFile(file, external));
+    const raw = projectErrors(diagnosticsOf(project));
+    const load = nonEmpty(raw.load);
+    if (load !== undefined) {
+        return { kind: "load", errors: load };
+    }
+    const reading = readErrors(project, ownErrors(raw.check, referenceOnly), {
+        host,
+        targetRoot: root,
+        paths: pathsOf(plan.configFile, plan.parsed.options),
+        member: (manifest) => workspace?.workspace.memberOf(manifest) !== undefined,
+    });
+    const failures = nonEmpty(reading.missing) ??
+        nonEmpty(conventionFailuresFor(run.conventions, plan.configFile, project.ownSourceFiles().map((file) => file.fileName)));
+    if (failures !== undefined) {
+        return { kind: "setup", failures };
+    }
+    const display = (path) => relativePath(root, path) ?? path;
+    unfound.push(...raw.unfound.map((one) => ({
+        configFile: plan.configFile,
+        error: renderDiagnostic(one, display),
+    })));
+    const missingGlobal = raw.unfound.find(({ diagnostic }) => diagnostic.code === MISSING_GLOBAL_TYPE);
+    // The checker types every use of a missing global against nothing and places no error in
+    // a file, so every file of the project is skipped whole.
+    const skips = missingGlobal === undefined
+        ? reading.skips
+        : [
+            ...reading.skips,
+            ...project.ownSourceFiles().map((file) => ({
+                record: {
+                    path: display(file.fileName),
+                    line: 1,
+                    message: missingGlobal.diagnostic.text,
+                },
+                file,
+                unit: file,
+            })),
+        ];
+    return { plan, project, skips, referenceOnly };
+}
+/**
+ * One consumer project read for what keeps its references from being read. A workspace
+ * declaration that cannot be read fails it where an import asks whether a package is a member.
+ */
+function classifyConsumer(host, place, plan, consumer, project) {
+    const raw = projectErrors(diagnosticsOf(project));
+    const load = nonEmpty(raw.load);
+    if (load !== undefined) {
+        return { kind: "load", errors: load };
+    }
+    let faulted;
+    const reading = readErrors(project, raw.check, {
+        host,
+        targetRoot: resolvePath(host.workingDirectory(), consumer.path),
+        paths: pathsOf(plan.configFile, plan.parsed.options),
+        member: (manifest) => {
+            if (place !== undefined && "fault" in place) {
+                faulted = place.fault;
+                return false;
+            }
+            return place?.workspace?.memberOf(manifest) !== undefined;
+        },
+    });
+    const details = faulted === undefined
+        ? reading.missing.map((one) => `the consumer ${consumer.path} does not build, its dependencies not installed: ${one.detail}`)
+        : [
+            `the consumer ${consumer.path} imports a dependency a package below it declares, and its workspace declaration cannot be read to tell whether that package is a member: ${faulted}`,
+        ];
+    const failures = nonEmpty(details.map((detail) => ({ failureClass: "missing-consumer", detail })));
+    return failures === undefined ? { project, consumer } : { kind: "setup", failures };
+}
+/** The setup failure one failed configuration ends the run with, its located errors printed first. */
+function ending(plan, failed, root) {
+    if (failed.kind === "setup") {
+        return failed.failures;
+    }
+    const what = failed.kind === "load"
+        ? `the configuration ${relativePath(root, plan.configFile) ?? plan.configFile} does not load, its errors printed above`
+        : `the compiler opened no project for ${plan.configFile}`;
+    return plan.consumer === undefined
+        ? [
+            {
+                failureClass: "no-program",
+                detail: `${what}: correct the configuration, or name the configurations to analyze`,
+            },
+        ]
+        : [
+            {
+                failureClass: "missing-consumer",
+                detail: `${what}, for the consumer ${plan.consumer.path}: check the consumer out at ${plan.consumer.path} and install its dependencies`,
+            },
+        ];
+}
+/** The first line of the error that drops one derived configuration. */
+function droppedBy(failed, root) {
+    return failed.kind === "load"
+        ? targetRelative(renderDiagnostic(failed.errors[0], (path) => relativePath(root, path) ?? path), root)
+        : failed.kind === "setup"
+            ? targetRelative(failureLine(failed.failures[0]), root)
+            : "the compiler opened no project for the configuration";
+}
+/**
+ * Every opened project of the run classified as analyzed, dropped or failing by the policy
+ * table, before any stage reads one. A failure that ends the run is one {@link FailureExit}, by
+ * this precedence: a configuration the snapshot opened nothing for, then the setup failures,
+ * then the configurations that did not load with their errors, then, where every derived
+ * configuration was dropped, their setup failures or the first reason.
+ */
+export function classify(host, run, views) {
+    const { root } = run;
+    const notBuilt = [...run.discovery.notBuilt];
+    const librariesUnfound = [];
+    const analyzed = [];
+    const consumed = [];
+    const ended = new Map();
+    const dropped = [];
+    const unopened = run.plans.filter((plan) => !views.has(plan.configFile));
+    const outcomes = [
+        ...run.plans.flatMap((plan) => {
+            const view = views.get(plan.configFile);
+            return view === undefined
+                ? []
+                : [
+                    {
+                        plan,
+                        outcome: plan.consumer === undefined
+                            ? classifyTarget(host, run, plan, view, librariesUnfound)
+                            : classifyConsumer(host, run.consumerWorkspaces.get(plan.consumer.path), plan, plan.consumer, view),
+                    },
+                ];
+        }),
+        ...unopened.map((plan) => ({ plan, outcome: { kind: "unopened" } })),
+    ];
+    for (const { plan, outcome } of outcomes) {
+        if (!("kind" in outcome)) {
+            if ("consumer" in outcome) {
+                consumed.push(outcome);
+            }
+            else {
+                analyzed.push(outcome);
+            }
+        }
+        else if (POLICY[plan.origin][outcome.kind] === "end") {
+            ended.set(outcome.kind, [...(ended.get(outcome.kind) ?? []), { plan, failed: outcome }]);
+        }
+        else {
+            dropped.push(outcome);
+            notBuilt.push({ id: plan.id, configFile: plan.configFile, error: droppedBy(outcome, root) });
+        }
+    }
+    for (const kind of ["unopened", "setup", "load"]) {
+        const all = ended.get(kind) ?? [];
+        const failures = nonEmpty(all.flatMap(({ plan, failed }) => ending(plan, failed, root)));
+        if (failures !== undefined) {
+            throw new FailureExit(kind === "unopened" ? [failures[0]] : failures, all.flatMap(({ failed }) => (failed.kind === "load" ? failed.errors : [])));
+        }
+    }
+    const setupDropped = nonEmpty(dropped.flatMap((one) => (one.kind === "setup" ? one.failures : [])));
+    const [first] = notBuilt;
+    if (analyzed.length === 0 && first !== undefined) {
+        throw new FailureExit(setupDropped ?? [
+            {
+                failureClass: "no-program",
+                detail: `no configuration discovery derived could be built; ${first.id}: ${first.error}`,
+            },
+        ]);
+    }
+    return { analyzed, consumed, notBuilt, librariesUnfound };
+}

package/dist/src/load/diagnostics.js

@@ -0,0 +1,79 @@
+import { DiagnosticCategory } from "@typescript/native/sync";
+/** The code of a global type the checker finds in no library the program holds. */
+export const MISSING_GLOBAL_TYPE = 2318;
+/**
+ * What each error diagnostic does, first matching row first. In no file: an unfound type library
+ * or lib (https://github.com/microsoft/typescript-go/blob/89d5d5b2849a0db0957065889ca58536fa6d2e4a/internal/compiler/processingDiagnostic.go),
+ * then the semantic band from 2000; the option band from 5000 leaves the program whole
+ * (https://github.com/microsoft/TypeScript/wiki/Coding-guidelines#diagnostic-message-codes).
+ * In a file: an unfound module, and where the configuration places the file (5055, 5056, 6059,
+ * 6307), which changes no type a statement carries.
+ */
+const DIAGNOSTIC_TABLE = [
+    {
+        placed: false,
+        codes: new Set([MISSING_GLOBAL_TYPE, 2688, 2726, 2727]),
+        class: "unfound-library",
+    },
+    { placed: false, codes: { from: 2000, below: 3000 }, class: "load" },
+    { placed: true, codes: new Set([2307, 2792]), class: "module-not-found" },
+    { placed: true, codes: new Set([5055, 5056, 6059, 6307]), class: "ignored" },
+];
+/** The category an error diagnostic carries, which the protocol sends as a number. */
+const ERROR_CATEGORY = DiagnosticCategory.Error;
+function isError(diagnostic) {
+    return diagnostic.category === ERROR_CATEGORY;
+}
+/**
+ * What one diagnostic does, placed in one of the project's own files or in none. A diagnostic
+ * the compiler marks as reporting unnecessary code in a file is no error of the program's.
+ */
+export function classOf(diagnostic, placed) {
+    if (!isError(diagnostic) || (placed && diagnostic.reportsUnnecessary === true)) {
+        return "ignored";
+    }
+    const row = DIAGNOSTIC_TABLE.find(({ placed: where, codes }) => where === placed &&
+        ("has" in codes
+            ? codes.has(diagnostic.code)
+            : diagnostic.code >= codes.from && diagnostic.code < codes.below));
+    return row?.class ?? (placed ? "type-error" : "ignored");
+}
+/**
+ * One diagnostic as `path:line:column: TScode: message`, the position left out where it names
+ * none and the file where it names none. `display` spells the file's path.
+ */
+export function renderDiagnostic(located, display = (path) => path) {
+    const { diagnostic, at } = located;
+    const message = `TS${String(diagnostic.code)}: ${diagnostic.text}`;
+    if (diagnostic.fileName === undefined) {
+        return message;
+    }
+    const where = display(diagnostic.fileName);
+    return at === undefined
+        ? `${where}: ${message}`
+        : `${where}:${String(at.line)}:${String(at.column)}: ${message}`;
+}
+function locatedIn(diagnostics, locate) {
+    return diagnostics.map((diagnostic) => ({
+        diagnostic,
+        at: diagnostic.fileName === undefined ? undefined : locate(diagnostic.fileName, diagnostic.pos),
+    }));
+}
+/**
+ * Every error a project's three diagnostic sets carry, in the order the compiler reported
+ * them. A resolved configuration carries no diagnostics of its own, so a configuration written
+ * with an unreadable option resolves and is refused here, once its project is open.
+ */
+export function diagnosticErrors(sets) {
+    return [...sets.configParsing, ...sets.syntactic, ...sets.semantic].filter(isError);
+}
+/** The errors one open project carries, each located in the file it names. */
+export function projectErrors(sets) {
+    const unplaced = (kind) => sets.unplaced.filter((diagnostic) => classOf(diagnostic, false) === kind);
+    const load = [...sets.configParsing.filter(isError), ...unplaced("load")];
+    return {
+        load: locatedIn(load, sets.locate),
+        check: load.length > 0 ? [] : locatedIn(diagnosticErrors(sets), sets.locate),
+        unfound: load.length > 0 ? [] : locatedIn(unplaced("unfound-library"), sets.locate),
+    };
+}

package/dist/src/load/discover.js

@@ -0,0 +1,230 @@
+import { LANGUAGE_ROWS } from "../contract/contract.generated.js";
+import { filesBelow } from "../fs/tree.js";
+import { packageScope } from "../inventory.js";
+import { dirnamePath, joinPath, relativePath, resolvePath } from "../paths.js";
+import { LANGUAGE, message } from "../product.js";
+import { globExpression } from "../text/glob.js";
+import { failureExit } from "../failure.js";
+/** 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. */
+export function isConfigFile(name) {
+    return MARKER_EXPRESSIONS.some((marker) => marker.test(name));
+}
+/** Whether the run analyzes one configuration as the target's. */
+export function isTargetConfiguration(configuration) {
+    return configuration.origin !== "consumer";
+}
+/**
+ * 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, targetRoot) {
+    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;
+}
+/** The configuration files below `root`, by absolute path in ascending order. */
+function configFilesUnder(host, root) {
+    return filesBelow(host, root, isConfigFile).map((path) => joinPath(root, path));
+}
+/** The configuration files one parsed configuration's `references` name. */
+function referencesOf(parsed) {
+    // 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, configFile) {
+    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) {
+        return { reason: message(error) };
+    }
+}
+/**
+ * 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, host, pending, follows, unreadable) {
+    const seen = new Set();
+    const found = [];
+    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, module) {
+    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, holds no
+ * configuration or holds one 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, host, root) {
+    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}`);
+    });
+    if (found.length === 0) {
+        throw failureExit("missing-consumer", `the consumer ${root} holds no compiler configuration, so none of its references can be read: check the consumer out at ${root} with its ${MARKERS.join(", ")}`);
+    }
+    return found;
+}
+/** A target configuration a matrix or the invocation names that cannot be built, ending the run. */
+function unbuilt(named, reason) {
+    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 entry a file below the target
+ * root: an entry naming an absent file, a directory or a file the compiler cannot read ends
+ * the run naming it, and 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, host, targetRoot, entries) {
+    const projects = [];
+    const references = new Map();
+    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)) {
+            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));
+        projects.push({ id: entry.id, configFile, origin: "declared", parsed: read.parsed });
+    }
+    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 projects;
+}
+/**
+ * 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.
+ */
+function derivedProjects(engine, host, scope) {
+    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) => relativePath(targetRoot, configFile) ?? configFile;
+    const 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),
+        });
+    });
+    return {
+        configurations: found.map(({ configFile, parsed }) => ({
+            id: idOf(configFile),
+            configFile,
+            origin: fromScope.includes(configFile) ? "scope" : "derived",
+            parsed,
+        })),
+        notBuilt,
+    };
+}
+/**
+ * Every configuration 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. A
+ * target holding none ends the run with the setup failure `no-program`. No build output is
+ * read: a project is the files its configuration names.
+ */
+export function discoverProjects(engine, host, scope, configurations = []) {
+    const declared = configurations.filter((entry) => "project" in entry);
+    const target = declared.length > 0
+        ? {
+            mode: "declared",
+            configurations: declaredProjects(engine, host, scope.target.path, declared),
+            notBuilt: [],
+        }
+        : { mode: "derived", ...derivedProjects(engine, host, scope) };
+    if (target.configurations.length === 0 && target.notBuilt.length === 0) {
+        throw failureExit("no-program", `${scope.target.path} holds no compiler configuration, no file named ${MARKERS.join(", ")}: run from the directory that holds one, or name the languages to analyze`);
+    }
+    const opened = new Set(target.configurations.map((one) => one.configFile));
+    const consumers = [];
+    const consumed = [];
+    for (const module of scope.consumers) {
+        const read = consumerProjects(engine, host, module.path);
+        const consumer = { id: moduleIdentity(host, module), path: module.path };
+        consumers.push(consumer);
+        for (const { configFile, parsed } of read.filter((one) => !opened.has(one.configFile))) {
+            opened.add(configFile);
+            consumed.push({ id: configFile, configFile, origin: "consumer", parsed, consumer });
+        }
+    }
+    return {
+        mode: target.mode,
+        configurations: [...target.configurations, ...consumed],
+        notBuilt: target.notBuilt,
+        consumers,
+    };
+}