@cplieger/deadset-ts 3.6.0 → 3.8.0

package/dist/src/findings/reads-and-writes.js

@@ -1,28 +1,12 @@
 import { positionKey } from "../position.js";
-import { findingComponents, RANK, reachabilityClasses, severityOf, } from "./completion.js";
-/**
- * Each code's severity where the configuration sets none, as the issue-kind vocabulary
- * states it.
- */
-export const DEFAULT_SEVERITY = {
-    DS1301: "deny",
-    DS1302: "deny",
-    DS1303: "deny",
-};
 /** The containers whose type parameters `DS1303` reports: a function and a class method. */
 const SIGNATURES = new Set(["function", "method"]);
-/** The severity the configuration gives one code of the family. */
-function severityIn(input, code) {
-    return severityOf(input.config, code, DEFAULT_SEVERITY[code]);
-}
 function indexed(input) {
     const { matrix, sweep } = input.swept;
     return {
         input,
         symbols: new Map(matrix.union.symbols.map((symbol) => [symbol.id, symbol])),
         candidates: new Map(sweep.candidates.map((candidate) => [candidate.id, candidate])),
-        componentOf: findingComponents(input.swept),
-        classOf: reachabilityClasses(input.swept),
     };
 }
 /** Where one declaration is, as a finding states it. */
@@ -34,11 +18,9 @@ function positionOf(symbol) {
         endLine: Math.max(symbol.position.line, symbol.endLine),
     };
 }
