@cplieger/deadset-ts 3.8.0 → 3.9.0

package/src/run.ts

@@ -9,7 +9,9 @@ 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 { ANALYZE_OPTIONS, analyzeVerb } from "./verbs/analyze.ts";
+import { describeVerb } from "./verbs/describe.ts";
+import { EXIT_FAILURE, EXIT_USAGE, type Verb, type VerbOptions } from "./verbs/verb.ts";
 import { versionVerb } from "./verbs/version.ts";
 
 /** One output stream of the command line. `process.stdout` and `process.stderr` satisfy it. */
@@ -21,14 +23,18 @@ export interface Writer {
  * 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" },
+const VERBS: readonly {
+  readonly name: string;
+  readonly run?: Verb;
+  readonly options?: VerbOptions;
+}[] = [
+  { name: "analyze", run: analyzeVerb, options: ANALYZE_OPTIONS },
   { 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: "describe", run: describeVerb },
   { name: "version", run: versionVerb },
 ];
 
@@ -69,11 +75,15 @@ const INTEGER_OPTIONS: ReadonlySet<string> = new Set(["max-findings"]);
 /** An integer as an option writes it: an optional minus sign and digits alone. */
 const INTEGER_TEXT = /^-?[0-9]+$/u;
 
-/** One invocation's options, by name, with the verb's remaining arguments. */
+/** One invocation's options, by name: the last value of each, and every value of a repeatable one. */
 interface Options {
   readonly named: ReadonlyMap<string, string>;
+  readonly repeated: ReadonlyMap<string, readonly string[]>;
 }
 
+/** No option beyond the ones every verb takes. */
+const NO_OPTIONS: VerbOptions = { plain: [], repeatable: [] };
+
 /**
  * The first option whose name carries a source-edit token, because every verb
  * reports and never edits. The match is on the name alone, so an option whose
@@ -93,16 +103,22 @@ function sourceEditOption(args: readonly string[]): string | undefined {
   return undefined;
 }
 
-/** Reads one verb's options, refusing a name this command does not offer. */
-function readOptions(args: readonly string[]): Options {
+/** Reads one verb's options, refusing a name neither this command nor the verb offers. */
+function readOptions(args: readonly string[], own: VerbOptions): Options {
   const named = new Map<string, string>();
+  const repeated = new Map<string, string[]>();
   for (const arg of args) {
     if (!arg.startsWith("-")) {
       throw new ConfigError("malformed", "", `unexpected argument ${JSON.stringify(arg)}`);
     }
     const [spelled, ...rest] = arg.split("=");
     const name = (spelled ?? "").replace(/^-+/u, "");
-    if (!PLAIN_OPTIONS.has(name) && !SETTING_OPTIONS.has(name)) {
+    if (
+      !PLAIN_OPTIONS.has(name) &&
+      !SETTING_OPTIONS.has(name) &&
+      !own.plain.includes(name) &&
+      !own.repeatable.includes(name)
+    ) {
       throw new ConfigError("malformed", "", `unknown option ${JSON.stringify(spelled ?? arg)}`);
     }
     if (rest.length === 0) {
@@ -112,9 +128,11 @@ function readOptions(args: readonly string[]): Options {
         `option ${JSON.stringify(spelled ?? arg)} takes a value`,
       );
     }
-    named.set(name, rest.join("="));
+    const value = rest.join("=");
+    named.set(name, value);
+    repeated.set(name, [...(repeated.get(name) ?? []), value]);
   }
-  return { named };
+  return { named, repeated };
 }
 
 function readFileOr(host: Host, path: string, orUndefined: boolean): string | undefined {
@@ -202,7 +220,13 @@ export function run(
   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);
+    return invoke(
+      verb.run,
+      verb.options ?? NO_OPTIONS,
+      args.slice(1),
+      { out, err, host },
+      openClient,
+    );
   }
   if (verb !== undefined) {
     err.write(`deadset-ts: ${verb.name} is not implemented\n`);
@@ -222,18 +246,22 @@ export function run(
  */
 function invoke(
   verb: Verb,
+  own: VerbOptions,
   args: readonly string[],
   streams: { readonly out: Writer; readonly err: Writer; readonly host: Host },
   openClient: (collectTiming: boolean) => Engine,
 ): number {
   let options: Options | undefined;
-  const read = (): Options => (options ??= readOptions(args));
+  const read = (): Options => (options ??= readOptions(args, own));
   let opened: Engine | undefined;
   try {
     return verb({
       ...streams,
+      args,
       inputs: () => inputsOf(streams.host, read()),
       scope: () => scopeOf(streams.host, read()),
+      option: (name) => read().named.get(name),
+      repeated: (name) => read().repeated.get(name) ?? [],
       openClient: (collectTiming) => {
         opened = openClient(collectTiming);
         return opened;

package/src/verbs/analyze.ts

@@ -0,0 +1,234 @@
+import { runAnalysis, type RunProject } from "../analysis.ts";
+import { ConfigError, type Format } from "../config.ts";
+import { RECORDED_CONFORMANCE, reportedConformance } from "../conformance.ts";
+import { analyzerProvenance, recordedFindings, verdictOf } from "../findings-pass.ts";
+import { packageScope } from "../inventory.ts";
+import { normalizePath, relativePath, resolvePath } from "../paths.ts";
+import type { Host } from "../host.ts";
+import {
+  buildReport,
+  capFindings,
+  sortFindings,
+  type Report,
+  type ReportConfiguration,
+} from "../report.ts";
+import { json } from "../reporters/json.ts";
+import { RENDERINGS } from "../reporters/reporters.ts";
+import { resolve } from "../resolve.ts";
+import type { Module } from "../scope.ts";
+import { writeBaseline, type Recorded } from "../suppress-file.ts";
+import { CONTRACT_VERSION } from "../version.ts";
+import { EXIT_CLEAN, EXIT_FAILURE, type Verb, type VerbOptions } from "./verb.ts";
+
+/** The options `analyze` takes beside the ones every verb takes. */
+export const ANALYZE_OPTIONS: VerbOptions = {
+  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: string) {
+    super(message);
+    this.name = "ReportPathError";
+  }
+}
+
+/** The formats this analyzer renders, for a message that names them. */
+function formatNames(): string {
+  return [...RENDERINGS.keys()].sort().join(", ");
+}
+
+/** The renderings one invocation writes: the ones it named, else the configuration's. */
+function formatsOf(named: readonly string[], configured: readonly Format[]): readonly Format[] {
+  const formats = named.length > 0 ? named : configured;
+  const seen = new Set<string>();
+  for (const format of formats) {
+    if (!RENDERINGS.has(format as 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 as readonly Format[];
+}
+
+/**
+ * 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: string, path: string): string {
+  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: readonly RunProject[],
+  targetRoot: string,
+): readonly ReportConfiguration[] {
+  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: Module, host: Host): string {
+  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: number, noun: string): string {
+  return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
+}
+
+/** Every document one invocation asked for: the report, each rendering beside it, a baseline. */
+interface Documents {
+  readonly report: string;
+  readonly formats: readonly Format[];
+  readonly baseline: string | undefined;
+}
+
+/**
+ * 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: Verb = ({ 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: 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: string;
+  try {
+    version = host.analyzerVersion();
+  } catch (error: unknown) {
+    err.write(`deadset-ts: ${error instanceof Error ? error.message : String(error)}\n`);
+    return EXIT_FAILURE;
+  }
+
+  let report: Report;
+  let recorded: readonly Recorded[];
+  let verdict: number;
+  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: unknown) {
+    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: unknown) {
+    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/src/verbs/describe.ts

@@ -0,0 +1,46 @@
+import { RECORDED_CONFORMANCE, type Conformance } from "../conformance.ts";
+import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSION } from "../report.ts";
+import { CONTRACT_VERSION } from "../version.ts";
+import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verb.ts";
+
+/**
+ * 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: string, recorded: Conformance | undefined): string {
+  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: Verb = ({ 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: string;
+  try {
+    version = host.analyzerVersion();
+  } catch (error: unknown) {
+    err.write(`deadset-ts: describe: ${error instanceof Error ? error.message : String(error)}\n`);
+    return EXIT_FAILURE;
+  }
+  out.write(describeDocument(version, RECORDED_CONFORMANCE));
+  return EXIT_CLEAN;
+};

package/src/verbs/verb.ts

@@ -28,6 +28,19 @@ export interface Invocation {
   readonly openClient: (collectTiming: boolean) => Engine;
   /** The emitter of every kind family, which a verb that reports findings runs. */
   readonly emitters: Emitters;
+  /** The arguments after the verb's name, as written. */
+  readonly args: readonly string[];
+  /** The last value one of the verb's own options was given, undefined where none was. */
+  readonly option: (name: string) => string | undefined;
+  /** Every value a repeatable option of the verb was given, in the order they were written. */
+  readonly repeated: (name: string) => readonly string[];
+}
+
+/** The options one verb takes beside the ones every verb takes, each taking a value. */
+export interface VerbOptions {
+  readonly plain: readonly string[];
+  /** The options that may be written more than once, each occurrence one value. */
+  readonly repeatable: readonly string[];
 }
 
 /**