@cplieger/deadset-ts 3.7.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/suppress-file.ts

@@ -0,0 +1,283 @@
+/**
+ * The two file-backed suppression documents at the target root: the ignore file, whose
+ * entries a maintainer writes, and the baseline, whose rows an analyzer writes. They share
+ * one record shape, so one decoder and one matcher serve both, and a row moves into the
+ * ignore file by gaining a maintainer's reason.
+ */
+
+import type { Host } from "./host.ts";
+import type { InventorySymbol } from "./inventory.ts";
+import { joinPath } from "./paths.ts";
+import { positionAt, walkDocument } from "./json-document.ts";
+import type { Position } from "./position.ts";
+import {
+  CODE_FORM,
+  SUPPRESSION_WITHOUT_REASON,
+  SuppressionError,
+  UNSCOPED_ENTRY,
+  blankReason,
+  isEntryPath,
+  isSymbolRef,
+  siteText,
+  type Mechanism,
+  type Refusal,
+  type SuppressionRecord,
+  type Suppressions,
+} from "./suppress.ts";
+
+/** The name and the location the grammar fixes for the ignore file. */
+export const IGNORE_FILE = "deadset-ignore.json";
+
+/** The name and the location the grammar fixes for the baseline. */
+export const BASELINE_FILE = "deadset-baseline.json";
+
+/** One file-backed document as a reader sees it. */
+interface Shape {
+  readonly file: string;
+  /** The member holding the records. */
+  readonly array: string;
+  readonly mechanism: Mechanism;
+  readonly documentWant: string;
+  readonly recordWant: string;
+}
+
+const IGNORE_SHAPE: Shape = {
+  file: IGNORE_FILE,
+  array: "ignore",
+  mechanism: "ignore",
+  documentWant: "an object carrying the ignore array, and an optional description",
+  recordWant: "an entry naming code, symbol, path and reason, each a string",
+};
+
+const BASELINE_SHAPE: Shape = {
+  file: BASELINE_FILE,
+  array: "baseline",
+  mechanism: "baseline",
+  documentWant: "an object carrying the baseline array, and an optional description",
+  recordWant: "a row naming code, symbol, path and reason, each a string",
+};
+
+/** The closed key list of one entry or row. */
+const RECORD_KEYS: ReadonlySet<string> = new Set(["code", "symbol", "path", "reason"]);
+
+const CODE_WANT = "DS followed by four digits";
+const SYMBOL_WANT =
+  "a stable symbol reference, go://<import-path>#<fragment> or ts://<package>/<source-path>#<fragment>";
+const PATH_WANT = "a path relative to the target root, with the solidus as separator";
+
+/** The document itself, for a defect no record position describes. */
+function documentSite(shape: Shape): Position {
+  return { path: shape.file, line: 0, column: 0 };
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** What one entry or row resolves to. */
+interface Read {
+  readonly records: readonly SuppressionRecord[];
+  readonly refusals: readonly Refusal[];
+}
+
+/** The declarations of the run by reference and file, which is what an entry names. */
+type ByReference = ReadonlyMap<string, readonly InventorySymbol[]>;
+
+function referenceKey(ref: string, path: string): string {
+  return `${ref}\u0000${path}`;
+}
+
+/**
+ * Reads one entry or row: the records it binds, the refusals it carries, or the
+ * malformed value that ends the run.
+ */
+function readRecord(value: unknown, site: Position, byReference: ByReference, shape: Shape): Read {
+  const refuse = (text: string, want: string): never => {
+    throw new SuppressionError(shape.mechanism, `${shape.file} ${siteText(site)}`, text, want);
+  };
+  if (!isObject(value)) {
+    return refuse(JSON.stringify(value), shape.recordWant);
+  }
+  for (const [key, held] of Object.entries(value)) {
+    if (!RECORD_KEYS.has(key)) {
+      refuse(`the member ${JSON.stringify(key)} is not one the grammar declares`, shape.recordWant);
+    }
+    if (typeof held !== "string") {
+      refuse(`the member ${JSON.stringify(key)} holds ${JSON.stringify(held)}`, shape.recordWant);
+    }
+  }
+  const entry = value as Readonly<Record<string, string | undefined>>;
+  const { code, symbol, path, reason } = {
+    code: entry["code"],
+    symbol: entry["symbol"],
+    path: entry["path"],
+    reason: entry["reason"],
+  };
+  if (code === undefined) {
+    return refuse("a record naming no code", shape.recordWant);
+  }
+  if (symbol === undefined) {
+    return refuse("a record naming no symbol", shape.recordWant);
+  }
+  if (!CODE_FORM.test(code)) {
+    return refuse(JSON.stringify(code), CODE_WANT);
+  }
+  if (!isSymbolRef(symbol)) {
+    return refuse(JSON.stringify(symbol), SYMBOL_WANT);
+  }
+  if (path !== undefined && path !== "" && !isEntryPath(path)) {
+    return refuse(JSON.stringify(path), PATH_WANT);
+  }
+
+  const written = {
+    code,
+    symbol,
+    path: path ?? "",
+    reason: reason ?? "",
+    site,
+    mechanism: shape.mechanism,
+  };
+  const refusals: Refusal[] = [];
+  if (blankReason(reason)) {
+    refusals.push({ ...written, reported: SUPPRESSION_WITHOUT_REASON });
+  }
+  if (written.path === "") {
+    refusals.push({ ...written, reported: UNSCOPED_ENTRY });
+  }
+  if (refusals.length > 0) {
+    return { records: [], refusals };
+  }
+  const named = byReference.get(referenceKey(symbol, written.path)) ?? [];
+  if (named.length === 0) {
+    return { records: [{ ...written, bound: "" }], refusals: [] };
+  }
+  return { records: named.map((one) => ({ ...written, bound: one.id })), refusals: [] };
+}
+
+/** Reads one document at the target root, binding each record against the run's declarations. */
+function readDocument(
+  host: Host,
+  targetRoot: string,
+  symbols: readonly InventorySymbol[],
+  shape: Shape,
+): Suppressions {
+  const file = joinPath(targetRoot, shape.file);
+  if (host.kindOf(file) === "absent") {
+    return { records: [], refusals: [] };
+  }
+  const text = host.readFile(file);
+  const malformed = (detail: string, site = documentSite(shape)): never => {
+    throw new SuppressionError(shape.mechanism, siteText(site), detail, shape.documentWant);
+  };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error: unknown) {
+    return malformed(`${shape.file}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isObject(parsed)) {
+    return malformed(shape.file);
+  }
+  const walk = walkDocument(text, shape.array);
+  if (walk.twice !== undefined) {
+    malformed(
+      `the member ${JSON.stringify(walk.twice.name)} is written twice, so neither value is chosen`,
+      positionAt(text, shape.file, walk.twice.offset),
+    );
+  }
+  for (const key of Object.keys(parsed)) {
+    if (key !== "description" && key !== shape.array) {
+      malformed(`the member ${JSON.stringify(key)} is not one the grammar declares`);
+    }
+  }
+  const description = parsed["description"];
+  const held = parsed[shape.array];
+  if ((description !== undefined && typeof description !== "string") || !Array.isArray(held)) {
+    return malformed(shape.file);
+  }
+
+  const byReference = new Map<string, InventorySymbol[]>();
+  for (const symbol of symbols) {
+    const key = referenceKey(symbol.ref, symbol.position.path);
+    byReference.set(key, [...(byReference.get(key) ?? []), symbol]);
+  }
+  const records: SuppressionRecord[] = [];
+  const refusals: Refusal[] = [];
+  (held as readonly unknown[]).forEach((value, index) => {
+    const offset = walk.opened[index];
+    const site = offset === undefined ? documentSite(shape) : positionAt(text, shape.file, offset);
+    const read = readRecord(value, site, byReference, shape);
+    records.push(...read.records);
+    refusals.push(...read.refusals);
+  });
+  return { records, refusals };
+}
+
+/**
+ * The ignore file at the target root, each entry bound to the declaration whose reference
+ * and file both equal the ones it names, and never by glob, pattern or substring. An
+ * absent file is an empty one.
+ */
+export function readIgnoreFile(
+  host: Host,
+  targetRoot: string,
+  symbols: readonly InventorySymbol[],
+): Suppressions {
+  return readDocument(host, targetRoot, symbols, IGNORE_SHAPE);
+}
+
+/**
+ * The baseline at the target root, each row matched exactly as an ignore entry is. A row's
+ * reason is the provenance an analyzer wrote, never a maintainer's judgement: the finding
+ * it records is real, and the row says only that it was there when the baseline was
+ * written. An absent file is an empty one.
+ */
+export function readBaseline(
+  host: Host,
+  targetRoot: string,
+  symbols: readonly InventorySymbol[],
+): Suppressions {
+  return readDocument(host, targetRoot, symbols, BASELINE_SHAPE);
+}
+
+/** One finding a written row records: what a later run matches the row on. */
+export interface Recorded {
+  readonly code: string;
+  readonly symbol: string;
+  readonly path: string;
+}
+
+/** The analyzer a written row names as its provenance, as the same run's report names it. */
+export interface Provenance {
+  readonly analyzer: string;
+  readonly version: string;
+}
+
+/** What a written document says about itself, so the same report writes the same bytes. */
+const BASELINE_DESCRIPTION =
+  "Recorded findings: a run fails only on a finding this document does not hold. " +
+  "Every reason is the analyzer that recorded the row, never an adjudication.";
+
+/**
+ * A baseline holding one row per finding, in the order given, which is the report's. Every
+ * row carries the provenance as its reason. A finding missing a value a row needs, and an
+ * identity missing its name or version, are refused rather than written, because the
+ * grammar requires a reason on every row.
+ */
+export function writeBaseline(findings: readonly Recorded[], provenance: Provenance): string {
+  if (provenance.analyzer === "" || provenance.version === "") {
+    throw new Error(
+      `a baseline row would carry no reason: the analyzer identity names ${JSON.stringify(provenance.analyzer)} at version ${JSON.stringify(provenance.version)}`,
+    );
+  }
+  const reason = `recorded by ${provenance.analyzer} ${provenance.version}`;
+  const baseline = findings.map((found) => {
+    if (found.code === "" || found.symbol === "" || found.path === "") {
+      throw new Error(
+        `a baseline row would carry no reason: a finding names code ${JSON.stringify(found.code)}, symbol ${JSON.stringify(found.symbol)} and path ${JSON.stringify(found.path)}`,
+      );
+    }
+    return { code: found.code, symbol: found.symbol, path: found.path, reason };
+  });
+  return `${JSON.stringify({ description: BASELINE_DESCRIPTION, baseline }, null, 2)}\n`;
+}