-/** The finding about one declaration, every member the family decides filled in. */
-function findingAbout(run, symbol, code, message, facts) {
+/** The finding one code makes about one declaration. */
+function findingAbout(symbol, code, message, details) {
     const position = positionOf(symbol);
-    const reachabilityClass = run.classOf(symbol.id);
-    const component = run.componentOf(symbol.id);
     return {
         code,
         position,
@@ -49,14 +31,7 @@ function findingAbout(run, symbol, code, message, facts) {
             sizeLines: position.endLine - position.line + 1,
         },
         message,
-        reachabilityClass,
-        confidence: reachabilityClass,
-        ...(facts.livenessRelation === undefined ? {} : { livenessRelation: facts.livenessRelation }),
-        testOnly: facts.testOnly,
-        ...(component === undefined ? {} : { component }),
-        configurations: facts.configurations,
-        severity: severityIn(run.input, code),
-        details: facts.details,
+        ...(details === undefined ? {} : { details }),
     };
 }
 /**
@@ -85,15 +60,9 @@ function writeOnlySymbols(run) {
     for (const reference of stores.references) {
         let held = uses.get(reference.to);
         if (held === undefined) {
-            held = { writes: [], reads: 0, production: 0, test: 0 };
+            held = { writes: [], reads: 0 };
             uses.set(reference.to, held);
         }
-        if (reference.test) {
-            held.test += 1;
-        }
-        else {
-            held.production += 1;
-        }
         if (reference.use !== "write") {
             held.reads += 1;
             continue;
@@ -105,7 +74,7 @@ function writeOnlySymbols(run) {
         }
     }
     const found = [];
-    matrix.union.symbols.forEach((symbol, at) => {
+    for (const symbol of matrix.union.symbols) {
         const held = uses.get(symbol.id);
         if (held === undefined ||
             held.writes.length === 0 ||
@@ -113,16 +82,14 @@ function writeOnlySymbols(run) {
             !writable(run, symbol) ||
             stores.exempt.has(symbol.id) ||
             run.candidates.has(symbol.id)) {
-            return;
+            continue;
         }
         const writes = held.writes.length === 1 ? "once" : `at ${String(held.writes.length)} positions`;
         const word = symbol.kind === "variable" ? "variable" : "member";
-        found.push(findingAbout(run, symbol, "DS1301", `${word} ${symbol.name} is written ${writes} and never read`, {
-            testOnly: held.production === 0 && held.test > 0,
-            configurations: matrix.heldIn[at] ?? [],
-            details: { writePositions: held.writes },
+        found.push(findingAbout(symbol, "DS1301", `${word} ${symbol.name} is written ${writes} and never read`, {
+            writePositions: held.writes,
         }));
-    });
+    }
     return found;
 }
 /**
@@ -139,7 +106,7 @@ function unnamed(run, kind) {
             run.candidates.has(symbol.parent)) {
             return [];
         }
-        return [[candidate, symbol]];
+        return [symbol];
     });
 }
 /**
@@ -148,12 +115,7 @@ function unnamed(run, kind) {
  * this kind.
  */
 function unusedEnumMembers(run) {
-    return unnamed(run, "enum-member").map(([candidate, symbol]) => findingAbout(run, symbol, "DS1302", `enum member ${symbol.name} is named nowhere`, {
-        livenessRelation: candidate.relation,
-        testOnly: false,
-        configurations: candidate.configurations,
-        details: {},
-    }));
+    return unnamed(run, "enum-member").map((symbol) => findingAbout(symbol, "DS1302", `enum member ${symbol.name} is named nowhere`));
 }
 /**
  * `DS1303`: a type parameter of a function or a class method that neither the
@@ -163,13 +125,8 @@ function unusedEnumMembers(run) {
  */
 function unusedTypeParameters(run) {
     return unnamed(run, "type-parameter")
-        .filter(([, symbol]) => SIGNATURES.has(run.symbols.get(symbol.parent)?.kind ?? ""))
-        .map(([candidate, symbol]) => findingAbout(run, symbol, "DS1303", `type parameter ${symbol.name} is named in neither its signature nor its body`, {
-        livenessRelation: candidate.relation,
-        testOnly: false,
-        configurations: candidate.configurations,
-        details: {},
-    }));
+        .filter((symbol) => SIGNATURES.has(run.symbols.get(symbol.parent)?.kind ?? ""))
+        .map((symbol) => findingAbout(symbol, "DS1303", `type parameter ${symbol.name} is named in neither its signature nor its body`));
 }
 /**
  * The references of the declarations the write-only kind reports, whatever the
@@ -179,21 +136,11 @@ function unusedTypeParameters(run) {
 export function writeOnlyDeclarations(input) {
     return new Set(writeOnlySymbols(indexed(input)).map((finding) => finding.symbol.ref));
 }
-/** Each code's rule, in code order. */
-const RULES = [
-    ["DS1301", writeOnlySymbols],
-    ["DS1302", unusedEnumMembers],
-    ["DS1303", unusedTypeParameters],
-];
 /**
- * The findings of the reads-and-writes family, `DS1300` to `DS1399`, each code's in site
- * order. A code the configuration sets to `allow` reports nothing, and a finding whose
- * confidence is below the configured minimum is withheld.
+ * The findings of the reads-and-writes family, `DS1300` to `DS1399`, in code order and
+ * each code's in site order.
  */
 export const readsAndWrites = (input) => {
     const run = indexed(input);
-    const least = RANK[input.config.analysis.minConfidence];
-    return RULES.flatMap(([code, rule]) => severityIn(input, code) === "allow"
-        ? []
-        : rule(run).filter((finding) => RANK[finding.confidence] >= least));
+    return [...writeOnlySymbols(run), ...unusedEnumMembers(run), ...unusedTypeParameters(run)];
 };

package/dist/src/findings/self-check.js

@@ -1,2 +1,127 @@
-/** The findings of the self-check family, `DS1700` to `DS1799`. */
-export const selfCheck = () => [];
+import { REPOSITORY_DOCUMENT } from "../config.js";
+import { STALE_SUPPRESSION, SUPPRESSION_WITHOUT_REASON, } from "../suppress.js";
+/** 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;
+/** A run with nothing for the self-check family to report. */
+export const NO_SELF_CHECK = {
+    refusals: [],
+    unmatchedRoots: [],
+    rootsDocument: "",
+};
+/** The words a message names a mechanism by. */
+const WRITTEN = {
+    inline: "inline directive",
+    ignore: "ignore entry",
+    baseline: "baseline row",
+};
+/** The file references of a run's declarations, by path. */
+export function fileRefsOf(symbols) {
+    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) {
+    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, ref, site, message) {
+    return {
+        code,
+        position: { ...site, endLine: site.line },
+        symbol: { ref, kind: SUPPRESSION_SUBJECT, name: ref, sizeLines: 1 },
+        message,
+    };
+}
+/**
+ * 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, path, files) {
+    return symbol === "" ? (files(path) ?? path) : symbol;
+}
+/** One finding per refused suppression: the grammar's reason refusal and its scope refusal. */
+export function refusedSuppressions(refusals, files) {
+    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 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, files) {
+    const bySite = new Map();
+    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, document) {
+    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 = ({ selfCheck: facts, swept }) => [
+    ...refusedSuppressions(facts.refusals, fileRefsOf(swept.matrix.union.symbols)),
+    ...unmatchedRootFindings(facts.unmatchedRoots, facts.rootsDocument),
+];

package/dist/src/findings/unused-declarations.js

@@ -1,14 +1,4 @@
-import { capped, findingComponents, reachabilityClasses, reportable, severityOf, } from "./completion.js";
 import { unreachableExports } from "./visibility-narrowing.js";
-/** The codes of the unused-declarations family, each by its row of the vocabulary. */
-export const UNUSED_DECLARATION_KINDS = new Map([
-    ["DS1001", { defaultSeverity: "deny", maxClass: "certain" }],
-    ["DS1002", { defaultSeverity: "deny", maxClass: "certain" }],
-    ["DS1003", { defaultSeverity: "deny", maxClass: "certain" }],
-    ["DS1004", { defaultSeverity: "deny", maxClass: "certain" }],
-    ["DS1005", { defaultSeverity: "deny", maxClass: "certain" }],
-    ["DS1006", { defaultSeverity: "deny", maxClass: "certain" }],
-]);
 /** The kinds of declaration that are members of a class, an interface, a type or an enum. */
 const MEMBERS = new Set([
     "method",
@@ -120,19 +110,13 @@ function messageOf(code, judged) {
     }
     return `${subject} has no reference in the target`;
 }
-/**
- * The findings of the unused-declarations family, `DS1000` to `DS1099`, completed and
- * with what the dials withhold left out.
- */
-export function unusedDeclarationFindings(input) {
-    const { config, swept } = input;
-    const union = swept.matrix.union;
-    const dead = new Set(swept.sweep.candidates.map((candidate) => candidate.id));
-    const classOf = reachabilityClasses(swept);
-    const componentOf = findingComponents(swept);
+/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
+export const unusedDeclarations = (input) => {
+    const union = input.swept.matrix.union;
+    const dead = new Set(input.swept.sweep.candidates.map((candidate) => candidate.id));
     const unreachable = unreachableExports(input);
     const found = [];
-    for (const candidate of swept.sweep.candidates) {
+    for (const candidate of input.swept.sweep.candidates) {
         const at = union.at(candidate.id);
         const symbol = union.symbols[at];
         if (symbol === undefined) {
@@ -147,16 +131,10 @@ export function unusedDeclarationFindings(input) {
             unreachable: unreachable.has(symbol.id),
         };
         const code = codeOf(judged);
-        const row = code === undefined ? undefined : UNUSED_DECLARATION_KINDS.get(code);
-        if (code === undefined || row === undefined) {
+        if (code === undefined) {
             continue;
         }
-        const component = componentOf(symbol.id);
-        if (component === undefined) {
-            throw new Error(`${symbol.id} is reported dead and falls in no dead component`);
-        }
         const endLine = Math.max(symbol.position.line, symbol.endLine);
-        const reachabilityClass = classOf(symbol.id);
         found.push({
             code,
             position: { ...symbol.position, endLine },
@@ -167,17 +145,7 @@ export function unusedDeclarationFindings(input) {
                 sizeLines: endLine - symbol.position.line + 1,
             },
             message: messageOf(code, judged),
-            reachabilityClass,
-            confidence: capped(reachabilityClass, row.maxClass),
-            livenessRelation: candidate.relation,
-            testOnly: candidate.productionRefs === 0 && candidate.testRefs > 0,
-            component,
-            configurations: candidate.configurations,
-            severity: severityOf(config, code, row.defaultSeverity),
-            details: {},
         });
     }
-    return reportable(found, config.analysis.minConfidence);
-}
-/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
-export const unusedDeclarations = unusedDeclarationFindings;
+    return found;
+};

package/dist/src/findings/visibility-narrowing.js

@@ -164,49 +164,29 @@ function unreachable(facts, at, symbol, candidate, input) {
         : "has no reference in the target";
     return findingOf(symbol, UNREACHABLE_EXPORT, `exported ${wordOf(symbol)} ${found}, and nothing outside can import the file that declares it`);
 }
-/** Two strings ordered bytewise. */
-function compare(a, b) {
-    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) {
-    const { boundary } = input;
     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(input.swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
     const findings = [];
-    const pending = [];
     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;
 }
 /**
  * The declarations the unreachable-export kind reports, whether or not a declared edge
@@ -224,16 +204,5 @@ export function unreachableExports(input) {
     }
     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 = (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 = narrowings;

package/dist/src/findings-pass.js

@@ -0,0 +1,97 @@
+/**
+ * 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 { decidedFindings } from "./findings/emitters.js";
+import { fileRefsOf, staleSuppressions, } from "./findings/self-check.js";
+import { isRowSubject, pairs, suppressionCounts } from "./suppress.js";
+import { EXIT_CLEAN, EXIT_FINDINGS } from "./verbs/verb.js";
+/** 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 = { allow: 0, warn: 1, deny: 2 };
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/** The canonical order: path, line, column, code, then the symbol reference. */
+function canonical(a, b) {
+    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) {
+    const { marked, unmarked, suppressions } = inputs;
+    const decided = decidedFindings(marked, { unmarked, records: suppressions.records });
+    const { ledger, would } = decided;
+    const stale = [];
+    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, config) {
+    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) {
+    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) {
+    return { analyzer: "deadset-ts", version };
+}

package/dist/src/json-document.js

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+/** The token walk over a document `JSON.parse` accepted, so every token is well formed. */
+class Walk {
+    opened = [];
+    /** The member written twice, where one is, as the offset of its name. */
+    twice;
+    text;
+    array;
+    at = 0;
+    constructor(text, array) {
+        this.text = text;
+        this.array = array;
+    }
+    run() {
+        this.value("document");
+    }
+    skip() {
+        while (/[ \t\r\n]/u.test(this.text[this.at] ?? "")) {
+            this.at += 1;
+        }
+    }
+    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));
+    }
+    value(role) {
+        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;
+            }
+        }
+    }
+    object(role) {
+        const seen = new Set();
+        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");
+        }
+    }
+    list(element) {
+        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);
+        }
+    }
+}
+/**
+ * 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, array) {
+    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, file, offset) {
+    const before = text.slice(0, offset);
+    const lineStart = before.lastIndexOf("\n") + 1;
+    return { path: file, line: before.split("\n").length, column: offset - lineStart + 1 };
+}