@aoelite/refpact-ts 0.0.0-stage → 0.1.2

package/dist/core/results.d.ts

@@ -0,0 +1,237 @@
+/** What the core gives back: violations, errors, and baselines (SPEC sections 4, 5 and 7). */
+import type { Certainty, FactSet, Path } from "./model.ts";
+/** The violations in fact order, or the reasons why the rule cannot be evaluated. */
+export type EvaluateResult = {
+    readonly ok: true;
+    /** The violations in fact order. May be empty. */
+    readonly violations: readonly Violation[];
+} | {
+    readonly ok: false;
+    /** The reasons, in the order of the specification. */
+    readonly errors: readonly RuleError[];
+};
+/** One place where the code breaks a rule. */
+export interface Violation {
+    /** The name of the rule. */
+    readonly rule: string;
+    /** The unit that breaks the rule. */
+    readonly unit: Path;
+    /**
+     * The file of the place. For a violation about a unit as a whole, the file of the first
+     * fact of the unit, or empty.
+     */
+    readonly file: string;
+    /** The line, or 0 for a violation about a unit as a whole. */
+    readonly line: number;
+    /** The column, or 0 for a violation about a unit as a whole. */
+    readonly column: number;
+    /** The note of the fact, when it has one. */
+    readonly note?: string;
+    /** What the unit does. */
+    readonly detail: Detail;
+}
+/**
+ * What a violation is about.
+ *
+ * - `uses`: the unit refers to a path that the rule does not allow.
+ * - `contains`: the unit contains a marker that the rule forbids.
+ * - `cycle`: one cycle of a tangle, which is a group of nodes that all reach each other.
+ * - `unused`: nothing outside the unit and the units below it refers to it.
+ * - `reaches`: a chain of references leads from the unit to a forbidden target.
+ * - `unreachable`: no chain of references leads from a root to the unit.
+ * - `outside`: the unit is in none of the places of the rule.
+ * - `item`: a declaration that does not meet a rule about items.
+ * - `custom`: what a check of the user found.
+ */
+export type Detail = {
+    readonly type: "uses";
+    /** For a rule about items: the item whose code has the reference. */
+    readonly item?: Path;
+    /** The forbidden path. */
+    readonly target: Path;
+    /** The path as the code names it, when it differs from `target`. */
+    readonly written?: Path;
+    /** The kind of the reference. */
+    readonly kind: string;
+    /** Whether the front end proved the path. */
+    readonly certainty: Certainty;
+} | {
+    readonly type: "contains";
+    /** The marker. */
+    readonly marker: string;
+} | {
+    readonly type: "cycle";
+    /** The edges of the cycle, in order. The last step leads back to the first node. */
+    readonly steps: readonly Step[];
+    /** The number of nodes in the tangle. */
+    readonly size: number;
+} | {
+    readonly type: "unused";
+} | {
+    readonly type: "reaches";
+    /** The edges from the unit to the unit that uses the target. Empty when the unit uses the target itself. */
+    readonly steps: readonly Step[];
+    /** The use of the target at the end of the chain. */
+    readonly end: End;
+} | {
+    readonly type: "unreachable";
+} | {
+    readonly type: "outside";
+} | {
+    readonly type: "item";
+    /** The path of the item. */
+    readonly item: Path;
+    /** The kind of the item. */
+    readonly kind: string;
+} | {
+    /** The unit, or one declaration of it, has more lines than the rule allows (SPEC 4.16). */
+    readonly type: "too-long";
+    /** For a rule about items: the path of the item. */
+    readonly item?: Path;
+    /** For a rule about items: the kind of the item. */
+    readonly kind?: string;
+    /** The number of lines. */
+    readonly lines: number;
+    /** The number of lines that the rule allows. */
+    readonly limit: number;
+} | {
+    readonly type: "custom";
+    /** What the unit does, printed after the unit. */
+    readonly message: string;
+    /** What a baseline counts the violation as. Absent: the message. */
+    readonly key?: string;
+};
+/** What a rule sees (SPEC section 8), or the reasons why the rule cannot be evaluated. Units, facts and declarations are given by their position in the fact set. */
+export type SelectResult = {
+    /** The rule can be evaluated. */
+    readonly ok: true;
+    /** The units that the rule selects. */
+    readonly subjects: readonly number[];
+    /** For each list of unit patterns of the check: the units that it matches. */
+    readonly units: readonly (readonly number[])[];
+    /** The references that the rule sees, of all units, in the order of the facts. */
+    readonly references: readonly SelectedReference[];
+    /** The markers of the subjects that the rule sees. */
+    readonly markers: readonly number[];
+    /** The declarations of the subjects that the rule sees. */
+    readonly declarations: readonly number[];
+    /** For a rule about items: the declarations that its filters select. */
+    readonly items?: readonly number[];
+} | {
+    /** The rule cannot be evaluated. */
+    readonly ok: false;
+    /** The reasons, in the order of the specification. */
+    readonly errors: readonly RuleError[];
+};
+/** A reference that a rule sees. */
+export interface SelectedReference {
+    /** The position of the fact. */
+    readonly fact: number;
+    /** The unit of the fact. */
+    readonly unit: number;
+    /** For each path of the reference, `[target, ...aliases]`: the unit that owns it, or `null`. */
+    readonly owners: readonly (number | null)[];
+    /**
+     * For each list of targets of the check: the first path that it matches, by its place in
+     * `[target, ...aliases]`, or `null`. Absent when no list matches a path.
+     */
+    readonly hits?: readonly (number | null)[];
+    /** For a rule about items: the reference is inside an item that the filters select. */
+    readonly inside?: true;
+}
+/** The reference at the end of a chain: the use of the forbidden target. */
+export interface End {
+    /** The unit that uses the target. */
+    readonly unit: Path;
+    /** The file of the use. */
+    readonly file: string;
+    /** The line of the use. */
+    readonly line: number;
+    /** The column of the use. */
+    readonly column: number;
+    /** The forbidden path. */
+    readonly target: Path;
+    /** The kind of the reference. */
+    readonly kind: string;
+}
+/** One edge of a cycle or of a chain, with the reference that makes it. */
+export interface Step {
+    /** The node the edge leaves. */
+    readonly from: Path;
+    /** The node the edge leads to. */
+    readonly to: Path;
+    /** The file of the reference. */
+    readonly file: string;
+    /** The line of the reference. */
+    readonly line: number;
+    /** The column of the reference. */
+    readonly column: number;
+    /** The path the reference names. */
+    readonly target: Path;
+    /** The kind of the reference. */
+    readonly kind: string;
+}
+/** Why a rule cannot be evaluated (SPEC section 5). */
+export interface RuleError {
+    /** The check that failed. */
+    readonly code: ErrorCode;
+    /** The part of the rule or of the fact set that the error is about, when there is one. */
+    readonly role?: Role;
+    /** The offending value, such as a pattern, when there is one. */
+    readonly value?: string;
+}
+/** The check that failed (SPEC section 5). */
+export type ErrorCode = "invalid-facts" | "empty-name" | "empty-list" | "invalid-pattern" | "pattern-matches-nothing" | "no-subjects" | "too-few-nodes" | "unknown-marker" | "unknown-kind" | "unknown-tag" | "unused-exemption" | "unknown-item-kind" | "unknown-visibility" | "unknown-relation" | "unknown-modifier" | "unknown-property";
+/** The part of a rule or of a fact set that an error is about. */
+export type Role = "unit" | "subject" | "subject-exception" | "target" | "unverified-target" | "marker" | "slice" | "root" | "kind" | "tag" | "place" | "user" | "exemption-from" | "exemption-to" | "exemption" | "name" | "item-kind" | "visibility" | "relation" | "related" | "required-name" | "required" | "modifier" | "required-modifier" | "layer" | "property";
+/**
+ * How reports and baselines print paths (SPEC section 3). A fact set is a path format, so a
+ * report can take the fact set itself.
+ */
+export type PathFormat = Pick<FactSet, "separator" | "attachedPrefixes" | "hiddenPrefixes">;
+/** One line of a baseline: `count` accepted violations with one key. */
+export interface BaselineEntry {
+    /** The name of the rule. */
+    readonly rule: string;
+    /** The unit, printed as in reports. */
+    readonly unit: string;
+    /** What the violations are, as SPEC section 7 writes it for each kind of violation. */
+    readonly what: string;
+    /** The number of accepted violations with this key. */
+    readonly count: number;
+}
+/** An entry that accepts more violations than the code has. */
+export interface StaleEntry {
+    /** The unit of the entry. */
+    readonly unit: string;
+    /** What the entry accepts, as in {@link BaselineEntry.what}. */
+    readonly what: string;
+    /** The number of violations that the baseline accepts for this key. */
+    readonly count: number;
+    /** The number of violations that the code has. */
+    readonly found: number;
+}
+/** The entries, or the number of the first invalid line, from 1. */
+export type ParsedBaseline = {
+    readonly ok: true;
+    /** The entries, in the order of the text. */
+    readonly entries: readonly BaselineEntry[];
+} | {
+    readonly ok: false;
+    /** The number of the first invalid line, from 1. */
+    readonly line: number;
+};
+/** The result of `applyBaseline`. */
+export interface Applied {
+    /** The violations that the baseline does not accept. */
+    readonly remaining: readonly Violation[];
+    /** The entries that accept more violations than the code has. */
+    readonly stale: readonly StaleEntry[];
+}
+/** The key of a violation in a baseline. */
+export interface BaselineKey {
+    /** The unit, printed as in reports. */
+    readonly unit: string;
+    /** What the violation is, as SPEC section 7 writes it. */
+    readonly what: string;
+}

