@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.21

package/dist/src/verbs/analyze.js

@@ -1,36 +1,36 @@
-import { runAnalysis, runBaselineWrite, unansweredCounts, } from "../analysis.js";
-import { ConfigError, kindOf } from "../config.js";
+import { CONTRACT_VERSION, EXIT_CLEAN } from "../contract/contract.generated.js";
+import { productionMode, runAnalysis, runBaselineWrite, unansweredCounts, } from "../analysis.js";
+import { kindOf } from "../config.js";
 import { CONFORMANCE, DECLARED_GAPS } from "../conformance.js";
-import { moduleIdentity } from "../consumers.js";
 import { analyzerProvenance, verdictOf } from "../findings-pass.js";
-import { joinPath, normalizePath, relativePath, resolvePath } from "../paths.js";
+import { factsDocument } from "../facts.js";
+import { dirnamePath, joinPath, normalizePath, relativePath, resolvePath } from "../paths.js";
+import { moduleIdentity } from "../load/discover.js";
 import { partialNotes } from "../partial.js";
-import { buildReport, LANGUAGE, capFindings, sortFindings, } from "../report.js";
+import { buildReport, capFindings, sortFindings, } from "../report.js";
+import { reportRefusals } from "../report-schema.js";
 import { json } from "../reporters/json.js";
 import { RENDERINGS } from "../reporters/reporters.js";
 import { parseTemplate, TemplateError } from "../reporters/template.js";
 import { resolve } from "../resolve.js";
 import { otherSchemeRows, rowReason, writeBaseline } from "../suppress-file.js";
-import { CONTRACT_VERSION } from "../version.js";
-import { EXIT_CLEAN, EXIT_FAILURE } from "./verb.js";
+import {} from "./verb.js";
+import { UsageError } from "../usage.js";
+import { bytewise } from "../text/compare.js";
+import { productFault, failureExit } from "../failure.js";
+import { diagnose, message } from "../product.js";
+import { ownVersion } from "./version.js";
 /** The options `analyze` takes beside the ones every verb takes. */
 export const ANALYZE_OPTIONS = {
-    plain: ["report", "baseline-write", "exit-code", "template"],
+    plain: ["report", "facts", "baseline-write", "exit-code", "template"],
     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";
-/** A path of the run no report can name, which ends the run with the failure code. */
-class ReportPathError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "ReportPathError";
-    }
-}
 /** The formats this analyzer renders, for a message that names them. */
 function formatNames() {
-    return [...RENDERINGS.keys()].sort().join(", ");
+    return [...RENDERINGS.keys()].sort(bytewise).join(", ");
 }
 /** The renderings one invocation writes: the ones it named, else the configuration's. */
 function formatsOf(named, configured) {
@@ -38,10 +38,10 @@ function formatsOf(named, configured) {
     const seen = new Set();
     for (const format of formats) {
         if (!RENDERINGS.has(format)) {
-            throw new ConfigError("malformed", "", `${JSON.stringify(format)} is not a format this analyzer renders: the formats are ${formatNames()}`);
+            throw new UsageError(`${JSON.stringify(format)} is not a format this analyzer renders: the formats are ${formatNames()}`);
         }
         if (seen.has(format)) {
-            throw new ConfigError("malformed", "", `the format ${JSON.stringify(format)} is named twice`);
+            throw new UsageError(`the format ${JSON.stringify(format)} is named twice`);
         }
         seen.add(format);
     }
@@ -58,7 +58,7 @@ function runRelative(invoked, path) {
     }
     const below = relativePath(invoked, path);
     if (below === undefined) {
-        throw new ReportPathError(`a report names its target relative to the directory the run was invoked from, and ${invoked} does not contain ${path}: run from a directory that does`);
+        throw failureExit("unreportable-path", `a report names its target relative to the directory the run was invoked from, and ${invoked} does not contain ${path}: run from a directory that does`);
     }
     return below;
 }
@@ -77,12 +77,76 @@ function unmappedNotes(entries, targetRoot) {
         };
     });
 }
