@cplieger/deadset-ts 3.7.0 → 3.8.0

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

package/src/suppress-inline.ts

@@ -0,0 +1,318 @@
+/**
+ * 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, type Node, type SourceFile } from "@typescript/native/unstable/ast";
+import { nodeKey, type Inventory } from "./inventory.ts";
+import { byPosition, positionKey, renderPosition, type Position } from "./position.ts";
+import type { ProjectView } from "./session.ts";
+import {
+  SUPPRESSION_WITHOUT_REASON,
+  SuppressionError,
+  siteText,
+  type Refusal,
+  type SuppressionRecord,
+  type Suppressions,
+} from "./suppress.ts";
+
+/**
+ * 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]*$`,
+} as const;
+
+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>";
+
+/** What the grammar's decision procedure makes of one comment. */
+export type Directive =
+  | { readonly is: "none" }
+  | { readonly is: "directive"; readonly codes: readonly string[]; readonly reason: string }
+  | { readonly is: "no-reason"; readonly codes: readonly string[] }
+  | { readonly is: "malformed" };
+
+/** Applies the grammar's three expressions to the text of one comment, in order. */
+export function classifyComment(text: string): Directive {
+  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" };
+}
+
+/** One `//` line comment: the offset of its first solidus, and its text to the end of its line. */
+export interface LineComment {
+  readonly offset: number;
+  readonly text: string;
+}
+
+/** The literal tokens whose text may hold `//` or `/*` without starting a comment. */
+const LITERALS: ReadonlySet<SyntaxKind> = 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: string | undefined): boolean {
+  return char === "\n" || char === "\r" || char === "\u2028" || char === "\u2029";
+}
+
+/** The offset where the line holding `from` ends. */
+function lineEnd(text: string, from: number): number {
+  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: string, from: number): number {
+  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: SourceFile): readonly LineComment[] {
+  const text = file.text;
+  const spans: { readonly start: number; readonly end: number }[] = [];
+  const visit = (node: Node): void => {
+    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: LineComment[] = [];
+  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;
+}
+
+/** One declaration a directive can bind: its identifier and its reference. */
+interface Declared {
+  readonly id: string;
+  readonly ref: string;
+  readonly position: Position;
+}
+
+/**
+ * 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: SourceFile,
+  held: Inventory,
+  symbols: ReadonlyMap<string, Declared>,
+): ReadonlyMap<number, readonly Declared[]> {
+  const below = new Map<number, Declared[]>();
+  const add = (offset: number, one: Declared): void => {
+    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: Node): void => {
+    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;
+}
+
+/** One comment in the namespace, what the grammar made of it, and what it bound. */
+export interface InlineDirective {
+  readonly site: Position;
+  readonly text: string;
+  readonly directive: Directive;
+  readonly bound: Declared[];
+}
+
+/**
+ * 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<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  targetRoot: string,
+): readonly InlineDirective[] {
+  const symbols = new Map<string, Declared>(
+    held.symbols
+      .filter((symbol) => symbol.kind !== "file")
+      .map((symbol) => [symbol.id, { id: symbol.id, ref: symbol.ref, position: symbol.position }]),
+  );
+  const found: InlineDirective[] = [];
+  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: readonly (readonly InlineDirective[])[],
+): Suppressions {
+  const merged = new Map<string, InlineDirective>();
+  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: SuppressionRecord[] = [];
+  const refusals: Refusal[] = [];
+  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",
+          } as const;
+          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 };
+}