package/dist/core/results.js

@@ -0,0 +1 @@
+export {};

package/dist/core/wasm.d.ts

@@ -0,0 +1,7 @@
+/** The instance that the handles of fact sets belong to. */
+export declare function currentGeneration(): number;
+/**
+ * Sends one request and returns the answer as JSON text. Throws when the core finds the
+ * request not valid, which is a bug of this package and not of the rule.
+ */
+export declare function call(request: string): string;

package/dist/core/wasm.js

@@ -0,0 +1,67 @@
+/**
+ * The core of refpact, the Rust crate `refpact-core`, as WebAssembly (SPEC section 8).
+ *
+ * The module is `wasm/refpact_core.wasm` beside `src` and `dist`, built by `cargo xtask wasm`.
+ * It is compiled once, on the first call, and speaks JSON requests. This is the only file of
+ * the core that reads a file.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** The version of the wire format that this package speaks. */
+const VERSION = 1;
+let core;
+/** Counts the instances. A handle of a fact set is valid only in the instance that made it. */
+let generation = 0;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function instance() {
+    if (core !== undefined) {
+        return core;
+    }
+    const url = new URL("../../wasm/refpact_core.wasm", import.meta.url);
+    let bytes;
+    try {
+        bytes = readFileSync(url);
+    }
+    catch (cause) {
+        throw new Error(`refpact: the core is missing at ${fileURLToPath(url)}. Build it with \`cargo xtask wasm\`.`, { cause });
+    }
+    const made = new WebAssembly.Instance(new WebAssembly.Module(bytes), {}).exports;
+    core = made;
+    generation += 1;
+    const { version } = JSON.parse(call('{"op":"version"}'));
+    if (version !== VERSION) {
+        core = undefined;
+        throw new Error(`refpact: the core speaks version ${version} of the wire format, not ${VERSION}. Build it again with \`cargo xtask wasm\`.`);
+    }
+    return made;
+}
+/** The instance that the handles of fact sets belong to. */
+export function currentGeneration() {
+    instance();
+    return generation;
+}
+/**
+ * Sends one request and returns the answer as JSON text. Throws when the core finds the
+ * request not valid, which is a bug of this package and not of the rule.
+ */
+export function call(request) {
+    const exports = instance();
+    const bytes = encoder.encode(request);
+    const address = exports.refpact_alloc(bytes.length);
+    new Uint8Array(exports.memory.buffer, address, bytes.length).set(bytes);
+    let status;
+    try {
+        status = exports.refpact_call(address, bytes.length);
+    }
+    catch (error) {
+        // A trap leaves the instance in an unknown state. The next call starts a new one.
+        core = undefined;
+        throw error;
+    }
+    const answer = decoder.decode(new Uint8Array(exports.memory.buffer, exports.refpact_answer(), exports.refpact_answer_len()));
+    if (status !== 0) {
+        throw new Error(`refpact: the core rejected a request: ${answer}`);
+    }
+    return answer;
+}

