@cplieger/deadset-ts 3.7.0 → 3.9.0

package/dist/src/suppress-inline.js

@@ -0,0 +1,259 @@
+/**
+ * The inline directive: `deadset:ignore`, the first token of a `//` line comment, naming
+ * one or more codes and a reason, and binding to every declaration that begins on the line
+ * below it.
+ */
+import { SyntaxKind } from "@typescript/native/unstable/ast";
+import { nodeKey } from "./inventory.js";
+import { byPosition, positionKey, renderPosition } from "./position.js";
+import { SUPPRESSION_WITHOUT_REASON, SuppressionError, siteText, } from "./suppress.js";
+/**
+ * The three expressions the grammar applies to the text of each line comment, in this
+ * order: a comment in the namespace, a well-formed directive, and a directive that lacks
+ * only its reason. A test pins each to the line the grammar page carries.
+ */
+export const DIRECTIVE_EXPRESSIONS = {
+    candidate: String.raw `^//[ \t]*deadset:`,
+    wellFormed: String.raw `^//[ \t]*deadset:ignore[ \t]+(?<codes>DS[0-9]{4}(?:,DS[0-9]{4})*)[ \t]+--[ \t]+(?<reason>[^ \t\r\n][^\r\n]*?)[ \t]*$`,
+    noReason: String.raw `^//[ \t]*deadset:ignore[ \t]+(?<codes>DS[0-9]{4}(?:,DS[0-9]{4})*)(?:[ \t]+--)?[ \t]*$`,
+};
+const CANDIDATE = new RegExp(DIRECTIVE_EXPRESSIONS.candidate);
+const WELL_FORMED = new RegExp(DIRECTIVE_EXPRESSIONS.wellFormed);
+const NO_REASON = new RegExp(DIRECTIVE_EXPRESSIONS.noReason);
+/** The form a malformed directive is told to take. */
+const DIRECTIVE_FORM = "// deadset:ignore DS0000[,DS0000...] -- <reason>";
+/** Applies the grammar's three expressions to the text of one comment, in order. */
+export function classifyComment(text) {
+    if (!CANDIDATE.test(text)) {
+        return { is: "none" };
+    }
+    const groups = WELL_FORMED.exec(text)?.groups;
+    if (groups !== undefined) {
+        return {
+            is: "directive",
+            codes: (groups["codes"] ?? "").split(","),
+            reason: groups["reason"] ?? "",
+        };
+    }
+    const bare = NO_REASON.exec(text)?.groups;
+    if (bare !== undefined) {
+        return { is: "no-reason", codes: (bare["codes"] ?? "").split(",") };
+    }
+    return { is: "malformed" };
+}
+/** The literal tokens whose text may hold `//` or `/*` without starting a comment. */
+const LITERALS = new Set([
+    SyntaxKind.StringLiteral,
+    SyntaxKind.NoSubstitutionTemplateLiteral,
+    SyntaxKind.TemplateHead,
+    SyntaxKind.TemplateMiddle,
+    SyntaxKind.TemplateTail,
+    SyntaxKind.RegularExpressionLiteral,
+    SyntaxKind.JsxText,
+]);
+/** Whether one character ends a line, under the language's line terminators. */
+function endsLine(char) {
+    return char === "\n" || char === "\r" || char === "\u2028" || char === "\u2029";
+}
+/** The offset where the line holding `from` ends. */
+function lineEnd(text, from) {
+    let at = from;
+    while (at < text.length && !endsLine(text[at])) {
+        at += 1;
+    }
+    return at;
+}
+/**
+ * The offset of the first token at or after `from`: whitespace, comments and a leading
+ * hashbang are trivia.
+ */
+export function tokenStart(text, from) {
+    let at = from;
+    if (at === 0 && text.startsWith("#!")) {
+        at = lineEnd(text, 0);
+    }
+    for (;;) {
+        if (/\s/u.test(text[at] ?? "")) {
+            at += 1;
+        }
+        else if (text.startsWith("//", at)) {
+            at = lineEnd(text, at);
+        }
+        else if (text.startsWith("/*", at)) {
+            const close = text.indexOf("*/", at + 2);
+            at = close < 0 ? text.length : close + 2;
+        }
+        else {
+            return at;
+        }
+    }
+}
+/**
+ * Every `//` line comment of one file, in file order. The text between tokens is read as
+ * the language reads it: a block comment holds no line comment, and the literal tokens the
+ * syntax tree holds are skipped, so a `//` inside a string, a template or a regular
+ * expression starts nothing.
+ */
+export function lineComments(file) {
+    const text = file.text;
+    const spans = [];
+    const visit = (node) => {
+        if (LITERALS.has(node.kind)) {
+            spans.push({ start: tokenStart(text, node.pos), end: node.end });
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    spans.sort((a, b) => a.start - b.start);
+    const found = [];
+    let next = 0;
+    let at = 0;
+    while (at < text.length) {
+        while (next < spans.length && (spans[next]?.start ?? 0) < at) {
+            next += 1;
+        }
+        const span = spans[next];
+        if (span?.start === at) {
+            at = Math.max(span.end, at + 1);
+        }
+        else if (text.startsWith("//", at)) {
+            const end = lineEnd(text, at);
+            found.push({ offset: at, text: text.slice(at, end) });
+            at = end;
+        }
+        else if (text.startsWith("/*", at)) {
+            const close = text.indexOf("*/", at + 2);
+            at = close < 0 ? text.length : close + 2;
+        }
+        else {
+            at += 1;
+        }
+    }
+    return found;
+}
+/**
+ * The declarations of one file by the line each begins on, the line of its first token: a
+ * decorator, a modifier or the keyword. A variable's first token is its statement's
+ * keyword, and a variable written on a later line of the statement also begins there.
+ */
+function declarationLines(file, held, symbols) {
+    const below = new Map();
+    const add = (offset, one) => {
+        const line = file.getLineAndCharacterOfPosition(tokenStart(file.text, offset)).line + 1;
+        const at = below.get(line) ?? [];
+        if (!at.some((known) => known.id === one.id)) {
+            at.push(one);
+        }
+        below.set(line, at);
+    };
+    const visit = (node) => {
+        const id = held.declarations.get(nodeKey(file, node));
+        const one = id === undefined ? undefined : symbols.get(id);
+        if (one !== undefined) {
+            add(node.pos, one);
+            const list = node.parent;
+            if (node.kind === SyntaxKind.VariableDeclaration &&
+                list.kind === SyntaxKind.VariableDeclarationList &&
+                list.parent.kind === SyntaxKind.VariableStatement) {
+                add(list.parent.pos, one);
+            }
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    return below;
+}
+/**
+ * Every comment in the namespace one project's own files hold, each with the declarations
+ * it binds, read while the project's view is open.
+ */
+export function inlineDirectives(project, held, targetRoot) {
+    const symbols = new Map(held.symbols
+        .filter((symbol) => symbol.kind !== "file")
+        .map((symbol) => [symbol.id, { id: symbol.id, ref: symbol.ref, position: symbol.position }]));
+    const found = [];
+    for (const file of project.ownSourceFiles()) {
+        const comments = lineComments(file).filter((comment) => CANDIDATE.test(comment.text));
+        if (comments.length === 0) {
+            continue;
+        }
+        const below = declarationLines(file, held, symbols);
+        for (const comment of comments) {
+            const site = renderPosition(file, targetRoot, comment.offset);
+            found.push({
+                site,
+                text: comment.text,
+                directive: classifyComment(comment.text),
+                bound: [...(below.get(site.line + 1) ?? [])],
+            });
+        }
+    }
+    return found;
+}
+/**
+ * The inline directives of a run's projects, each bound to the declarations that begin on
+ * the line below it, one directive binding the union of what each project holding its file
+ * declares there. A directive that lacks only its reason is one {@link Refusal} per code;
+ * any other malformed comment in the namespace ends the read with a
+ * {@link SuppressionError} naming the first one written.
+ */
+export function inlineSuppressions(perProject) {
+    const merged = new Map();
+    for (const written of perProject.flat()) {
+        const key = positionKey(written.site);
+        const known = merged.get(key);
+        if (known === undefined) {
+            merged.set(key, { ...written, bound: [...written.bound] });
+            continue;
+        }
+        for (const one of written.bound) {
+            if (!known.bound.some((other) => other.id === one.id)) {
+                known.bound.push(one);
+            }
+        }
+    }
+    const ordered = [...merged.values()].sort((a, b) => byPosition(a.site, b.site));
+    const records = [];
+    const refusals = [];
+    for (const { site, text, directive, bound } of ordered) {
+        switch (directive.is) {
+            case "none":
+                break;
+            case "malformed":
+                throw new SuppressionError("inline", siteText(site), JSON.stringify(text), DIRECTIVE_FORM);
+            case "no-reason":
+                for (const code of directive.codes) {
+                    refusals.push({
+                        reported: SUPPRESSION_WITHOUT_REASON,
+                        code,
+                        symbol: "",
+                        path: site.path,
+                        reason: "",
+                        site,
+                        mechanism: "inline",
+                    });
+                }
+                break;
+            case "directive": {
+                const declared = [...bound].sort((a, b) => byPosition(a.position, b.position));
+                for (const code of directive.codes) {
+                    const base = {
+                        code,
+                        path: site.path,
+                        reason: directive.reason,
+                        site,
+                        mechanism: "inline",
+                    };
+                    if (declared.length === 0) {
+                        records.push({ ...base, symbol: "", bound: "" });
+                    }
+                    for (const one of declared) {
+                        records.push({ ...base, symbol: one.ref, bound: one.id });
+                    }
+                }
+                break;
+            }
+        }
+    }
+    return { records, refusals };
+}

package/dist/src/suppress.js

@@ -0,0 +1,148 @@
+/**
+ * The suppression grammar's records, and the ledger that decides what each one did. A
+ * record is one code bound to one site with its reason, from an inline directive, an
+ * ignore entry or a baseline row. A bound record marks its declaration live before the
+ * sweep, and is in effect when it withholds the finding its code would have produced
+ * there, dormant when the configuration withholds that finding anyway, and stale otherwise.
+ */
+import { ConfigError } from "./config.js";
+import { positionKey } from "./position.js";
+import { isRef } from "./ref.js";
+/** The code a suppression that carries no reason is reported under. */
+export const SUPPRESSION_WITHOUT_REASON = "DS1701";
+/** The code an ignore entry or a baseline row that names no path is reported under. */
+export const UNSCOPED_ENTRY = "DS1702";
+/** The code a suppression that withholds nothing is reported under. */
+export const STALE_SUPPRESSION = "DS1703";
+/** A target that carries no suppression. */
+export const NO_SUPPRESSIONS = { records: [], refusals: [] };
+/**
+ * A directive, an entry or a document the grammar refuses before any finding exists: an
+ * instruction the analysis cannot carry out. It is a malformed input, so the command line
+ * answers it with the usage code.
+ */
+export class SuppressionError extends ConfigError {
+    constructor(mechanism, at, text, want) {
+        super("malformed", at, `${mechanism} ${at}: ${text}: want ${want}`);
+        this.name = "SuppressionError";
+    }
+}
+/** Where a position is written, as an error names it. */
+export function siteText(site) {
+    return site.line > 0 ? positionKey(site) : site.path;
+}
+/** An issue-kind code: `DS` and four digits. */
+export const CODE_FORM = /^DS[0-9]{4}$/u;
+/**
+ * A path inside the target: relative to the target root, the solidus as separator, no
+ * leading `./`, no trailing solidus, no `.` or `..` segment, never absolute.
+ */
+export const PATH_EXPRESSION = String.raw `^(?:[^/\\.\r\n][^/\\\r\n]*|\.[^/\\.\r\n][^/\\\r\n]*|\.\.[^/\\\r\n]+)(?:/(?:[^/\\.\r\n][^/\\\r\n]*|\.[^/\\.\r\n][^/\\\r\n]*|\.\.[^/\\\r\n]+))*$`;
+const PATH_FORM = new RegExp(PATH_EXPRESSION, "u");
+/** Whether one value is a path in the form an entry's `path` takes. */
+export function isEntryPath(value) {
+    return PATH_FORM.test(value);
+}
+const GO_IDENT = String.raw `(?:[A-Za-z_]|[^\x00-\x7F])(?:[A-Za-z0-9_]|[^\x00-\x7F])*`;
+const GO_PATH = String.raw `[A-Za-z0-9._~-]+(?:/[A-Za-z0-9._~-]+)*`;
+const GO_VERSION = String.raw `[A-Za-z0-9.+-]+`;
+const GO_FILE = String.raw `[^/\\:#\r\n]+\.go`;
+/**
+ * The reference forms of the Go analyzer's grammar. One target holds one ignore file,
+ * whose entries may name a symbol of either language, so an entry naming a Go symbol is
+ * well formed here and binds nothing.
+ */
+export const GO_REF_EXPRESSIONS = [
+    `^go://${GO_PATH}#$`,
+    `^go://${GO_PATH}#${GO_IDENT}$`,
+    `^go://${GO_PATH}#${GO_IDENT}(?:\\.${GO_IDENT})+$`,
+    `^go://${GO_PATH}#${GO_IDENT}(?:\\.${GO_IDENT})?\\[${GO_IDENT}\\]$`,
+    `^go://${GO_PATH}#${GO_FILE}:file$`,
+    `^go://${GO_PATH}#${GO_PATH}(?:@${GO_VERSION})?:require$`,
+    `^go://${GO_PATH}#${GO_PATH}(?:@${GO_VERSION})?:replace$`,
+];
+const GO_REF_FORMS = GO_REF_EXPRESSIONS.map((expression) => new RegExp(expression, "u"));
+/** Whether one value is a stable symbol reference of either language's grammar. */
+export function isSymbolRef(value) {
+    return isRef(value) || GO_REF_FORMS.some((form) => form.test(value));
+}
+/** Whether a reason is absent, empty or whitespace only, which the grammar reads as none. */
+export function blankReason(reason) {
+    return reason === undefined || /^[ \t\r\n]*$/u.test(reason);
+}
+/**
+ * The subject kinds that are a row of a document rather than a declaration of the program.
+ * A record binds to a declaration, so nothing withholds a finding about one.
+ */
+const ROW_SUBJECTS = new Set([
+    "file",
+    "dependency",
+    "module-directive",
+    "root",
+    "suppression",
+    "edge",
+]);
+/** Whether a finding's subject is a row of a document, which no record can withhold. */
+export function isRowSubject(kind) {
+    return ROW_SUBJECTS.has(kind);
+}
+/** One finding's identity: its code and the position of the thing it names. */
+function claimKey(finding) {
+    return `${finding.code}\u0000${positionKey(finding.position)}`;
+}
+/**
+ * Whether one record names one finding. A record reaches a finding in two ways: it bound
+ * the declaration at the finding's position, or it names the finding's reference and the
+ * file the finding is reported in, each exactly. The second is how an entry copied from a
+ * finding about a part of a declaration reaches the part.
+ */
+export function pairs(record, finding) {
+    if (record.code !== finding.code || ROW_SUBJECTS.has(finding.symbol.kind)) {
+        return false;
+    }
+    if (record.bound !== "" && record.bound === positionKey(finding.position)) {
+        return true;
+    }
+    return record.symbol === finding.symbol.ref && record.path === finding.position.path;
+}
+/**
+ * Decides every record against `would`, the findings the run would produce were no record
+ * there: swept with no mark, where a kind about liveness reports the marked declaration,
+ * and as swept, where a kind whose subject the sweep holds live reports it. The first
+ * record in reading order claims a finding, so a second naming it is stale. A record whose
+ * code the dials withhold from its declaration, or whose claimed finding they withhold, is
+ * dormant.
+ */
+export function ledgerOf(records, would, dials) {
+    const taken = new Set();
+    const verdicts = [];
+    const claims = [];
+    for (const record of records) {
+        if (record.bound !== "" && dials.withholdsCode(record.code, record.bound)) {
+            verdicts.push("dormant");
+            claims.push(undefined);
+            continue;
+        }
+        const claimed = would.find((finding) => !taken.has(claimKey(finding)) && pairs(record, finding));
+        claims.push(claimed);
+        if (claimed === undefined) {
+            verdicts.push("stale");
+            continue;
+        }
+        taken.add(claimKey(claimed));
+        verdicts.push(dials.withholds(claimed) ? "dormant" : "in-effect");
+    }
+    return {
+        verdicts,
+        claims,
+        withheld: (finding) => taken.has(claimKey(finding)) && !ROW_SUBJECTS.has(finding.symbol.kind),
+    };
+}
+/** The suppression counts of one run's records and the ledger over them. */
+export function suppressionCounts(records, ledger) {
+    const sites = new Set(records.map((record) => `${record.mechanism}\u0000${positionKey(record.site)}`));
+    return {
+        inEffect: ledger.verdicts.filter((verdict) => verdict === "in-effect").length,
+        reasonsRecorded: sites.size,
+    };
+}

package/dist/src/verbs/analyze.js

@@ -0,0 +1,184 @@
+import { runAnalysis } from "../analysis.js";
+import { ConfigError } from "../config.js";
+import { RECORDED_CONFORMANCE, reportedConformance } from "../conformance.js";
+import { analyzerProvenance, recordedFindings, verdictOf } from "../findings-pass.js";
+import { packageScope } from "../inventory.js";
+import { normalizePath, relativePath, resolvePath } from "../paths.js";
+import { buildReport, capFindings, sortFindings, } from "../report.js";
+import { json } from "../reporters/json.js";
+import { RENDERINGS } from "../reporters/reporters.js";
+import { resolve } from "../resolve.js";
+import { writeBaseline } from "../suppress-file.js";
+import { CONTRACT_VERSION } from "../version.js";
+import { EXIT_CLEAN, EXIT_FAILURE } from "./verb.js";
+/** The options `analyze` takes beside the ones every verb takes. */
+export const ANALYZE_OPTIONS = {
+    plain: ["report", "baseline-write", "exit-code"],
+    repeatable: ["format"],
+};
+/** 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";
+/** Why a declared consumer is not loaded, which every report names it with. */
+const NOT_LOADED = "this analyzer loads no consumer beside the target";
+/** 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(", ");
+}
+/** The renderings one invocation writes: the ones it named, else the configuration's. */
+function formatsOf(named, configured) {
+    const formats = named.length > 0 ? 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()}`);
+        }
+        if (seen.has(format)) {
+            throw new ConfigError("malformed", "", `the format ${JSON.stringify(format)} is named twice`);
+        }
+        seen.add(format);
+    }
+    return formats;
+}
+/**
+ * One directory of the run below the directory the run was invoked from, as a report names
+ * it. A report admits that directory and every path below it and none that climbs out, so a
+ * target elsewhere has no spelling a report can carry and fails the run.
+ */
+function runRelative(invoked, path) {
+    if (normalizePath(invoked) === normalizePath(path)) {
+        return ".";
+    }
+    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`);
+    }
+    return below;
+}
+/** Each project of the run as a report names it, by its configuration file below the target. */
+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`);
+        }
+        return { id: one.id, project };
+    });
+}
+/** The name one module publishes itself under: the scope's, else its manifest's. */
+function identityOf(module, host) {
+    return module.id === "" ? packageScope(host, module.path)("index.ts").package : module.id;
+}
+/** 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"}`;
+}
+/**
+ * Analyzes the scope under the configuration and writes the JSON report to the path
+ * `--report` names, each rendering `--format` names beside it at the report's path with the
+ * format's suffix appended, and a baseline of every finding where `--baseline-write` names a
+ * path. Nothing is written to the output stream; diagnostics go to the error stream and the
+ * verdict is the exit code, or 0 under `--exit-code=off`.
+ */
+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");
+    }
+    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}`);
+    }
+    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 = {
+        report: resolvePath(invoked, reportPath),
+        formats: formatsOf(repeated("format"), config.reporters.formats),
+        baseline: baseline === undefined ? undefined : resolvePath(invoked, baseline),
+    };
+    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;
+    let recorded;
+    let verdict;
+    try {
+        const root = runRelative(invoked, targetRoot);
+        const { result, run } = runAnalysis(openClient(false), host, scoped, config, provenance, {
+            production: true,
+        });
+        const built = buildReport({
+            contractVersion: CONTRACT_VERSION,
+            version,
+            conformance: reportedConformance(RECORDED_CONFORMANCE),
+            target: { kind, root, identity: identityOf(scoped.target, host) },
+            configurations: configurationsOf(run.projects, targetRoot),
+            unavailable: scoped.consumers.map((consumer) => ({
+                id: identityOf(consumer, host),
+                reason: NOT_LOADED,
+            })),
+            result,
+            testFileRules: run.testFileRules,
+        });
+        // The baseline records every finding, so its rows are taken before the cap bounds what
+        // a rendering prints: a baseline missing a reported finding fails the next run on it.
+        recorded = recordedFindings(result);
+        report = capFindings(sortFindings(built, config.reporters.sort), config.reporters.maxFindings);
+        verdict = verdictOf(result, config);
+    }
+    catch (error) {
+        if (!(error instanceof ReportPathError)) {
+            throw error;
+        }
+        err.write(`deadset-ts: ${error.message}\n`);
+        return EXIT_FAILURE;
+    }
+    try {
+        host.writeFile(documents.report, json(report));
+        for (const format of documents.formats) {
+            const rendering = RENDERINGS.get(format);
+            if (rendering !== undefined) {
+                host.writeFile(documents.report + rendering.suffix, rendering.render(report));
+            }
+        }
+        if (documents.baseline !== undefined) {
+            host.writeFile(documents.baseline, writeBaseline(recorded, analyzerProvenance(version)));
+        }
+    }
+    catch (error) {
+        err.write(`deadset-ts: ${error instanceof Error ? error.message : String(error)}\n`);
+        return EXIT_FAILURE;
+    }
+    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`);
+    }
+    if (report.totals.stale_suppressions > 0) {
+        err.write(`deadset-ts: ${counted(report.totals.stale_suppressions, "stale suppression")}\n`);
+    }
+    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`);
+        }
+        return EXIT_CLEAN;
+    }
+    return verdict;
+};

package/dist/src/verbs/describe.js

@@ -0,0 +1,45 @@
+import { RECORDED_CONFORMANCE } from "../conformance.js";
+import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSION } from "../report.js";
+import { CONTRACT_VERSION } from "../version.js";
+import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE } from "./verb.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
+ * the conformance corpus, absent where it records none.
+ */
+export function describeDocument(version, recorded) {
+    const document = {
+        name: ANALYZER_NAME,
+        version,
+        contract_version: CONTRACT_VERSION,
+        schema_versions_accepted: [SCHEMA_VERSION],
+        languages: [LANGUAGE],
+        ...(recorded === undefined
+            ? {}
+            : {
+                conformance: {
+                    corpus_version: recorded.corpusVersion,
+                    result: recorded.result,
+                    digest: recorded.digest,
+                },
+            }),
+    };
+    return `${JSON.stringify(document, null, 2)}\n`;
+}
+/** Writes this analyzer's description to the output stream, and nothing to the error 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`);
+        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, RECORDED_CONFORMANCE));
+    return EXIT_CLEAN;
+};

package/jsr.json

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

package/package.json

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