@cplieger/deadset-ts 3.3.0 → 3.3.1

package/dist/src/findings/dependencies-and-module-machinery.js

@@ -0,0 +1,2 @@
+/** The findings of the dependencies-and-module-machinery family, `DS1600` to `DS1699`. */
+export const dependenciesAndModuleMachinery = () => [];

package/dist/src/findings/emitter.js

@@ -0,0 +1 @@
+export {};

package/dist/src/findings/emitters.js

@@ -0,0 +1,19 @@
+import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.js";
+import { interfaces } from "./interfaces.js";
+import { intraFunction } from "./intra-function.js";
+import { nonCodeArtifacts } from "./non-code-artifacts.js";
+import { readsAndWrites } from "./reads-and-writes.js";
+import { selfCheck } from "./self-check.js";
+import { unusedDeclarations } from "./unused-declarations.js";
+import { visibilityNarrowing } from "./visibility-narrowing.js";
+/** Every kind family this analyzer reports, each by its emitter, in code order. */
+export const EMITTERS = new Map([
+    ["unused-declarations", unusedDeclarations],
+    ["visibility-narrowing", visibilityNarrowing],
+    ["interfaces", interfaces],
+    ["reads-and-writes", readsAndWrites],
+    ["non-code-artifacts", nonCodeArtifacts],
+    ["dependencies-and-module-machinery", dependenciesAndModuleMachinery],
+    ["self-check", selfCheck],
+    ["intra-function", intraFunction],
+]);

package/dist/src/findings/interfaces.js

@@ -0,0 +1,2 @@
+/** The findings of the interfaces family, `DS1200` to `DS1299`. */
+export const interfaces = () => [];

package/dist/src/findings/intra-function.js

@@ -0,0 +1,2 @@
+/** The findings of the intra-function family, `DS1800` to `DS1899`. */
+export const intraFunction = () => [];

package/dist/src/findings/non-code-artifacts.js

@@ -0,0 +1,2 @@
+/** The findings of the non-code-artifacts family, `DS1500` to `DS1599`. */
+export const nonCodeArtifacts = () => [];

package/dist/src/findings/reads-and-writes.js

@@ -0,0 +1,2 @@
+/** The findings of the reads-and-writes family, `DS1300` to `DS1399`. */
+export const readsAndWrites = () => [];

package/dist/src/findings/self-check.js

@@ -0,0 +1,2 @@
+/** The findings of the self-check family, `DS1700` to `DS1799`. */
+export const selfCheck = () => [];

package/dist/src/findings/unused-declarations.js

@@ -0,0 +1,2 @@
+/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
+export const unusedDeclarations = () => [];

package/dist/src/findings/visibility-narrowing.js

@@ -0,0 +1,2 @@
+/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
+export const visibilityNarrowing = () => [];

package/dist/src/run.js

@@ -1,29 +1,30 @@
-import { runRoots, runSweep } from "./analysis.js";
 import { ConfigError, REPOSITORY_DOCUMENT } from "./config.js";
-import { diagnosticErrors, discoverProjects, DiscoveryError, renderDiagnostic, } from "./discover.js";
-import { retainedLines } from "./exempt.js";
+import { DiscoveryError, renderDiagnostic } from "./discover.js";
+import { EMITTERS } from "./findings/emitters.js";
 import { joinPath, resolvePath } from "./paths.js";
-import { printConfig } from "./print.js";
-import { resolve, resolveMatrix } from "./resolve.js";
 import { readScope, ScopeError, scopeForDir } from "./scope.js";
-import { diagnosticsOf, openEngine, runSession } from "./session.js";
-import { CONTRACT_VERSION } from "./version.js";
-/** The exit codes the Contract's exit-code table names. */
-const EXIT_CLEAN = 0;
-const EXIT_FINDINGS = 1;
-const EXIT_USAGE = 2;
-const EXIT_FAILURE = 3;
+import { openEngine } from "./session.js";
+import { printConfigVerb } from "./verbs/print-config.js";
+import { printProjectsVerb } from "./verbs/print-projects.js";
+import { printRetainedVerb } from "./verbs/print-retained.js";
+import { printRootsVerb } from "./verbs/print-roots.js";
+import { EXIT_FAILURE, EXIT_USAGE } from "./verbs/verb.js";
+import { versionVerb } from "./verbs/version.js";
+/**
+ * Every verb this command answers, in the order the usage text lists them. A verb
+ * with no `run` is listed, and invoking it is a usage error.
+ */
 const VERBS = [
-    "analyze",
-    "explain",
-    "print-config",
-    "print-projects",
-    "print-roots",
-    "print-retained",
-    "describe",
-    "version",
+    { name: "analyze" },
+    { name: "explain" },
+    { name: "print-config", run: printConfigVerb },
+    { name: "print-projects", run: printProjectsVerb },
+    { name: "print-roots", run: printRootsVerb },
+    { name: "print-retained", run: printRetainedVerb },
+    { name: "describe" },
+    { name: "version", run: versionVerb },
 ];