package/dist/custom.d.ts

@@ -0,0 +1,129 @@
+/** Checks of the user: what a rule sees, and how its violations are made (SPEC 4.15). */
+import type { Declaration, Detail, Fact, FactSet, Path, Reference, SelectResult, Step, Violation } from "./core/index.ts";
+/** An import that the rule sees: the filters and the exemptions of the rule let it pass. */
+export interface SeenImport {
+    /** The fact of the import. */
+    readonly fact: Fact;
+    /** The reference of the fact. */
+    readonly reference: Reference;
+    /** The file that imports. */
+    readonly file: Path;
+    /** Whether the rule selects the file that imports. */
+    readonly subject: boolean;
+    /** The paths of the import, `[target, ...aliases]`. */
+    readonly paths: readonly Path[];
+    /** For each path, the file that has it, or `undefined` for a package or a module of Node. */
+    readonly owners: readonly (Path | undefined)[];
+    /**
+     * For each list of targets that the check names: the first path of the import that the
+     * list matches. A list that matches no path of the import has no entry.
+     */
+    readonly hits: Readonly<Record<string, Path>>;
+}
+/** A marker of a selected file that the rule sees. */
+export interface SeenMarker {
+    /** The fact of the marker. */
+    readonly fact: Fact;
+    /** The file. */
+    readonly file: Path;
+    /** The marker. */
+    readonly marker: string;
+}
+/** An edge of the graph of files, with the first import that makes it. */
+export interface ImportEdge {
+    /** The file that the edge leads to. */
+    readonly to: Path;
+    /** The fact of the import. */
+    readonly fact: Fact;
+    /** The path of the import that leads to the file. */
+    readonly target: Path;
+}
+/** The names of the lists of patterns of a check, in the order of the lists in the request. @internal */
+export interface ListNames {
+    readonly targets: readonly string[];
+    readonly files: readonly string[];
+}
+type Selection = Extract<SelectResult, {
+    ok: true;
+}>;
+/**
+ * What a check of the user gets: the files that the rule selects and what the rule sees. The
+ * rule has applied its filters and its exemptions.
+ */
+export declare class Scope {
+    /** The name of the rule. */
+    readonly ruleName: string;
+    /** The facts of the project. */
+    readonly facts: FactSet;
+    /** The files that the rule selects, in order. */
+    readonly subjects: readonly Path[];
+    /** The imports that the rule sees, of all files, in the order of the facts. */
+    readonly imports: readonly SeenImport[];
+    /** The markers of the selected files that the rule sees. */
+    readonly markers: readonly SeenMarker[];
+    /** The declarations of the selected files that the rule sees. */
+    readonly declarations: readonly Declaration[];
+    /** @internal */
+    protected readonly selection: Selection;
+    private readonly selected;
+    private readonly lists;
+    private firstFiles;
+    private made;
+    /** @internal */
+    constructor(ruleName: string, facts: FactSet, selection: Selection, names: ListNames);
+    /** Whether the rule selects the file. */
+    selects(file: Path): boolean;
+    /**
+     * The files that a list of file patterns of the check matches, by the name of the list.
+     * The files match as the files of a rule do. Throws when the check names no such list.
+     */
+    matched(list: string): readonly Path[];
+    /**
+     * The graph of all files, selected or not, from the imports that the rule sees. An import
+     * leads to the file of each of its paths, so an import through a barrel file leads to the
+     * barrel and to the file that declares the name. An import of the own file is no edge.
+     */
+    graph(): Graph;
+    /**
+     * A violation at the place of a fact, with its note. A message gives a `custom` detail,
+     * which a baseline counts by `key`, or by the message when there is no key.
+     */
+    violationAt(fact: Fact, detail: string | Detail, key?: string): Violation;
+    /** A violation at the place of a declaration. */
+    violationOfItem(declaration: Declaration, detail: string | Detail, baselineKey?: string): Violation;
+    /** A violation about a file as a whole, with no line. */
+    violationOfFile(file: Path, detail: string | Detail, baselineKey?: string): Violation;
+}
+/**
+ * What a check of items gets: the {@link Scope} of the rule, and the items that the filters
+ * of the rule select.
+ */
+export declare class ItemScope extends Scope {
+    /** The items that the rule selects, in order. */
+    readonly items: readonly Declaration[];
+    /**
+     * The imports that the rule sees inside the selected items. A front end that does not say
+     * which item holds an import gives none: the TypeScript front end is one.
+     */
+    readonly itemImports: readonly SeenImport[];
+    /** @internal */
+    constructor(ruleName: string, facts: FactSet, selection: Selection, names: ListNames);
+}
+/** The graph of the files of a project: see {@link Scope.graph}. */
+export declare class Graph {
+    private readonly units;
+    private readonly numbers;
+    /** For each file, by its number: the edges, each with the number of the file that it leads to. */
+    private readonly edges;
+    /** @internal */
+    constructor(facts: FactSet, selection: Selection);
+    /** The edges of a file, in the order of their first imports. A path that is no file has none. */
+    edgesOf(file: Path): readonly ImportEdge[];
+    /**
+     * A shortest chain of imports from a file to a file that is an end, as the steps of a
+     * report. No steps: the file itself is an end. `undefined`: no chain leads to an end. The
+     * search is breadth-first with the edges of each file in their order.
+     */
+    chain(from: Path, isEnd: (file: Path) => boolean): Step[] | undefined;
+}
+export {};

