@cplieger/deadset-ts 3.7.0 → 3.8.0

package/src/findings/emitters.ts

@@ -1,6 +1,8 @@
-import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.ts";
+import { evaluateEdges, type EdgeEvaluation } from "../edges.ts";
 import type { CompletedFinding } from "../finding.ts";
-import { completed, reportable } from "./completion.ts";
+import { ledgerOf, type Dials, type Ledger, type SuppressionRecord } from "../suppress.ts";
+import { completed, dialsOf, reportable } from "./completion.ts";
+import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.ts";
 import type { Emitter, EmitterInput, Emitters } from "./emitter.ts";
 import { interfaces } from "./interfaces.ts";
 import { intraFunction } from "./intra-function.ts";
@@ -22,12 +24,84 @@ export const EMITTERS: Emitters = new Map<string, Emitter>([
   ["intra-function", intraFunction],
 ]);
 
+/** What the suppressions of a run swept under their marks are decided against. */
+export interface Suppressed {
+  /** The same run swept with no mark, which is where a kind about liveness reports a marked declaration. */
+  readonly unmarked: EmitterInput;
+  /** The run's suppression records, in reading order. */
+  readonly records: readonly SuppressionRecord[];
+}
+
+/** What the emitter table answers about one run. */
+export interface DecidedFindings {
+  /** Every finding the run reports, each family's in table order. */
+  readonly findings: readonly CompletedFinding[];
+  /** One evaluation per declared edge side of this language, ordered by edge, then by side. */
+  readonly evaluations: readonly EdgeEvaluation<CompletedFinding>[];
+  /** What every suppression record did, in reading order. */
+  readonly ledger: Ledger<CompletedFinding>;
+  /** Every finding a record could name: the run's with no mark, then the run's as swept. */
+  readonly would: readonly CompletedFinding[];
+}
+
+/** Every family's findings over one sweep, completed by one step. */
+function completedOver(input: EmitterInput): readonly CompletedFinding[] {
+  return completed(
+    input,
+    [...EMITTERS.values()].flatMap((emit) => emit(input)),
+  );
+}
+
 /**
- * Every finding of the run the dials do not withhold, each family's in table order: every
- * family's findings completed by one step, then withheld by one step, so a root one
- * family reports withholds what another family reports in its component.
+ * The dials over the findings a record could name, each read against the sweep that
+ * produced it, so a component one sweep numbers withholds nothing of the other's.
  */
+function dialsOver(
+  input: EmitterInput,
+  found: readonly CompletedFinding[],
+  suppressed: Suppressed,
+  unmarked: readonly CompletedFinding[],
+): Dials<CompletedFinding> {
+  const marked = dialsOf(input, found);
+  const before = dialsOf(suppressed.unmarked, unmarked);
+  const fromUnmarked = new Set(unmarked);
+  return {
+    withholdsCode: marked.withholdsCode,
+    withholds: (finding) =>
+      fromUnmarked.has(finding) ? before.withholds(finding) : marked.withholds(finding),
+  };
+}
+
+/**
+ * Every finding of one run swept under its suppressions' marks, decided in one pass: every
+ * family's findings completed by one step, so every component number is minted once, a
+ * pending finding's among them; the finding each record claims withheld, whatever its
+ * kind; the rest withheld by the dials, so a root one family reports withholds what
+ * another family reports in its component; and every declared edge evaluated over what
+ * remains, so a finding it holds pending is in its evaluation and nowhere else.
+ */
+export function decidedFindings(
+  input: EmitterInput,
+  suppressed: Suppressed = { unmarked: input, records: [] },
+): DecidedFindings {
+  const found = completedOver(input);
+  const unmarked = suppressed.records.length === 0 ? [] : completedOver(suppressed.unmarked);
+  const would = [...unmarked, ...found];
+  const ledger = ledgerOf(suppressed.records, would, dialsOver(input, found, suppressed, unmarked));
+  const kept = reportable(
+    input,
+    found.filter((finding) => !ledger.withheld(finding)),
+  );
+  const evaluated = evaluateEdges(kept, input.boundary.edges, input.swept.matrix.union.symbols);
+  return {
+    findings: evaluated.findings,
+    evaluations: evaluated.evaluations,
+    ledger,
+    would,
+  };
+}
+
+/** Every finding the run reports, each family's in table order. */
 export function findingsOf(input: EmitterInput): readonly CompletedFinding[] {
-  const found = [...EMITTERS.values()].flatMap((emit) => emit(input));
-  return reportable(completed(input, found), input.config.analysis.minConfidence);
+  return decidedFindings(input).findings;
 }

