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

package/dist/src/unseen-loads.js

@@ -0,0 +1,100 @@
+/**
+ * The loads of a project's production files whose target the analysis cannot resolve: an
+ * `import()` or `require()` call whose path is computed and starts with no relative literal
+ * naming a directory below the calling file's. The files such a load runs are roots the
+ * analysis does not see, so the configuration's roots are never complete.
+ */
+import { isBinaryExpression, isCallExpression, isIdentifier, isNoSubstitutionTemplateLiteral, isStringLiteral, isTemplateExpression, SyntaxKind, } from "@typescript/native/ast";
+import { dirnamePath, relativePath, resolvePath } from "./paths.js";
+import { renderPosition } from "./position.js";
+import { UNANSWERED } from "./query.js";
+import { sourceFilesOf } from "./source-files.js";
+import { unwrapped } from "./unwrap.js";
+/** The literal text a computed path starts with: a template's head, or a concatenation's first literal. */
+export function leadingLiteral(node) {
+    const at = unwrapped(node);
+    if (isTemplateExpression(at)) {
+        return at.head.text;
+    }
+    if (isBinaryExpression(at) && at.operatorToken.kind === SyntaxKind.PlusToken) {
+        const left = unwrapped(at.left);
+        return isStringLiteral(left) || isNoSubstitutionTemplateLiteral(left)
+            ? left.text
+            : leadingLiteral(at.left);
+    }
+    return undefined;
+}
+/**
+ * The directory below `dir` a computed load's leading literal names, which the entry
+ * rules root every file of, or none where it names a package, `dir` itself or a
+ * directory holding it, each of which would name files no rule roots.
+ */
+export function computedLoadDirectory(dir, prefix) {
+    if (!(prefix.startsWith("./") || prefix.startsWith("../")) || !prefix.endsWith("/")) {
+        return undefined;
+    }
+    const target = resolvePath(dir, prefix);
+    return target === dir || relativePath(target, dir) !== undefined ? undefined : target;
+}
+/** Whether a computed path's leading literal names a package, whose files are none of the target's. */
+function namesPackage(prefix) {
+    return (prefix !== undefined &&
+        prefix !== "" &&
+        !prefix.startsWith(".") &&
+        !prefix.startsWith("/") &&
+        !/^[A-Za-z][A-Za-z\d+.-]*:/u.test(prefix));
+}
+/**
+ * Every unresolved load the project's production files write, in file then source order.
+ * `testFiles` holds the test files by their path below the target root. A `require` call
+ * loads a module only where the name resolves to no declaration of the project's own
+ * files: one the project declares is its own function.
+ */
+export function unseenLoadsOf(project, configuration, targetRoot, testFiles) {
+    const tests = new Set(testFiles);
+    const sites = [];
+    for (const [path, file] of sourceFilesOf(project, targetRoot).byPath) {
+        if (tests.has(path) || file.isDeclarationFile) {
+            continue;
+        }
+        const dir = dirnamePath(file.fileName);
+        const visit = (node) => {
+            if (isCallExpression(node)) {
+                const callee = node.expression;
+                const required = isIdentifier(callee) && callee.text === "require";
+                const [first] = node.arguments;
+                const argument = first === undefined ? undefined : unwrapped(first);
+                if ((callee.kind === SyntaxKind.ImportKeyword || required) &&
+                    argument !== undefined &&
+                    !isStringLiteral(argument) &&
+                    !isNoSubstitutionTemplateLiteral(argument)) {
+                    const prefix = leadingLiteral(argument);
+                    const seen = namesPackage(prefix) ||
+                        (prefix !== undefined && computedLoadDirectory(dir, prefix) !== undefined);
+                    if (!seen) {
+                        sites.push({
+                            position: renderPosition(file, targetRoot, node.getStart()),
+                            require: required ? callee : undefined,
+                        });
+                    }
+                }
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    const requires = sites.flatMap((site) => (site.require === undefined ? [] : [site.require]));
+    const own = project.ownPaths();
+    const local = new Set();
+    project.symbolsAt(requires.map((node) => project.handle(node))).forEach((symbol, at) => {
+        const node = requires[at];
+        if (node !== undefined &&
+            symbol !== UNANSWERED &&
+            symbol?.declarations.some((handle) => own.has(handle.path)) === true) {
+            local.add(node);
+        }
+    });
+    return sites
+        .filter((site) => site.require === undefined || !local.has(site.require))
+        .map((site) => ({ configuration, position: site.position }));
+}

package/dist/src/unwrap.js

@@ -0,0 +1,23 @@
+import { isAsExpression, isNonNullExpression, isParenthesizedExpression, isSatisfiesExpression, } from "@typescript/native/ast";
+/** The expression inside every pair of parentheses around `node`. */
+export function parenthesesRemoved(node) {
+    let at = node;
+    while (isParenthesizedExpression(at)) {
+        at = at.expression;
+    }
+    return at;
+}
+/**
+ * The expression inside every wrapper around `node` that changes no value it evaluates to:
+ * parentheses, `as` and `satisfies` assertions and the non-null assertion.
+ */
+export function unwrapped(node) {
+    let at = node;
+    while (isParenthesizedExpression(at) ||
+        isAsExpression(at) ||
+        isSatisfiesExpression(at) ||
+        isNonNullExpression(at)) {
+        at = at.expression;
+    }
+    return at;
+}

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,18 +1,24 @@
+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 { joinPath, normalizePath, relativePath, resolvePath } from "../paths.js";
+import { dirnamePath, joinPath, normalizePath, relativePath, resolvePath } from "../paths.js";
+import { moduleIdentity } from "../load/discover.js";
 import { partialNotes } from "../partial.js";
-import { buildReport, LANGUAGE, capFindings, sortFindings, } from "../report.js";
+import { buildReport, capFindings, sortFindings, } from "../report.js";
+import { reportRefusals } from "../report-schema.js";
 import { json } from "../reporters/json.js";
 import { RENDERINGS } from "../reporters/reporters.js";
 import { parseTemplate, TemplateError } from "../reporters/template.js";
 import { resolve } from "../resolve.js";
 import { otherSchemeRows, rowReason, writeBaseline } from "../suppress-file.js";
-import { CONTRACT_VERSION } from "../version.js";
-import { EXIT_CLEAN, EXIT_FAILURE } from "./verb.js";
+import {} from "./verb.js";
+import { UsageError } from "../usage.js";
+import { bytewise } from "../text/compare.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"],
@@ -21,16 +27,9 @@ 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().join(", ");
+    return [...RENDERINGS.keys()].sort(bytewise).join(", ");
 }
 /** The renderings one invocation writes: the ones it named, else the configuration's. */
 function formatsOf(named, configured) {
@@ -38,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);
     }
