@descent-vtt/spec-graph 0.2.0

package/dist/graph.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The specification graph.
+ *
+ * An immutable, fully indexed view over the resolved corpus. Construction pays
+ * for adjacency in both directions once so that every rule, query and report is
+ * a lookup rather than a scan - the difference between a linter that runs on
+ * every save and one that gets moved to a nightly job and then ignored.
+ *
+ * The algorithms here are the ones the rules genuinely need and no more:
+ * adjacency, reachability, and Tarjan's strongly connected components for
+ * finding circular delegations.
+ */
+import type { DocumentNode, Edge, EdgeKind, ItemNode, SpecNode } from './types.js';
+export interface SpecGraph {
+    readonly nodes: ReadonlyMap<string, SpecNode>;
+    readonly edges: readonly Edge[];
+    readonly documents: readonly DocumentNode[];
+    readonly items: readonly ItemNode[];
+    node(id: string): SpecNode | undefined;
+    document(id: string): DocumentNode | undefined;
+    /** The document a node belongs to: itself, or the item's owner. */
+    owningDocument(id: string): DocumentNode | undefined;
+    itemsOf(documentId: string): readonly ItemNode[];
+    /** Edges leaving `id`, optionally filtered by kind. */
+    out(id: string, kinds?: readonly EdgeKind[]): readonly Edge[];
+    /** Edges entering `id`, optionally filtered by kind. */
+    in(id: string, kinds?: readonly EdgeKind[]): readonly Edge[];
+    /**
+     * Every node reachable from `id` over the given edge kinds, with the shortest
+     * path to each. `id` itself is included only when a cycle returns to it.
+     */
+    reach(id: string, kinds: readonly EdgeKind[]): ReadonlyMap<string, readonly Edge[]>;
+    /**
+     * Strongly connected components with more than one member, over the given
+     * edge kinds. Each is a real cycle.
+     *
+     * With `byDocument`, relations are projected onto the documents that own
+     * their endpoints before the search. That is what catches two documents
+     * ping-ponging one obligation: the delegation runs item -> document in each
+     * direction, so there is no cycle among the raw nodes even though the two
+     * documents are plainly passing the same question back and forth.
+     */
+    cycles(kinds: readonly EdgeKind[], options?: {
+        byDocument?: boolean;
+    }): readonly (readonly string[])[];
+}
+/** Builds the graph. Edges naming an unknown node are dropped, not stored. */
+export declare function buildGraph(input: {
+    readonly nodes: ReadonlyMap<string, SpecNode>;
+    readonly edges: readonly Edge[];
+}): SpecGraph;
+/** Edge kinds that move an obligation from one document to another. */
+export declare const OBLIGATION_EDGES: readonly EdgeKind[];
+/** Edge kinds whose source depends on what the target says. */
+export declare const LOAD_BEARING_EDGES: readonly EdgeKind[];

package/dist/graph.js