package/src/findings/self-check.ts

@@ -1,4 +1,207 @@
+import { REPOSITORY_DOCUMENT } from "../config.ts";
+import type { Finding } from "../finding.ts";
+import type { InventorySymbol } from "../inventory.ts";
+import type { Position } from "../position.ts";
+import {
+  STALE_SUPPRESSION,
+  SUPPRESSION_WITHOUT_REASON,
+  type Mechanism,
+  type Refusal,
+  type SuppressionRecord,
+} from "../suppress.ts";
 import type { Emitter } from "./emitter.ts";
 
-/** The findings of the self-check family, `DS1700` to `DS1799`. */
-export const selfCheck: Emitter = () => [];
+/** The code a configured root that matches nothing is reported under. */
+const UNMATCHED_ROOT = "DS1704";
+
+/** The subject kind of a finding about a suppression record. */
+const SUPPRESSION_SUBJECT = "suppression";
+
+/** The subject kind of a finding about a configured root. */
+const ROOT_SUBJECT = "root";
+
+/** The fixed position of a finding about a document rather than about a line of one. */
+const DOCUMENT_POSITION = 1;
+
+/** One record no finding matched, and the codes its declaration reports instead. */
+export interface StaleRecord {
+  readonly record: SuppressionRecord;
+  /** The codes the bound declaration would report, none of them the record's own. */
+  readonly reports: readonly string[];
+}
+
+/** What the self-check family reads: the run's refused suppressions and its configured roots. */
+export interface SelfCheckFacts {
+  /** The suppressions the grammar refused with a finding, in reading order. */
+  readonly refusals: readonly Refusal[];
+  /** Every configured root or pattern that matched nothing in any project. */
+  readonly unmatchedRoots: readonly string[];
+  /** The document below the target root that declared the roots, empty where none did. */
+  readonly rootsDocument: string;
+}
+
+/** A run with nothing for the self-check family to report. */
+export const NO_SELF_CHECK: SelfCheckFacts = {
+  refusals: [],
+  unmatchedRoots: [],
+  rootsDocument: "",
+};
+
+/** The words a message names a mechanism by. */
+const WRITTEN: Readonly<Record<Mechanism, string>> = {
+  inline: "inline directive",
+  ignore: "ignore entry",
+  baseline: "baseline row",
+};
+
+/** The file references of a run's declarations, by path. */
+export function fileRefsOf(symbols: readonly InventorySymbol[]): FileRefs {
+  const byPath = new Map(
+    symbols
+      .filter((symbol) => symbol.kind === "file")
+      .map((symbol) => [symbol.position.path, symbol.ref]),
+  );
+  return (path) => byPath.get(path);
+}
+
+/** A list of codes as a sentence names them. */
+function spelled(codes: readonly string[]): string {
+  if (codes.length < 2) {
+    return codes.join("");
+  }
+  return `${codes.slice(0, -1).join(", ")} and ${codes.at(-1) ?? ""}`;
+}
+
+/** A finding about one suppression, at the suppression's own site. */
+function aboutSuppression(code: string, ref: string, site: Position, message: string): Finding {
+  return {
+    code,
+    position: { ...site, endLine: site.line },
+    symbol: { ref, kind: SUPPRESSION_SUBJECT, name: ref, sizeLines: 1 },
+    message,
+  };
+}
+
+/** Each file of the run by its path, as the reference of the file it is. */
+export type FileRefs = (path: string) => string | undefined;
+
+/**
+ * The reference a finding about a suppression names: the symbol it names or bound, else
+ * the file form of the document that holds it, else that document's path.
+ */
+function suppressionRef(symbol: string, path: string, files: FileRefs): string {
+  return symbol === "" ? (files(path) ?? path) : symbol;
+}
+
+/** One finding per refused suppression: the grammar's reason refusal and its scope refusal. */
+export function refusedSuppressions(
+  refusals: readonly Refusal[],
+  files: FileRefs,
+): readonly Finding[] {
+  return refusals.map((refused) =>
+    aboutSuppression(
+      refused.reported,
+      suppressionRef(refused.symbol, refused.path, files),
+      refused.site,
+      `${WRITTEN[refused.mechanism]} for ${refused.code} ${
+        refused.reported === SUPPRESSION_WITHOUT_REASON
+          ? "carries no reason"
+          : "names a symbol and no path"
+      }`,
+    ),
+  );
+}
+
+/** One stale suppression as the report's stale-suppression record carries it. */
+export interface StaleSuppression {
+  readonly code: typeof STALE_SUPPRESSION;
+  readonly mechanism: Mechanism;
+  readonly entry: {
+    readonly code: string;
+    readonly symbol?: string;
+    readonly path: string;
+    readonly reason: string;
+  };
+  readonly position: Position;
+  readonly symbol: string;
+  readonly message: string;
+}
+
+/**
+ * One record per site at which a suppression matched nothing, whatever the number of
+ * codes or declarations written there: the first record names the entry, and the message
+ * names every code the site's records named and every code the declaration reports
+ * instead, so the maintainer corrects the code rather than hunting for it.
+ */
+export function staleSuppressions(
+  stale: readonly StaleRecord[],
+  files: FileRefs,
+): readonly StaleSuppression[] {
+  const bySite = new Map<string, { first: SuppressionRecord; records: StaleRecord[] }>();
+  for (const one of stale) {
+    const { site, mechanism } = one.record;
+    const key = `${mechanism}\u0000${site.path}\u0000${String(site.line)}\u0000${String(site.column)}`;
+    const held = bySite.get(key) ?? { first: one.record, records: [] };
+    held.records.push(one);
+    bySite.set(key, held);
+  }
+  return [...bySite.values()].map(({ first, records }) => {
+    const codes = [...new Set(records.map((one) => one.record.code))].sort();
+    const reports = [...new Set(records.flatMap((one) => one.reports))]
+      .filter((code) => !codes.includes(code))
+      .sort();
+    const instead = reports.length === 0 ? "" : `, and its declaration reports ${spelled(reports)}`;
+    return {
+      code: STALE_SUPPRESSION,
+      mechanism: first.mechanism,
+      entry: {
+        code: first.code,
+        ...(first.symbol === "" ? {} : { symbol: first.symbol }),
+        path: first.path,
+        reason: first.reason,
+      },
+      position: first.site,
+      symbol: suppressionRef(first.symbol, first.path, files),
+      message: `${WRITTEN[first.mechanism]} for ${spelled(codes)} matches no current finding${instead}`,
+    };
+  });
+}
+
+/**
+ * One finding per configured root or pattern that named nothing in any project. A finding
+ * names the document that declared the roots, or the conventional repository configuration
+ * where no document of the target did, and every finding of one run sits at that
+ * document's first position: the roots are an array whose members carry no line of their
+ * own, so the string each finding names tells one from another.
+ */
+export function unmatchedRootFindings(
+  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,
+    position,
+    symbol: { ref: source, kind: ROOT_SUBJECT, name: source, sizeLines: 1 },
+    message:
+      source.includes("*") || source.includes("?")
+        ? "configured root pattern matches no symbol of the inventory"
+        : "configured root matches no symbol of the inventory",
+  }));
+}
+
+/**
+ * The findings of the self-check family, `DS1700` to `DS1799`: a suppression refused for
+ * carrying no reason or naming no path, and a configured root that named nothing. A
+ * suppression that matched nothing is a record of the report's stale suppressions, which
+ * {@link staleSuppressions} builds, and a stale cross-language edge is the merge's to report.
+ */
+export const selfCheck: Emitter = ({ selfCheck: facts, swept }) => [
+  ...refusedSuppressions(facts.refusals, fileRefsOf(swept.matrix.union.symbols)),
+  ...unmatchedRootFindings(facts.unmatchedRoots, facts.rootsDocument),
+];

