@cplieger/deadset-ts 3.6.0 → 3.8.0

package/src/json-document.ts

@@ -0,0 +1,130 @@
+/**
+ * A read of a strict JSON document beside its parse: what a parse into a value cannot
+ * report, the offset of each record of one array and a member written twice.
+ */
+
+import type { Position } from "./position.ts";
+
+/** The token walk over a document `JSON.parse` accepted, so every token is well formed. */
+class Walk {
+  readonly opened: number[] = [];
+  /** The member written twice, where one is, as the offset of its name. */
+  twice: { readonly name: string; readonly offset: number } | undefined;
+  private readonly text: string;
+  private readonly array: string;
+  private at = 0;
+
+  constructor(text: string, array: string) {
+    this.text = text;
+    this.array = array;
+  }
+
+  run(): void {
+    this.value("document");
+  }
+
+  private skip(): void {
+    while (/[ \t\r\n]/u.test(this.text[this.at] ?? "")) {
+      this.at += 1;
+    }
+  }
+
+  private string(): string {
+    const start = this.at;
+    this.at += 1;
+    while (this.text[this.at] !== '"') {
+      this.at += this.text[this.at] === "\\" ? 2 : 1;
+    }
+    this.at += 1;
+    return JSON.parse(this.text.slice(start, this.at)) as string;
+  }
+
+  private value(role: "document" | "array" | "record" | "other"): void {
+    this.skip();
+    const char = this.text[this.at];
+    if (char === "{") {
+      if (role === "record") {
+        this.opened.push(this.at);
+      }
+      this.object(role);
+    } else if (char === "[") {
+      this.list(role === "array" ? "record" : "other");
+    } else if (char === '"') {
+      this.string();
+    } else {
+      while (this.at < this.text.length && !/[,\]} \t\r\n]/u.test(this.text[this.at] ?? "")) {
+        this.at += 1;
+      }
+    }
+  }
+
+  private object(role: string): void {
+    const seen = new Set<string>();
+    this.at += 1;
+    for (;;) {
+      this.skip();
+      if (this.text[this.at] === "}") {
+        this.at += 1;
+        return;
+      }
+      if (this.text[this.at] === ",") {
+        this.at += 1;
+        this.skip();
+      }
+      const offset = this.at;
+      const name = this.string();
+      if (seen.has(name) && this.twice === undefined) {
+        this.twice = { name, offset };
+      }
+      seen.add(name);
+      this.skip();
+      this.at += 1;
+      this.value(role === "document" && name === this.array ? "array" : "other");
+    }
+  }
+
+  private list(element: "record" | "other"): void {
+    this.at += 1;
+    for (;;) {
+      this.skip();
+      if (this.text[this.at] === "]") {
+        this.at += 1;
+        return;
+      }
+      if (this.text[this.at] === ",") {
+        this.at += 1;
+      }
+      this.value(element);
+    }
+  }
+}
+
+/** What a walk of one document found. */
+export interface DocumentWalk {
+  /** The offset of the brace opening each object of the document's array member, in order. */
+  readonly opened: readonly number[];
+  /** The first member one object writes twice, at any depth, as the offset of its name. */
+  readonly twice: { readonly name: string; readonly offset: number } | undefined;
+}
+
+/**
+ * Walks a document `JSON.parse` accepted, whose top-level member `array` holds the
+ * records. A member one object writes twice reads as though it were written once, its
+ * later value silently replacing the earlier one, so a document holding one is one a
+ * reader names rather than reads.
+ */
+export function walkDocument(text: string, array: string): DocumentWalk {
+  const walk = new Walk(text, array);
+  walk.run();
+  return { opened: walk.opened, twice: walk.twice };
+}
+
+/**
+ * One offset of a document as a finding carries it: the line counted from one, and the
+ * column counted from one in UTF-16 code units.
+ */
+export function positionAt(text: string, file: string, offset: number): Position {
+  const before = text.slice(0, offset);
+  const lineStart = before.lastIndexOf("\n") + 1;
+  return { path: file, line: before.split("\n").length, column: offset - lineStart + 1 };
+}

package/src/kinds.ts