@@ -58,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;
 }
@@ -77,12 +76,61 @@ function unmappedNotes(entries, targetRoot) {
         };
     });
 }
+/**
+ * One note per load of a production file the run cannot resolve, each site once: a file
+ * it loads is a root the run does not see, so `ts.roots_complete` lifts no cap there.
+ */
+function unseenLoadNotes(loads) {
+    return [
+        ...new Map(loads.map((load) => {
+            const { path, line, column } = load.position;
+            const site = `${path}:${String(line)}:${String(column)}`;
+            const note = {
+                kind: "computed-load",
+                path: dirnamePath(path),
+                message: `${site} loads a module by a computed path the analysis cannot resolve, so the configurations compiling it report what no root reaches at probable at most, whatever ts.roots_complete says`,
+            };
+            return [site, note];
+        })).values(),
+    ];
+}
+/** One note per package whose command strings name files a configuration holds, naming every such file. */
+function heldScriptNotes(held, targetRoot) {
+    const files = new Map();
+    for (const one of held) {
+        files.set(one.dir, new Set([...(files.get(one.dir) ?? []), ...one.files]));
+    }
+    return [...files].map(([dir, paths]) => ({
+        kind: "unread-command",
+        path: relativePath(targetRoot, dir) ?? ".",
+        message: `commands the analysis does not read name ${[...paths].sort(bytewise).join(", ")}, so no finding is reported about ${paths.size === 1 ? "that file itself or the names it exports" : "those files themselves or the names they export"}`,
+    }));
+}
+function unresolvedNotes(specifiers) {
+    return specifiers.map(({ specifier, position }) => ({
+        kind: "unresolved-specifier",
+        path: dirnamePath(position.path),
+        message: `${position.path}:${String(position.line)}:${String(position.column)} loads ${JSON.stringify(specifier)}, which resolves to no file, so it references nothing`,
+    }));
+}
+function unreadLine(input, targetRoot) {
+    switch (input.kind) {
+        case "manifest": {
+            const path = relativePath(targetRoot, input.manifest) ?? input.manifest;
+            return input.reason === undefined
+                ? `${path} does not parse, so the manifest facts of the program formed for its package are unanswered: correct the manifest`
+                : `${path} cannot be read, so the manifest facts of the program formed for its package are unanswered: give the run read access to it: ${input.reason}`;
+        }
+        case "ignore-file":
+            return `${relativePath(targetRoot, input.path) ?? input.path} cannot be read, so the JavaScript files it would ignore are analyzed: ${input.reason}`;
+    }
+}
 /** Each project the run dropped as a report names it, by its configuration file below the target. */
 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 };
     });
