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

package/src/verbs/analyze.ts

@@ -1,37 +1,44 @@
+import { CONTRACT_VERSION, EXIT_CLEAN, type Format } from "../contract/contract.generated.ts";
 import {
   runAnalysis,
   runBaselineWrite,
   unansweredCounts,
-  type ComponentWarning,
   type RunAnalysis,
   type RunProject,
 } from "../analysis.ts";
-import { ConfigError, kindOf, type Format } from "../config.ts";
+import { kindOf } from "../config.ts";
 import { CONFORMANCE, DECLARED_GAPS } from "../conformance.ts";
-import { moduleIdentity } from "../consumers.ts";
 import { analyzerProvenance, verdictOf } from "../findings-pass.ts";
-import { joinPath, normalizePath, relativePath, resolvePath } from "../paths.ts";
+import { dirnamePath, joinPath, normalizePath, relativePath, resolvePath } from "../paths.ts";
 import type { Host } from "../host.ts";
 import type { ManifestEntry } from "../manifest.ts";
-import type { NotBuilt } from "../discover.ts";
+import type { HeldScripts } from "../roots.ts";
+import { moduleIdentity, type NotBuilt } from "../load/discover.ts";
 import { partialNotes } from "../partial.ts";
 import {
   buildReport,
-  LANGUAGE,
   capFindings,
   sortFindings,
-  type Report,
   type ReportConfiguration,
   type ReportNotBuilt,
   type ReportNote,
 } from "../report.ts";
+import { reportRefusals } from "../report-schema.ts";
 import { json } from "../reporters/json.ts";
 import { RENDERINGS } from "../reporters/reporters.ts";
 import { parseTemplate, TemplateError, type Template } from "../reporters/template.ts";
 import { resolve } from "../resolve.ts";
 import { otherSchemeRows, rowReason, writeBaseline, type Recorded } from "../suppress-file.ts";
-import { CONTRACT_VERSION } from "../version.ts";
-import { EXIT_CLEAN, EXIT_FAILURE, type Verb, type VerbOptions } from "./verb.ts";
+import type { UnseenLoad } from "../unseen-loads.ts";
+import type { UnreadInput } from "../load/plan.ts";
+import type { UnresolvedSpecifier } from "../load/specifiers.ts";
+
+import { type Verb, type VerbOptions } from "./verb.ts";
+import { UsageError } from "../usage.ts";
+import { bytewise } from "../text/compare.ts";
+import { productFault, failureExit } from "../failure.ts";
+import { diagnose, message } from "../product.ts";
+import { ownVersion } from "./version.ts";
 
 /** The options `analyze` takes beside the ones every verb takes. */
 export const ANALYZE_OPTIONS: VerbOptions = {
@@ -43,17 +50,9 @@ export const ANALYZE_OPTIONS: VerbOptions = {
 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: string) {
-    super(message);
-    this.name = "ReportPathError";
-  }
-}
-
 /** The formats this analyzer renders, for a message that names them. */
 function formatNames(): string {
-  return [...RENDERINGS.keys()].sort().join(", ");
+  return [...RENDERINGS.keys()].sort(bytewise).join(", ");
 }
 
 /** The renderings one invocation writes: the ones it named, else the configuration's. */
@@ -62,14 +61,12 @@ function formatsOf(named: readonly string[], configured: readonly Format[]): rea
   const seen = new Set<string>();
   for (const format of formats) {
     if (!RENDERINGS.has(format as Format)) {
-      throw new ConfigError(
-        "malformed",
-        "",
+      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);
   }
@@ -87,7 +84,8 @@ function runRelative(invoked: string, path: string): string {
   }
   const below = relativePath(invoked, path);
   if (below === undefined) {
-    throw new ReportPathError(
+    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`,
     );
   }
@@ -113,13 +111,69 @@ function unmappedNotes(
   });
 }
 
+/**
+ * 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: readonly UnseenLoad[]): readonly ReportNote[] {
+  return [
+    ...new Map(
+      loads.map((load) => {
+        const { path, line, column } = load.position;
+        const site = `${path}:${String(line)}:${String(column)}`;
+        const note: ReportNote = {
+          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] as const;
+      }),
+    ).values(),
+  ];
+}
+
+/** One note per package whose command strings name files a configuration holds, naming every such file. */
+function heldScriptNotes(held: readonly HeldScripts[], targetRoot: string): readonly ReportNote[] {
+  const files = new Map<string, Set<string>>();
+  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: readonly UnresolvedSpecifier[]): readonly ReportNote[] {
+  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: UnreadInput, targetRoot: string): string {
+  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: readonly NotBuilt[], targetRoot: string): readonly ReportNotBuilt[] {
   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 };
@@ -134,14 +188,33 @@ function configurationsOf(
   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: Host,
+  path: string,
+  fix: string,
+  produce: () => Iterable<string>,
+): void {
+  try {
+    host.writeDocument(path, produce());
+  } catch (error: unknown) {
+    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: number, noun: string): string {
   return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
@@ -160,9 +233,7 @@ function templateOf(
 ): Template | undefined {
   if (named === undefined || named === "") {
     if (formats.includes("template")) {
-      throw new ConfigError(
-        "malformed",
-        "",
+      throw new UsageError(
         "the template format renders the template --template names, and none was named",
       );
     }
@@ -172,11 +243,7 @@ function templateOf(
   try {
     source = host.readFile(resolvePath(invoked, named));
   } catch (error: unknown) {
-    throw new ConfigError(
-      "malformed",
-      "",
-      `--template=${named}: ${error instanceof Error ? error.message : String(error)}`,
-    );
+    throw new UsageError(`--template=${named}: ${message(error)}`);
   }
   try {
     return parseTemplate(source);
@@ -184,7 +251,7 @@ function templateOf(
     if (!(error instanceof TemplateError)) {
       throw error;
     }
-    throw new ConfigError("malformed", "", `--template=${named}: ${error.message}`);
+    throw new UsageError(`--template=${named}: ${error.message}`);
   }
 }
 
@@ -206,25 +273,17 @@ interface Documents {
 export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option, repeated }) => {
   const reportPath = option("report");
   if (reportPath === undefined || reportPath === "") {
-    throw new ConfigError(
-      "malformed",
-      "",
+    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",
-      "",
+    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: Documents = {
@@ -236,147 +295,150 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
   const scoped = scope();
   const targetRoot = scoped.target.path;
 
-  let version: string;
-  try {
-    version = host.analyzerVersion();
-  } catch (error: unknown) {
-    err.write(`deadset-ts: ${error instanceof Error ? error.message : String(error)}\n`);
-    return EXIT_FAILURE;
-  }
+  const version = ownVersion(host);
 
-  let report: Report;
   let recorded: readonly Recorded[];
-  let verdict: number;
-  let partial: readonly string[];
-  let warnings: readonly ComponentWarning[];
-  let unread: readonly string[];
-  let unfound: readonly string[];
-  try {
-    const root = runRelative(invoked, targetRoot);
-    const mode = { production: true };
-    let analysis: RunAnalysis;
-    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}`,
+  const root = runRelative(invoked, targetRoot);
+  const mode = { production: true };
+  let analysis: RunAnalysis;
+  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,
     );
-    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);
-  } catch (error: unknown) {
-    if (!(error instanceof ReportPathError)) {
-      throw error;
-    }
-    err.write(`deadset-ts: ${error.message}\n`);
-    return EXIT_FAILURE;
+    analysis = write.first;
+    recorded = write.rows;
   }