@@ -0,0 +1,201 @@
+/**
+ * The specification graph.
+ *
+ * An immutable, fully indexed view over the resolved corpus. Construction pays
+ * for adjacency in both directions once so that every rule, query and report is
+ * a lookup rather than a scan - the difference between a linter that runs on
+ * every save and one that gets moved to a nightly job and then ignored.
+ *
+ * The algorithms here are the ones the rules genuinely need and no more:
+ * adjacency, reachability, and Tarjan's strongly connected components for
+ * finding circular delegations.
+ */
+import { EDGE_TRAITS } from './types.js';
+/** Builds the graph. Edges naming an unknown node are dropped, not stored. */
+export function buildGraph(input) {
+    const nodes = input.nodes;
+    const edges = input.edges.filter((edge) => nodes.has(edge.from) && nodes.has(edge.to));
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const edge of edges) {
+        push(outgoing, edge.from, edge);
+        push(incoming, edge.to, edge);
+    }
+    const documents = [];
+    const items = [];
+    const itemsByDocument = new Map();
+    for (const node of nodes.values()) {
+        if (node.kind === 'document')
+            documents.push(node);
+        else {
+            items.push(node);
+            push(itemsByDocument, node.document, node);
+        }
+    }
+    const filter = (list, kinds) => {
+        if (!list)
+            return EMPTY_EDGES;
+        if (!kinds || kinds.length === 0)
+            return list;
+        return list.filter((edge) => kinds.includes(edge.kind));
+    };
+    const graph = {
+        nodes,
+        edges,
+        documents,
+        items,
+        node: (id) => nodes.get(id),
+        document: (id) => {
+            const found = nodes.get(id);
+            return found?.kind === 'document' ? found : undefined;
+        },
+        owningDocument: (id) => {
+            const found = nodes.get(id);
+            if (!found)
+                return undefined;
+            if (found.kind === 'document')
+                return found;
+            const owner = nodes.get(found.document);
+            return owner?.kind === 'document' ? owner : undefined;
+        },
+        itemsOf: (documentId) => itemsByDocument.get(documentId) ?? EMPTY_ITEMS,
+        out: (id, kinds) => filter(outgoing.get(id), kinds),
+        in: (id, kinds) => filter(incoming.get(id), kinds),
+        reach(id, kinds) {
+            const paths = new Map();
+            const queue = [id];
+            const pathTo = new Map([[id, EMPTY_EDGES]]);
+            while (queue.length > 0) {
+                const current = queue.shift();
+                const prefix = pathTo.get(current);
+                for (const edge of filter(outgoing.get(current), kinds)) {
+                    if (pathTo.has(edge.to) && edge.to !== id)
+                        continue;
+                    const path = [...prefix, edge];
+                    if (edge.to === id) {
+                        // A cycle back to the origin: record it, but do not re-expand.
+                        if (!paths.has(id))
+                            paths.set(id, path);
+                        continue;
+                    }
+                    pathTo.set(edge.to, path);
+                    paths.set(edge.to, path);
+                    queue.push(edge.to);
+                }
+            }
+            return paths;
+        },
+        cycles(kinds, options) {
+            const relevant = (id) => [...filter(outgoing.get(id), kinds)];
+            if (!options?.byDocument) {
+                return tarjan([...nodes.keys()], (id) => relevant(id).map((edge) => edge.to).filter((to) => nodes.has(to)));
+            }
+            const ownerOf = (id) => graph.owningDocument(id)?.id ?? id;
+            const projected = new Map();
+            for (const node of nodes.values()) {
+                for (const edge of relevant(node.id)) {
+                    const from = ownerOf(edge.from);
+                    const to = ownerOf(edge.to);
+                    // A relation that stays inside one document is a self-reference, not
+                    // a cycle, and has a rule of its own.
+                    if (from === to)
+                        continue;
+                    const set = projected.get(from) ?? new Set();
+                    set.add(to);
+                    projected.set(from, set);
+                }
+            }
+            return tarjan(documents.map((document) => document.id), (id) => [...(projected.get(id) ?? [])]);
+        },
+    };
+    return graph;
+}
+const EMPTY_EDGES = Object.freeze([]);
+const EMPTY_ITEMS = Object.freeze([]);
+function push(map, key, value) {
+    const list = map.get(key);
+    if (list)
+        list.push(value);
+    else
+        map.set(key, [value]);
+}
+/* -------------------------------------------------------------------------- */
+/* Cycles                                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * Tarjan's strongly connected components, iterative.
+ *
+ * Iterative rather than recursive because a monorepo's reference graph can be
+ * deep enough to blow the call stack, and a linter that crashes on the largest
+ * repository in the company is a linter nobody trusts on the small ones either.
+ *
+ * Takes a successor function so the same search serves both the raw graph and
+ * the document-level projection.
+ */
+function tarjan(ids, successors) {
+    const indexOf = new Map();
+    const lowLink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const components = [];
+    let counter = 0;
+    for (const root of ids) {
+        if (indexOf.has(root))
+            continue;
+        const work = [
+            { id: root, next: 0, children: successors(root) },
+        ];
+        indexOf.set(root, counter);
+        lowLink.set(root, counter);
+        counter += 1;
+        stack.push(root);
+        onStack.add(root);
+        while (work.length > 0) {
+            const frame = work[work.length - 1];
+            if (frame.next < frame.children.length) {
+                const child = frame.children[frame.next];
+                frame.next += 1;
+                if (!indexOf.has(child)) {
+                    indexOf.set(child, counter);
+                    lowLink.set(child, counter);
+                    counter += 1;
+                    stack.push(child);
+                    onStack.add(child);
+                    work.push({ id: child, next: 0, children: successors(child) });
+                }
+                else if (onStack.has(child)) {
+                    lowLink.set(frame.id, Math.min(lowLink.get(frame.id), indexOf.get(child)));
+                }
+                continue;
+            }
+            work.pop();
+            const parent = work[work.length - 1];
+            if (parent) {
+                lowLink.set(parent.id, Math.min(lowLink.get(parent.id), lowLink.get(frame.id)));
+            }
+            if (lowLink.get(frame.id) === indexOf.get(frame.id)) {
+                const component = [];
+                for (;;) {
+                    const popped = stack.pop();
+                    onStack.delete(popped);
+                    component.push(popped);
+                    if (popped === frame.id)
+                        break;
+                }
+                if (component.length > 1)
+                    components.push(component.reverse());
+                else if (successors(frame.id).includes(frame.id))
+                    components.push(component);
+            }
+        }
+    }
+    return components;
+}
+/* -------------------------------------------------------------------------- */
+/* Derived predicates                                                         */
+/* -------------------------------------------------------------------------- */
+/** Edge kinds that move an obligation from one document to another. */
+export const OBLIGATION_EDGES = Object.freeze(Object.keys(EDGE_TRAITS).filter((kind) => EDGE_TRAITS[kind].transfersObligation));
+/** Edge kinds whose source depends on what the target says. */
+export const LOAD_BEARING_EDGES = Object.freeze(Object.keys(EDGE_TRAITS).filter((kind) => EDGE_TRAITS[kind].loadBearing));
+//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The specification graph.\n *\n * An immutable, fully indexed view over the resolved corpus. Construction pays\n * for adjacency in both directions once so that every rule, query and report is\n * a lookup rather than a scan - the difference between a linter that runs on\n * every save and one that gets moved to a nightly job and then ignored.\n *\n * The algorithms here are the ones the rules genuinely need and no more:\n * adjacency, reachability, and Tarjan's strongly connected components for\n * finding circular delegations.\n */\n\nimport type { DocumentNode, Edge, EdgeKind, ItemNode, SpecNode } from './types.js';\nimport { EDGE_TRAITS } from './types.js';\n\nexport interface SpecGraph {\n  readonly nodes: ReadonlyMap<string, SpecNode>;\n  readonly edges: readonly Edge[];\n  readonly documents: readonly DocumentNode[];\n  readonly items: readonly ItemNode[];\n\n  node(id: string): SpecNode | undefined;\n  document(id: string): DocumentNode | undefined;\n  /** The document a node belongs to: itself, or the item's owner. */\n  owningDocument(id: string): DocumentNode | undefined;\n  itemsOf(documentId: string): readonly ItemNode[];\n\n  /** Edges leaving `id`, optionally filtered by kind. */\n  out(id: string, kinds?: readonly EdgeKind[]): readonly Edge[];\n  /** Edges entering `id`, optionally filtered by kind. */\n  in(id: string, kinds?: readonly EdgeKind[]): readonly Edge[];\n\n  /**\n   * Every node reachable from `id` over the given edge kinds, with the shortest\n   * path to each. `id` itself is included only when a cycle returns to it.\n   */\n  reach(id: string, kinds: readonly EdgeKind[]): ReadonlyMap<string, readonly Edge[]>;\n\n  /**\n   * Strongly connected components with more than one member, over the given\n   * edge kinds. Each is a real cycle.\n   *\n   * With `byDocument`, relations are projected onto the documents that own\n   * their endpoints before the search. That is what catches two documents\n   * ping-ponging one obligation: the delegation runs item -> document in each\n   * direction, so there is no cycle among the raw nodes even though the two\n   * documents are plainly passing the same question back and forth.\n   */\n  cycles(kinds: readonly EdgeKind[], options?: { byDocument?: boolean }): readonly (readonly string[])[];\n}\n\n/** Builds the graph. Edges naming an unknown node are dropped, not stored. */\nexport function buildGraph(input: {\n  readonly nodes: ReadonlyMap<string, SpecNode>;\n  readonly edges: readonly Edge[];\n}): SpecGraph {\n  const nodes = input.nodes;\n  const edges = input.edges.filter((edge) => nodes.has(edge.from) && nodes.has(edge.to));\n\n  const outgoing = new Map<string, Edge[]>();\n  const incoming = new Map<string, Edge[]>();\n  for (const edge of edges) {\n    push(outgoing, edge.from, edge);\n    push(incoming, edge.to, edge);\n  }\n\n  const documents: DocumentNode[] = [];\n  const items: ItemNode[] = [];\n  const itemsByDocument = new Map<string, ItemNode[]>();\n  for (const node of nodes.values()) {\n    if (node.kind === 'document') documents.push(node);\n    else {\n      items.push(node);\n      push(itemsByDocument, node.document, node);\n    }\n  }\n\n  const filter = (list: readonly Edge[] | undefined, kinds?: readonly EdgeKind[]): readonly Edge[] => {\n    if (!list) return EMPTY_EDGES;\n    if (!kinds || kinds.length === 0) return list;\n    return list.filter((edge) => kinds.includes(edge.kind));\n  };\n\n  const graph: SpecGraph = {\n    nodes,\n    edges,\n    documents,\n    items,\n\n    node: (id) => nodes.get(id),\n    document: (id) => {\n      const found = nodes.get(id);\n      return found?.kind === 'document' ? found : undefined;\n    },\n    owningDocument: (id) => {\n      const found = nodes.get(id);\n      if (!found) return undefined;\n      if (found.kind === 'document') return found;\n      const owner = nodes.get(found.document);\n      return owner?.kind === 'document' ? owner : undefined;\n    },\n    itemsOf: (documentId) => itemsByDocument.get(documentId) ?? EMPTY_ITEMS,\n\n    out: (id, kinds) => filter(outgoing.get(id), kinds),\n    in: (id, kinds) => filter(incoming.get(id), kinds),\n\n    reach(id, kinds) {\n      const paths = new Map<string, readonly Edge[]>();\n      const queue: string[] = [id];\n      const pathTo = new Map<string, readonly Edge[]>([[id, EMPTY_EDGES]]);\n\n      while (queue.length > 0) {\n        const current = queue.shift() as string;\n        const prefix = pathTo.get(current) as readonly Edge[];\n        for (const edge of filter(outgoing.get(current), kinds)) {\n          if (pathTo.has(edge.to) && edge.to !== id) continue;\n          const path = [...prefix, edge];\n          if (edge.to === id) {\n            // A cycle back to the origin: record it, but do not re-expand.\n            if (!paths.has(id)) paths.set(id, path);\n            continue;\n          }\n          pathTo.set(edge.to, path);\n          paths.set(edge.to, path);\n          queue.push(edge.to);\n        }\n      }\n      return paths;\n    },\n\n    cycles(kinds, options) {\n      const relevant = (id: string): Edge[] => [...filter(outgoing.get(id), kinds)];\n      if (!options?.byDocument) {\n        return tarjan([...nodes.keys()], (id) => relevant(id).map((edge) => edge.to).filter((to) => nodes.has(to)));\n      }\n      const ownerOf = (id: string): string => graph.owningDocument(id)?.id ?? id;\n      const projected = new Map<string, Set<string>>();\n      for (const node of nodes.values()) {\n        for (const edge of relevant(node.id)) {\n          const from = ownerOf(edge.from);\n          const to = ownerOf(edge.to);\n          // A relation that stays inside one document is a self-reference, not\n          // a cycle, and has a rule of its own.\n          if (from === to) continue;\n          const set = projected.get(from) ?? new Set<string>();\n          set.add(to);\n          projected.set(from, set);\n        }\n      }\n      return tarjan(\n        documents.map((document) => document.id),\n        (id) => [...(projected.get(id) ?? [])],\n      );\n    },\n  };\n\n  return graph;\n}\n\nconst EMPTY_EDGES: readonly Edge[] = Object.freeze([]);\nconst EMPTY_ITEMS: readonly ItemNode[] = Object.freeze([]);\n\nfunction push<T>(map: Map<string, T[]>, key: string, value: T): void {\n  const list = map.get(key);\n  if (list) list.push(value);\n  else map.set(key, [value]);\n}\n\n/* -------------------------------------------------------------------------- */\n/* Cycles                                                                     */\n/* -------------------------------------------------------------------------- */\n\n/**\n * Tarjan's strongly connected components, iterative.\n *\n * Iterative rather than recursive because a monorepo's reference graph can be\n * deep enough to blow the call stack, and a linter that crashes on the largest\n * repository in the company is a linter nobody trusts on the small ones either.\n *\n * Takes a successor function so the same search serves both the raw graph and\n * the document-level projection.\n */\nfunction tarjan(ids: readonly string[], successors: (id: string) => string[]): string[][] {\n  const indexOf = new Map<string, number>();\n  const lowLink = new Map<string, number>();\n  const onStack = new Set<string>();\n  const stack: string[] = [];\n  const components: string[][] = [];\n  let counter = 0;\n\n  for (const root of ids) {\n    if (indexOf.has(root)) continue;\n\n    const work: { id: string; next: number; children: string[] }[] = [\n      { id: root, next: 0, children: successors(root) },\n    ];\n    indexOf.set(root, counter);\n    lowLink.set(root, counter);\n    counter += 1;\n    stack.push(root);\n    onStack.add(root);\n\n    while (work.length > 0) {\n      const frame = work[work.length - 1] as { id: string; next: number; children: string[] };\n      if (frame.next < frame.children.length) {\n        const child = frame.children[frame.next] as string;\n        frame.next += 1;\n        if (!indexOf.has(child)) {\n          indexOf.set(child, counter);\n          lowLink.set(child, counter);\n          counter += 1;\n          stack.push(child);\n          onStack.add(child);\n          work.push({ id: child, next: 0, children: successors(child) });\n        } else if (onStack.has(child)) {\n          lowLink.set(frame.id, Math.min(lowLink.get(frame.id) as number, indexOf.get(child) as number));\n        }\n        continue;\n      }\n\n      work.pop();\n      const parent = work[work.length - 1];\n      if (parent) {\n        lowLink.set(parent.id, Math.min(lowLink.get(parent.id) as number, lowLink.get(frame.id) as number));\n      }\n\n      if (lowLink.get(frame.id) === indexOf.get(frame.id)) {\n        const component: string[] = [];\n        for (;;) {\n          const popped = stack.pop() as string;\n          onStack.delete(popped);\n          component.push(popped);\n          if (popped === frame.id) break;\n        }\n        if (component.length > 1) components.push(component.reverse());\n        else if (successors(frame.id).includes(frame.id)) components.push(component);\n      }\n    }\n  }\n\n  return components;\n}\n\n/* -------------------------------------------------------------------------- */\n/* Derived predicates                                                         */\n/* -------------------------------------------------------------------------- */\n\n/** Edge kinds that move an obligation from one document to another. */\nexport const OBLIGATION_EDGES: readonly EdgeKind[] = Object.freeze(\n  (Object.keys(EDGE_TRAITS) as EdgeKind[]).filter((kind) => EDGE_TRAITS[kind].transfersObligation),\n);\n\n/** Edge kinds whose source depends on what the target says. */\nexport const LOAD_BEARING_EDGES: readonly EdgeKind[] = Object.freeze(\n  (Object.keys(EDGE_TRAITS) as EdgeKind[]).filter((kind) => EDGE_TRAITS[kind].loadBearing),\n);\n"]}