package/dist/custom.js

@@ -0,0 +1,217 @@
+/**
+ * What a check of the user gets: the files that the rule selects and what the rule sees. The
+ * rule has applied its filters and its exemptions.
+ */
+export class Scope {
+    /** The name of the rule. */
+    ruleName;
+    /** The facts of the project. */
+    facts;
+    /** The files that the rule selects, in order. */
+    subjects;
+    /** The imports that the rule sees, of all files, in the order of the facts. */
+    imports;
+    /** The markers of the selected files that the rule sees. */
+    markers;
+    /** The declarations of the selected files that the rule sees. */
+    declarations;
+    /** @internal */
+    selection;
+    selected;
+    lists;
+    firstFiles;
+    made;
+    /** @internal */
+    constructor(ruleName, facts, selection, names) {
+        this.ruleName = ruleName;
+        this.facts = facts;
+        this.selection = selection;
+        const units = facts.units;
+        this.subjects = selection.subjects.map((unit) => units[unit]);
+        this.selected = new Set(this.subjects.map(key));
+        this.lists = new Map(names.files.map((name, list) => [name, (selection.units[list] ?? []).map((unit) => units[unit])]));
+        const subjectSet = new Set(selection.subjects);
+        this.imports = selection.references.map((seen) => {
+            const fact = facts.facts[seen.fact];
+            const reference = fact.what;
+            const paths = [reference.target, ...reference.aliases];
+            const hits = {};
+            seen.hits?.forEach((hit, list) => {
+                if (hit !== null) {
+                    hits[names.targets[list]] = paths[hit];
+                }
+            });
+            return {
+                fact,
+                reference,
+                file: units[seen.unit],
+                subject: subjectSet.has(seen.unit),
+                paths,
+                owners: seen.owners.map((owner) => (owner === null ? undefined : units[owner])),
+                hits,
+            };
+        });
+        this.markers = selection.markers.map((position) => {
+            const fact = facts.facts[position];
+            return { fact, file: fact.unit, marker: fact.what.marker };
+        });
+        const declarations = facts.declarations ?? [];
+        this.declarations = selection.declarations.map((position) => declarations[position]);
+    }
+    /** Whether the rule selects the file. */
+    selects(file) {
+        return this.selected.has(key(file));
+    }
+    /**
+     * The files that a list of file patterns of the check matches, by the name of the list.
+     * The files match as the files of a rule do. Throws when the check names no such list.
+     */
+    matched(list) {
+        const files = this.lists.get(list);
+        if (files === undefined) {
+            throw new TypeError(`refpact: rule \`${this.ruleName}\`: the check names no list of files \`${list}\``);
+        }
+        return files;
+    }
+    /**
+     * The graph of all files, selected or not, from the imports that the rule sees. An import
+     * leads to the file of each of its paths, so an import through a barrel file leads to the
+     * barrel and to the file that declares the name. An import of the own file is no edge.
+     */
+    graph() {
+        this.made ??= new Graph(this.facts, this.selection);
+        return this.made;
+    }
+    /**
+     * A violation at the place of a fact, with its note. A message gives a `custom` detail,
+     * which a baseline counts by `key`, or by the message when there is no key.
+     */
+    violationAt(fact, detail, key) {
+        return {
+            rule: this.ruleName,
+            unit: fact.unit,
+            file: fact.file,
+            line: fact.line,
+            column: fact.column,
+            ...(fact.note !== undefined ? { note: fact.note } : {}),
+            detail: custom(detail, key),
+        };
+    }
+    /** A violation at the place of a declaration. */
+    violationOfItem(declaration, detail, baselineKey) {
+        const { unit, file, line, column } = declaration;
+        return { rule: this.ruleName, unit, file, line, column, detail: custom(detail, baselineKey) };
+    }
+    /** A violation about a file as a whole, with no line. */
+    violationOfFile(file, detail, baselineKey) {
+        if (this.firstFiles === undefined) {
+            this.firstFiles = new Map();
+            for (const fact of this.facts.facts) {
+                const unit = key(fact.unit);
+                if (!this.firstFiles.has(unit)) {
+                    this.firstFiles.set(unit, fact.file);
+                }
+            }
+        }
+        return { rule: this.ruleName, unit: file, file: this.firstFiles.get(key(file)) ?? "", line: 0, column: 0, detail: custom(detail, baselineKey) };
+    }
+}
+/**
+ * What a check of items gets: the {@link Scope} of the rule, and the items that the filters
+ * of the rule select.
+ */
+export class ItemScope extends Scope {
+    /** The items that the rule selects, in order. */
+    items;
+    /**
+     * The imports that the rule sees inside the selected items. A front end that does not say
+     * which item holds an import gives none: the TypeScript front end is one.
+     */
+    itemImports;
+    /** @internal */
+    constructor(ruleName, facts, selection, names) {
+        super(ruleName, facts, selection, names);
+        const declarations = facts.declarations ?? [];
+        this.items = (selection.items ?? []).map((position) => declarations[position]);
+        this.itemImports = this.imports.filter((_, index) => selection.references[index]?.inside === true);
+    }
+}
+/** The graph of the files of a project: see {@link Scope.graph}. */
+export class Graph {
+    units;
+    numbers;
+    /** For each file, by its number: the edges, each with the number of the file that it leads to. */
+    edges;
+    /** @internal */
+    constructor(facts, selection) {
+        this.units = facts.units;
+        this.numbers = new Map();
+        this.units.forEach((unit, number) => {
+            if (!this.numbers.has(key(unit))) {
+                this.numbers.set(key(unit), number);
+            }
+        });
+        this.edges = this.units.map(() => []);
+        const known = new Set();
+        const count = this.units.length;
+        for (const seen of selection.references) {
+            const path = seen.owners.findIndex((owner) => owner !== null);
+            const to = seen.owners[path];
+            if (to === undefined || to === null || to === seen.unit || known.has(seen.unit * count + to)) {
+                continue;
+            }
+            known.add(seen.unit * count + to);
+            const fact = facts.facts[seen.fact];
+            const reference = fact.what;
+            const target = [reference.target, ...reference.aliases][path];
+            this.edges[seen.unit].push({ to: this.units[to], node: to, fact, target });
+        }
+    }
+    /** The edges of a file, in the order of their first imports. A path that is no file has none. */
+    edgesOf(file) {
+        const node = this.numbers.get(key(file));
+        return node === undefined ? [] : this.edges[node];
+    }
+    /**
+     * A shortest chain of imports from a file to a file that is an end, as the steps of a
+     * report. No steps: the file itself is an end. `undefined`: no chain leads to an end. The
+     * search is breadth-first with the edges of each file in their order.
+     */
+    chain(from, isEnd) {
+        const start = this.numbers.get(key(from));
+        if (start === undefined) {
+            return undefined;
+        }
+        // For each file that the search found: the file and the edge that led to it.
+        const foundBy = new Map();
+        const queue = [start];
+        for (let next = 0; next < queue.length; next++) {
+            const node = queue[next];
+            if (isEnd(this.units[node])) {
+                const steps = [];
+                for (let current = node, found = foundBy.get(current); found !== undefined; current = found.from, found = foundBy.get(current)) {
+                    const { fact, target } = found.edge;
+                    const kind = fact.what.kind;
+                    steps.push({ from: this.units[found.from], to: this.units[current], file: fact.file, line: fact.line, column: fact.column, target, kind });
+                }
+                return steps.reverse();
+            }
+            for (const edge of this.edges[node] ?? []) {
+                if (edge.node !== start && !foundBy.has(edge.node)) {
+                    foundBy.set(edge.node, { from: node, edge });
+                    queue.push(edge.node);
+                }
+            }
+        }
+        return undefined;
+    }
+}
+function key(path) {
+    return path.join("\u0000");
+}
+function custom(detail, key) {
+    if (typeof detail !== "string") {
+        return detail;
+    }
+    return { type: "custom", message: detail, ...(key !== undefined ? { key } : {}) };
+}