+  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)));
 
-  try {
-    host.writeDocument(documents.report, json(report));
-    const options = {
-      failOn: config.reporters.failOn,
-      readSource: (path: string) => 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 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: string) => 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: unknown) {
-    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/src/verbs/describe.ts

@@ -1,7 +1,13 @@
+import {
+  CONTRACT_VERSION,
+  EXIT_CLEAN,
+  EXIT_USAGE,
+  SCHEMA_VERSIONS,
+} from "../contract/contract.generated.ts";
 import { CONFORMANCE, type Conformance } from "../conformance.ts";
-import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSIONS_ACCEPTED } from "../report.ts";
-import { CONTRACT_VERSION } from "../version.ts";
-import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verb.ts";
+import { type Verb } from "./verb.ts";
+import { diagnose, LANGUAGE, PRODUCT } from "../product.ts";
+import { ownVersion } from "./version.ts";
 
 /**
  * The document `describe` writes: the analyzer, the Contract version it implements, the
@@ -10,10 +16,10 @@ import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verb.ts";
  */
 export function describeDocument(version: string, recorded: Conformance | undefined): string {
   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
       ? {}
@@ -28,19 +34,12 @@ export function describeDocument(version: string, recorded: Conformance | undefi
   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: Verb = ({ 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: string;
-  try {
-    version = host.analyzerVersion();
-  } catch (error: unknown) {
-    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/src/verbs/explain.ts

@@ -1,7 +1,7 @@
+import { EXIT_CLEAN, EXIT_USAGE } from "../contract/contract.generated.ts";
 import { runAnalysis, type RunAnalysis } from "../analysis.ts";
 import { listing } from "../components.ts";
 import type { Cascade } from "../config.ts";
-import { ConfigError } from "../config.ts";
 import type { CompletedFinding } from "../finding.ts";
 import { OUTSIDE, swept as judged } from "../graph.ts";
 import type { InventorySymbol } from "../inventory.ts";
@@ -12,7 +12,10 @@ import { positionKey } from "../position.ts";
 import type { Reference } from "../references.ts";
 import { resolve } from "../resolve.ts";
 import type { Root } from "../roots.ts";
-import { EXIT_CLEAN, EXIT_USAGE, type Verb, type VerbOptions } from "./verb.ts";
+import { type Verb, type VerbOptions } from "./verb.ts";
+import { UsageError } from "../usage.ts";
+import { bytewise } from "../text/compare.ts";
+import { diagnose } from "../product.ts";
 
 /**
  * The three spellings of an explanation request, each naming the symbol to explain. They are
@@ -44,16 +47,12 @@ function namedSymbol(option: (name: string) => string | undefined): string {
   });
   const [only, ...more] = named;
   if (only === undefined) {
-    throw new ConfigError(
-      "malformed",
-      "",
+    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",
-      "",
+    throw new UsageError(
       `explain explains one symbol, and ${named.map((one) => `--${one.name}`).join(", ")} each name one`,
     );
   }
@@ -101,7 +100,7 @@ function subjectOf(
         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) };
 }
 
@@ -380,7 +379,7 @@ export const explainVerb: Verb = ({ out, err, host, inputs, scope, openClient, o
     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`);
     }
@@ -391,7 +390,7 @@ export const explainVerb: Verb = ({ out, err, host, inputs, scope, openClient, o
     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;
 };

package/src/verbs/print-config.ts

@@ -1,6 +1,7 @@
+import { EXIT_CLEAN } from "../contract/contract.generated.ts";
 import { printConfig } from "../print.ts";
 import { resolve } from "../resolve.ts";
-import { EXIT_CLEAN, type Verb } from "./verb.ts";
+import { type Verb } from "./verb.ts";
 
 /** Writes the resolved configuration with the source of every setting. */
 export const printConfigVerb: Verb = ({ out, inputs }) => {