package/dist/identity.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Document identity and reference normalisation.
+ *
+ * Foreign-key validation across a corpus of Markdown only works if `ADR-7`,
+ * `ADR-0007`, `adr 7`, `[[0007-sharding]]` and `../adr/0007-sharding.md` are
+ * understood to name the same document. Getting that wrong in either direction
+ * is fatal: too strict and every real repository drowns in false "broken
+ * reference" findings, too loose and `RFC 7` silently resolves to `ADR-7`.
+ *
+ * The resolution here is deliberately asymmetric. **Textual aliases** (`adr-7`)
+ * are global, because a prefix already names the family. **Bare numbers** (`7`,
+ * `#0007`) are resolved only within the citing document's own family, because a
+ * repository with both `adr/0007` and `rfc/0007` is normal and guessing between
+ * them would be worse than reporting nothing.
+ */
+/** Front-matter keys that may carry an explicit identifier, in preference order. */
+export declare const ID_KEYS: readonly string[];
+export interface DocumentIdentity {
+    /** The canonical id: `ADR-0007`, or a path when nothing better exists. */
+    readonly id: string;
+    /** Family prefix, upper-cased. `null` when the document is not numbered. */
+    readonly family: string | null;
+    /** Sequence number without leading zeros. `null` when not numbered. */
+    readonly number: number | null;
+    /** Every lower-cased spelling that should resolve to this document. */
+    readonly aliases: readonly string[];
+}
+export interface IdentityInput {
+    /** Repository-relative POSIX path. */
+    readonly path: string;
+    /** An id declared by a directive or front matter, if any. */
+    readonly declaredId: string | null;
+    /** Extra aliases declared by a directive or front matter. */
+    readonly declaredAliases: readonly string[];
+    /** The document H1, if any. */
+    readonly heading: string | null;
+    /**
+     * Register the file path and stem as aliases. Default true.
+     *
+     * A specification that is a *region* of a file must not claim the file's
+     * path: the file already answers to it, and two nodes answering to one path
+     * would make every link to that file ambiguous.
+     */
+    readonly includePathAliases?: boolean | undefined;
+}
+/**
+ * Derives a document's canonical id and every alias that should reach it.
+ *
+ * Evidence is used in order of how deliberate it is: an explicit declaration,
+ * then the file name, then the H1. Whatever loses still contributes aliases, so
+ * a reference written in any of those forms still resolves.
+ */
+export declare function identify(input: IdentityInput): DocumentIdentity;
+/**
+ * Folds a reference to its lookup key.
+ *
+ * Case, separators and surrounding punctuation carry no meaning in a citation,
+ * so `ADR-0007`, `adr 0007` and `Adr_0007` all become `adr0007`.
+ */
+export declare function normaliseRef(value: string): string;
+/** Splits a `target#anchor` reference. */
+export declare function splitAnchor(target: string): {
+    target: string;
+    anchor: string | null;
+};
+/** Parses `ADR-0007` into its family and number, or returns `null`. */
+export declare function parsePrefixedRef(value: string): {
+    family: string;
+    number: number;
+} | null;
+/** Parses a bare `7` or `#0007`, or returns `null`. */
+export declare function parseBareRef(value: string): number | null;
+/** True when a reference target names a location rather than an identifier. */
+export declare function looksLikePath(target: string): boolean;
+/**
+ * True when a path-like target could name a specification.
+ *
+ * A specification linking to `../../src/rules.ts` is citing source code, which
+ * is a different tool's job. Treating it as a dangling specification reference
+ * would report an error on one of the most ordinary things a design document
+ * does, so targets carrying a non-document extension are not references at all.
+ */
+export declare function isDocumentTarget(target: string): boolean;
+/** True when a reference target points outside the repository. */
+export declare function isExternal(target: string): boolean;
+/** The family prefix implied by a document's directory, if any. */
+export declare function familyFromPath(posixPath: string): string | null;