@@ -92,11 +140,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"}`;
@@ -109,7 +170,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;
     }
@@ -118,7 +179,7 @@ function templateOf(host, invoked, named, formats) {
         source = host.readFile(resolvePath(invoked, named));
     }
     catch (error) {
-        throw new ConfigError("malformed", "", `--template=${named}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new UsageError(`--template=${named}: ${message(error)}`);
     }
     try {
         return parseTemplate(source);
@@ -127,7 +188,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}`);
     }
 }
 /**
@@ -141,17 +202,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 = {
@@ -162,123 +219,106 @@ 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) {
-        err.write(`deadset-ts: ${error instanceof Error ? error.message : String(error)}\n`);
-        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,
-            notes: unmappedNotes(run.unmappedEntries, resolvePath(invoked, targetRoot)),
-        });
-        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;
-        }
-        err.write(`deadset-ts: ${error.message}\n`);
-        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 {
-        host.writeDocument(documents.report, json(report));
-        const options = {
-            failOn: config.reporters.failOn,
-            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 unreadInputs = run.unread.map((one) => unreadLine(one, resolvePath(invoked, targetRoot)));
+    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),
+            ...unresolvedNotes(run.unresolvedSpecifiers),
+            ...heldScriptNotes(run.heldScripts, resolvePath(invoked, targetRoot)),
+        ],
+    });
+    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) {
-        err.write(`deadset-ts: ${error instanceof Error ? error.message : String(error)}\n`);
-        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) {
-        err.write(`deadset-ts: ${note}\n`);
+        diagnose(err, note);
     }
-    for (const line of [...unread, ...unfound]) {
-        err.write(`deadset-ts: ${line}\n`);
+    for (const line of [...unread, ...unfound, ...unreadInputs]) {
+        diagnose(err, line);
     }
     for (const warning of warnings) {
-        err.write(`deadset-ts: ${warning.path}:${String(warning.line)}: a <script> start tag that begins a line is not read as a block: ${warning.reason}\n`);
+        diagnose(err, `${warning.path}:${String(warning.line)}: a <script> start tag that begins a line is not read as a block: ${warning.reason}`);
     }
     for (const skip of report.type_error_skips) {
-        err.write(`deadset-ts: ${skip.path}:${String(skip.line)}: ${skip.message}: the function or statement holding this type error is not evaluated\n`);
+        diagnose(err, `${skip.path}:${String(skip.line)}: ${skip.message}: the function or statement holding this type error is not evaluated`);
     }
     if (report.totals.pending > 0) {
-        err.write(`deadset-ts: ${counted(report.totals.pending, "pending finding")}: the report names a declared cross-language edge, and no merge has resolved it\n`);
+        diagnose(err, `${counted(report.totals.pending, "pending finding")}: the report names a declared cross-language edge, and no merge has resolved it`);
     }
     if (report.totals.stale_suppressions > 0) {
-        err.write(`deadset-ts: ${counted(report.totals.stale_suppressions, "stale suppression")}\n`);
+        diagnose(err, counted(report.totals.stale_suppressions, "stale suppression"));
     }
     if (exitCode === EXIT_CODE_OFF) {
         if (verdict !== EXIT_CLEAN) {
-            err.write(`deadset-ts: the exit code is configured off: the verdict of this run is ${String(verdict)}\n`);
+            diagnose(err, `the exit code is configured off: the verdict of this run is ${String(verdict)}`);
         }
         return EXIT_CLEAN;
     }

package/dist/src/verbs/describe.js

@@ -1,7 +1,8 @@
+import { CONTRACT_VERSION, EXIT_CLEAN, EXIT_USAGE, SCHEMA_VERSIONS, } from "../contract/contract.generated.js";
 import { CONFORMANCE } from "../conformance.js";
-import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSIONS_ACCEPTED } from "../report.js";
-import { CONTRACT_VERSION } from "../version.js";
-import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE } from "./verb.js";
+import {} from "./verb.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
@@ -9,10 +10,10 @@ import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE } from "./verb.js";
  */
 export function describeDocument(version, recorded) {
     const document = {
-        name: ANALYZER_NAME,
+        name: PRODUCT,
         version,
         contract_version: CONTRACT_VERSION,
-        schema_versions_accepted: SCHEMA_VERSIONS_ACCEPTED,
+        schema_versions_accepted: SCHEMA_VERSIONS,
         languages: [LANGUAGE],
         ...(recorded === undefined
             ? {}
@@ -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) {
-        err.write(`deadset-ts: describe takes no argument, got ${JSON.stringify(args[0])}\n`);
+        diagnose(err, `describe takes no argument, got ${JSON.stringify(args[0])}`);
         return EXIT_USAGE;
     }
-    let version;
-    try {
-        version = host.analyzerVersion();
-    }
-    catch (error) {
-        err.write(`deadset-ts: describe: ${error instanceof Error ? error.message : String(error)}\n`);
-        return EXIT_FAILURE;
-    }
-    out.write(describeDocument(version, CONFORMANCE));
+    out.write(describeDocument(ownVersion(host), CONFORMANCE));
     return EXIT_CLEAN;
 };

package/dist/src/verbs/explain.js

@@ -1,13 +1,16 @@
+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";
 import { resolvePath } from "../paths.js";
 import { positionKey } from "../position.js";
 import { resolve } from "../resolve.js";
-import { EXIT_CLEAN, EXIT_USAGE } from "./verb.js";
+import {} from "./verb.js";
+import { UsageError } from "../usage.js";
+import { bytewise } from "../text/compare.js";
+import { diagnose } from "../product.js";
 /**
  * The three spellings of an explanation request, each naming the symbol to explain. They are
  * one request, because exactly one state holds for a symbol and the answer is that state.
@@ -33,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;
 }
@@ -73,7 +76,7 @@ function subjectOf(symbols, named) {
     const partial = symbols
         .filter((symbol) => symbol.ref.toLowerCase().includes(folded) || symbol.name.toLowerCase().includes(folded))
         .map(described)
-        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        .sort(bytewise);
     return { candidates: partial.slice(0, MAX_PARTIAL_MATCHES) };
 }
 /** Every reference of the run once, a reference several configurations make counted once. */
@@ -317,7 +320,7 @@ export const explainVerb = ({ out, err, host, inputs, scope, openClient, option
         targetRoot: resolvePath(host.workingDirectory(), scoped.target.path),
     });
     if (subject === undefined) {
-        err.write(`deadset-ts: ${JSON.stringify(named)} names no one symbol of the target\n`);
+        diagnose(err, `${JSON.stringify(named)} names no one symbol of the target`);
         for (const candidate of candidates) {
             err.write(`  ${candidate}\n`);
         }
@@ -329,7 +332,7 @@ export const explainVerb = ({ out, err, host, inputs, scope, openClient, option
         out.write(explanation(analysis, subject, config.reporters.cascade));
     }
     for (const note of notes) {
-        err.write(`deadset-ts: ${note}\n`);
+        diagnose(err, note);
     }
     return subject === undefined ? EXIT_USAGE : EXIT_CLEAN;
 };