-const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.join(", ")}\n`;
+const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.map((verb) => verb.name).join(", ")}\n`;
 /**
  * The tokens whose presence in an option's name makes that option a request to
  * edit a source file. The set is closed, and a token is matched in any position of
@@ -31,15 +32,11 @@ const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.join(", ")}\n`
  */
 const SOURCE_EDIT_TOKENS = ["fix", "edit", "delete", "rewrite"];
 /**
- * Maps an option name to the setting it supplies, so one entry registers the
- * option, supplies the document resolution reads, and gives the spelling the
- * setting's provenance names.
- *
- * An option's name is this command's own vocabulary, chosen for how it reads on a
- * command line, and its path is the setting of the Contract's configuration schema
- * that option supplies. The two are mapped here and never derived from one
- * another, so this table is the authority for both: a setting reaches the command
- * line only by an entry, and a path names a key the schema declares.
+ * Maps an option name to the setting of the Contract's configuration schema it supplies,
+ * so one entry registers the option, supplies the document resolution reads, and gives
+ * the spelling the setting's provenance names. The name is this command's vocabulary and
+ * is never derived from the path: a setting reaches the command line only by an entry,
+ * and a path names a key the schema declares.
  */
 export const SETTING_OPTIONS = new Map([
     ["min-confidence", "analysis.min_confidence"],
@@ -139,20 +136,13 @@ function scopeOf(host, options) {
     return scopeForDir(host, options.named.get("target") ?? ".");
 }
 /**
- * Runs the deadset-ts command line over `args` (the arguments after the program
- * name) and returns the process exit code: 0 for a completed verb, 2 for a usage
- * error or a configuration this analyzer refuses, 3 for a failure that produced no
- * answer. It writes nothing outside `out` and `err` and never exits the process,
- * so a caller decides what the code means.
- *
- * An option asking for a source edit is refused before the verb is read: this
- * analyzer reports and never edits a source file.
- *
- * `host` is the platform the run reads, the version it reports included;
- * `openClient` opens the compiler client a verb that reads projects needs.
- * Both are parameters because both are the platform, which no module below this one
- * names: the command entry binds them, and a caller that wants to watch what a run
- * reads supplies its own.
+ * Runs the command line over `args`, the arguments after the program name, and returns
+ * the exit code: 0 for a completed verb, 1 for a finding that fails the run, 2 for a
+ * usage error, a requested source edit or a refused configuration, 3 for a failure that
+ * produced no answer. It writes nothing outside `out` and `err` and never exits the
+ * process. `host` is the platform the run reads, the version it reports included, and
+ * `openClient` opens the compiler client; a caller that watches what a run reads
+ * supplies its own of either.
  */
 export function run(args, out, err, host, openClient = (collectTiming) => openEngine({ collectTiming })) {
     const editing = sourceEditOption(args);
@@ -161,151 +151,45 @@ export function run(args, out, err, host, openClient = (collectTiming) => openEn
         err.write(USAGE);
         return EXIT_USAGE;
     }
-    const verb = args[0];
-    if (verb === "version") {
-        out.write(`deadset-ts ${host.analyzerVersion()}\ncontract ${CONTRACT_VERSION}\n`);
-        return EXIT_CLEAN;
-    }
-    if (verb === "print-config") {
-        return printConfigVerb(args.slice(1), out, err, host);
-    }
-    if (verb === "print-projects") {
-        return printProjectsVerb(args.slice(1), out, err, host, openClient);
-    }
-    if (verb === "print-roots") {
-        return printRootsVerb(args.slice(1), out, err, host, openClient);
+    const name = args[0];
+    const verb = VERBS.find((listed) => listed.name === name);
+    if (verb?.run !== undefined) {
+        return invoke(verb.run, args.slice(1), { out, err, host }, openClient);
     }
-    if (verb === "print-retained") {
-        return printRetainedVerb(args.slice(1), out, err, host, openClient);
-    }
-    if (verb !== undefined && VERBS.includes(verb)) {
-        err.write(`deadset-ts: ${verb} is not implemented\n`);
+    if (verb !== undefined) {
+        err.write(`deadset-ts: ${verb.name} is not implemented\n`);
         return EXIT_USAGE;
     }
-    if (verb !== undefined) {
-        err.write(`deadset-ts: unknown verb ${JSON.stringify(verb)}\n`);
+    if (name !== undefined) {
+        err.write(`deadset-ts: unknown verb ${JSON.stringify(name)}\n`);
     }
     err.write(USAGE);
     return EXIT_USAGE;
 }
-/** Writes the resolved configuration with the source of every setting. */
-function printConfigVerb(args, out, err, host) {
-    try {
-        const options = readOptions(args);
-        const { config, provenance } = resolve(inputsOf(host, options));
-        out.write(printConfig(config, provenance));
-        return EXIT_CLEAN;
-    }
-    catch (error) {
-        return refuse(error, err);
-    }
-}
 /**
- * Writes the name of every project one run analyzes, one per line, having read each
- * project's diagnostics first: the identifier the build matrix declares for it, or,
- * where discovery derived the project, its configuration file's path below the
- * target root.
+ * Runs one verb over the arguments after its name. The options are read the first
+ * time the verb asks for what they name, and a refusal the verb throws is written
+ * and turned into its exit code once the client the verb opened is closed.
  */
-function printProjectsVerb(args, out, err, host, openClient) {
-    let engine;
+function invoke(verb, args, streams, openClient) {
+    let options;
+    const read = () => (options ??= readOptions(args));
+    let opened;
     try {
-        const options = readOptions(args);
-        const matrix = resolveMatrix(inputsOf(host, options));
-        const scope = scopeOf(host, options);
-        engine = openClient(false);
-        const discovered = discoverProjects(engine, host, scope, matrix);
-        const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
-        const failures = [];
-        const { projects } = runSession(engine, discovered.configFiles, (project) => {
-            const errors = diagnosticErrors(diagnosticsOf(project));
-            failures.push(...errors.map(renderDiagnostic));
-            return ids.get(project.configFile) ?? project.configFile;
+        return verb({
+            ...streams,
+            inputs: () => inputsOf(streams.host, read()),
+            scope: () => scopeOf(streams.host, read()),
+            openClient: (collectTiming) => {
+                opened = openClient(collectTiming);
+                return opened;
+            },
+            emitters: EMITTERS,
         });
-        if (failures.length > 0) {
-            for (const line of failures) {
-                err.write(`${line}\n`);
-            }
-            err.write(`deadset-ts: ${String(failures.length)} error(s); no answer was produced\n`);
-            return EXIT_FAILURE;
-        }
-        for (const id of projects) {
-            out.write(`${id}\n`);
-        }
-        return EXIT_CLEAN;
-    }
-    catch (error) {
-        engine?.close();
-        return refuse(error, err);
-    }
-}
-/**
- * One root as a line: the declaration's reference, why it is a root, and the string
- * that named it, separated by tabs. A run of several configurations adds the ones
- * whose project holds the root as a fourth field, and writes the third present and
- * empty where no string named the root, so every line of one run holds the same
- * fields.
- */
-function rootLine(root, several) {
-    const line = `${root.ref}\t${root.kind}`;
-    if (several) {
-        return `${line}\t${root.source}\t${root.configurations.join(" ")}`;
-    }
-    return root.source === "" ? line : `${line}\t${root.source}`;
-}
-/**
- * Writes the root set of the run, one root per line, and then names on the error
- * stream, by its issue kind, every configured root or pattern that named nothing;
- * one such string fails the run. The line shape is this command's own rather than a
- * Contract format, so that sort and cut read it.
- */
-function printRootsVerb(args, out, err, host, openClient) {
-    let engine;
-    try {
-        const options = readOptions(args);
-        const { config, provenance } = resolve(inputsOf(host, options));
-        const scope = scopeOf(host, options);
-        engine = openClient(false);
-        const answer = runRoots(engine, host, scope, config, provenance);
-        const several = answer.configurations.length > 1;
-        for (const root of answer.roots) {
-            out.write(`${rootLine(root, several)}\n`);
-        }
-        for (const finding of answer.findings) {
-            err.write(`${finding.code}: roots.patterns names nothing: ${finding.symbol.ref}\n`);
-        }
-        return answer.findings.length > 0 ? EXIT_FINDINGS : EXIT_CLEAN;
-    }
-    catch (error) {
-        engine?.close();
-        return refuse(error, err);
-    }
-}
-/**
- * Writes every declaration an exemption held back in the production sweep a report is
- * built from, one per line, and nothing where no exemption held one back. One fact
- * several configurations found is one record, so the line names no configuration. The
- * line shape is this command's own rather than a Contract format, so that sort and cut
- * read it.
- */
-function printRetainedVerb(args, out, err, host, openClient) {
-    let engine;
-    try {
-        const options = readOptions(args);
-        const { config } = resolve(inputsOf(host, options));
-        const scope = scopeOf(host, options);
-        engine = openClient(false);
-        const swept = runSweep(engine, host, scope, config, {
-            marked: [],
-            mode: { production: true },
-        });
-        for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
-            out.write(`${line}\n`);
-        }
-        return EXIT_CLEAN;
     }
     catch (error) {
-        engine?.close();
-        return refuse(error, err);
+        opened?.close();
+        return refuse(error, streams.err);
     }
 }
 /** Turns one refusal into the exit code the Contract's table gives it. */

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

@@ -0,0 +1,9 @@
+import { printConfig } from "../print.js";
+import { resolve } from "../resolve.js";
+import { EXIT_CLEAN } from "./verb.js";
+/** Writes the resolved configuration with the source of every setting. */
+export const printConfigVerb = ({ out, inputs }) => {
+    const { config, provenance } = resolve(inputs());
+    out.write(printConfig(config, provenance));
+    return EXIT_CLEAN;
+};

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

@@ -0,0 +1,34 @@
+import { diagnosticErrors, discoverProjects, renderDiagnostic } from "../discover.js";
+import { resolveMatrix } from "../resolve.js";
+import { diagnosticsOf, runSession } from "../session.js";
+import { EXIT_CLEAN, EXIT_FAILURE } from "./verb.js";
+/**
+ * Writes the name of every project one run analyzes, one per line, having read each
+ * project's diagnostics first: the identifier the build matrix declares for it, or,
+ * where discovery derived the project, its configuration file's path below the
+ * target root.
+ */
+export const printProjectsVerb = ({ out, err, host, inputs, scope, openClient }) => {
+    const matrix = resolveMatrix(inputs());
+    const scoped = scope();
+    const engine = openClient(false);
+    const discovered = discoverProjects(engine, host, scoped, matrix);
+    const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
+    const failures = [];
+    const { projects } = runSession(engine, discovered.configFiles, (project) => {
+        const errors = diagnosticErrors(diagnosticsOf(project));
+        failures.push(...errors.map(renderDiagnostic));
+        return ids.get(project.configFile) ?? project.configFile;
+    });
+    if (failures.length > 0) {
+        for (const line of failures) {
+            err.write(`${line}\n`);
+        }
+        err.write(`deadset-ts: ${String(failures.length)} error(s); no answer was produced\n`);
+        return EXIT_FAILURE;
+    }
+    for (const id of projects) {
+        out.write(`${id}\n`);
+    }
+    return EXIT_CLEAN;
+};

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

@@ -0,0 +1,23 @@
+import { runSweep } from "../analysis.js";
+import { retainedLines } from "../exempt.js";
+import { resolve } from "../resolve.js";
+import { EXIT_CLEAN } from "./verb.js";
+/**
+ * Writes every declaration an exemption held back in the production sweep a report is
+ * built from, one per line, and nothing where no exemption held one back. One fact
+ * several configurations found is one record, so the line names no configuration. The
+ * line shape is this command's own rather than a Contract format, so that sort and cut
+ * read it.
+ */
+export const printRetainedVerb = ({ out, host, inputs, scope, openClient }) => {
+    const { config } = resolve(inputs());
+    const scoped = scope();
+    const swept = runSweep(openClient(false), host, scoped, config, {
+        marked: [],
+        mode: { production: true },
+    });
+    for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
+        out.write(`${line}\n`);
+    }
+    return EXIT_CLEAN;
+};

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

@@ -0,0 +1,36 @@
+import { runRoots } from "../analysis.js";
+import { resolve } from "../resolve.js";
+import { EXIT_CLEAN, EXIT_FINDINGS } from "./verb.js";
+/**
+ * One root as a line: the declaration's reference, why it is a root, and the string
+ * that named it, separated by tabs. A run of several configurations adds the ones
+ * whose project holds the root as a fourth field, and writes the third present and
+ * empty where no string named the root, so every line of one run holds the same
+ * fields.
+ */
+function rootLine(root, several) {
+    const line = `${root.ref}\t${root.kind}`;
+    if (several) {
+        return `${line}\t${root.source}\t${root.configurations.join(" ")}`;
+    }
+    return root.source === "" ? line : `${line}\t${root.source}`;
+}
+/**
+ * Writes the root set of the run, one root per line, and then names on the error
+ * stream, by its issue kind, every configured root or pattern that named nothing;
+ * one such string fails the run. The line shape is this command's own rather than a
+ * Contract format, so that sort and cut read it.
+ */
+export const printRootsVerb = ({ out, err, host, inputs, scope, openClient }) => {
+    const { config, provenance } = resolve(inputs());
+    const scoped = scope();
+    const answer = runRoots(openClient(false), host, scoped, config, provenance);
+    const several = answer.configurations.length > 1;
+    for (const root of answer.roots) {
+        out.write(`${rootLine(root, several)}\n`);
+    }
+    for (const finding of answer.findings) {
+        err.write(`${finding.code}: roots.patterns names nothing: ${finding.symbol.ref}\n`);
+    }
+    return answer.findings.length > 0 ? EXIT_FINDINGS : EXIT_CLEAN;
+};

package/dist/src/verbs/verb.js

@@ -0,0 +1,5 @@
+/** The exit codes the Contract's exit-code table names. */
+export const EXIT_CLEAN = 0;
+export const EXIT_FINDINGS = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_FAILURE = 3;

package/dist/src/verbs/version.js

@@ -0,0 +1,7 @@
+import { CONTRACT_VERSION } from "../version.js";
+import { EXIT_CLEAN } from "./verb.js";
+/** Writes the version the host reports and the Contract version this analyzer implements. */
+export const versionVerb = ({ out, host }) => {
+    out.write(`deadset-ts ${host.analyzerVersion()}\ncontract ${CONTRACT_VERSION}\n`);
+    return EXIT_CLEAN;
+};

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",

package/src/findings/dependencies-and-module-machinery.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the dependencies-and-module-machinery family, `DS1600` to `DS1699`. */
+export const dependenciesAndModuleMachinery: Emitter = () => [];

package/src/findings/emitter.ts

@@ -0,0 +1,19 @@
+import type { RunSweep } from "../analysis.ts";
+import type { Config } from "../config.ts";
+import type { Finding } from "../finding.ts";
+
+/** What every emitter reads: the configuration the run resolved and the run's sweep. */
+export interface EmitterInput {
+  readonly config: Config;
+  /** The production sweep a report is built from, beside the matrix it judged. */
+  readonly swept: RunSweep;
+}
+
+/**
+ * One kind family's rule over one run: the findings of the codes in its family's range
+ * of the Contract's code space, in no particular order.
+ */
+export type Emitter = (input: EmitterInput) => readonly Finding[];
+
+/** The emitter of each kind family, by the family's name in the Contract, in code order. */
+export type Emitters = ReadonlyMap<string, Emitter>;

package/src/findings/emitters.ts

@@ -0,0 +1,21 @@
+import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.ts";
+import type { Emitter, Emitters } from "./emitter.ts";
+import { interfaces } from "./interfaces.ts";
+import { intraFunction } from "./intra-function.ts";
+import { nonCodeArtifacts } from "./non-code-artifacts.ts";
+import { readsAndWrites } from "./reads-and-writes.ts";
+import { selfCheck } from "./self-check.ts";
+import { unusedDeclarations } from "./unused-declarations.ts";
+import { visibilityNarrowing } from "./visibility-narrowing.ts";
+
+/** Every kind family this analyzer reports, each by its emitter, in code order. */
+export const EMITTERS: Emitters = new Map<string, Emitter>([
+  ["unused-declarations", unusedDeclarations],
+  ["visibility-narrowing", visibilityNarrowing],
+  ["interfaces", interfaces],
+  ["reads-and-writes", readsAndWrites],
+  ["non-code-artifacts", nonCodeArtifacts],
+  ["dependencies-and-module-machinery", dependenciesAndModuleMachinery],
+  ["self-check", selfCheck],
+  ["intra-function", intraFunction],
+]);

package/src/findings/interfaces.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the interfaces family, `DS1200` to `DS1299`. */
+export const interfaces: Emitter = () => [];

package/src/findings/intra-function.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the intra-function family, `DS1800` to `DS1899`. */
+export const intraFunction: Emitter = () => [];

package/src/findings/non-code-artifacts.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the non-code-artifacts family, `DS1500` to `DS1599`. */
+export const nonCodeArtifacts: Emitter = () => [];

package/src/findings/reads-and-writes.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the reads-and-writes family, `DS1300` to `DS1399`. */
+export const readsAndWrites: Emitter = () => [];

package/src/findings/self-check.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the self-check family, `DS1700` to `DS1799`. */
+export const selfCheck: Emitter = () => [];

package/src/findings/unused-declarations.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
+export const unusedDeclarations: Emitter = () => [];

package/src/findings/visibility-narrowing.ts

@@ -0,0 +1,4 @@
+import type { Emitter } from "./emitter.ts";
+
+/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
+export const visibilityNarrowing: Emitter = () => [];

package/src/run.ts

@@ -1,43 +1,38 @@
-import { runRoots, runSweep, type RunRoot } from "./analysis.ts";
 import { ConfigError, REPOSITORY_DOCUMENT, type Inputs } from "./config.ts";
-import {
-  diagnosticErrors,
-  discoverProjects,
-  DiscoveryError,
-  renderDiagnostic,
-} from "./discover.ts";
-import { retainedLines } from "./exempt.ts";
+import { DiscoveryError, renderDiagnostic } from "./discover.ts";
+import { EMITTERS } from "./findings/emitters.ts";
 import type { Host } from "./host.ts";
 import { joinPath, resolvePath } from "./paths.ts";
-import { printConfig } from "./print.ts";
-import { resolve, resolveMatrix } from "./resolve.ts";
 import { readScope, ScopeError, scopeForDir, type Scope } from "./scope.ts";
-import { diagnosticsOf, openEngine, runSession, type Engine } from "./session.ts";
-import { CONTRACT_VERSION } from "./version.ts";
+import { openEngine, type Engine } from "./session.ts";
+import { printConfigVerb } from "./verbs/print-config.ts";
+import { printProjectsVerb } from "./verbs/print-projects.ts";
+import { printRetainedVerb } from "./verbs/print-retained.ts";
+import { printRootsVerb } from "./verbs/print-roots.ts";
+import { EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verbs/verb.ts";
+import { versionVerb } from "./verbs/version.ts";
 
 /** One output stream of the command line. `process.stdout` and `process.stderr` satisfy it. */
 export interface Writer {
   write(text: string): void;
 }
 
-/** The exit codes the Contract's exit-code table names. */
-const EXIT_CLEAN = 0;
-const EXIT_FINDINGS = 1;
-const EXIT_USAGE = 2;
-const EXIT_FAILURE = 3;
-
-const VERBS = [
-  "analyze",
-  "explain",
-  "print-config",
-  "print-projects",
-  "print-roots",
-  "print-retained",
-  "describe",
-  "version",
-] as const;
+/**
+ * Every verb this command answers, in the order the usage text lists them. A verb
+ * with no `run` is listed, and invoking it is a usage error.
+ */
+const VERBS: readonly { readonly name: string; readonly run?: Verb }[] = [
+  { name: "analyze" },
+  { name: "explain" },
+  { name: "print-config", run: printConfigVerb },
+  { name: "print-projects", run: printProjectsVerb },
+  { name: "print-roots", run: printRootsVerb },
+  { name: "print-retained", run: printRetainedVerb },
+  { name: "describe" },
+  { name: "version", run: versionVerb },
+];
 
-const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.join(", ")}\n`;
+const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.map((verb) => verb.name).join(", ")}\n`;
 
 /**
  * The tokens whose presence in an option's name makes that option a request to
@@ -47,15 +42,11 @@ const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.join(", ")}\n`
 const SOURCE_EDIT_TOKENS = ["fix", "edit", "delete", "rewrite"] as const;
 
 /**
- * Maps an option name to the setting it supplies, so one entry registers the
- * option, supplies the document resolution reads, and gives the spelling the
- * setting's provenance names.
- *
- * An option's name is this command's own vocabulary, chosen for how it reads on a
- * command line, and its path is the setting of the Contract's configuration schema
- * that option supplies. The two are mapped here and never derived from one
- * another, so this table is the authority for both: a setting reaches the command
- * line only by an entry, and a path names a key the schema declares.
+ * Maps an option name to the setting of the Contract's configuration schema it supplies,
+ * so one entry registers the option, supplies the document resolution reads, and gives
+ * the spelling the setting's provenance names. The name is this command's vocabulary and
+ * is never derived from the path: a setting reaches the command line only by an entry,
+ * and a path names a key the schema declares.
  */
 export const SETTING_OPTIONS: ReadonlyMap<string, string> = new Map([
   ["min-confidence", "analysis.min_confidence"],
@@ -177,20 +168,13 @@ function scopeOf(host: Host, options: Options): Scope {
 }
 
 /**
- * Runs the deadset-ts command line over `args` (the arguments after the program
- * name) and returns the process exit code: 0 for a completed verb, 2 for a usage
- * error or a configuration this analyzer refuses, 3 for a failure that produced no
- * answer. It writes nothing outside `out` and `err` and never exits the process,
- * so a caller decides what the code means.
- *
- * An option asking for a source edit is refused before the verb is read: this
- * analyzer reports and never edits a source file.
- *
- * `host` is the platform the run reads, the version it reports included;
- * `openClient` opens the compiler client a verb that reads projects needs.
- * Both are parameters because both are the platform, which no module below this one
- * names: the command entry binds them, and a caller that wants to watch what a run
- * reads supplies its own.
+ * Runs the command line over `args`, the arguments after the program name, and returns
+ * the exit code: 0 for a completed verb, 1 for a finding that fails the run, 2 for a
+ * usage error, a requested source edit or a refused configuration, 3 for a failure that
+ * produced no answer. It writes nothing outside `out` and `err` and never exits the
+ * process. `host` is the platform the run reads, the version it reports included, and
+ * `openClient` opens the compiler client; a caller that watches what a run reads
+ * supplies its own of either.
  */
 export function run(
   args: readonly string[],
@@ -208,170 +192,50 @@ export function run(
     return EXIT_USAGE;
   }
 
-  const verb = args[0];
-  if (verb === "version") {
-    out.write(`deadset-ts ${host.analyzerVersion()}\ncontract ${CONTRACT_VERSION}\n`);
-    return EXIT_CLEAN;
-  }
-  if (verb === "print-config") {
-    return printConfigVerb(args.slice(1), out, err, host);
-  }
-  if (verb === "print-projects") {
-    return printProjectsVerb(args.slice(1), out, err, host, openClient);
-  }
-  if (verb === "print-roots") {
-    return printRootsVerb(args.slice(1), out, err, host, openClient);
-  }
-  if (verb === "print-retained") {
-    return printRetainedVerb(args.slice(1), out, err, host, openClient);
+  const name = args[0];
+  const verb = VERBS.find((listed) => listed.name === name);
+  if (verb?.run !== undefined) {
+    return invoke(verb.run, args.slice(1), { out, err, host }, openClient);
   }
-  if (verb !== undefined && (VERBS as readonly string[]).includes(verb)) {
-    err.write(`deadset-ts: ${verb} is not implemented\n`);
+  if (verb !== undefined) {
+    err.write(`deadset-ts: ${verb.name} is not implemented\n`);
     return EXIT_USAGE;
   }
-  if (verb !== undefined) {
-    err.write(`deadset-ts: unknown verb ${JSON.stringify(verb)}\n`);
+  if (name !== undefined) {
+    err.write(`deadset-ts: unknown verb ${JSON.stringify(name)}\n`);
   }
   err.write(USAGE);
   return EXIT_USAGE;
 }
 
-/** Writes the resolved configuration with the source of every setting. */
-function printConfigVerb(args: readonly string[], out: Writer, err: Writer, host: Host): number {
-  try {
-    const options = readOptions(args);
-    const { config, provenance } = resolve(inputsOf(host, options));
-    out.write(printConfig(config, provenance));
-    return EXIT_CLEAN;
-  } catch (error: unknown) {
-    return refuse(error, err);
-  }
-}
-
-/**
- * Writes the name of every project one run analyzes, one per line, having read each
- * project's diagnostics first: the identifier the build matrix declares for it, or,
- * where discovery derived the project, its configuration file's path below the
- * target root.
- */
-function printProjectsVerb(
-  args: readonly string[],
-  out: Writer,
-  err: Writer,
-  host: Host,
-  openClient: (collectTiming: boolean) => Engine,
-): number {
-  let engine: Engine | undefined;
-  try {
-    const options = readOptions(args);
-    const matrix = resolveMatrix(inputsOf(host, options));
-    const scope = scopeOf(host, options);
-    engine = openClient(false);
-    const discovered = discoverProjects(engine, host, scope, matrix);
-    const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
-    const failures: string[] = [];
-    const { projects } = runSession(engine, discovered.configFiles, (project) => {
-      const errors = diagnosticErrors(diagnosticsOf(project));
-      failures.push(...errors.map(renderDiagnostic));
-      return ids.get(project.configFile) ?? project.configFile;
-    });
-    if (failures.length > 0) {
-      for (const line of failures) {
-        err.write(`${line}\n`);
-      }
-      err.write(`deadset-ts: ${String(failures.length)} error(s); no answer was produced\n`);
-      return EXIT_FAILURE;
-    }
-    for (const id of projects) {
-      out.write(`${id}\n`);
-    }
-    return EXIT_CLEAN;
-  } catch (error: unknown) {
-    engine?.close();
-    return refuse(error, err);
-  }
-}
-
-/**
- * One root as a line: the declaration's reference, why it is a root, and the string
- * that named it, separated by tabs. A run of several configurations adds the ones
- * whose project holds the root as a fourth field, and writes the third present and
- * empty where no string named the root, so every line of one run holds the same
- * fields.
- */
-function rootLine(root: RunRoot, several: boolean): string {
-  const line = `${root.ref}\t${root.kind}`;
-  if (several) {
-    return `${line}\t${root.source}\t${root.configurations.join(" ")}`;
-  }
-  return root.source === "" ? line : `${line}\t${root.source}`;
-}
-
 /**
- * Writes the root set of the run, one root per line, and then names on the error
- * stream, by its issue kind, every configured root or pattern that named nothing;
- * one such string fails the run. The line shape is this command's own rather than a
- * Contract format, so that sort and cut read it.
+ * Runs one verb over the arguments after its name. The options are read the first
+ * time the verb asks for what they name, and a refusal the verb throws is written
+ * and turned into its exit code once the client the verb opened is closed.
  */
-function printRootsVerb(
+function invoke(
+  verb: Verb,
   args: readonly string[],
-  out: Writer,
-  err: Writer,
-  host: Host,
+  streams: { readonly out: Writer; readonly err: Writer; readonly host: Host },
   openClient: (collectTiming: boolean) => Engine,
 ): number {
-  let engine: Engine | undefined;
+  let options: Options | undefined;
+  const read = (): Options => (options ??= readOptions(args));
+  let opened: Engine | undefined;
   try {
-    const options = readOptions(args);
-    const { config, provenance } = resolve(inputsOf(host, options));
-    const scope = scopeOf(host, options);
-    engine = openClient(false);
-    const answer = runRoots(engine, host, scope, config, provenance);
-    const several = answer.configurations.length > 1;
-    for (const root of answer.roots) {
-      out.write(`${rootLine(root, several)}\n`);
-    }
-    for (const finding of answer.findings) {
-      err.write(`${finding.code}: roots.patterns names nothing: ${finding.symbol.ref}\n`);
-    }
-    return answer.findings.length > 0 ? EXIT_FINDINGS : EXIT_CLEAN;
-  } catch (error: unknown) {
-    engine?.close();
-    return refuse(error, err);
-  }
-}
-
-/**
- * Writes every declaration an exemption held back in the production sweep a report is
- * built from, one per line, and nothing where no exemption held one back. One fact
- * several configurations found is one record, so the line names no configuration. The
- * line shape is this command's own rather than a Contract format, so that sort and cut
- * read it.
- */
-function printRetainedVerb(
-  args: readonly string[],
-  out: Writer,
-  err: Writer,
-  host: Host,
-  openClient: (collectTiming: boolean) => Engine,
-): number {
-  let engine: Engine | undefined;
-  try {
-    const options = readOptions(args);
-    const { config } = resolve(inputsOf(host, options));
-    const scope = scopeOf(host, options);
-    engine = openClient(false);
-    const swept = runSweep(engine, host, scope, config, {
-      marked: [],
-      mode: { production: true },
+    return verb({
+      ...streams,
+      inputs: () => inputsOf(streams.host, read()),
+      scope: () => scopeOf(streams.host, read()),
+      openClient: (collectTiming) => {
+        opened = openClient(collectTiming);
+        return opened;
+      },
+      emitters: EMITTERS,
     });
-    for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
-      out.write(`${line}\n`);
-    }
-    return EXIT_CLEAN;
   } catch (error: unknown) {
-    engine?.close();
-    return refuse(error, err);
+    opened?.close();
+    return refuse(error, streams.err);
   }
 }
 

package/src/verbs/print-config.ts

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

package/src/verbs/print-projects.ts

@@ -0,0 +1,35 @@
+import { diagnosticErrors, discoverProjects, renderDiagnostic } from "../discover.ts";
+import { resolveMatrix } from "../resolve.ts";
+import { diagnosticsOf, runSession } from "../session.ts";
+import { EXIT_CLEAN, EXIT_FAILURE, type Verb } from "./verb.ts";
+
+/**
+ * Writes the name of every project one run analyzes, one per line, having read each
+ * project's diagnostics first: the identifier the build matrix declares for it, or,
+ * where discovery derived the project, its configuration file's path below the
+ * target root.
+ */
+export const printProjectsVerb: Verb = ({ out, err, host, inputs, scope, openClient }) => {
+  const matrix = resolveMatrix(inputs());
+  const scoped = scope();
+  const engine = openClient(false);
+  const discovered = discoverProjects(engine, host, scoped, matrix);
+  const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
+  const failures: string[] = [];
+  const { projects } = runSession(engine, discovered.configFiles, (project) => {
+    const errors = diagnosticErrors(diagnosticsOf(project));
+    failures.push(...errors.map(renderDiagnostic));
+    return ids.get(project.configFile) ?? project.configFile;
+  });
+  if (failures.length > 0) {
+    for (const line of failures) {
+      err.write(`${line}\n`);
+    }
+    err.write(`deadset-ts: ${String(failures.length)} error(s); no answer was produced\n`);
+    return EXIT_FAILURE;
+  }
+  for (const id of projects) {
+    out.write(`${id}\n`);
+  }
+  return EXIT_CLEAN;
+};

package/src/verbs/print-retained.ts

@@ -0,0 +1,24 @@
+import { runSweep } from "../analysis.ts";
+import { retainedLines } from "../exempt.ts";
+import { resolve } from "../resolve.ts";
+import { EXIT_CLEAN, type Verb } from "./verb.ts";
+
+/**
+ * Writes every declaration an exemption held back in the production sweep a report is
+ * built from, one per line, and nothing where no exemption held one back. One fact
+ * several configurations found is one record, so the line names no configuration. The
+ * line shape is this command's own rather than a Contract format, so that sort and cut
+ * read it.
+ */
+export const printRetainedVerb: Verb = ({ out, host, inputs, scope, openClient }) => {
+  const { config } = resolve(inputs());
+  const scoped = scope();
+  const swept = runSweep(openClient(false), host, scoped, config, {
+    marked: [],
+    mode: { production: true },
+  });
+  for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
+    out.write(`${line}\n`);
+  }
+  return EXIT_CLEAN;
+};

package/src/verbs/print-roots.ts

@@ -0,0 +1,38 @@
+import { runRoots, type RunRoot } from "../analysis.ts";
+import { resolve } from "../resolve.ts";
+import { EXIT_CLEAN, EXIT_FINDINGS, type Verb } from "./verb.ts";
+
+/**
+ * One root as a line: the declaration's reference, why it is a root, and the string
+ * that named it, separated by tabs. A run of several configurations adds the ones
+ * whose project holds the root as a fourth field, and writes the third present and
+ * empty where no string named the root, so every line of one run holds the same
+ * fields.
+ */
+function rootLine(root: RunRoot, several: boolean): string {
+  const line = `${root.ref}\t${root.kind}`;
+  if (several) {
+    return `${line}\t${root.source}\t${root.configurations.join(" ")}`;
+  }
+  return root.source === "" ? line : `${line}\t${root.source}`;
+}
+
+/**
+ * Writes the root set of the run, one root per line, and then names on the error
+ * stream, by its issue kind, every configured root or pattern that named nothing;
+ * one such string fails the run. The line shape is this command's own rather than a
+ * Contract format, so that sort and cut read it.
+ */
+export const printRootsVerb: Verb = ({ out, err, host, inputs, scope, openClient }) => {
+  const { config, provenance } = resolve(inputs());
+  const scoped = scope();
+  const answer = runRoots(openClient(false), host, scoped, config, provenance);
+  const several = answer.configurations.length > 1;
+  for (const root of answer.roots) {
+    out.write(`${rootLine(root, several)}\n`);
+  }
+  for (const finding of answer.findings) {
+    err.write(`${finding.code}: roots.patterns names nothing: ${finding.symbol.ref}\n`);
+  }
+  return answer.findings.length > 0 ? EXIT_FINDINGS : EXIT_CLEAN;
+};

package/src/verbs/verb.ts

@@ -0,0 +1,38 @@
+import type { Inputs } from "../config.ts";
+import type { Emitters } from "../findings/emitter.ts";
+import type { Host } from "../host.ts";
+import type { Writer } from "../run.ts";
+import type { Scope } from "../scope.ts";
+import type { Engine } from "../session.ts";
+
+/** The exit codes the Contract's exit-code table names. */
+export const EXIT_CLEAN = 0;
+export const EXIT_FINDINGS = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_FAILURE = 3;
+
+/**
+ * What one verb is handed: the streams it writes, the platform it reads, and the
+ * options that follow its name, read only when the verb asks for what they name, so
+ * a verb that asks for nothing refuses no option.
+ */
+export interface Invocation {
+  readonly out: Writer;
+  readonly err: Writer;
+  readonly host: Host;
+  /** The configuration documents the options name, and the settings they supply. */
+  readonly inputs: () => Inputs;
+  /** The scope the options name: the document `--scope` names, or the target. */
+  readonly scope: () => Scope;
+  /** Opens the compiler client. A client the verb opened is closed if the verb throws. */
+  readonly openClient: (collectTiming: boolean) => Engine;
+  /** The emitter of every kind family, which a verb that reports findings runs. */
+  readonly emitters: Emitters;
+}
+
+/**
+ * One verb of the command line. It returns the exit code, and refuses by throwing a
+ * configuration, discovery or scope error, which the command line writes and turns
+ * into the code the Contract's table gives it.
+ */
+export type Verb = (invocation: Invocation) => number;

package/src/verbs/version.ts

@@ -0,0 +1,8 @@
+import { CONTRACT_VERSION } from "../version.ts";
+import { EXIT_CLEAN, type Verb } from "./verb.ts";
+
+/** Writes the version the host reports and the Contract version this analyzer implements. */
+export const versionVerb: Verb = ({ out, host }) => {
+  out.write(`deadset-ts ${host.analyzerVersion()}\ncontract ${CONTRACT_VERSION}\n`);
+  return EXIT_CLEAN;
+};