package/dist/identity.js

@@ -0,0 +1,294 @@
+/**
+ * Document identity and reference normalisation.
+ *
+ * Foreign-key validation across a corpus of Markdown only works if `ADR-7`,
+ * `ADR-0007`, `adr 7`, `[[0007-sharding]]` and `../adr/0007-sharding.md` are
+ * understood to name the same document. Getting that wrong in either direction
+ * is fatal: too strict and every real repository drowns in false "broken
+ * reference" findings, too loose and `RFC 7` silently resolves to `ADR-7`.
+ *
+ * The resolution here is deliberately asymmetric. **Textual aliases** (`adr-7`)
+ * are global, because a prefix already names the family. **Bare numbers** (`7`,
+ * `#0007`) are resolved only within the citing document's own family, because a
+ * repository with both `adr/0007` and `rfc/0007` is normal and guessing between
+ * them would be worse than reporting nothing.
+ */
+/** Directory names that name a specification family, mapped to a canonical prefix. */
+const FAMILY_DIRECTORIES = {
+    adr: 'ADR',
+    adrs: 'ADR',
+    'architecture-decisions': 'ADR',
+    'decision-records': 'ADR',
+    decisions: 'ADR',
+    rfc: 'RFC',
+    rfcs: 'RFC',
+    kep: 'KEP',
+    keps: 'KEP',
+    enhancements: 'KEP',
+    proposal: 'PROPOSAL',
+    proposals: 'PROPOSAL',
+    design: 'DESIGN',
+    designs: 'DESIGN',
+    prd: 'PRD',
+    prds: 'PRD',
+    spec: 'SPEC',
+    specs: 'SPEC',
+};
+/** Front-matter keys that may carry an explicit identifier, in preference order. */
+export const ID_KEYS = ['id', 'adr', 'adr-id', 'rfc', 'rfc-id', 'kep-number', 'number', 'slug'];
+/** `ADR-0007`, `KEP 1234`, `rfc2119`: a family prefix followed by a number. */
+const PREFIXED_ID = /^([A-Za-z][A-Za-z0-9_]{0,15}?)[\s._-]*(\d{1,6})$/;
+/** A bare number, optionally hash-prefixed: `7`, `#0007`. */
+const BARE_NUMBER = /^#?(\d{1,6})$/;
+/**
+ * Derives a document's canonical id and every alias that should reach it.
+ *
+ * Evidence is used in order of how deliberate it is: an explicit declaration,
+ * then the file name, then the H1. Whatever loses still contributes aliases, so
+ * a reference written in any of those forms still resolves.
+ */
+export function identify(input) {
+    const stem = fileStem(input.path);
+    const directoryFamily = familyFromPath(input.path);
+    const aliases = new Set();
+    const add = (value) => {
+        if (!value)
+            return;
+        const key = normaliseRef(value);
+        if (key.length > 0)
+            aliases.add(key);
+    };
+    const candidates = [];
+    const consider = (raw, allowBare) => {
+        if (!raw)
+            return;
+        const cleaned = raw.trim();
+        if (cleaned.length === 0)
+            return;
+        const prefixed = PREFIXED_ID.exec(cleaned);
+        if (prefixed) {
+            candidates.push({
+                family: prefixed[1].toUpperCase(),
+                number: Number.parseInt(prefixed[2], 10),
+                label: cleaned,
+            });
+            return;
+        }
+        const bare = BARE_NUMBER.exec(cleaned);
+        if (bare && allowBare) {
+            candidates.push({
+                family: directoryFamily,
+                number: Number.parseInt(bare[1], 10),
+                label: cleaned,
+            });
+            return;
+        }
+        candidates.push({ family: null, number: null, label: cleaned });
+    };
+    consider(input.declaredId, true);
+    // `0007-sharding-the-write-path.md` and `kep-1234-foo.md` both start with the
+    // identifier; take the leading token rather than the whole stem.
+    consider(leadingToken(stem), true);
+    consider(headingId(input.heading), false);
+    const numbered = candidates.find((c) => c.number !== null);
+    const family = numbered?.family ?? directoryFamily;
+    const number = numbered?.number ?? null;
+    // Witnesses to the local zero-padding convention, most authoritative first.
+    // The spelling that actually produced the number comes first: an id read from
+    // the H1 of `sharding.md` must still render as ADR-0007, not ADR-7.
+    const witnesses = [numbered?.label, input.declaredId, stem];
+    let id;
+    if (number !== null && family !== null) {
+        id = `${family}-${padNumber(number, witnesses)}`;
+    }
+    else if (input.declaredId) {
+        id = input.declaredId.trim();
+    }
+    else if (number !== null) {
+        // Numbered but with no family to prefix - a Rust RFC in `text/0001-foo.md`,
+        // say. The file stem is a far better identity than a bare "1": it is what
+        // people actually type, and it stays unique across the repository.
+        id = stem.length > 0 ? stem : String(number);
+    }
+    else {
+        id = stem.length > 0 ? stem : input.path;
+    }
+    add(id);
+    if (input.includePathAliases !== false) {
+        add(stem);
+        add(input.path);
+        add(stripExtension(input.path));
+    }
+    add(input.declaredId);
+    for (const alias of input.declaredAliases)
+        add(alias);
+    if (input.heading)
+        add(headingId(input.heading));
+    if (number !== null) {
+        const spellings = numberSpellings(number, witnesses);
+        if (family !== null) {
+            // Every spelling a human might type. `normaliseRef` folds separators, so
+            // `adr-7`, `adr 7` and `adr7` collapse to one key; the padding variants do
+            // not, and each needs registering.
+            for (const digits of spellings)
+                add(`${family}-${digits}`);
+        }
+        else {
+            // With no family there is only one number space in the repository, so a
+            // bare `0001` is unambiguous and worth resolving.
+            for (const digits of spellings)
+                add(digits);
+        }
+    }
+    return { id, family, number, aliases: [...aliases] };
+}
+/**
+ * Folds a reference to its lookup key.
+ *
+ * Case, separators and surrounding punctuation carry no meaning in a citation,
+ * so `ADR-0007`, `adr 0007` and `Adr_0007` all become `adr0007`.
+ */
+export function normaliseRef(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/^[#<([]+|[)\]>.,;:]+$/g, '')
+        .replace(/[\s._-]+/g, '')
+        .trim();
+}
+/** Splits a `target#anchor` reference. */
+export function splitAnchor(target) {
+    const hash = target.indexOf('#');
+    if (hash === -1)
+        return { target, anchor: null };
+    // A leading `#` is an in-document anchor, not a separator.
+    if (hash === 0)
+        return { target: '', anchor: target.slice(1) };
+    return { target: target.slice(0, hash), anchor: target.slice(hash + 1) };
+}
+/** Parses `ADR-0007` into its family and number, or returns `null`. */
+export function parsePrefixedRef(value) {
+    const match = PREFIXED_ID.exec(value.trim().replace(/^[#([]+/, ''));
+    if (!match)
+        return null;
+    return { family: match[1].toUpperCase(), number: Number.parseInt(match[2], 10) };
+}
+/** Parses a bare `7` or `#0007`, or returns `null`. */
+export function parseBareRef(value) {
+    const match = BARE_NUMBER.exec(value.trim());
+    return match ? Number.parseInt(match[1], 10) : null;
+}
+/** True when a reference target names a location rather than an identifier. */
+export function looksLikePath(target) {
+    return target.includes('/') || DOCUMENT_EXTENSION.test(target);
+}
+const DOCUMENT_EXTENSION = /\.(md|markdown|mdx|txt|rst|adoc|asciidoc)$/i;
+/**
+ * True when a path-like target could name a specification.
+ *
+ * A specification linking to `../../src/rules.ts` is citing source code, which
+ * is a different tool's job. Treating it as a dangling specification reference
+ * would report an error on one of the most ordinary things a design document
+ * does, so targets carrying a non-document extension are not references at all.
+ */
+export function isDocumentTarget(target) {
+    const withoutAnchor = splitAnchor(target).target;
+    const base = withoutAnchor.slice(withoutAnchor.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    // No extension: a directory, or an extensionless spec such as `rfcs/0007`.
+    if (dot <= 0)
+        return true;
+    const extension = base.slice(dot);
+    // Only a plausible file extension disqualifies a target. An identifier like
+    // `v1.2` or `ADR-0007.1` keeps its dot and is still resolved as an id.
+    if (!/^\.[A-Za-z][A-Za-z0-9]{0,5}$/.test(extension))
+        return true;
+    return DOCUMENT_EXTENSION.test(base);
+}
+/** True when a reference target points outside the repository. */
+export function isExternal(target) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(target) && !/^[a-z]:[\\/]/i.test(target);
+}
+/** The family prefix implied by a document's directory, if any. */
+export function familyFromPath(posixPath) {
+    const segments = posixPath.toLowerCase().split('/');
+    // Nearest enclosing directory wins: `docs/rfcs/adr/0007.md` is an ADR.
+    for (let i = segments.length - 2; i >= 0; i -= 1) {
+        const found = FAMILY_DIRECTORIES[segments[i]];
+        if (found)
+            return found;
+    }
+    return null;
+}
+/* -------------------------------------------------------------------------- */
+/* Internals                                                                  */
+/* -------------------------------------------------------------------------- */
+function fileStem(posixPath) {
+    const base = posixPath.slice(posixPath.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    const stem = dot > 0 ? base.slice(0, dot) : base;
+    // `docs/adr/0007-sharding/README.md` is identified by its directory - but a
+    // README at the repository root has no directory to be named after, and must
+    // keep its own name.
+    const slash = posixPath.lastIndexOf('/');
+    if (slash > 0 && /^(readme|index)$/i.test(stem)) {
+        const parent = posixPath.slice(0, slash);
+        return parent.slice(parent.lastIndexOf('/') + 1);
+    }
+    return stem;
+}
+function stripExtension(posixPath) {
+    const dot = posixPath.lastIndexOf('.');
+    const slash = posixPath.lastIndexOf('/');
+    return dot > slash ? posixPath.slice(0, dot) : posixPath;
+}
+/** `kep-1234-foo` -> `kep-1234`; `0007-sharding` -> `0007`; `sharding` -> `sharding`. */
+function leadingToken(stem) {
+    const prefixed = /^([A-Za-z]{1,15}[\s._-]?\d{1,6})(?:[\s._-]|$)/.exec(stem);
+    if (prefixed)
+        return prefixed[1];
+    const bare = /^(\d{1,6})(?:[\s._-]|$)/.exec(stem);
+    if (bare)
+        return bare[1];
+    return stem;
+}
+/** `# ADR-0007: Sharding the write path` -> `ADR-0007`. */
+function headingId(heading) {
+    if (!heading)
+        return null;
+    const match = /^\s*([A-Za-z]{1,15}[\s._-]?\d{1,6})\b/.exec(heading);
+    return match ? match[1] : null;
+}
+/**
+ * Chooses the digit width of the canonical id.
+ *
+ * A repository that writes `0007` everywhere should see `ADR-0007` in reports,
+ * not `ADR-7`. The file name is the most reliable witness of the local
+ * convention, so it decides.
+ */
+function padNumber(number, witnesses) {
+    const width = paddingWidth(number, witnesses) ?? String(number).length;
+    return String(number).padStart(width, '0');
+}
+/** The digit width of the first witness that actually spells this number. */
+function paddingWidth(number, witnesses) {
+    for (const witness of witnesses) {
+        if (!witness)
+            continue;
+        const digits = /(\d{1,6})/.exec(witness)?.[1];
+        if (digits && Number.parseInt(digits, 10) === number)
+            return digits.length;
+    }
+    return null;
+}
+/** Zero-padded spellings a citation might reasonably use. */
+function numberSpellings(number, witnesses) {
+    const out = new Set([String(number)]);
+    const observed = paddingWidth(number, witnesses);
+    if (observed !== null)
+        out.add(String(number).padStart(observed, '0'));
+    for (const width of [3, 4])
+        out.add(String(number).padStart(width, '0'));
+    return [...out];
+}
+//# sourceMappingURL=identity.js.map