package/src/findings/visibility-narrowing.ts

@@ -3,7 +3,6 @@ import { OUTSIDE, type Graph } from "../graph.ts";
 import type { InventorySymbol, SymbolKind } from "../inventory.ts";
 import type { MatrixCandidate } from "../matrix.ts";
 import type { RootKind } from "../roots.ts";
-import type { PendingFinding } from "./boundary.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
 import { writeOnlyDeclarations } from "./reads-and-writes.ts";
 
@@ -33,13 +32,6 @@ const WORDS: Partial<Readonly<Record<SymbolKind, string>>> = {
   "export-alias": "re-export",
 };
 
-/** What the family found: the findings it reports, and those a declared edge holds pending. */
-export interface Narrowings {
-  readonly findings: readonly Finding[];
-  /** Ordered by edge, then by side. */
-  readonly pending: readonly PendingFinding[];
-}
-
 /** Per declaration of the run, the facts both rules read. */
 interface Facts {
   readonly graph: Graph;
@@ -236,26 +228,15 @@ function unreachable(
   );
 }
 
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /**
- * The visibility-narrowing family over one run: `DS1101`, `DS1103` and `DS1104`.
- *
- * A finding about a symbol a declared cross-language edge names is pending instead of
- * reported, once per side naming it: the edge counts as a reference from outside the
- * file and the package, and whether it is a use is decided on the side in the other
- * language.
+ * The visibility-narrowing family over one run: `DS1101`, `DS1103` and `DS1104`. A finding
+ * about a symbol a declared cross-language edge names is reported here like any other, and
+ * the edge's evaluation then holds it pending, because the edge stands for a reference from
+ * outside the file and the package whose use is decided in the other language.
  */
