@descent-vtt/spec-graph 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,294 @@
+/**
+ * The spec-graph data model.
+ *
+ * Three ideas carry the whole design:
+ *
+ * 1. **Documents have a lifecycle phase**, normalised from whatever vocabulary
+ *    the repository already uses (MADR `accepted`, KEP `implementable`, RFC
+ *    `final`, plain English `archived`). The phase answers one question that
+ *    matters more than any other: *can this document still absorb new work?*
+ *
+ * 2. **Items are obligations with nuanced state.** A checkbox is not a boolean.
+ *    An item can be open, narrowed to a smaller scope, satisfied, consciously
+ *    accepted as debt, or obviated because the premise it rested on evaporated.
+ *    Collapsing those five into `[ ]` / `[x]` is what makes ad-hoc greps lie.
+ *
+ * 3. **Edges are typed and carry provenance.** Every relation records where it
+ *    was *declared*, which is frequently not the node it points at. That is what
+ *    lets a diagnostic say "ADR-0009 line 12 claims to supersede ADR-0003"
+ *    instead of "something, somewhere, is inconsistent".
+ */
+/** A point in a source file. `offset` is a UTF-16 code-unit index. */
+export interface Position {
+    readonly offset: number;
+    /** 1-based. */
+    readonly line: number;
+    /** 1-based, counted in UTF-16 code units. */
+    readonly column: number;
+}
+/** A half-open `[start, end)` range of a source file. */
+export interface Span {
+    readonly start: Position;
+    readonly end: Position;
+}
+/** A span plus the file it belongs to. Everything user-visible carries one. */
+export interface SourceRef {
+    /** Repository-relative POSIX path. */
+    readonly file: string;
+    readonly span: Span;
+}
+/**
+ * The normalised document lifecycle, as a four-state lattice.
+ *
+ * Ecosystem vocabularies are large and mutually incompatible; the *consequences*
+ * of a status are not. These four phases are chosen so that every question
+ * spec-graph asks can be answered from the phase alone.
+ *
+ * - `draft`   - not yet binding. Mutable. Absorbs new work.
+ * - `active`  - binding and mutable. Absorbs new work.
+ * - `frozen`  - binding and immutable. Changes require a new document.
+ * - `retired` - no longer binding: superseded, rejected, withdrawn, archived.
+ *
+ * `unknown` is a fifth, deliberately non-lattice value for documents that never
+ * declared a status. Rules treat it permissively rather than guessing.
+ */
+export type Phase = 'draft' | 'active' | 'frozen' | 'retired' | 'record' | 'unknown';
+/**
+ * Can a document in this phase take on a *new* open obligation?
+ *
+ * This is the single predicate behind ghost-handover detection. Delegating an
+ * open question into a `frozen` or `retired` document is a write to a closed
+ * ledger: nobody will ever read it again.
+ */
+export type Receptivity = 'receptive' | 'sealed' | 'unknown';
+/**
+ * How much of an obligation is left.
+ *
+ * Kept separate from {@link Disposition} because the two answer different
+ * questions: `openness` is "does someone still owe work?", `disposition` is
+ * "what happened to it?". Rules almost always want the former; humans reading a
+ * report always want the latter.
+ */
+export type Openness = 'open' | 'partial' | 'closed';
+/** Why an item is in the state it is in. */
+export type Disposition = 
+/** Nothing has happened yet. */
+'unresolved'
+/** Scope was cut down, but a remainder is still owed. */
+ | 'narrowed'
+/** Ownership moved elsewhere. Still owed - by somebody else. */
+ | 'delegated'
+/** Done, answered, decided. */
+ | 'satisfied'
+/** Knowingly not done. A closed item with a scar. */
+ | 'accepted-debt'
+/** Decided against. */
+ | 'rejected'
+/**
+ * The premise evaporated, so the question stopped being a question.
+ * Load-bearing citations to an obviated item are stale premises.
+ */
+ | 'obviated';
+export declare const DISPOSITIONS: readonly Disposition[];
+/** The openness implied by each disposition. */
+export declare const OPENNESS_OF: Readonly<Record<Disposition, Openness>>;
+/**
+ * Relation kinds.
+ *
+ * The set is small on purpose. Two orthogonal properties - declared once in
+ * {@link EDGE_TRAITS} - do the actual work, so adding a kind never means
+ * touching a rule.
+ */
+export type EdgeKind = 
+/** Structural: a document contains an item. Never inferred from prose. */
+'contains'
+/** A neutral citation. */
+ | 'references'
+/** Explicitly *not* load-bearing: "See also", "History", "Prior art". */
+ | 'relates-to'
+/** The source design depends on the target content. */
+ | 'depends-on'
+/** The source rests on a claim made by the target. */
+ | 'assumes'
+/** The source hands an obligation to the target. */
+ | 'delegates-to'
+/** The source cannot proceed until the target does. */
+ | 'blocked-by'
+/** The source replaces the target. */
+ | 'supersedes'
+/** The source modifies the target without replacing it. */
+ | 'amends';
+export interface EdgeTraits {
+    /**
+     * Does the source continued validity depend on what the target says?
+     *
+     * Load-bearing edges into retired documents are stale premises. Non
+     * load-bearing ones ("see also") are just history, and reporting them would
+     * bury the real findings - which is exactly how ad-hoc linters lose trust.
+     */
+    readonly loadBearing: boolean;
+    /** Does the edge move an obligation from source to target? */
+    readonly transfersObligation: boolean;
+    /** Does the edge assert something about the target lifecycle? */
+    readonly lifecycle: boolean;
+    /** Human-readable phrase used in diagnostics: "ADR-1 <phrase> ADR-2". */
+    readonly phrase: string;
+}
+export declare const EDGE_TRAITS: Readonly<Record<EdgeKind, EdgeTraits>>;
+export declare const EDGE_KINDS: readonly EdgeKind[];
+/** How an edge came to exist. Reported verbatim so findings are auditable. */
+export type EdgeOrigin = 
+/** A `<!-- @spec-edge -->` directive. */
+'directive'
+/** A front-matter field such as `supersedes:` or `superseded-by:`. */
+ | 'front-matter'
+/** A Markdown link, classified by the section it sits in. */
+ | 'link'
+/** A bare textual identifier such as `ADR-0007` in prose. */
+ | 'text'
+/** Synthesised by the extractor (document -> item). */
+ | 'structural';
+export interface Edge {
+    readonly kind: EdgeKind;
+    /** Node id. */
+    readonly from: string;
+    /** Node id. */
+    readonly to: string;
+    readonly origin: EdgeOrigin;
+    /**
+     * Where the relation was written down. Not necessarily inside `from`: a
+     * `superseded-by: ADR-9` field in ADR-3 declares `ADR-9 supersedes ADR-3`,
+     * and the only place a human can go fix it is ADR-3.
+     */
+    readonly declaredAt: SourceRef;
+    /** The raw text that produced the edge, for diagnostics. */
+    readonly raw: string;
+    /**
+     * Every file that declares this relation.
+     *
+     * A supersession stated only in the superseding document leaves the
+     * superseded one silently presenting itself as current, which is a finding in
+     * its own right - so the set of declaration sites has to survive de-duplication.
+     */
+    readonly declaredIn: readonly string[];
+    /** True when `from` and `to` are the same node. Kept, never traversed. */
+    readonly reflexive: boolean;
+}
+export type NodeKind = 'document' | 'item';
+interface NodeBase {
+    /** Canonical, graph-unique. Documents: `ADR-0007`. Items: `ADR-0007#q.1`. */
+    readonly id: string;
+    readonly kind: NodeKind;
+    /** Short human label used in reports. */
+    readonly title: string;
+    readonly at: SourceRef;
+}
+export interface DocumentNode extends NodeBase {
+    readonly kind: 'document';
+    /** Repository-relative POSIX path. */
+    readonly path: string;
+    /** Every spelling that resolves to this document, lowercased. */
+    readonly aliases: readonly string[];
+    readonly phase: Phase;
+    /** The status string as written, before normalisation. `null` if absent. */
+    readonly rawStatus: string | null;
+    /** Where the status was declared, when it was declared anywhere. */
+    readonly statusAt: SourceRef | null;
+    /** Front-matter fields, flattened to strings and string arrays. */
+    readonly frontMatter: Readonly<Record<string, string | readonly string[]>>;
+}
+export interface ItemNode extends NodeBase {
+    readonly kind: 'item';
+    /** Owning document id. */
+    readonly document: string;
+    /** Heading path the item sits under, outermost first. */
+    readonly section: readonly string[];
+    /** First line of the item, normalised to one line for reports. */
+    readonly text: string;
+    /** The full multi-line body, continuations included. */
+    readonly body: string;
+    readonly disposition: Disposition;
+    readonly openness: Openness;
+    /** Which signal decided the disposition. */
+    readonly evidence: StateSignal;
+    /** Conflicting signals found while resolving the state. */
+    readonly conflicts: readonly StateSignal[];
+}
+export type SpecNode = DocumentNode | ItemNode;
+/** One observation about an item state. */
+export interface StateSignal {
+    /** Higher wins. See `SIGNAL_PRIORITY` in `state.ts`. */
+    readonly source: 'directive' | 'marker' | 'strikethrough' | 'checkbox' | 'section' | 'default';
+    readonly disposition: Disposition;
+    /** The literal text that produced the signal. */
+    readonly raw: string;
+    readonly at: SourceRef;
+}
+export type DanglingReason = 
+/** Nothing in the corpus answers to this identifier. */
+'unknown-target'
+/** More than one document answers to it. */
+ | 'ambiguous'
+/** The path exists on disk but is not a parsed specification. */
+ | 'not-a-spec'
+/** The document resolved, but the `#anchor` did not. */
+ | 'unknown-anchor';
+/** A citation that failed foreign-key validation. */
+export interface DanglingRef {
+    readonly kind: EdgeKind;
+    readonly from: string;
+    /** The identifier as written. */
+    readonly target: string;
+    readonly reason: DanglingReason;
+    readonly origin: EdgeOrigin;
+    readonly declaredAt: SourceRef;
+    readonly raw: string;
+    /** Candidate ids when `reason` is `ambiguous`, or near-misses otherwise. */
+    readonly candidates: readonly string[];
+}
+export type Severity = 'error' | 'warn' | 'info' | 'off';
+export type RuleId = 'ghost-handover' | 'stale-premise' | 'broken-reference' | 'reference-outside-corpus' | 'ambiguous-reference' | 'circular-delegation' | 'orphaned-obligation' | 'unreciprocated-supersession' | 'live-supersession' | 'state-conflict' | 'self-reference';
+export interface RelatedLocation {
+    readonly at: SourceRef;
+    readonly note: string;
+}
+export interface Diagnostic {
+    readonly rule: RuleId;
+    readonly severity: Exclude<Severity, 'off'>;
+    /** One line, no trailing period. The headline of the finding. */
+    readonly message: string;
+    /** Where a human should go to fix it. */
+    readonly at: SourceRef;
+    /** Node ids involved, most relevant first. */
+    readonly nodes: readonly string[];
+    /**
+     * The citation this finding is about, for the rules that are about one.
+     *
+     * `null` everywhere else, where `nodes` already names the subject. It exists
+     * because a broken reference names something that is not a node - that is
+     * what makes it broken - and a baseline still has to be able to tell one
+     * broken reference from another. See ADR-0012.
+     */
+    readonly target: string | null;
+    /** Supporting locations: the other end of an edge, a cycle members. */
+    readonly related: readonly RelatedLocation[];
+    /** Concrete next action. */
+    readonly hint: string;
+}
+/** A problem with the input itself, as opposed to a finding about the graph. */
+export interface ParseProblem {
+    readonly message: string;
+    readonly at: SourceRef;
+}
+export interface AnalysisSummary {
+    readonly documents: number;
+    readonly items: number;
+    readonly edges: number;
+    readonly openObligations: number;
+    readonly errors: number;
+    readonly warnings: number;
+    readonly infos: number;
+    /** Milliseconds, wall clock. */
+    readonly durationMs: number;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,52 @@
+/**
+ * The spec-graph data model.
+ *
+ * Three ideas carry the whole design:
+ *
+ * 1. **Documents have a lifecycle phase**, normalised from whatever vocabulary
+ *    the repository already uses (MADR `accepted`, KEP `implementable`, RFC
+ *    `final`, plain English `archived`). The phase answers one question that
+ *    matters more than any other: *can this document still absorb new work?*
+ *
+ * 2. **Items are obligations with nuanced state.** A checkbox is not a boolean.
+ *    An item can be open, narrowed to a smaller scope, satisfied, consciously
+ *    accepted as debt, or obviated because the premise it rested on evaporated.
+ *    Collapsing those five into `[ ]` / `[x]` is what makes ad-hoc greps lie.
+ *
+ * 3. **Edges are typed and carry provenance.** Every relation records where it
+ *    was *declared*, which is frequently not the node it points at. That is what
+ *    lets a diagnostic say "ADR-0009 line 12 claims to supersede ADR-0003"
+ *    instead of "something, somewhere, is inconsistent".
+ */
+export const DISPOSITIONS = Object.freeze([
+    'unresolved',
+    'narrowed',
+    'delegated',
+    'satisfied',
+    'accepted-debt',
+    'rejected',
+    'obviated',
+]);
+/** The openness implied by each disposition. */
+export const OPENNESS_OF = Object.freeze({
+    unresolved: 'open',
+    narrowed: 'partial',
+    delegated: 'open',
+    satisfied: 'closed',
+    'accepted-debt': 'closed',
+    rejected: 'closed',
+    obviated: 'closed',
+});
+export const EDGE_TRAITS = Object.freeze({
+    contains: { loadBearing: false, transfersObligation: false, lifecycle: false, phrase: 'contains' },
+    references: { loadBearing: false, transfersObligation: false, lifecycle: false, phrase: 'references' },
+    'relates-to': { loadBearing: false, transfersObligation: false, lifecycle: false, phrase: 'relates to' },
+    'depends-on': { loadBearing: true, transfersObligation: false, lifecycle: false, phrase: 'depends on' },
+    assumes: { loadBearing: true, transfersObligation: false, lifecycle: false, phrase: 'assumes' },
+    'delegates-to': { loadBearing: false, transfersObligation: true, lifecycle: false, phrase: 'delegates to' },
+    'blocked-by': { loadBearing: true, transfersObligation: true, lifecycle: false, phrase: 'is blocked by' },
+    supersedes: { loadBearing: false, transfersObligation: false, lifecycle: true, phrase: 'supersedes' },
+    amends: { loadBearing: true, transfersObligation: false, lifecycle: true, phrase: 'amends' },
+});
+export const EDGE_KINDS = Object.keys(EDGE_TRAITS);
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA4FH,MAAM,CAAC,MAAM,YAAY,GAA2B,MAAM,CAAC,MAAM,CAAC;IAChE,YAAY;IACZ,UAAU;IACV,WAAW;IACX,WAAW;IACX,eAAe;IACf,UAAU;IACV,UAAU;CACX,CAAC,CAAC;AAEH,gDAAgD;AAChD,MAAM,CAAC,MAAM,WAAW,GAA4C,MAAM,CAAC,MAAM,CAAC;IAChF,UAAU,EAAE,MAAM;IAClB,QAAQ,EAAE,SAAS;IACnB,SAAS,EAAE,MAAM;IACjB,SAAS,EAAE,QAAQ;IACnB,eAAe,EAAE,QAAQ;IACzB,QAAQ,EAAE,QAAQ;IAClB,QAAQ,EAAE,QAAQ;CACnB,CAAC,CAAC;AAkDH,MAAM,CAAC,MAAM,WAAW,GAA2C,MAAM,CAAC,MAAM,CAAC;IAC/E,QAAQ,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE;IAClG,UAAU,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE;IACtG,YAAY,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE;IACxG,YAAY,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE;IACvG,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE;IAC/F,cAAc,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE;IAC3G,YAAY,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE;IACzG,UAAU,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE;IACrG,MAAM,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE;CAC7F,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAwB,CAAC","sourcesContent":["/**\n * The spec-graph data model.\n *\n * Three ideas carry the whole design:\n *\n * 1. **Documents have a lifecycle phase**, normalised from whatever vocabulary\n *    the repository already uses (MADR `accepted`, KEP `implementable`, RFC\n *    `final`, plain English `archived`). The phase answers one question that\n *    matters more than any other: *can this document still absorb new work?*\n *\n * 2. **Items are obligations with nuanced state.** A checkbox is not a boolean.\n *    An item can be open, narrowed to a smaller scope, satisfied, consciously\n *    accepted as debt, or obviated because the premise it rested on evaporated.\n *    Collapsing those five into `[ ]` / `[x]` is what makes ad-hoc greps lie.\n *\n * 3. **Edges are typed and carry provenance.** Every relation records where it\n *    was *declared*, which is frequently not the node it points at. That is what\n *    lets a diagnostic say \"ADR-0009 line 12 claims to supersede ADR-0003\"\n *    instead of \"something, somewhere, is inconsistent\".\n */\n\n/* -------------------------------------------------------------------------- */\n/* Source positions                                                           */\n/* -------------------------------------------------------------------------- */\n\n/** A point in a source file. `offset` is a UTF-16 code-unit index. */\nexport interface Position {\n  readonly offset: number;\n  /** 1-based. */\n  readonly line: number;\n  /** 1-based, counted in UTF-16 code units. */\n  readonly column: number;\n}\n\n/** A half-open `[start, end)` range of a source file. */\nexport interface Span {\n  readonly start: Position;\n  readonly end: Position;\n}\n\n/** A span plus the file it belongs to. Everything user-visible carries one. */\nexport interface SourceRef {\n  /** Repository-relative POSIX path. */\n  readonly file: string;\n  readonly span: Span;\n}\n\n/* -------------------------------------------------------------------------- */\n/* Lifecycle                                                                  */\n/* -------------------------------------------------------------------------- */\n\n/**\n * The normalised document lifecycle, as a four-state lattice.\n *\n * Ecosystem vocabularies are large and mutually incompatible; the *consequences*\n * of a status are not. These four phases are chosen so that every question\n * spec-graph asks can be answered from the phase alone.\n *\n * - `draft`   - not yet binding. Mutable. Absorbs new work.\n * - `active`  - binding and mutable. Absorbs new work.\n * - `frozen`  - binding and immutable. Changes require a new document.\n * - `retired` - no longer binding: superseded, rejected, withdrawn, archived.\n *\n * `unknown` is a fifth, deliberately non-lattice value for documents that never\n * declared a status. Rules treat it permissively rather than guessing.\n */\nexport type Phase = 'draft' | 'active' | 'frozen' | 'retired' | 'record' | 'unknown';\n\n/**\n * Can a document in this phase take on a *new* open obligation?\n *\n * This is the single predicate behind ghost-handover detection. Delegating an\n * open question into a `frozen` or `retired` document is a write to a closed\n * ledger: nobody will ever read it again.\n */\nexport type Receptivity = 'receptive' | 'sealed' | 'unknown';\n\n/* -------------------------------------------------------------------------- */\n/* Item state                                                                 */\n/* -------------------------------------------------------------------------- */\n\n/**\n * How much of an obligation is left.\n *\n * Kept separate from {@link Disposition} because the two answer different\n * questions: `openness` is \"does someone still owe work?\", `disposition` is\n * \"what happened to it?\". Rules almost always want the former; humans reading a\n * report always want the latter.\n */\nexport type Openness = 'open' | 'partial' | 'closed';\n\n/** Why an item is in the state it is in. */\nexport type Disposition =\n  /** Nothing has happened yet. */\n  | 'unresolved'\n  /** Scope was cut down, but a remainder is still owed. */\n  | 'narrowed'\n  /** Ownership moved elsewhere. Still owed - by somebody else. */\n  | 'delegated'\n  /** Done, answered, decided. */\n  | 'satisfied'\n  /** Knowingly not done. A closed item with a scar. */\n  | 'accepted-debt'\n  /** Decided against. */\n  | 'rejected'\n  /**\n   * The premise evaporated, so the question stopped being a question.\n   * Load-bearing citations to an obviated item are stale premises.\n   */\n  | 'obviated';\n\nexport const DISPOSITIONS: readonly Disposition[] = Object.freeze([\n  'unresolved',\n  'narrowed',\n  'delegated',\n  'satisfied',\n  'accepted-debt',\n  'rejected',\n  'obviated',\n]);\n\n/** The openness implied by each disposition. */\nexport const OPENNESS_OF: Readonly<Record<Disposition, Openness>> = Object.freeze({\n  unresolved: 'open',\n  narrowed: 'partial',\n  delegated: 'open',\n  satisfied: 'closed',\n  'accepted-debt': 'closed',\n  rejected: 'closed',\n  obviated: 'closed',\n});\n\n/* -------------------------------------------------------------------------- */\n/* Edges                                                                      */\n/* -------------------------------------------------------------------------- */\n\n/**\n * Relation kinds.\n *\n * The set is small on purpose. Two orthogonal properties - declared once in\n * {@link EDGE_TRAITS} - do the actual work, so adding a kind never means\n * touching a rule.\n */\nexport type EdgeKind =\n  /** Structural: a document contains an item. Never inferred from prose. */\n  | 'contains'\n  /** A neutral citation. */\n  | 'references'\n  /** Explicitly *not* load-bearing: \"See also\", \"History\", \"Prior art\". */\n  | 'relates-to'\n  /** The source design depends on the target content. */\n  | 'depends-on'\n  /** The source rests on a claim made by the target. */\n  | 'assumes'\n  /** The source hands an obligation to the target. */\n  | 'delegates-to'\n  /** The source cannot proceed until the target does. */\n  | 'blocked-by'\n  /** The source replaces the target. */\n  | 'supersedes'\n  /** The source modifies the target without replacing it. */\n  | 'amends';\n\nexport interface EdgeTraits {\n  /**\n   * Does the source continued validity depend on what the target says?\n   *\n   * Load-bearing edges into retired documents are stale premises. Non\n   * load-bearing ones (\"see also\") are just history, and reporting them would\n   * bury the real findings - which is exactly how ad-hoc linters lose trust.\n   */\n  readonly loadBearing: boolean;\n  /** Does the edge move an obligation from source to target? */\n  readonly transfersObligation: boolean;\n  /** Does the edge assert something about the target lifecycle? */\n  readonly lifecycle: boolean;\n  /** Human-readable phrase used in diagnostics: \"ADR-1 <phrase> ADR-2\". */\n  readonly phrase: string;\n}\n\nexport const EDGE_TRAITS: Readonly<Record<EdgeKind, EdgeTraits>> = Object.freeze({\n  contains: { loadBearing: false, transfersObligation: false, lifecycle: false, phrase: 'contains' },\n  references: { loadBearing: false, transfersObligation: false, lifecycle: false, phrase: 'references' },\n  'relates-to': { loadBearing: false, transfersObligation: false, lifecycle: false, phrase: 'relates to' },\n  'depends-on': { loadBearing: true, transfersObligation: false, lifecycle: false, phrase: 'depends on' },\n  assumes: { loadBearing: true, transfersObligation: false, lifecycle: false, phrase: 'assumes' },\n  'delegates-to': { loadBearing: false, transfersObligation: true, lifecycle: false, phrase: 'delegates to' },\n  'blocked-by': { loadBearing: true, transfersObligation: true, lifecycle: false, phrase: 'is blocked by' },\n  supersedes: { loadBearing: false, transfersObligation: false, lifecycle: true, phrase: 'supersedes' },\n  amends: { loadBearing: true, transfersObligation: false, lifecycle: true, phrase: 'amends' },\n});\n\nexport const EDGE_KINDS = Object.keys(EDGE_TRAITS) as readonly EdgeKind[];\n\n/** How an edge came to exist. Reported verbatim so findings are auditable. */\nexport type EdgeOrigin =\n  /** A `<!-- @spec-edge -->` directive. */\n  | 'directive'\n  /** A front-matter field such as `supersedes:` or `superseded-by:`. */\n  | 'front-matter'\n  /** A Markdown link, classified by the section it sits in. */\n  | 'link'\n  /** A bare textual identifier such as `ADR-0007` in prose. */\n  | 'text'\n  /** Synthesised by the extractor (document -> item). */\n  | 'structural';\n\nexport interface Edge {\n  readonly kind: EdgeKind;\n  /** Node id. */\n  readonly from: string;\n  /** Node id. */\n  readonly to: string;\n  readonly origin: EdgeOrigin;\n  /**\n   * Where the relation was written down. Not necessarily inside `from`: a\n   * `superseded-by: ADR-9` field in ADR-3 declares `ADR-9 supersedes ADR-3`,\n   * and the only place a human can go fix it is ADR-3.\n   */\n  readonly declaredAt: SourceRef;\n  /** The raw text that produced the edge, for diagnostics. */\n  readonly raw: string;\n  /**\n   * Every file that declares this relation.\n   *\n   * A supersession stated only in the superseding document leaves the\n   * superseded one silently presenting itself as current, which is a finding in\n   * its own right - so the set of declaration sites has to survive de-duplication.\n   */\n  readonly declaredIn: readonly string[];\n  /** True when `from` and `to` are the same node. Kept, never traversed. */\n  readonly reflexive: boolean;\n}\n\n/* -------------------------------------------------------------------------- */\n/* Nodes                                                                      */\n/* -------------------------------------------------------------------------- */\n\nexport type NodeKind = 'document' | 'item';\n\ninterface NodeBase {\n  /** Canonical, graph-unique. Documents: `ADR-0007`. Items: `ADR-0007#q.1`. */\n  readonly id: string;\n  readonly kind: NodeKind;\n  /** Short human label used in reports. */\n  readonly title: string;\n  readonly at: SourceRef;\n}\n\nexport interface DocumentNode extends NodeBase {\n  readonly kind: 'document';\n  /** Repository-relative POSIX path. */\n  readonly path: string;\n  /** Every spelling that resolves to this document, lowercased. */\n  readonly aliases: readonly string[];\n  readonly phase: Phase;\n  /** The status string as written, before normalisation. `null` if absent. */\n  readonly rawStatus: string | null;\n  /** Where the status was declared, when it was declared anywhere. */\n  readonly statusAt: SourceRef | null;\n  /** Front-matter fields, flattened to strings and string arrays. */\n  readonly frontMatter: Readonly<Record<string, string | readonly string[]>>;\n}\n\nexport interface ItemNode extends NodeBase {\n  readonly kind: 'item';\n  /** Owning document id. */\n  readonly document: string;\n  /** Heading path the item sits under, outermost first. */\n  readonly section: readonly string[];\n  /** First line of the item, normalised to one line for reports. */\n  readonly text: string;\n  /** The full multi-line body, continuations included. */\n  readonly body: string;\n  readonly disposition: Disposition;\n  readonly openness: Openness;\n  /** Which signal decided the disposition. */\n  readonly evidence: StateSignal;\n  /** Conflicting signals found while resolving the state. */\n  readonly conflicts: readonly StateSignal[];\n}\n\nexport type SpecNode = DocumentNode | ItemNode;\n\n/** One observation about an item state. */\nexport interface StateSignal {\n  /** Higher wins. See `SIGNAL_PRIORITY` in `state.ts`. */\n  readonly source: 'directive' | 'marker' | 'strikethrough' | 'checkbox' | 'section' | 'default';\n  readonly disposition: Disposition;\n  /** The literal text that produced the signal. */\n  readonly raw: string;\n  readonly at: SourceRef;\n}\n\n/* -------------------------------------------------------------------------- */\n/* Unresolved references                                                      */\n/* -------------------------------------------------------------------------- */\n\nexport type DanglingReason =\n  /** Nothing in the corpus answers to this identifier. */\n  | 'unknown-target'\n  /** More than one document answers to it. */\n  | 'ambiguous'\n  /** The path exists on disk but is not a parsed specification. */\n  | 'not-a-spec'\n  /** The document resolved, but the `#anchor` did not. */\n  | 'unknown-anchor';\n\n/** A citation that failed foreign-key validation. */\nexport interface DanglingRef {\n  readonly kind: EdgeKind;\n  readonly from: string;\n  /** The identifier as written. */\n  readonly target: string;\n  readonly reason: DanglingReason;\n  readonly origin: EdgeOrigin;\n  readonly declaredAt: SourceRef;\n  readonly raw: string;\n  /** Candidate ids when `reason` is `ambiguous`, or near-misses otherwise. */\n  readonly candidates: readonly string[];\n}\n\n/* -------------------------------------------------------------------------- */\n/* Diagnostics                                                                */\n/* -------------------------------------------------------------------------- */\n\nexport type Severity = 'error' | 'warn' | 'info' | 'off';\n\nexport type RuleId =\n  | 'ghost-handover'\n  | 'stale-premise'\n  | 'broken-reference'\n  | 'reference-outside-corpus'\n  | 'ambiguous-reference'\n  | 'circular-delegation'\n  | 'orphaned-obligation'\n  | 'unreciprocated-supersession'\n  | 'live-supersession'\n  | 'state-conflict'\n  | 'self-reference';\n\nexport interface RelatedLocation {\n  readonly at: SourceRef;\n  readonly note: string;\n}\n\nexport interface Diagnostic {\n  readonly rule: RuleId;\n  readonly severity: Exclude<Severity, 'off'>;\n  /** One line, no trailing period. The headline of the finding. */\n  readonly message: string;\n  /** Where a human should go to fix it. */\n  readonly at: SourceRef;\n  /** Node ids involved, most relevant first. */\n  readonly nodes: readonly string[];\n  /**\n   * The citation this finding is about, for the rules that are about one.\n   *\n   * `null` everywhere else, where `nodes` already names the subject. It exists\n   * because a broken reference names something that is not a node - that is\n   * what makes it broken - and a baseline still has to be able to tell one\n   * broken reference from another. See ADR-0012.\n   */\n  readonly target: string | null;\n  /** Supporting locations: the other end of an edge, a cycle members. */\n  readonly related: readonly RelatedLocation[];\n  /** Concrete next action. */\n  readonly hint: string;\n}\n\n/* -------------------------------------------------------------------------- */\n/* Analysis output                                                            */\n/* -------------------------------------------------------------------------- */\n\n/** A problem with the input itself, as opposed to a finding about the graph. */\nexport interface ParseProblem {\n  readonly message: string;\n  readonly at: SourceRef;\n}\n\nexport interface AnalysisSummary {\n  readonly documents: number;\n  readonly items: number;\n  readonly edges: number;\n  readonly openObligations: number;\n  readonly errors: number;\n  readonly warnings: number;\n  readonly infos: number;\n  /** Milliseconds, wall clock. */\n  readonly durationMs: number;\n}\n"]}

package/dist/yaml.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A front-matter reader for the subset of YAML that specifications actually use.
+ *
+ * Front matter in an ADR is a flat bag of scalars and lists. Pulling in a full
+ * YAML implementation to read `status: accepted` would add a parser with its own
+ * CVE history, and would still need wrapping to recover the byte offset of the
+ * value - which is the whole reason we parse it ourselves: when a status is
+ * wrong, the report has to point at the line that declares it.
+ *
+ * Supported: scalars, quoted scalars, inline `[a, b]` sequences, block `- item`
+ * sequences, one level of nested mapping (flattened to `parent.child`), and `#`
+ * comments. Anything richer is preserved as the raw scalar text rather than
+ * being silently mangled.
+ */
+export interface YamlEntry {
+    /** Lower-cased key. Nested keys are flattened with a dot. */
+    readonly key: string;
+    readonly value: string | readonly string[];
+    /** Offset of the key. */
+    readonly start: number;
+    /** Offset just past the value. */
+    readonly end: number;
+    /** Offset of the first character of the value, for precise diagnostics. */
+    readonly valueStart: number;
+}
+/**
+ * Parses front-matter text.
+ *
+ * @param raw The text between the delimiters.
+ * @param baseOffset Offset of `raw` within the containing file, so the returned
+ *   spans address the file rather than the fragment.
+ */
+export declare function parseFrontMatter(raw: string, baseOffset?: number): YamlEntry[];
+/** Collapses parsed entries into the flat record stored on a document node. */
+export declare function toRecord(entries: readonly YamlEntry[]): Record<string, string | readonly string[]>;
+/** Every value of a key as a flat list, whether it was a scalar or a sequence. */
+export declare function valuesOf(entry: YamlEntry | undefined): string[];

package/dist/yaml.js

@@ -0,0 +1,240 @@
+/**
+ * A front-matter reader for the subset of YAML that specifications actually use.
+ *
+ * Front matter in an ADR is a flat bag of scalars and lists. Pulling in a full
+ * YAML implementation to read `status: accepted` would add a parser with its own
+ * CVE history, and would still need wrapping to recover the byte offset of the
+ * value - which is the whole reason we parse it ourselves: when a status is
+ * wrong, the report has to point at the line that declares it.
+ *
+ * Supported: scalars, quoted scalars, inline `[a, b]` sequences, block `- item`
+ * sequences, one level of nested mapping (flattened to `parent.child`), and `#`
+ * comments. Anything richer is preserved as the raw scalar text rather than
+ * being silently mangled.
+ */
+const KEY_LINE = /^(\s*)([A-Za-z0-9_.$-]+)\s*:(.*)$/;
+const SEQUENCE_ITEM = /^(\s*)-\s*(.*)$/;
+/**
+ * Parses front-matter text.
+ *
+ * @param raw The text between the delimiters.
+ * @param baseOffset Offset of `raw` within the containing file, so the returned
+ *   spans address the file rather than the fragment.
+ */
+export function parseFrontMatter(raw, baseOffset = 0) {
+    const entries = [];
+    const lines = splitLines(raw);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const match = KEY_LINE.exec(line.text);
+        if (!match)
+            continue;
+        const indent = match[1].length;
+        const key = match[2].toLowerCase();
+        const rest = match[3];
+        const restStart = line.start + indent + match[2].length + 1;
+        const trimmed = stripComment(rest).trim();
+        if (trimmed.length > 0) {
+            const valueStart = restStart + rest.indexOf(trimmed);
+            entries.push({
+                key,
+                value: parseScalarOrFlow(trimmed),
+                start: baseOffset + line.start + indent,
+                end: baseOffset + valueStart + trimmed.length,
+                valueStart: baseOffset + valueStart,
+            });
+            continue;
+        }
+        // An empty value opens either a block sequence or a nested mapping.
+        const block = readBlock(lines, i + 1, indent);
+        if (block.kind === 'sequence') {
+            entries.push({
+                key,
+                value: block.items,
+                start: baseOffset + line.start + indent,
+                end: baseOffset + block.end,
+                valueStart: baseOffset + block.valueStart,
+            });
+            i = block.lastIndex;
+        }
+        else if (block.kind === 'mapping') {
+            for (const child of block.entries) {
+                entries.push({
+                    key: `${key}.${child.key}`,
+                    value: child.value,
+                    start: baseOffset + child.start,
+                    end: baseOffset + child.end,
+                    valueStart: baseOffset + child.valueStart,
+                });
+            }
+            i = block.lastIndex;
+        }
+        else {
+            entries.push({
+                key,
+                value: '',
+                start: baseOffset + line.start + indent,
+                end: baseOffset + line.end,
+                valueStart: baseOffset + line.end,
+            });
+        }
+    }
+    return entries;
+}
+/** Collapses parsed entries into the flat record stored on a document node. */
+export function toRecord(entries) {
+    const out = {};
+    for (const entry of entries)
+        out[entry.key] = entry.value;
+    return out;
+}
+/** Every value of a key as a flat list, whether it was a scalar or a sequence. */
+export function valuesOf(entry) {
+    if (!entry)
+        return [];
+    return typeof entry.value === 'string'
+        ? entry.value.length > 0
+            ? [entry.value]
+            : []
+        : [...entry.value];
+}
+function splitLines(raw) {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i <= raw.length; i += 1) {
+        if (i === raw.length || raw[i] === '\n') {
+            let end = i;
+            if (end > start && raw[end - 1] === '\r')
+                end -= 1;
+            out.push({ text: raw.slice(start, end), start, end });
+            start = i + 1;
+        }
+    }
+    if (out.length > 0 && out[out.length - 1].text === '' && raw.endsWith('\n'))
+        out.pop();
+    return out;
+}
+function readBlock(lines, from, indent) {
+    const items = [];
+    let valueStart = -1;
+    let end = -1;
+    let last = from - 1;
+    for (let i = from; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.text.trim().length === 0) {
+            last = i;
+            continue;
+        }
+        const lineIndent = line.text.length - line.text.trimStart().length;
+        if (lineIndent <= indent)
+            break;
+        const seq = SEQUENCE_ITEM.exec(line.text);
+        if (!seq) {
+            if (items.length > 0)
+                break;
+            // A nested mapping: re-parse the indented region as its own document.
+            const region = collectRegion(lines, from, indent);
+            if (region.text.trim().length === 0)
+                return { kind: 'empty', lastIndex: from - 1 };
+            const nested = parseFrontMatter(region.text, region.start);
+            return { kind: 'mapping', entries: nested, lastIndex: region.lastIndex };
+        }
+        const value = stripComment(seq[2]).trim();
+        const offset = line.start + line.text.indexOf(value, seq[1].length + 1);
+        if (valueStart === -1)
+            valueStart = value.length > 0 ? offset : line.start;
+        items.push(unquote(value));
+        end = line.start + line.text.length;
+        last = i;
+    }
+    if (items.length === 0)
+        return { kind: 'empty', lastIndex: from - 1 };
+    return { kind: 'sequence', items, end, valueStart, lastIndex: last };
+}
+function collectRegion(lines, from, indent) {
+    let last = from - 1;
+    for (let i = from; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.text.trim().length === 0) {
+            last = i;
+            continue;
+        }
+        const lineIndent = line.text.length - line.text.trimStart().length;
+        if (lineIndent <= indent)
+            break;
+        last = i;
+    }
+    if (last < from)
+        return { text: '', start: 0, lastIndex: from - 1 };
+    const start = lines[from].start;
+    const stop = lines[last].end;
+    const parts = [];
+    for (let i = from; i <= last; i += 1)
+        parts.push(lines[i].text);
+    return { text: parts.join('\n'), start, lastIndex: last };
+    void stop;
+}
+/** Drops a trailing `#` comment, respecting quotes. */
+function stripComment(value) {
+    let quote = null;
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (quote) {
+            if (ch === '\\')
+                i += 1;
+            else if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === '#' && (i === 0 || value[i - 1] === ' ' || value[i - 1] === '\t')) {
+            return value.slice(0, i);
+        }
+    }
+    return value;
+}
+function parseScalarOrFlow(value) {
+    if (value.startsWith('[') && value.endsWith(']')) {
+        const inner = value.slice(1, -1).trim();
+        if (inner.length === 0)
+            return [];
+        return splitFlow(inner).map(unquote);
+    }
+    return unquote(value);
+}
+/** Splits `a, "b, c", d` on commas that are not inside quotes. */
+function splitFlow(value) {
+    const out = [];
+    let quote = null;
+    let start = 0;
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (quote) {
+            if (ch === '\\')
+                i += 1;
+            else if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === ',') {
+            out.push(value.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    out.push(value.slice(start).trim());
+    return out.filter((part) => part.length > 0);
+}
+function unquote(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return value.slice(1, -1).replace(/\\(.)/g, '$1');
+        }
+    }
+    return value;
+}
+//# sourceMappingURL=yaml.js.map