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

package/dist/src/type-errors.js

@@ -1,159 +1,15 @@
 /**
- * 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, } from "@typescript/native/ast";
-import { packageOfSpecifier } from "./dependencies.js";
+import { isClassDeclaration, isFunctionLikeDeclaration, isPropertyAccessExpression, } from "@typescript/native/ast";
 import { nodeKey } from "./inventory.js";
-import { ancestors, dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath, } from "./paths.js";
+import { relativePath } from "./paths.js";
 import { isAnswered } from "./query.js";
-import { findWorkspace } from "./workspace.js";
-import { entriesOf } from "./fs/tree.js";
-import { INSTALLED_PACKAGES, MANIFEST, manifestAt } from "./fs/manifest.js";
-/** The compiler's codes for an import whose module it cannot find. */
-const MODULE_NOT_FOUND = 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 = new Set([5055, 5056, 6059, 6307]);
-const MANIFEST_SECTIONS = [
-    "dependencies",
-    "devDependencies",
-    "peerDependencies",
-    "optionalDependencies",
-];
 /** Whether a finding's position falls inside a skipped unit. */
 export function insideSkipped(skipped, position) {
     return skipped.some((unit) => unit.path === position.path && unit.fromLine <= position.line && position.line <= unit.toLine);
 }
-/** The string literal holding one offset, innermost first, a doc comment's included. */
-function literalAt(file, offset) {
-    let found;
-    const visit = (node) => {
-        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.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, specifier) {
-    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, star) {
-    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, path, fileOnly) {
-    const counts = (at) => 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, dir, targetRoot, name) {
-    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, dir, name) {
-    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, importer, specifier) {
-    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.
@@ -184,55 +40,13 @@ function messageOf(text, targetRoot) {
     const line = text.split(`${targetRoot}/`).join("").split(/\s+/u).join(" ").trim();
     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(project, errors, where) {
-    let workspace = null;
-    const context = {
-        ...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 = [];
-    const skips = [];
-    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, offset, line, text, targetRoot) {
+    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. */
 export function skippedUnits(skips, targetRoot) {
@@ -297,22 +111,3 @@ export function skippedRoots(project, held, skips) {
     }
     return [...kept];
 }
-/** One compiler configuration's `paths` mapping, empty where it cannot be read. */
-export function pathsOf(engine, configFile) {
-    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.pathsBasePath;
-        return {
-            base: typeof declaredAt === "string" ? declaredAt : base,
-            entries: Object.entries(paths ?? {}).map(([key, targets]) => ({ key, targets })),
-        };
-    }
-    catch {
-        return { base, entries: [] };
-    }
-}

package/dist/src/usage.js

@@ -0,0 +1,10 @@
+/**
+ * A refusal of the invocation: the fix is to the command line or to a document it
+ * names, so the run ends with the usage code before any analysis.
+ */
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UsageError";
+    }
+}

package/dist/src/verbs/analyze.js

@@ -1,10 +1,10 @@
-import { CONTRACT_VERSION, EXIT_CLEAN, EXIT_FAILURE, } from "../contract/contract.generated.js";
+import { CONTRACT_VERSION, EXIT_CLEAN } from "../contract/contract.generated.js";
 import { runAnalysis, runBaselineWrite, unansweredCounts, } from "../analysis.js";
-import { ConfigError, kindOf } from "../config.js";
+import { kindOf } from "../config.js";
 import { CONFORMANCE, DECLARED_GAPS } from "../conformance.js";
-import { moduleIdentity } from "../consumers.js";
 import { analyzerProvenance, verdictOf } from "../findings-pass.js";
 import { dirnamePath, joinPath, normalizePath, relativePath, resolvePath } from "../paths.js";
+import { moduleIdentity } from "../load/discover.js";
 import { partialNotes } from "../partial.js";
 import { buildReport, capFindings, sortFindings, } from "../report.js";
 import { reportRefusals } from "../report-schema.js";
@@ -14,8 +14,11 @@ import { parseTemplate, TemplateError } from "../reporters/template.js";
 import { resolve } from "../resolve.js";
 import { otherSchemeRows, rowReason, writeBaseline } from "../suppress-file.js";
 import {} from "./verb.js";
+import { UsageError } from "../usage.js";
 import { bytewise } from "../text/compare.js";
-import { diagnose, LANGUAGE, message } from "../product.js";
+import { productFault, failureExit } from "../failure.js";
+import { diagnose, message } from "../product.js";
+import { ownVersion } from "./version.js";
 /** The options `analyze` takes beside the ones every verb takes. */
 export const ANALYZE_OPTIONS = {
     plain: ["report", "baseline-write", "exit-code", "template"],
@@ -24,13 +27,6 @@ export const ANALYZE_OPTIONS = {
 /** The two values `--exit-code` takes; on, the default, puts the run's verdict in the exit code. */
 const EXIT_CODE_ON = "on";
 const EXIT_CODE_OFF = "off";
-/** A path of the run no report can name, which ends the run with the failure code. */
-class ReportPathError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "ReportPathError";
-    }
-}
 /** The formats this analyzer renders, for a message that names them. */
 function formatNames() {
     return [...RENDERINGS.keys()].sort(bytewise).join(", ");
@@ -41,10 +37,10 @@ function formatsOf(named, configured) {
     const seen = new Set();
     for (const format of formats) {
         if (!RENDERINGS.has(format)) {
-            throw new ConfigError("malformed", "", `${JSON.stringify(format)} is not a format this analyzer renders: the formats are ${formatNames()}`);
+            throw new UsageError(`${JSON.stringify(format)} is not a format this analyzer renders: the formats are ${formatNames()}`);
         }
         if (seen.has(format)) {
-            throw new ConfigError("malformed", "", `the format ${JSON.stringify(format)} is named twice`);
+            throw new UsageError(`the format ${JSON.stringify(format)} is named twice`);
         }
         seen.add(format);
     }
@@ -61,7 +57,7 @@ function runRelative(invoked, path) {
     }
     const below = relativePath(invoked, path);
     if (below === undefined) {
-        throw new ReportPathError(`a report names its target relative to the directory the run was invoked from, and ${invoked} does not contain ${path}: run from a directory that does`);
+        throw failureExit("unreportable-path", `a report names its target relative to the directory the run was invoked from, and ${invoked} does not contain ${path}: run from a directory that does`);
     }
     return below;
 }
@@ -103,7 +99,7 @@ function notBuiltOf(dropped, targetRoot) {
     return dropped.map((one) => {
         const project = relativePath(targetRoot, one.configFile);
         if (project === undefined) {
-            throw new ReportPathError(`the project ${one.id} would be opened from ${one.configFile}, which is not below the target ${targetRoot}, so no report can name it`);
+            throw failureExit("unreportable-path", `the project ${one.id} would be opened from ${one.configFile}, which is not below the target ${targetRoot}, so no report can name it: analyze a target that holds it`);
         }
         return { id: one.id, project, error: one.error };
     });
@@ -113,11 +109,24 @@ function configurationsOf(projects, targetRoot) {
     return projects.map((one) => {
         const project = relativePath(targetRoot, one.configFile);
         if (project === undefined) {
-            throw new ReportPathError(`the project ${one.id} is opened from ${one.configFile}, which is not below the target ${targetRoot}, so no report can name it`);
+            throw failureExit("unreportable-path", `the project ${one.id} is opened from ${one.configFile}, which is not below the target ${targetRoot}, so no report can name it: analyze a target that holds it`);
         }
         return { id: one.id, project };
     });
 }
+/**
+ * Writes one document the run was asked for. A document that cannot be produced or written
+ * ends the run with the run failure that names it and `fix`, the documents written before it
+ * kept.
+ */
+function writeDocument(host, path, fix, produce) {
+    try {
+        host.writeDocument(path, produce());
+    }
+    catch (error) {
+        throw failureExit("unwritten-output", `${path}: ${message(error)}: ${fix}`);
+    }
+}
 /** A count with its noun, so a message reads for one record as well as for several. */
 function counted(n, noun) {
     return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
@@ -130,7 +139,7 @@ function counted(n, noun) {
 function templateOf(host, invoked, named, formats) {
     if (named === undefined || named === "") {
         if (formats.includes("template")) {
-            throw new ConfigError("malformed", "", "the template format renders the template --template names, and none was named");
+            throw new UsageError("the template format renders the template --template names, and none was named");
         }
         return undefined;
     }
@@ -139,7 +148,7 @@ function templateOf(host, invoked, named, formats) {
         source = host.readFile(resolvePath(invoked, named));
     }
     catch (error) {
-        throw new ConfigError("malformed", "", `--template=${named}: ${message(error)}`);
+        throw new UsageError(`--template=${named}: ${message(error)}`);
     }
     try {
         return parseTemplate(source);
@@ -148,7 +157,7 @@ function templateOf(host, invoked, named, formats) {
         if (!(error instanceof TemplateError)) {
             throw error;
         }
-        throw new ConfigError("malformed", "", `--template=${named}: ${error.message}`);
+        throw new UsageError(`--template=${named}: ${error.message}`);
     }
 }
 /**
@@ -162,17 +171,13 @@ function templateOf(host, invoked, named, formats) {
 export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repeated }) => {
     const reportPath = option("report");
     if (reportPath === undefined || reportPath === "") {
-        throw new ConfigError("malformed", "", "analyze writes its report to the path --report names, and no path was named");
+        throw new UsageError("analyze writes its report to the path --report names, and no path was named");
     }
     const exitCode = option("exit-code") ?? EXIT_CODE_ON;
     if (exitCode !== EXIT_CODE_ON && exitCode !== EXIT_CODE_OFF) {
-        throw new ConfigError("malformed", "", `--exit-code=${JSON.stringify(exitCode)}: the values are ${EXIT_CODE_ON} and ${EXIT_CODE_OFF}`);
+        throw new UsageError(`--exit-code=${JSON.stringify(exitCode)}: the values are ${EXIT_CODE_ON} and ${EXIT_CODE_OFF}`);
     }
     const { config, provenance } = resolve(inputs());
-    const kind = config.targetKind;
-    if (kind === "") {
-        throw new ConfigError("missing-target-kind", "target.kind", "target.kind is not set");
-    }
     const invoked = host.workingDirectory();
     const baseline = option("baseline-write");
     const documents = {
@@ -183,108 +188,81 @@ export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repe
     const template = templateOf(host, invoked, option("template"), documents.formats);
     const scoped = scope();
     const targetRoot = scoped.target.path;
-    let version;
-    try {
-        version = host.analyzerVersion();
-    }
-    catch (error) {
-        diagnose(err, message(error));
-        return EXIT_FAILURE;
-    }
-    let report;
+    const version = ownVersion(host);
     let recorded;
-    let verdict;
-    let partial;
-    let warnings;
-    let unread;
-    let unfound;
-    try {
-        const root = runRelative(invoked, targetRoot);
-        const mode = { production: true };
-        let analysis;
-        if (documents.baseline === undefined) {
-            analysis = runAnalysis(openClient(config), host, scoped, config, provenance, mode);
-            recorded = [];
-        }
-        else {
-            const reason = rowReason(analyzerProvenance(version));
-            const write = runBaselineWrite(openClient(config), host, scoped, config, provenance, mode, reason);
-            analysis = write.first;
-            recorded = write.rows;
-        }
-        const { result, run } = analysis;
-        warnings = run.componentWarnings;
-        unread = run.componentsUnread.map(({ configFile, reason }) => `${relativePath(resolvePath(invoked, targetRoot), configFile) ?? configFile}: its component files are not read: ${reason}`);
-        unfound = run.librariesUnfound.map(({ configFile, error }) => `${relativePath(resolvePath(invoked, targetRoot), configFile) ?? configFile}: ${error}: the configuration is analyzed without that library`);
-        partial = partialNotes({
-            notBuilt: run.notBuilt,
-            unanswered: run.unanswered,
-            targetRoot: resolvePath(invoked, targetRoot),
-        });
-        const built = buildReport({
-            contractVersion: CONTRACT_VERSION,
-            version,
-            conformance: CONFORMANCE,
-            declaredGaps: DECLARED_GAPS,
-            target: {
-                kind: kindOf(kind, LANGUAGE),
-                root,
-                identity: moduleIdentity(host, scoped.target),
-            },
-            configurations: configurationsOf(run.projects, targetRoot),
-            notBuilt: notBuiltOf(run.notBuilt, targetRoot),
-            loaded: run.consumers.map((consumer) => ({
-                id: consumer.id,
-                path: runRelative(invoked, consumer.path),
-            })),
-            unavailable: [],
-            result,
-            testFileRules: run.testFileRules,
-            typeErrorSkips: run.typeErrorSkips,
-            unanswered: unansweredCounts(analysis),
-            conventionsApplied: run.conventionsApplied,
-            listsComponents: config.reporters.cascade === "full",
-            notes: [
-                ...unmappedNotes(run.unmappedEntries, resolvePath(invoked, targetRoot)),
-                ...unseenLoadNotes(run.unseenLoads),
-            ],
-        });
-        report = capFindings(sortFindings(built, config.reporters.sort), config.reporters.maxFindings);
-        verdict = verdictOf(result, config);
+    const root = runRelative(invoked, targetRoot);
+    const mode = { production: true };
+    let analysis;
+    if (documents.baseline === undefined) {
+        analysis = runAnalysis(openClient(config), host, scoped, config, provenance, mode);
+        recorded = [];
     }
-    catch (error) {
-        if (!(error instanceof ReportPathError)) {
-            throw error;
-        }
-        diagnose(err, error.message);
-        return EXIT_FAILURE;
+    else {
+        const reason = rowReason(analyzerProvenance(version));
+        const write = runBaselineWrite(openClient(config), host, scoped, config, provenance, mode, reason);
+        analysis = write.first;
+        recorded = write.rows;
     }
-    try {
-        const [refused] = reportRefusals(report);
-        if (refused !== undefined) {
-            throw new Error(`the report breaks the report schema at ${refused.pointer || "the document"}: ${refused.keyword}: ${refused.reason}`);
-        }
-        host.writeDocument(documents.report, json(report));
-        const options = {
-            readSource: (path) => host.readFile(joinPath(targetRoot, path)),
-            template,
-        };
-        for (const format of documents.formats) {
-            const rendering = RENDERINGS.get(format);
-            if (rendering !== undefined) {
-                host.writeDocument(documents.report + rendering.suffix, rendering.render(report, options));
-            }
-        }
-        if (documents.baseline !== undefined) {
-            const kept = host.kindOf(documents.baseline) === "file"
-                ? otherSchemeRows(host.readFile(documents.baseline))
-                : [];
-            host.writeDocument(documents.baseline, writeBaseline(recorded, analyzerProvenance(version), kept));
+    const { result, run } = analysis;
+    const warnings = run.componentWarnings;
+    const unread = run.componentsUnread.map(({ configFile, reason }) => `${relativePath(resolvePath(invoked, targetRoot), configFile) ?? configFile}: its component files are not read: ${reason}`);
+    const unfound = run.librariesUnfound.map(({ configFile, error }) => `${relativePath(resolvePath(invoked, targetRoot), configFile) ?? configFile}: ${error}: the configuration is analyzed without that library`);
+    const partial = partialNotes({
+        notBuilt: run.notBuilt,
+        unanswered: run.unanswered,
+        targetRoot: resolvePath(invoked, targetRoot),
+    });
+    const built = buildReport({
+        contractVersion: CONTRACT_VERSION,
+        version,
+        conformance: CONFORMANCE,
+        declaredGaps: DECLARED_GAPS,
+        target: {
+            kind: kindOf(config.target.kind),
+            root,
+            identity: moduleIdentity(host, scoped.target),
+        },
+        configurations: configurationsOf(run.projects, targetRoot),
+        notBuilt: notBuiltOf(run.notBuilt, targetRoot),
+        loaded: run.consumers.map((consumer) => ({
+            id: consumer.id,
+            path: runRelative(invoked, consumer.path),
+        })),
+        unavailable: [],
+        result,
+        testFileRules: run.testFileRules,
+        typeErrorSkips: run.typeErrorSkips,
+        unanswered: unansweredCounts(analysis),
+        conventionsApplied: run.conventionsApplied,
+        listsComponents: config.reporters.cascade === "full",
+        notes: [
+            ...unmappedNotes(run.unmappedEntries, resolvePath(invoked, targetRoot)),
+            ...unseenLoadNotes(run.unseenLoads),
+        ],
+    });
+    const report = capFindings(sortFindings(built, config.reporters.sort), config.reporters.max_findings);
+    const verdict = verdictOf(result, config);
+    const [refused] = reportRefusals(report);
+    if (refused !== undefined) {
+        throw productFault(`built a report that breaks the report schema at ${refused.pointer || "the document"}: ${refused.keyword}: ${refused.reason}`);
+    }
+    writeDocument(host, documents.report, "name a path the run can write", () => json(report));
+    const options = {
+        readSource: (path) => host.readFile(joinPath(targetRoot, path)),
+        template,
+    };
+    for (const format of documents.formats) {
+        const rendering = RENDERINGS.get(format);
+        if (rendering !== undefined) {
+            writeDocument(host, documents.report + rendering.suffix, "name a path the run can write, or correct the template that renders it", () => rendering.render(report, options));
         }
     }
-    catch (error) {
-        diagnose(err, message(error));
-        return EXIT_FAILURE;
+    const baselinePath = documents.baseline;
+    if (baselinePath !== undefined) {
+        writeDocument(host, baselinePath, "name a path the run can write, or repair the rows of the baseline the run would keep", () => {
+            const kept = host.kindOf(baselinePath) === "file" ? otherSchemeRows(host.readFile(baselinePath)) : [];
+            return writeBaseline(recorded, analyzerProvenance(version), kept);
+        });
     }
     for (const note of partial) {
         diagnose(err, note);

package/dist/src/verbs/describe.js

@@ -1,7 +1,8 @@
-import { CONTRACT_VERSION, EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, SCHEMA_VERSIONS, } from "../contract/contract.generated.js";
+import { CONTRACT_VERSION, EXIT_CLEAN, EXIT_USAGE, SCHEMA_VERSIONS, } from "../contract/contract.generated.js";
 import { CONFORMANCE } from "../conformance.js";
 import {} from "./verb.js";
-import { diagnose, LANGUAGE, message, PRODUCT } from "../product.js";
+import { diagnose, LANGUAGE, PRODUCT } from "../product.js";
+import { ownVersion } from "./version.js";
 /**
  * The document `describe` writes: the analyzer, the Contract version it implements, the
  * report schema versions it reads, the languages it claims, and its recorded result over
@@ -26,20 +27,12 @@ export function describeDocument(version, recorded) {
     };
     return `${JSON.stringify(document, null, 2)}\n`;
 }
-/** Writes this analyzer's description to the output stream, and nothing to the error stream. */
+/** Writes this analyzer's description to the output stream. */
 export const describeVerb = ({ out, err, host, args }) => {
     if (args.length > 0) {
         diagnose(err, `describe takes no argument, got ${JSON.stringify(args[0])}`);
         return EXIT_USAGE;
     }
-    let version;
-    try {
-        version = host.analyzerVersion();
-    }
-    catch (error) {
-        diagnose(err, `describe: ${message(error)}`);
-        return EXIT_FAILURE;
-    }
-    out.write(describeDocument(version, CONFORMANCE));
+    out.write(describeDocument(ownVersion(host), CONFORMANCE));
     return EXIT_CLEAN;
 };

package/dist/src/verbs/explain.js

@@ -1,7 +1,6 @@
 import { EXIT_CLEAN, EXIT_USAGE } from "../contract/contract.generated.js";
 import { runAnalysis } from "../analysis.js";
 import { listing } from "../components.js";
-import { ConfigError } from "../config.js";
 import { OUTSIDE, swept as judged } from "../graph.js";
 import { referenceKey } from "../matrix.js";
 import { partialNotes } from "../partial.js";
@@ -9,6 +8,7 @@ import { resolvePath } from "../paths.js";
 import { positionKey } from "../position.js";
 import { resolve } from "../resolve.js";
 import {} from "./verb.js";
+import { UsageError } from "../usage.js";
 import { bytewise } from "../text/compare.js";
 import { diagnose } from "../product.js";
 /**
@@ -36,10 +36,10 @@ function namedSymbol(option) {
     });
     const [only, ...more] = named;
     if (only === undefined) {
-        throw new ConfigError("malformed", "", "explain explains the symbol --why, --why-live or --why-not names, and none was named");
+        throw new UsageError("explain explains the symbol --why, --why-live or --why-not names, and none was named");
     }
     if (more.length > 0) {
-        throw new ConfigError("malformed", "", `explain explains one symbol, and ${named.map((one) => `--${one.name}`).join(", ")} each name one`);
+        throw new UsageError(`explain explains one symbol, and ${named.map((one) => `--${one.name}`).join(", ")} each name one`);
     }
     return only.value;
 }

package/dist/src/verbs/print-projects.js

@@ -2,7 +2,7 @@ import { EXIT_CLEAN } from "../contract/contract.generated.js";
 import { runProjects } from "../analysis.js";
 import { partialNotes } from "../partial.js";
 import { resolvePath } from "../paths.js";
-import { resolveUnkinded } from "../resolve.js";
+import { resolvePartial } from "../resolve.js";
 import {} from "./verb.js";
 import { diagnose } from "../product.js";
 /**
@@ -13,7 +13,7 @@ import { diagnose } from "../product.js";
  * instead, and one that fails the analysis fails this command the same way.
  */
 export const printProjectsVerb = ({ out, err, host, inputs, scope, openClient }) => {
-    const config = resolveUnkinded(inputs());
+    const config = resolvePartial(inputs());
     const scoped = scope();
     const answer = runProjects(openClient(config), host, scoped, config);
     for (const id of answer.configurations) {