-export function narrowings(input: EmitterInput): Narrowings {
-  const { boundary } = input;
+export function narrowings(input: EmitterInput): readonly Finding[] {
   const facts = factsOf(input.swept.matrix.union);
-  const { declared, loaded } = boundary.consumers;
+  const { declared, loaded } = input.boundary.consumers;
   const closed = input.config.consumersComplete && declared.every((id) => loaded.includes(id));
   const world = { closed, writeOnly: writeOnlyDeclarations(input) };
   const candidates = new Map(
@@ -263,27 +244,17 @@ export function narrowings(input: EmitterInput): Narrowings {
   );
 
   const findings: Finding[] = [];
-  const pending: PendingFinding[] = [];
   facts.graph.symbols.forEach((symbol, at) => {
     const candidate = candidates.get(symbol.id);
     const found =
       candidate === undefined
         ? narrowing(facts, at, symbol, world)
         : unreachable(facts, at, symbol, candidate, input);
-    if (found === undefined) {
-      return;
-    }
-    const named = boundary.edges.filter((side) => side.symbol === symbol.ref);
-    if (named.length === 0) {
+    if (found !== undefined) {
       findings.push(found);
-      return;
-    }
-    for (const side of named) {
-      pending.push({ ...side, finding: found });
     }
   });
-  pending.sort((a, b) => compare(a.edge, b.edge) || compare(a.side, b.side));
-  return { findings, pending };
+  return findings;
 }
 
 /**
@@ -303,18 +274,5 @@ export function unreachableExports(input: EmitterInput): ReadonlySet<string> {
   return found;
 }
 
-/**
- * The findings of the visibility-narrowing family, `DS1100` to `DS1199`. A finding a
- * declared edge holds pending belongs in that edge's evaluation, which this analyzer
- * does not publish yet, so a run that holds one is refused rather than reported
- * without it.
- */
-export const visibilityNarrowing: Emitter = (input) => {
-  const { findings, pending } = narrowings(input);
-  if (pending.length > 0) {
-    throw new Error(
-      `${String(pending.length)} finding(s) a declared edge holds pending, and no edge evaluation is published`,
-    );
-  }
-  return findings;
-};
+/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
+export const visibilityNarrowing: Emitter = narrowings;

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