+/**
+ * One note per load of a production file the run cannot resolve, each site once: a file
+ * it loads is a root the run does not see, so `ts.roots_complete` lifts no cap there.
+ */
+function unseenLoadNotes(loads) {
+    return [
+        ...new Map(loads.map((load) => {
+            const { path, line, column } = load.position;
+            const site = `${path}:${String(line)}:${String(column)}`;
+            const note = {
+                kind: "computed-load",
+                path: dirnamePath(path),
+                message: `${site} loads a module by a computed path the analysis cannot resolve, so the configurations compiling it report what no root reaches at probable at most, whatever ts.roots_complete says`,
+            };
+            return [site, note];
+        })).values(),
+    ];
+}
+/** One note per package whose command strings name files a configuration holds, naming every such file. */
+function heldScriptNotes(held, targetRoot) {
+    const files = new Map();
+    const unwritten = new Set();
+    for (const one of held) {
+        files.set(one.dir, new Set([...(files.get(one.dir) ?? []), ...one.files]));
+        if (one.unwritten) {
+            unwritten.add(one.dir);
+        }
+    }
+    return [...files].map(([dir, paths]) => ({
+        kind: "unread-command",
+        path: relativePath(targetRoot, dir) ?? ".",
+        message: [
+            ...(paths.size === 0
+                ? []
+                : [
+                    `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"}`,
+                ]),
+            ...(unwritten.has(dir)
+                ? [
+                    "a command runs a file whose path no word of it writes, so a finding that a file of the package is never built or never imported is possible at most",
+                ]
+                : []),
+        ].join("; "),
+    }));
+}
+function unresolvedNotes(specifiers) {
+    return specifiers.map(({ specifier, position }) => ({
+        kind: "unresolved-specifier",
+        path: dirnamePath(position.path),
+        message: `${position.path}:${String(position.line)}:${String(position.column)} loads ${JSON.stringify(specifier)}, which resolves to no file, so it references nothing`,
+    }));
+}
+function unreadLine(input, targetRoot) {
+    switch (input.kind) {
+        case "manifest": {
+            const path = relativePath(targetRoot, input.manifest) ?? input.manifest;
+            return input.reason === undefined
+                ? `${path} does not parse, so the manifest facts of the program formed for its package are unanswered: correct the manifest`
+                : `${path} cannot be read, so the manifest facts of the program formed for its package are unanswered: give the run read access to it: ${input.reason}`;
+        }
+        case "ignore-file":
+            return `${relativePath(targetRoot, input.path) ?? input.path} cannot be read, so the JavaScript files it would ignore are analyzed: ${input.reason}`;
+    }
+}
 /** Each project the run dropped as a report names it, by its configuration file below the target. */
 function notBuiltOf(dropped, targetRoot) {
     return dropped.map((one) => {
         const project = relativePath(targetRoot, one.configFile);
         if (project === undefined) {
-            throw new ReportPathError(`the project ${one.id} would be opened from ${one.configFile}, which is not below the target ${targetRoot}, so no report can name it`);
+            throw failureExit("unreportable-path", `the project ${one.id} would be opened from ${one.configFile}, which is not below the target ${targetRoot}, so no report can name it: analyze a target that holds it`);
         }
         return { id: one.id, project, error: one.error };
     });
@@ -92,11 +156,24 @@ function configurationsOf(projects, targetRoot) {
     return projects.map((one) => {
         const project = relativePath(targetRoot, one.configFile);
         if (project === undefined) {
-            throw new ReportPathError(`the project ${one.id} is opened from ${one.configFile}, which is not below the target ${targetRoot}, so no report can name it`);
+            throw failureExit("unreportable-path", `the project ${one.id} is opened from ${one.configFile}, which is not below the target ${targetRoot}, so no report can name it: analyze a target that holds it`);
         }
         return { id: one.id, project };
     });
 }
+/**
+ * Writes one document the run was asked for. A document that cannot be produced or written
+ * ends the run with the run failure that names it and `fix`, the documents written before it
+ * kept.
+ */
+function writeDocument(host, path, fix, produce) {
+    try {
+        host.writeDocument(path, produce());
+    }
+    catch (error) {
+        throw failureExit("unwritten-output", `${path}: ${message(error)}: ${fix}`);
+    }
+}
 /** A count with its noun, so a message reads for one record as well as for several. */
 function counted(n, noun) {
     return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
@@ -109,7 +186,7 @@ function counted(n, noun) {
 function templateOf(host, invoked, named, formats) {
     if (named === undefined || named === "") {
         if (formats.includes("template")) {
-            throw new ConfigError("malformed", "", "the template format renders the template --template names, and none was named");
+            throw new UsageError("the template format renders the template --template names, and none was named");
         }
         return undefined;
     }
@@ -118,7 +195,7 @@ function templateOf(host, invoked, named, formats) {
         source = host.readFile(resolvePath(invoked, named));
     }
     catch (error) {
-        throw new ConfigError("malformed", "", `--template=${named}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new UsageError(`--template=${named}: ${message(error)}`);
     }
     try {
         return parseTemplate(source);
@@ -127,7 +204,7 @@ function templateOf(host, invoked, named, formats) {
         if (!(error instanceof TemplateError)) {
             throw error;
         }
-        throw new ConfigError("malformed", "", `--template=${named}: ${error.message}`);
+        throw new UsageError(`--template=${named}: ${error.message}`);
     }
 }
 /**
@@ -141,144 +218,134 @@ function templateOf(host, invoked, named, formats) {
 export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repeated }) => {
     const reportPath = option("report");
     if (reportPath === undefined || reportPath === "") {
-        throw new ConfigError("malformed", "", "analyze writes its report to the path --report names, and no path was named");
+        throw new UsageError("analyze writes its report to the path --report names, and no path was named");
     }
     const exitCode = option("exit-code") ?? EXIT_CODE_ON;
     if (exitCode !== EXIT_CODE_ON && exitCode !== EXIT_CODE_OFF) {
-        throw new ConfigError("malformed", "", `--exit-code=${JSON.stringify(exitCode)}: the values are ${EXIT_CODE_ON} and ${EXIT_CODE_OFF}`);
+        throw new UsageError(`--exit-code=${JSON.stringify(exitCode)}: the values are ${EXIT_CODE_ON} and ${EXIT_CODE_OFF}`);
     }
     const { config, provenance } = resolve(inputs());
-    const kind = config.targetKind;
-    if (kind === "") {
-        throw new ConfigError("missing-target-kind", "target.kind", "target.kind is not set");
-    }
     const invoked = host.workingDirectory();
     const baseline = option("baseline-write");
+    const facts = option("facts");
+    if (facts === "") {
+        throw new UsageError("--facts names the path the facts document is written to, and named none");
+    }
     const documents = {
         report: resolvePath(invoked, reportPath),
+        facts: facts === undefined ? undefined : resolvePath(invoked, facts),
         formats: formatsOf(repeated("format"), config.reporters.formats),
         baseline: baseline === undefined ? undefined : resolvePath(invoked, baseline),
     };
     const template = templateOf(host, invoked, option("template"), documents.formats);
     const scoped = scope();
     const targetRoot = scoped.target.path;
-    let version;
-    try {
-        version = host.analyzerVersion();
+    const version = ownVersion(host);
+    let recorded;
+    const root = runRelative(invoked, targetRoot);
+    const mode = productionMode(config);
+    let analysis;
+    if (documents.baseline === undefined) {
+        analysis = runAnalysis(openClient(config), host, scoped, config, provenance, mode);
+        recorded = [];
     }
-    catch (error) {
-        err.write(`deadset-ts: ${error instanceof Error ? error.message : String(error)}\n`);
-        return EXIT_FAILURE;
+    else {
+        const reason = rowReason(analyzerProvenance(version));
+        const write = runBaselineWrite(openClient(config), host, scoped, config, provenance, mode, reason);
+        analysis = write.first;
+        recorded = write.rows;
     }
-    let report;
-    let recorded;
-    let verdict;
-    let partial;
-    let warnings;
-    let unread;
-    let unfound;
-    try {
-        const root = runRelative(invoked, targetRoot);
-        const mode = { production: true };
-        let analysis;
-        if (documents.baseline === undefined) {
-            analysis = runAnalysis(openClient(config), host, scoped, config, provenance, mode);
-            recorded = [];
-        }
-        else {
-            const reason = rowReason(analyzerProvenance(version));
-            const write = runBaselineWrite(openClient(config), host, scoped, config, provenance, mode, reason);
-            analysis = write.first;
-            recorded = write.rows;
-        }
-        const { result, run } = analysis;
-        warnings = run.componentWarnings;
-        unread = run.componentsUnread.map(({ configFile, reason }) => `${relativePath(resolvePath(invoked, targetRoot), configFile) ?? configFile}: its component files are not read: ${reason}`);
-        unfound = run.librariesUnfound.map(({ configFile, error }) => `${relativePath(resolvePath(invoked, targetRoot), configFile) ?? configFile}: ${error}: the configuration is analyzed without that library`);
-        partial = partialNotes({
-            notBuilt: run.notBuilt,
-            unanswered: run.unanswered,
-            targetRoot: resolvePath(invoked, targetRoot),
-        });
-        const built = buildReport({
-            contractVersion: CONTRACT_VERSION,
-            version,
-            conformance: CONFORMANCE,
-            declaredGaps: DECLARED_GAPS,
-            target: {
-                kind: kindOf(kind, LANGUAGE),
-                root,
-                identity: moduleIdentity(host, scoped.target),
-            },
-            configurations: configurationsOf(run.projects, targetRoot),
-            notBuilt: notBuiltOf(run.notBuilt, targetRoot),
-            loaded: run.consumers.map((consumer) => ({
-                id: consumer.id,
-                path: runRelative(invoked, consumer.path),
-            })),
-            unavailable: [],
-            result,
-            testFileRules: run.testFileRules,
-            typeErrorSkips: run.typeErrorSkips,
-            unanswered: unansweredCounts(analysis),
-            conventionsApplied: run.conventionsApplied,
-            notes: unmappedNotes(run.unmappedEntries, resolvePath(invoked, targetRoot)),
-        });
-        report = capFindings(sortFindings(built, config.reporters.sort), config.reporters.maxFindings);
-        verdict = verdictOf(result, config);
+    const { result, run } = analysis;
+    const warnings = run.componentWarnings;
+    const unread = run.componentsUnread.map(({ configFile, reason }) => `${relativePath(resolvePath(invoked, targetRoot), configFile) ?? configFile}: its component files are not read: ${reason}`);
+    const unfound = run.librariesUnfound.map(({ configFile, error }) => `${relativePath(resolvePath(invoked, targetRoot), configFile) ?? configFile}: ${error}: the configuration is analyzed without that library`);
+    const unreadInputs = run.unread.map((one) => unreadLine(one, resolvePath(invoked, targetRoot)));
+    const partial = partialNotes({
+        notBuilt: run.notBuilt,
+        unanswered: run.unanswered,
+        targetRoot: resolvePath(invoked, targetRoot),
+    });
+    const built = buildReport({
+        contractVersion: CONTRACT_VERSION,
+        version,
+        conformance: CONFORMANCE,
+        declaredGaps: DECLARED_GAPS,
+        target: {
+            kind: kindOf(config.target.kind),
+            root,
+            identity: moduleIdentity(host, scoped.target),
+        },
+        configurations: configurationsOf(run.projects, targetRoot),
+        notBuilt: notBuiltOf(run.notBuilt, targetRoot),
+        loaded: run.consumers.map((consumer) => ({
+            id: consumer.id,
+            path: runRelative(invoked, consumer.path),
+        })),
+        unavailable: [],
+        result,
+        testFileRules: run.testFileRules,
+        typeErrorSkips: run.typeErrorSkips,
+        unanswered: unansweredCounts(analysis),
+        conventionsApplied: run.conventionsApplied,
+        listsComponents: config.reporters.cascade === "full",
+        notes: [
+            ...unmappedNotes(run.unmappedEntries, resolvePath(invoked, targetRoot)),
+            ...unseenLoadNotes(run.unseenLoads),
+            ...unresolvedNotes(run.unresolvedSpecifiers),
+            ...heldScriptNotes(run.heldScripts, resolvePath(invoked, targetRoot)),
+        ],
+    });
+    const report = capFindings(sortFindings(built, config.reporters.sort), config.reporters.max_findings);
+    const verdict = verdictOf(result, config);
+    const [refused] = reportRefusals(report);
+    if (refused !== undefined) {
+        throw productFault(`built a report that breaks the report schema at ${refused.pointer || "the document"}: ${refused.keyword}: ${refused.reason}`);
     }
-    catch (error) {
-        if (!(error instanceof ReportPathError)) {
-            throw error;
-        }
-        err.write(`deadset-ts: ${error.message}\n`);
-        return EXIT_FAILURE;
+    writeDocument(host, documents.report, "name a path the run can write", () => json(report));
+    const factsPath = documents.facts;
+    if (factsPath !== undefined) {
+        writeDocument(host, factsPath, "name a path the run can write", () => [
+            factsDocument(version, run.generated, run.bindings),
+        ]);
     }
-    try {
-        host.writeDocument(documents.report, json(report));
-        const options = {
-            failOn: config.reporters.failOn,
-            readSource: (path) => host.readFile(joinPath(targetRoot, path)),
-            template,
-        };
-        for (const format of documents.formats) {
-            const rendering = RENDERINGS.get(format);
-            if (rendering !== undefined) {
-                host.writeDocument(documents.report + rendering.suffix, rendering.render(report, options));
-            }
-        }
-        if (documents.baseline !== undefined) {
-            const kept = host.kindOf(documents.baseline) === "file"
-                ? otherSchemeRows(host.readFile(documents.baseline))
-                : [];
-            host.writeDocument(documents.baseline, writeBaseline(recorded, analyzerProvenance(version), kept));
+    const options = {
+        readSource: (path) => host.readFile(joinPath(targetRoot, path)),
+        template,
+    };
+    for (const format of documents.formats) {
+        const rendering = RENDERINGS.get(format);
+        if (rendering !== undefined) {
+            writeDocument(host, documents.report + rendering.suffix, "name a path the run can write, or correct the template that renders it", () => rendering.render(report, options));
         }
     }
-    catch (error) {
-        err.write(`deadset-ts: ${error instanceof Error ? error.message : String(error)}\n`);
-        return EXIT_FAILURE;
+    const baselinePath = documents.baseline;
+    if (baselinePath !== undefined) {
+        writeDocument(host, baselinePath, "name a path the run can write, or repair the rows of the baseline the run would keep", () => {
+            const kept = host.kindOf(baselinePath) === "file" ? otherSchemeRows(host.readFile(baselinePath)) : [];
+            return writeBaseline(recorded, analyzerProvenance(version), kept);
+        });
     }
     for (const note of partial) {
-        err.write(`deadset-ts: ${note}\n`);
+        diagnose(err, note);
     }
-    for (const line of [...unread, ...unfound]) {
-        err.write(`deadset-ts: ${line}\n`);
+    for (const line of [...unread, ...unfound, ...unreadInputs]) {
+        diagnose(err, line);
     }
     for (const warning of warnings) {
-        err.write(`deadset-ts: ${warning.path}:${String(warning.line)}: a <script> start tag that begins a line is not read as a block: ${warning.reason}\n`);
+        diagnose(err, `${warning.path}:${String(warning.line)}: a <script> start tag that begins a line is not read as a block: ${warning.reason}`);
     }
     for (const skip of report.type_error_skips) {
-        err.write(`deadset-ts: ${skip.path}:${String(skip.line)}: ${skip.message}: the function or statement holding this type error is not evaluated\n`);
+        diagnose(err, `${skip.path}:${String(skip.line)}: ${skip.message}: the function or statement holding this type error is not evaluated`);
     }
     if (report.totals.pending > 0) {
-        err.write(`deadset-ts: ${counted(report.totals.pending, "pending finding")}: the report names a declared cross-language edge, and no merge has resolved it\n`);
+        diagnose(err, `${counted(report.totals.pending, "pending finding")}: the report names a declared cross-language edge, and no merge has resolved it`);
     }
     if (report.totals.stale_suppressions > 0) {
-        err.write(`deadset-ts: ${counted(report.totals.stale_suppressions, "stale suppression")}\n`);
+        diagnose(err, counted(report.totals.stale_suppressions, "stale suppression"));
     }
     if (exitCode === EXIT_CODE_OFF) {
         if (verdict !== EXIT_CLEAN) {
-            err.write(`deadset-ts: the exit code is configured off: the verdict of this run is ${String(verdict)}\n`);
+            diagnose(err, `the exit code is configured off: the verdict of this run is ${String(verdict)}`);
         }
         return EXIT_CLEAN;
     }

package/dist/src/verbs/describe.js

@@ -1,19 +1,22 @@
+import { CONTRACT_VERSION, EXIT_CLEAN, EXIT_USAGE, FACTS_VERSION, SCHEMA_VERSIONS, } from "../contract/contract.generated.js";
 import { CONFORMANCE } from "../conformance.js";
-import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSIONS_ACCEPTED } from "../report.js";
-import { CONTRACT_VERSION } from "../version.js";
-import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE } from "./verb.js";
+import {} from "./verb.js";
+import { diagnose, LANGUAGE, PRODUCT } from "../product.js";
+import { ownVersion } from "./version.js";
 /**
  * The document `describe` writes: the analyzer, the Contract version it implements, the
- * report schema versions it reads, the languages it claims, and its recorded result over
- * the conformance corpus, a member the document omits where no run is recorded.
+ * report schema versions it reads, the languages it claims, the facts version it writes,
+ * and its recorded result over the conformance corpus, a member the document omits where
+ * no run is recorded.
  */
 export function describeDocument(version, recorded) {
     const document = {
-        name: ANALYZER_NAME,
+        name: PRODUCT,
         version,
         contract_version: CONTRACT_VERSION,
-        schema_versions_accepted: SCHEMA_VERSIONS_ACCEPTED,
+        schema_versions_accepted: SCHEMA_VERSIONS,
         languages: [LANGUAGE],
+        facts_version_written: FACTS_VERSION,
         ...(recorded === undefined
             ? {}
             : {
@@ -26,20 +29,12 @@ export function describeDocument(version, recorded) {
     };
     return `${JSON.stringify(document, null, 2)}\n`;
 }
-/** Writes this analyzer's description to the output stream, and nothing to the error stream. */
+/** Writes this analyzer's description to the output stream. */
 export const describeVerb = ({ out, err, host, args }) => {
     if (args.length > 0) {
-        err.write(`deadset-ts: describe takes no argument, got ${JSON.stringify(args[0])}\n`);
+        diagnose(err, `describe takes no argument, got ${JSON.stringify(args[0])}`);
         return EXIT_USAGE;
     }
-    let version;
-    try {
-        version = host.analyzerVersion();
-    }
-    catch (error) {
-        err.write(`deadset-ts: describe: ${error instanceof Error ? error.message : String(error)}\n`);
-        return EXIT_FAILURE;
-    }
-    out.write(describeDocument(version, CONFORMANCE));
+    out.write(describeDocument(ownVersion(host), CONFORMANCE));
     return EXIT_CLEAN;
 };