@cplieger/deadset-ts 3.7.0 → 3.9.0

package/src/findings-pass.ts

@@ -0,0 +1,145 @@
+/**
+ * The findings pass over one run: the emitter table's findings with the suppressions
+ * applied and the declared edges evaluated, and the stale suppressions, the totals and the
+ * verdict a report carries beside them.
+ */
+
+import type { AnalysisInputs } from "./analysis.ts";
+import type { Config, Severity } from "./config.ts";
+import type { EdgeEvaluation } from "./edges.ts";
+import type { CompletedFinding, Finding } from "./finding.ts";
+import { decidedFindings } from "./findings/emitters.ts";
+import {
+  fileRefsOf,
+  staleSuppressions,
+  type StaleRecord,
+  type StaleSuppression,
+} from "./findings/self-check.ts";
+import { isRowSubject, pairs, suppressionCounts, type Ledger } from "./suppress.ts";
+import type { Provenance, Recorded } from "./suppress-file.ts";
+import { EXIT_CLEAN, EXIT_FINDINGS } from "./verbs/verb.ts";
+
+/** The counts a report's totals carry beside its findings. */
+export interface PassTotals {
+  readonly suppressionsInEffect: number;
+  readonly reasonsRecorded: number;
+  readonly staleSuppressions: number;
+  /** The evaluations that hold a finding pending. */
+  readonly pending: number;
+}
+
+/** What the pass answers about one run. */
+export interface PassResult {
+  /** Every finding the report publishes, in the canonical order. */
+  readonly findings: readonly CompletedFinding[];
+  /** One record per site at which a suppression matched nothing, in reading order. */
+  readonly staleSuppressions: readonly StaleSuppression[];
+  /** One evaluation per declared edge side of this language. */
+  readonly edgeEvaluations: readonly EdgeEvaluation<CompletedFinding>[];
+  readonly totals: PassTotals;
+  /** What every suppression record did, in reading order. */
+  readonly ledger: Ledger<CompletedFinding>;
+}
+
+/** The exit code of a report holding at least one pending finding. */
+export const EXIT_PENDING = 4;
+
+/** The severities ranked, the strongest highest. */
+const SEVERITY_RANK: Readonly<Record<Severity, number>> = { allow: 0, warn: 1, deny: 2 };
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/** The canonical order: path, line, column, code, then the symbol reference. */
+function canonical(a: Finding, b: Finding): number {
+  return (
+    compare(a.position.path, b.position.path) ||
+    a.position.line - b.position.line ||
+    a.position.column - b.position.column ||
+    compare(a.code, b.code) ||
+    compare(a.symbol.ref, b.symbol.ref)
+  );
+}
+
+/**
+ * The pass over one run. The emitter table decides every record against every finding the
+ * run would produce with no record there, withholds what the records claim, and evaluates
+ * the declared edges; a stale record then names the codes its declaration reports instead.
+ */
+export function findingsPass(inputs: AnalysisInputs): PassResult {
+  const { marked, unmarked, suppressions } = inputs;
+  const decided = decidedFindings(marked, { unmarked, records: suppressions.records });
+  const { ledger, would } = decided;
+
+  const stale: StaleRecord[] = [];
+  suppressions.records.forEach((record, at) => {
+    if (ledger.verdicts[at] !== "stale") {
+      return;
+    }
+    const reports = would
+      .filter(
+        (finding) =>
+          finding.code !== record.code && pairs({ ...record, code: finding.code }, finding),
+      )
+      .map((finding) => finding.code);
+    stale.push({ record, reports });
+  });
+
+  const records = staleSuppressions(stale, fileRefsOf(marked.swept.matrix.union.symbols));
+  const counts = suppressionCounts(suppressions.records, ledger);
+  return {
+    findings: [...decided.findings].sort(canonical),
+    staleSuppressions: records,
+    edgeEvaluations: decided.evaluations,
+    totals: {
+      suppressionsInEffect: counts.inEffect,
+      reasonsRecorded: counts.reasonsRecorded,
+      staleSuppressions: records.length,
+      pending: decided.evaluations.filter((one) => one.finding !== undefined).length,
+    },
+    ledger,
+  };
+}
+
+/**
+ * The exit code of a report the pass answered: pending when an evaluation holds a finding,
+ * which outranks the rest because an unmerged report is not an answer; findings when a
+ * suppression is stale or a finding's severity reaches the configured failing severity;
+ * clean otherwise.
+ */
+export function verdictOf(result: PassResult, config: Config): number {
+  if (result.totals.pending > 0) {
+    return EXIT_PENDING;
+  }
+  if (result.totals.staleSuppressions > 0) {
+    return EXIT_FINDINGS;
+  }
+  const failing = SEVERITY_RANK[config.reporters.failOn];
+  const fails = result.findings.some((finding) => SEVERITY_RANK[finding.severity] >= failing);
+  return fails ? EXIT_FINDINGS : EXIT_CLEAN;
+}
+
+/**
+ * The findings of a report as a baseline records them, in report order. A finding about a
+ * row of a document is not recorded: no record withholds one, so a row recording it would
+ * be stale on the first read back.
+ */
+export function recordedFindings(result: PassResult): readonly Recorded[] {
+  return result.findings
+    .filter((finding) => !isRowSubject(finding.symbol.kind))
+    .map((finding) => ({
+      code: finding.code,
+      symbol: finding.symbol.ref,
+      path: finding.position.path,
+    }));
+}
+
+/** The analyzer identity a baseline this analyzer writes names as its rows' provenance. */
+export function analyzerProvenance(version: string): Provenance {
+  return { analyzer: "deadset-ts", version };
+}