@@ -1,53 +1,87 @@
+import type { Confidence, Severity } from "./config.ts";
+
+/** What a mechanical edit may do with a finding of one kind. */
+export type Fixability = "deletable" | "narrowable" | "manual" | "none";
+
+/** One live row of the issue-kind vocabulary, as far as an analyzer reads it. */
+export interface KindRow {
+  readonly code: string;
+  /** The kind's name, which a finding carries as its `kind`. */
+  readonly name: string;
+  /** The severity a finding carries where no severity key names its code or its family. */
+  readonly defaultSeverity: Severity;
+  /** The highest confidence a finding of the kind carries. */
+  readonly maxClass: Confidence;
+  readonly fixability: Fixability;
+  /**
+   * Whether the Contract fixes the kind on at its default severity, so a severity key
+   * naming the code, or a family prefix whose range holds it, is an unimplemented key.
+   */
+  readonly fixed: boolean;
+}
+
 /**
- * The issue-kind codes whose severity the Contract fixes. A severity key naming
- * one, or a family prefix whose range holds one, is an unimplemented key rather
- * than a setting.
- *
- * The codes are written out rather than read from the Contract at run time: the
- * Contract is data a reader outside this program consults, and a product that
- * read it while running would need it installed beside itself. A test compares
- * this list against the Contract release the analyzer is written against, so a
- * code the Contract fixes arrives here as a failing test.
+ * Every live row of the issue-kind vocabulary, in ascending code order, written out
+ * rather than read at run time, because a product that read the Contract while running
+ * would need it installed beside itself. A test compares this table against the
+ * Contract release the analyzer is written against.
  */
-export const FIXED_SEVERITY_CODES: readonly string[] = ["DS1703", "DS1704"];
+const ROWS: readonly KindRow[] = [
+  row("DS1001", "unused-exported", "deny", "deletable"),
+  row("DS1002", "unused-unexported", "deny", "deletable"),
+  row("DS1003", "unused-member", "deny", "deletable"),
+  row("DS1004", "test-only-use", "deny", "deletable"),
+  row("DS1005", "test-of-dead-code", "deny", "deletable"),
+  row("DS1006", "deprecated-unused", "deny", "deletable"),
+  row("DS1101", "unnecessary-export", "warn", "narrowable"),
+  row("DS1102", "unnecessary-exposure", "warn", "narrowable"),
+  row("DS1103", "unreachable-export", "deny", "deletable"),
+  row("DS1104", "redundant-export-keyword", "warn", "narrowable"),
+  row("DS1201", "unused-interface", "deny", "deletable"),
+  row("DS1203", "uncalled-interface-method", "warn", "manual"),
+  row("DS1204", "unused-satisfaction-assertion", "deny", "deletable"),
+  row("DS1301", "write-only-symbol", "deny", "deletable"),
+  row("DS1302", "unused-enum-member", "deny", "deletable"),
+  row("DS1303", "unused-type-parameter", "deny", "deletable"),
+  row("DS1501", "file-never-built", "deny", "deletable"),
+  row("DS1502", "file-never-imported", "deny", "deletable"),
+  row("DS1601", "unused-dependency", "deny", "manual"),
+  row("DS1605", "unused-module-directive", "warn", "deletable"),
+  row("DS1701", "suppression-without-reason", "deny", "none"),
+  row("DS1702", "unscoped-ignore-entry", "deny", "none"),
+  { ...row("DS1703", "stale-suppression", "deny", "none"), fixed: true },
+  { ...row("DS1704", "unmatched-root", "deny", "none"), fixed: true },
+  row("DS1705", "stale-cross-language-edge", "deny", "none"),
+  row("DS1801", "unused-parameter", "warn", "manual"),
+  row("DS1802", "unused-receiver", "warn", "deletable"),
+  row("DS1803", "unused-result", "warn", "manual"),
+  row("DS1805", "unreachable-statement", "deny", "deletable"),
+  row("DS1807", "dead-store", "deny", "deletable"),
+  row("DS1809", "unreachable-case", "deny", "deletable"),
+];
+
+/** A row at the `certain` ceiling whose severity a configuration may set. */
+function row(
+  code: string,
+  name: string,
+  defaultSeverity: Severity,
+  fixability: Fixability,
+): KindRow {
+  return { code, name, defaultSeverity, maxClass: "certain", fixability, fixed: false };
+}
+
+/** Every live row of the issue-kind vocabulary, by its code, in ascending code order. */
+export const KINDS: ReadonlyMap<string, KindRow> = new Map(ROWS.map((one) => [one.code, one]));
 
 /**
  * The code of every live issue kind, in ascending order. A severity key names one of
  * them or a family prefix whose range holds one; a key naming a retired code, an
  * unassigned code or a range holding no live kind is an unimplemented key, so every
- * severity a configuration sets is one some analyzer reports under. A test compares
- * this list against the Contract release the analyzer is written against.
+ * severity a configuration sets is one some analyzer reports under.
  */