package/src/host.ts

@@ -34,4 +34,9 @@ export interface Host {
    * says so at the one moment the value is asked for.
    */
   analyzerVersion(): string;
+  /**
+   * Writes one document whole, or a throw naming why it cannot. The write is atomic: a
+   * reader of the path sees the previous document or this one and never a part of it.
+   */
+  writeFile(path: string, text: string): void;
 }

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/references.ts

@@ -126,8 +126,6 @@ export interface References {
   /** The compiler configuration the project was opened from. */
   readonly configFile: string;
   readonly references: readonly Reference[];
-  /** The rules that classified files as test files, ordered by rule. */
-  readonly testFileRules: readonly TestFileRule[];
   /**
    * Every file the rules classified as a test file, by its path below the target root,
    * ascending. A declaration such a file holds is a test declaration, by the same
@@ -147,7 +145,7 @@ export interface ReferenceOptions {
   readonly batchCap?: number;
   /**
    * Glob patterns, relative to the target root, naming the files that are test files.
-   * Each pattern is a rule of its own and reports the files it matched.
+   * Each pattern is a rule of its own, which {@link testFileRulesOf} counts.
    */
   readonly testFiles: readonly string[];
 }
@@ -499,6 +497,26 @@ function patternRule(index: number): string {
   return `test-file-pattern-${String(index + 1)}`;
 }
 
+/**
+ * The rules over the test files of several projects at once, ordered by rule: a file two
+ * projects hold is one file, so each rule counts the distinct paths it matches.
+ */
+export function testFileRulesOf(
+  testFiles: readonly string[],
+  paths: readonly string[],
+): readonly TestFileRule[] {
+  const distinct = [...new Set(paths)];
+  return testFiles
+    .map((pattern, index) => {
+      const expression = globExpression(pattern);
+      return {
+        rule: patternRule(index),
+        matched: distinct.filter((path) => expression.test(path)).length,
+      };
+    })
+    .sort((a, b) => compare(a.rule, b.rule));
+}
+
 /** Two strings ordered bytewise, which is the order every set of a run is read in. */
 function compare(a: string, b: string): number {
   if (a === b) {
@@ -509,7 +527,7 @@ function compare(a: string, b: string): number {
 
 /**
  * Every reference one project's own files make to the project's own declarations, in
- * position order, and the test-file rules that classified those files.
+ * position order, and the files the test-file rules classified.
  *
  * `held` is the inventory of the same project, whose declaration map is what a resolved
  * symbol is looked up in; `targetRoot` is the absolute path every position is rendered
@@ -530,7 +548,6 @@ export function references<Brand>(
   const cap = options.batchCap ?? DEFAULT_BATCH_CAP;
   const declarations = held.declarations;
   const patterns = options.testFiles.map(globExpression);
-  const matched = options.testFiles.map(() => 0);
   const found: Reference[] = [];
   const tests: string[] = [];
   const chains = aliasChains(project, held);
@@ -574,13 +591,7 @@ export function references<Brand>(
 
   for (const file of files) {
     const path = renderPosition(file, targetRoot, 0).path;
-    const hits = patterns.map((pattern) => pattern.test(path));
-    hits.forEach((hit, index) => {
-      if (hit) {
-        matched[index] = (matched[index] ?? 0) + 1;
-      }
-    });
-    const test = hits.includes(true);
+    const test = patterns.some((pattern) => pattern.test(path));
     if (test) {
       tests.push(path);
     }
@@ -706,9 +717,6 @@ export function references<Brand>(
   return {
     configFile: project.configFile,
     references: found,
-    testFileRules: options.testFiles
-      .map((_pattern, index) => ({ rule: patternRule(index), matched: matched[index] ?? 0 }))
-      .sort((a, b) => compare(a.rule, b.rule)),
     testFilePaths: tests.sort(compare),
     cost: { batched, fileBatches, residueFallbacks, shorthandLookups, aliasSteps: chains.steps },
   };