-export const LIVE_CODES: readonly string[] = [
-  "DS1001",
-  "DS1002",
-  "DS1003",
-  "DS1004",
-  "DS1005",
-  "DS1006",
-  "DS1101",
-  "DS1102",
-  "DS1103",
-  "DS1104",
-  "DS1201",
-  "DS1203",
-  "DS1204",
-  "DS1301",
-  "DS1302",
-  "DS1303",
-  "DS1501",
-  "DS1502",
-  "DS1601",
-  "DS1605",
-  "DS1701",
-  "DS1702",
-  "DS1703",
-  "DS1704",
-  "DS1705",
-  "DS1801",
-  "DS1802",
-  "DS1803",
-  "DS1805",
-  "DS1807",
-  "DS1809",
-];
+export const LIVE_CODES: readonly string[] = ROWS.map((one) => one.code);
+
+/** The issue-kind codes whose severity the Contract fixes, in ascending order. */
+export const FIXED_SEVERITY_CODES: readonly string[] = ROWS.filter((one) => one.fixed).map(
+  (one) => one.code,
+);

package/src/roots.ts

@@ -11,9 +11,7 @@
 
 import type { SourceFile } from "@typescript/native/unstable/ast";
 import { aliasChains } from "./alias-chain.ts";
-import { REPOSITORY_DOCUMENT } from "./config.ts";
 import { entryPoints, type EntryRule } from "./entry-points.ts";
-import type { Finding } from "./finding.ts";
 import { globExpression } from "./glob.ts";
 import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
 import type { Manifest, ManifestEntry } from "./manifest.ts";
@@ -89,15 +87,6 @@ export interface RootOptions {
   readonly publishedAPI: boolean;
 }
 
-/** The code the Contract gives a configured root that matches nothing. */
-const UNMATCHED_ROOT_CODE = "DS1704";
-
-/** The subject kind a finding under that code carries, from the Contract's vocabulary. */
-const UNMATCHED_ROOT_SUBJECT = "root";
-
-/** The fixed position of a finding about a document rather than about a line of one. */
-const DOCUMENT_POSITION = 1;
-
 /** Whether a configured string carries either special character. */
 function isPattern(text: string): boolean {
   return text.includes("*") || text.includes("?");
@@ -406,31 +395,3 @@ export function unmatchedEverywhere(
     perProject.every((project) => project.unmatched.includes(pattern)),
   );
 }
-
-/**
- * The findings a run reports for the configured strings that named nothing.
- *
- * `document` is the path of the document that declared the roots, below the target
- * root; where the run read them from no document of the target it is empty and the
- * finding names the conventional repository configuration, which is the document a
- * maintainer writes a configured root in. Every finding of one run sits at that
- * document's first position: the roots are written as an array whose members carry
- * no line of their own, so the string each finding names is what tells one from
- * another.
- */
-export function unmatchedRoots(sources: readonly string[], document: string): readonly Finding[] {
-  const position = {
-    path: document === "" ? REPOSITORY_DOCUMENT : document,
-    line: DOCUMENT_POSITION,
-    column: DOCUMENT_POSITION,
-    endLine: DOCUMENT_POSITION,
-  };
-  return sources.map((source) => ({
-    code: UNMATCHED_ROOT_CODE,
-    position,
-    symbol: { ref: source, kind: UNMATCHED_ROOT_SUBJECT, name: source, sizeLines: 1 },
-    message: isPattern(source)
-      ? "configured root pattern matches no symbol of the inventory"
-      : "configured root matches no symbol of the inventory",
-  }));
-}

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`;
+}