@descent-vtt/spec-graph 0.2.0

package/dist/config.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Repository configuration.
+ *
+ * Three ADRs left the same open question: `--ignore-ref` patterns, include
+ * globs and rule severities all belong to a repository rather than to whoever
+ * typed the command, and an npm script was doing that job by accumulating
+ * flags. A CI invocation carrying eight `--ignore-ref` arguments is a
+ * configuration file that has not admitted what it is.
+ *
+ * The format is JSON, parsed with `JSON.parse`. That is not a shortcut - it is
+ * the reason this file exists at all. spec-graph has no runtime dependencies,
+ * and a YAML or TOML reader would be the largest thing in the package, to read
+ * a file with nine keys in it.
+ *
+ * Every key mirrors a flag, and a flag always wins. Configuration is where a
+ * team writes down what is true of the repository; a flag is where somebody
+ * overrides it for one run.
+ */
+import type { RuleId, Severity } from './types.js';
+/** File names looked for, in order. The first that exists is the one used. */
+export declare const CONFIG_FILES: readonly string[];
+/** The `package.json` key read when no config file is present. */
+export declare const CONFIG_PACKAGE_KEY = "spec-graph";
+export interface SpecGraphConfig {
+    readonly patterns?: readonly string[] | undefined;
+    readonly ignore?: readonly string[] | undefined;
+    readonly ignoreReferences?: readonly string[] | undefined;
+    /**
+     * Families a bare identifier in prose may name.
+     *
+     * When set, `ADR-0099` is only ever read as a citation if `ADR` is listed.
+     * Everything else in prose stays prose.
+     */
+    readonly families?: readonly string[] | undefined;
+    /** Families that are never citations, whatever else the corpus contains. */
+    readonly ignoreFamilies?: readonly string[] | undefined;
+    /**
+     * Files that are logs of what was decided rather than decisions themselves.
+     *
+     * Journals, changelogs, minutes. Their links are still checked; their
+     * obligations and lifecycle are not. See ADR-0011.
+     */
+    readonly historyPatterns?: readonly string[] | undefined;
+    /** Path to the accepted-debt baseline, relative to the root. See ADR-0012. */
+    readonly baseline?: string | undefined;
+    readonly severities?: Partial<Record<RuleId, Severity>> | undefined;
+    readonly strict?: boolean | undefined;
+    readonly maxRelated?: number | undefined;
+}
+export interface LoadedConfig {
+    readonly config: SpecGraphConfig;
+    /** Where it came from, for `--verbose` and for error messages. */
+    readonly source: string | null;
+    /** Keys that were present but unusable. Reported, never silently dropped. */
+    readonly problems: readonly string[];
+}
+/**
+ * Reads configuration from a directory.
+ *
+ * Never throws. A malformed config is reported as a problem and the run
+ * continues with defaults: a broken config file should not stop a team seeing
+ * the findings it was going to show them anyway.
+ */
+export declare function loadConfig(root: string, read?: (path: string) => string): LoadedConfig;
+/** Parses config text. Exported so the shape can be tested without a disk. */
+export declare function parseConfig(raw: string, source: string): LoadedConfig;

package/dist/config.js

@@ -0,0 +1,183 @@
+/**
+ * Repository configuration.
+ *
+ * Three ADRs left the same open question: `--ignore-ref` patterns, include
+ * globs and rule severities all belong to a repository rather than to whoever
+ * typed the command, and an npm script was doing that job by accumulating
+ * flags. A CI invocation carrying eight `--ignore-ref` arguments is a
+ * configuration file that has not admitted what it is.
+ *
+ * The format is JSON, parsed with `JSON.parse`. That is not a shortcut - it is
+ * the reason this file exists at all. spec-graph has no runtime dependencies,
+ * and a YAML or TOML reader would be the largest thing in the package, to read
+ * a file with nine keys in it.
+ *
+ * Every key mirrors a flag, and a flag always wins. Configuration is where a
+ * team writes down what is true of the repository; a flag is where somebody
+ * overrides it for one run.
+ */
+import { readFileSync } from 'node:fs';
+import { RULE_IDS } from './rules.js';
+/** File names looked for, in order. The first that exists is the one used. */
+export const CONFIG_FILES = Object.freeze([
+    '.spec-graph.json',
+    'spec-graph.config.json',
+]);
+/** The `package.json` key read when no config file is present. */
+export const CONFIG_PACKAGE_KEY = 'spec-graph';
+const EMPTY = { config: {}, source: null, problems: [] };
+/**
+ * Reads configuration from a directory.
+ *
+ * Never throws. A malformed config is reported as a problem and the run
+ * continues with defaults: a broken config file should not stop a team seeing
+ * the findings it was going to show them anyway.
+ */
+export function loadConfig(root, read = defaultRead) {
+    for (const name of CONFIG_FILES) {
+        const raw = tryRead(read, `${root}/${name}`);
+        if (raw === null)
+            continue;
+        return parseConfig(raw, name);
+    }
+    const pkg = tryRead(read, `${root}/package.json`);
+    if (pkg === null)
+        return EMPTY;
+    let parsed;
+    try {
+        parsed = JSON.parse(pkg);
+    }
+    catch {
+        return EMPTY;
+    }
+    if (!isRecord(parsed))
+        return EMPTY;
+    const section = parsed[CONFIG_PACKAGE_KEY];
+    if (section === undefined)
+        return EMPTY;
+    if (!isRecord(section)) {
+        return { config: {}, source: `package.json`, problems: [`"${CONFIG_PACKAGE_KEY}" must be an object`] };
+    }
+    return readFields(section, `package.json#${CONFIG_PACKAGE_KEY}`);
+}
+/** Parses config text. Exported so the shape can be tested without a disk. */
+export function parseConfig(raw, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(withoutBom(raw));
+    }
+    catch (error) {
+        return { config: {}, source, problems: [`${source} is not valid JSON: ${error.message}`] };
+    }
+    if (!isRecord(parsed))
+        return { config: {}, source, problems: [`${source} must contain a JSON object`] };
+    return readFields(parsed, source);
+}
+function readFields(raw, source) {
+    const problems = [];
+    const config = {};
+    const strings = (key) => {
+        const value = raw[key];
+        if (value === undefined)
+            return undefined;
+        if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+            problems.push(`${source}: "${key}" must be an array of strings`);
+            return undefined;
+        }
+        return value;
+    };
+    config.patterns = strings('patterns');
+    config.ignore = strings('ignore');
+    config.ignoreReferences = strings('ignoreReferences');
+    config.families = strings('families');
+    config.ignoreFamilies = strings('ignoreFamilies');
+    config.historyPatterns = strings('historyPatterns');
+    if (raw['baseline'] !== undefined) {
+        if (typeof raw['baseline'] !== 'string' || raw['baseline'].trim().length === 0) {
+            problems.push(`${source}: "baseline" must be a path`);
+        }
+        else {
+            config.baseline = raw['baseline'];
+        }
+    }
+    if (raw['strict'] !== undefined) {
+        if (typeof raw['strict'] !== 'boolean')
+            problems.push(`${source}: "strict" must be true or false`);
+        else
+            config.strict = raw['strict'];
+    }
+    if (raw['maxRelated'] !== undefined) {
+        const value = raw['maxRelated'];
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+            problems.push(`${source}: "maxRelated" must be a non-negative whole number`);
+        }
+        else {
+            config.maxRelated = value;
+        }
+    }
+    if (raw['severities'] !== undefined) {
+        const value = raw['severities'];
+        if (!isRecord(value)) {
+            problems.push(`${source}: "severities" must be an object of rule to severity`);
+        }
+        else {
+            const severities = {};
+            for (const [rule, level] of Object.entries(value)) {
+                if (!RULE_IDS.includes(rule)) {
+                    problems.push(`${source}: unknown rule "${rule}" in "severities"`);
+                    continue;
+                }
+                if (level !== 'error' && level !== 'warn' && level !== 'info' && level !== 'off') {
+                    problems.push(`${source}: "severities.${rule}" must be error, warn, info or off`);
+                    continue;
+                }
+                severities[rule] = level;
+            }
+            config.severities = severities;
+        }
+    }
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_KEYS.has(key))
+            problems.push(`${source}: unknown key "${key}"`);
+    }
+    return { config, source, problems };
+}
+const KNOWN_KEYS = new Set([
+    'patterns',
+    'ignore',
+    'ignoreReferences',
+    'families',
+    'ignoreFamilies',
+    'historyPatterns',
+    'baseline',
+    'severities',
+    'strict',
+    'maxRelated',
+    // Tolerated so an editor can be pointed at a schema without being told off.
+    '$schema',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function tryRead(read, path) {
+    try {
+        return withoutBom(read(path));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Drops a leading byte-order mark.
+ *
+ * `JSON.parse` rejects one, and several Windows editors write one by default -
+ * a config that silently stops applying because of an invisible first character
+ * is the worst kind of configuration bug.
+ */
+function withoutBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+function defaultRead(path) {
+    return readFileSync(path, 'utf8');
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Repository configuration.\n *\n * Three ADRs left the same open question: `--ignore-ref` patterns, include\n * globs and rule severities all belong to a repository rather than to whoever\n * typed the command, and an npm script was doing that job by accumulating\n * flags. A CI invocation carrying eight `--ignore-ref` arguments is a\n * configuration file that has not admitted what it is.\n *\n * The format is JSON, parsed with `JSON.parse`. That is not a shortcut - it is\n * the reason this file exists at all. spec-graph has no runtime dependencies,\n * and a YAML or TOML reader would be the largest thing in the package, to read\n * a file with nine keys in it.\n *\n * Every key mirrors a flag, and a flag always wins. Configuration is where a\n * team writes down what is true of the repository; a flag is where somebody\n * overrides it for one run.\n */\n\nimport { readFileSync } from 'node:fs';\n\nimport { RULE_IDS } from './rules.js';\nimport type { RuleId, Severity } from './types.js';\n\n/** File names looked for, in order. The first that exists is the one used. */\nexport const CONFIG_FILES: readonly string[] = Object.freeze([\n  '.spec-graph.json',\n  'spec-graph.config.json',\n]);\n\n/** The `package.json` key read when no config file is present. */\nexport const CONFIG_PACKAGE_KEY = 'spec-graph';\n\nexport interface SpecGraphConfig {\n  readonly patterns?: readonly string[] | undefined;\n  readonly ignore?: readonly string[] | undefined;\n  readonly ignoreReferences?: readonly string[] | undefined;\n  /**\n   * Families a bare identifier in prose may name.\n   *\n   * When set, `ADR-0099` is only ever read as a citation if `ADR` is listed.\n   * Everything else in prose stays prose.\n   */\n  readonly families?: readonly string[] | undefined;\n  /** Families that are never citations, whatever else the corpus contains. */\n  readonly ignoreFamilies?: readonly string[] | undefined;\n  /**\n   * Files that are logs of what was decided rather than decisions themselves.\n   *\n   * Journals, changelogs, minutes. Their links are still checked; their\n   * obligations and lifecycle are not. See ADR-0011.\n   */\n  readonly historyPatterns?: readonly string[] | undefined;\n  /** Path to the accepted-debt baseline, relative to the root. See ADR-0012. */\n  readonly baseline?: string | undefined;\n  readonly severities?: Partial<Record<RuleId, Severity>> | undefined;\n  readonly strict?: boolean | undefined;\n  readonly maxRelated?: number | undefined;\n}\n\nexport interface LoadedConfig {\n  readonly config: SpecGraphConfig;\n  /** Where it came from, for `--verbose` and for error messages. */\n  readonly source: string | null;\n  /** Keys that were present but unusable. Reported, never silently dropped. */\n  readonly problems: readonly string[];\n}\n\nconst EMPTY: LoadedConfig = { config: {}, source: null, problems: [] };\n\n/**\n * Reads configuration from a directory.\n *\n * Never throws. A malformed config is reported as a problem and the run\n * continues with defaults: a broken config file should not stop a team seeing\n * the findings it was going to show them anyway.\n */\nexport function loadConfig(root: string, read: (path: string) => string = defaultRead): LoadedConfig {\n  for (const name of CONFIG_FILES) {\n    const raw = tryRead(read, `${root}/${name}`);\n    if (raw === null) continue;\n    return parseConfig(raw, name);\n  }\n\n  const pkg = tryRead(read, `${root}/package.json`);\n  if (pkg === null) return EMPTY;\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(pkg);\n  } catch {\n    return EMPTY;\n  }\n  if (!isRecord(parsed)) return EMPTY;\n  const section = parsed[CONFIG_PACKAGE_KEY];\n  if (section === undefined) return EMPTY;\n  if (!isRecord(section)) {\n    return { config: {}, source: `package.json`, problems: [`\"${CONFIG_PACKAGE_KEY}\" must be an object`] };\n  }\n  return readFields(section, `package.json#${CONFIG_PACKAGE_KEY}`);\n}\n\n/** Parses config text. Exported so the shape can be tested without a disk. */\nexport function parseConfig(raw: string, source: string): LoadedConfig {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(withoutBom(raw));\n  } catch (error) {\n    return { config: {}, source, problems: [`${source} is not valid JSON: ${(error as Error).message}`] };\n  }\n  if (!isRecord(parsed)) return { config: {}, source, problems: [`${source} must contain a JSON object`] };\n  return readFields(parsed, source);\n}\n\nfunction readFields(raw: Record<string, unknown>, source: string): LoadedConfig {\n  const problems: string[] = [];\n  const config: {\n    -readonly [K in keyof SpecGraphConfig]: SpecGraphConfig[K];\n  } = {};\n\n  const strings = (key: keyof SpecGraphConfig): readonly string[] | undefined => {\n    const value = raw[key];\n    if (value === undefined) return undefined;\n    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {\n      problems.push(`${source}: \"${key}\" must be an array of strings`);\n      return undefined;\n    }\n    return value as string[];\n  };\n\n  config.patterns = strings('patterns');\n  config.ignore = strings('ignore');\n  config.ignoreReferences = strings('ignoreReferences');\n  config.families = strings('families');\n  config.ignoreFamilies = strings('ignoreFamilies');\n  config.historyPatterns = strings('historyPatterns');\n\n  if (raw['baseline'] !== undefined) {\n    if (typeof raw['baseline'] !== 'string' || raw['baseline'].trim().length === 0) {\n      problems.push(`${source}: \"baseline\" must be a path`);\n    } else {\n      config.baseline = raw['baseline'];\n    }\n  }\n\n  if (raw['strict'] !== undefined) {\n    if (typeof raw['strict'] !== 'boolean') problems.push(`${source}: \"strict\" must be true or false`);\n    else config.strict = raw['strict'];\n  }\n\n  if (raw['maxRelated'] !== undefined) {\n    const value = raw['maxRelated'];\n    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {\n      problems.push(`${source}: \"maxRelated\" must be a non-negative whole number`);\n    } else {\n      config.maxRelated = value;\n    }\n  }\n\n  if (raw['severities'] !== undefined) {\n    const value = raw['severities'];\n    if (!isRecord(value)) {\n      problems.push(`${source}: \"severities\" must be an object of rule to severity`);\n    } else {\n      const severities: Partial<Record<RuleId, Severity>> = {};\n      for (const [rule, level] of Object.entries(value)) {\n        if (!RULE_IDS.includes(rule as RuleId)) {\n          problems.push(`${source}: unknown rule \"${rule}\" in \"severities\"`);\n          continue;\n        }\n        if (level !== 'error' && level !== 'warn' && level !== 'info' && level !== 'off') {\n          problems.push(`${source}: \"severities.${rule}\" must be error, warn, info or off`);\n          continue;\n        }\n        severities[rule as RuleId] = level;\n      }\n      config.severities = severities;\n    }\n  }\n\n  for (const key of Object.keys(raw)) {\n    if (!KNOWN_KEYS.has(key)) problems.push(`${source}: unknown key \"${key}\"`);\n  }\n\n  return { config, source, problems };\n}\n\nconst KNOWN_KEYS: ReadonlySet<string> = new Set([\n  'patterns',\n  'ignore',\n  'ignoreReferences',\n  'families',\n  'ignoreFamilies',\n  'historyPatterns',\n  'baseline',\n  'severities',\n  'strict',\n  'maxRelated',\n  // Tolerated so an editor can be pointed at a schema without being told off.\n  '$schema',\n]);\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction tryRead(read: (path: string) => string, path: string): string | null {\n  try {\n    return withoutBom(read(path));\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Drops a leading byte-order mark.\n *\n * `JSON.parse` rejects one, and several Windows editors write one by default -\n * a config that silently stops applying because of an invisible first character\n * is the worst kind of configuration bug.\n */\nfunction withoutBom(text: string): string {\n  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;\n}\n\nfunction defaultRead(path: string): string {\n  return readFileSync(path, 'utf8');\n}\n"]}

package/dist/directives.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Explicit annotations, written as HTML comments.
+ *
+ * Inference covers the overwhelming majority of real documents, but inference
+ * that cannot be overridden is a trap: the first time it guesses wrong about a
+ * document somebody cannot restructure, the whole tool gets switched off. These
+ * directives are the escape hatch, and they are HTML comments so they stay
+ * invisible in GitHub, MkDocs, Docusaurus and every other renderer.
+ *
+ * ```md
+ * <!-- @spec-node id="ADR-0007" status="accepted" aliases="adr-7, sharding" -->
+ * <!-- @spec-item id="shard-key" state="narrowed" -->
+ * <!-- @spec-edge kind="delegates-to" to="ADR-0011#scope" -->
+ * <!-- @spec-ignore -->
+ * ```
+ *
+ * A directive always wins over anything inferred, and says so in the report, so
+ * an override is visible rather than mysterious.
+ */
+import type { HtmlComment } from './markdown.js';
+export type DirectiveName = 'spec-node' | 'spec-item' | 'spec-edge' | 'spec-ignore' | 'spec-history';
+export interface Attribute {
+    readonly value: string;
+    /** Absolute offset of the value text, quotes excluded. */
+    readonly start: number;
+    readonly end: number;
+}
+export interface Directive {
+    readonly name: DirectiveName;
+    readonly attributes: ReadonlyMap<string, Attribute>;
+    /** Offset of the enclosing comment. */
+    readonly start: number;
+    readonly end: number;
+    readonly line: number;
+    /** Attribute names that were written but are not part of this directive. */
+    readonly unknownAttributes: readonly string[];
+}
+/** Reads every spec-graph directive out of a document's HTML comments. */
+export declare function parseDirectives(comments: readonly HtmlComment[]): Directive[];
+/** Reads an attribute, trimmed. Returns `null` when absent or blank. */
+export declare function attr(directive: Directive, name: string): Attribute | null;
+/** Splits a comma- or whitespace-separated attribute into its parts. */
+export declare function attrList(directive: Directive, name: string): string[];
+/**
+ * Finds the directive that annotates a given region.
+ *
+ * A `@spec-item` directive may sit on the line above the item, on the same
+ * line, or inside the item body. All three read naturally in the source, so all
+ * three are accepted, with the closest preceding directive winning.
+ */
+export declare function directiveFor(directives: readonly Directive[], name: DirectiveName, region: {
+    start: number;
+    end: number;
+}, 
+/** How far above the region a directive may sit and still apply. */
+lookBehind: number): Directive | null;

package/dist/directives.js

@@ -0,0 +1,125 @@
+/**
+ * Explicit annotations, written as HTML comments.
+ *
+ * Inference covers the overwhelming majority of real documents, but inference
+ * that cannot be overridden is a trap: the first time it guesses wrong about a
+ * document somebody cannot restructure, the whole tool gets switched off. These
+ * directives are the escape hatch, and they are HTML comments so they stay
+ * invisible in GitHub, MkDocs, Docusaurus and every other renderer.
+ *
+ * ```md
+ * <!-- @spec-node id="ADR-0007" status="accepted" aliases="adr-7, sharding" -->
+ * <!-- @spec-item id="shard-key" state="narrowed" -->
+ * <!-- @spec-edge kind="delegates-to" to="ADR-0011#scope" -->
+ * <!-- @spec-ignore -->
+ * ```
+ *
+ * A directive always wins over anything inferred, and says so in the report, so
+ * an override is visible rather than mysterious.
+ */
+const KNOWN = new Set([
+    'spec-node',
+    'spec-item',
+    'spec-edge',
+    'spec-ignore',
+    'spec-history',
+]);
+const DIRECTIVE_HEAD = /^\s*@([a-z][a-z0-9-]*)/;
+const ATTRIBUTE = /([A-Za-z_][A-Za-z0-9_-]*)\s*(?:=\s*("([^"]*)"|'([^']*)'|([^\s"'<>]+)))?/g;
+/** Attributes each directive understands. Anything else is reported, not ignored. */
+const SCHEMA = {
+    'spec-node': ['id', 'status', 'title', 'aliases', 'kind'],
+    // Takes no attributes: the file either is a record or it is not.
+    'spec-history': [],
+    'spec-item': ['id', 'state', 'title', 'owner', 'note'],
+    'spec-edge': ['kind', 'to', 'from', 'reason'],
+    'spec-ignore': ['reason'],
+};
+/** Reads every spec-graph directive out of a document's HTML comments. */
+export function parseDirectives(comments) {
+    const out = [];
+    for (const comment of comments) {
+        const head = DIRECTIVE_HEAD.exec(comment.inner);
+        if (!head)
+            continue;
+        const name = head[1];
+        if (!KNOWN.has(name))
+            continue;
+        const directiveName = name;
+        const bodyStart = (head.index ?? 0) + head[0].length;
+        const body = comment.inner.slice(bodyStart);
+        const attributes = new Map();
+        const unknown = [];
+        const allowed = SCHEMA[directiveName];
+        ATTRIBUTE.lastIndex = 0;
+        for (let m = ATTRIBUTE.exec(body); m !== null; m = ATTRIBUTE.exec(body)) {
+            const key = m[1].toLowerCase();
+            const quoted = m[3] ?? m[4];
+            const bare = m[5];
+            // A bare attribute is a flag: `<!-- @spec-ignore reason -->`.
+            const value = quoted ?? bare ?? 'true';
+            const raw = m[2];
+            const valueOffset = raw === undefined
+                ? (m.index ?? 0) + m[0].length
+                : (m.index ?? 0) + m[0].indexOf(raw) + (quoted === undefined ? 0 : 1);
+            const start = comment.innerStart + bodyStart + valueOffset;
+            if (!allowed.includes(key))
+                unknown.push(key);
+            attributes.set(key, { value, start, end: start + value.length });
+        }
+        out.push({
+            name: directiveName,
+            attributes,
+            start: comment.start,
+            end: comment.end,
+            line: comment.line,
+            unknownAttributes: unknown,
+        });
+    }
+    return out;
+}
+/** Reads an attribute, trimmed. Returns `null` when absent or blank. */
+export function attr(directive, name) {
+    const found = directive.attributes.get(name);
+    if (!found)
+        return null;
+    const trimmed = found.value.trim();
+    if (trimmed.length === 0)
+        return null;
+    const offset = found.value.indexOf(trimmed);
+    return { value: trimmed, start: found.start + offset, end: found.start + offset + trimmed.length };
+}
+/** Splits a comma- or whitespace-separated attribute into its parts. */
+export function attrList(directive, name) {
+    const found = attr(directive, name);
+    if (!found)
+        return [];
+    return found.value
+        .split(/[,;\s]+/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+/**
+ * Finds the directive that annotates a given region.
+ *
+ * A `@spec-item` directive may sit on the line above the item, on the same
+ * line, or inside the item body. All three read naturally in the source, so all
+ * three are accepted, with the closest preceding directive winning.
+ */
+export function directiveFor(directives, name, region, 
+/** How far above the region a directive may sit and still apply. */
+lookBehind) {
+    let best = null;
+    for (const directive of directives) {
+        if (directive.name !== name)
+            continue;
+        const inside = directive.start >= region.start && directive.end <= region.end;
+        const above = directive.end <= region.start && region.start - directive.end <= lookBehind;
+        if (!inside && !above)
+            continue;
+        if (best === null || directive.start > best.start)
+            best = directive;
+    }
+    return best;
+}
+//# sourceMappingURL=directives.js.map

package/dist/directives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.js","sourceRoot":"","sources":["../src/directives.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Explicit annotations, written as HTML comments.\n *\n * Inference covers the overwhelming majority of real documents, but inference\n * that cannot be overridden is a trap: the first time it guesses wrong about a\n * document somebody cannot restructure, the whole tool gets switched off. These\n * directives are the escape hatch, and they are HTML comments so they stay\n * invisible in GitHub, MkDocs, Docusaurus and every other renderer.\n *\n * ```md\n * <!-- @spec-node id=\"ADR-0007\" status=\"accepted\" aliases=\"adr-7, sharding\" -->\n * <!-- @spec-item id=\"shard-key\" state=\"narrowed\" -->\n * <!-- @spec-edge kind=\"delegates-to\" to=\"ADR-0011#scope\" -->\n * <!-- @spec-ignore -->\n * ```\n *\n * A directive always wins over anything inferred, and says so in the report, so\n * an override is visible rather than mysterious.\n */\n\nimport type { HtmlComment } from './markdown.js';\n\nexport type DirectiveName = 'spec-node' | 'spec-item' | 'spec-edge' | 'spec-ignore' | 'spec-history';\n\nconst KNOWN: ReadonlySet<string> = new Set<DirectiveName>([\n  'spec-node',\n  'spec-item',\n  'spec-edge',\n  'spec-ignore',\n  'spec-history',\n]);\n\nexport interface Attribute {\n  readonly value: string;\n  /** Absolute offset of the value text, quotes excluded. */\n  readonly start: number;\n  readonly end: number;\n}\n\nexport interface Directive {\n  readonly name: DirectiveName;\n  readonly attributes: ReadonlyMap<string, Attribute>;\n  /** Offset of the enclosing comment. */\n  readonly start: number;\n  readonly end: number;\n  readonly line: number;\n  /** Attribute names that were written but are not part of this directive. */\n  readonly unknownAttributes: readonly string[];\n}\n\nconst DIRECTIVE_HEAD = /^\\s*@([a-z][a-z0-9-]*)/;\nconst ATTRIBUTE = /([A-Za-z_][A-Za-z0-9_-]*)\\s*(?:=\\s*(\"([^\"]*)\"|'([^']*)'|([^\\s\"'<>]+)))?/g;\n\n/** Attributes each directive understands. Anything else is reported, not ignored. */\nconst SCHEMA: Readonly<Record<DirectiveName, readonly string[]>> = {\n  'spec-node': ['id', 'status', 'title', 'aliases', 'kind'],\n  // Takes no attributes: the file either is a record or it is not.\n  'spec-history': [],\n  'spec-item': ['id', 'state', 'title', 'owner', 'note'],\n  'spec-edge': ['kind', 'to', 'from', 'reason'],\n  'spec-ignore': ['reason'],\n};\n\n/** Reads every spec-graph directive out of a document's HTML comments. */\nexport function parseDirectives(comments: readonly HtmlComment[]): Directive[] {\n  const out: Directive[] = [];\n  for (const comment of comments) {\n    const head = DIRECTIVE_HEAD.exec(comment.inner);\n    if (!head) continue;\n    const name = head[1] as string;\n    if (!KNOWN.has(name)) continue;\n\n    const directiveName = name as DirectiveName;\n    const bodyStart = (head.index ?? 0) + (head[0] as string).length;\n    const body = comment.inner.slice(bodyStart);\n    const attributes = new Map<string, Attribute>();\n    const unknown: string[] = [];\n    const allowed = SCHEMA[directiveName];\n\n    ATTRIBUTE.lastIndex = 0;\n    for (let m = ATTRIBUTE.exec(body); m !== null; m = ATTRIBUTE.exec(body)) {\n      const key = (m[1] as string).toLowerCase();\n      const quoted = m[3] ?? m[4];\n      const bare = m[5];\n      // A bare attribute is a flag: `<!-- @spec-ignore reason -->`.\n      const value = quoted ?? bare ?? 'true';\n      const raw = m[2];\n      const valueOffset =\n        raw === undefined\n          ? (m.index ?? 0) + (m[0] as string).length\n          : (m.index ?? 0) + (m[0] as string).indexOf(raw) + (quoted === undefined ? 0 : 1);\n      const start = comment.innerStart + bodyStart + valueOffset;\n\n      if (!allowed.includes(key)) unknown.push(key);\n      attributes.set(key, { value, start, end: start + value.length });\n    }\n\n    out.push({\n      name: directiveName,\n      attributes,\n      start: comment.start,\n      end: comment.end,\n      line: comment.line,\n      unknownAttributes: unknown,\n    });\n  }\n  return out;\n}\n\n/** Reads an attribute, trimmed. Returns `null` when absent or blank. */\nexport function attr(directive: Directive, name: string): Attribute | null {\n  const found = directive.attributes.get(name);\n  if (!found) return null;\n  const trimmed = found.value.trim();\n  if (trimmed.length === 0) return null;\n  const offset = found.value.indexOf(trimmed);\n  return { value: trimmed, start: found.start + offset, end: found.start + offset + trimmed.length };\n}\n\n/** Splits a comma- or whitespace-separated attribute into its parts. */\nexport function attrList(directive: Directive, name: string): string[] {\n  const found = attr(directive, name);\n  if (!found) return [];\n  return found.value\n    .split(/[,;\\s]+/)\n    .map((part) => part.trim())\n    .filter((part) => part.length > 0);\n}\n\n/**\n * Finds the directive that annotates a given region.\n *\n * A `@spec-item` directive may sit on the line above the item, on the same\n * line, or inside the item body. All three read naturally in the source, so all\n * three are accepted, with the closest preceding directive winning.\n */\nexport function directiveFor(\n  directives: readonly Directive[],\n  name: DirectiveName,\n  region: { start: number; end: number },\n  /** How far above the region a directive may sit and still apply. */\n  lookBehind: number,\n): Directive | null {\n  let best: Directive | null = null;\n  for (const directive of directives) {\n    if (directive.name !== name) continue;\n    const inside = directive.start >= region.start && directive.end <= region.end;\n    const above = directive.end <= region.start && region.start - directive.end <= lookBehind;\n    if (!inside && !above) continue;\n    if (best === null || directive.start > best.start) best = directive;\n  }\n  return best;\n}\n"]}

package/dist/extract.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Document extraction: Markdown in, graph fragments out.
+ *
+ * This module is where domain-agnosticism is won or lost. It never requires a
+ * repository to adopt a syntax. It reads what teams already write - front
+ * matter, a `## Status` section, a checklist under `## Open Questions`, a link
+ * that says "deferred to ADR-0011" - and turns each into a typed relation with a
+ * source position.
+ *
+ * The one rule it holds to everywhere: **an inference that cannot be justified
+ * is not made.** An unrecognised status becomes `unknown`, not a guess. A link
+ * with no governing verb becomes a neutral `references`, not a dependency. Bare
+ * identifiers found in prose are opportunistic and are dropped silently when
+ * they do not resolve, because the alternative is reporting `SHA-256` as a
+ * broken reference to specification 256.
+ */
+import { type DocumentIdentity } from './identity.js';
+import { type ScannedDocument } from './markdown.js';
+import type { DocumentNode, EdgeKind, EdgeOrigin, ItemNode, ParseProblem, SourceRef } from './types.js';
+/**
+ * A relation that has been read but not yet resolved to a target node.
+ *
+ * Resolution needs the whole corpus, so extraction stops at the raw target text.
+ */
+export interface ReferenceCandidate {
+    readonly kind: EdgeKind;
+    /** Id of the node the relation was written on. */
+    readonly from: string;
+    /** The target exactly as written: a path, an identifier, or a URL. */
+    readonly target: string;
+    readonly origin: EdgeOrigin;
+    readonly declaredAt: SourceRef;
+    readonly raw: string;
+    /**
+     * When true the relation runs `target -> from`.
+     *
+     * `superseded-by: ADR-0009` written in ADR-0003 declares that *ADR-0009*
+     * supersedes ADR-0003. The edge belongs to ADR-0009; the line a human must go
+     * and fix is in ADR-0003, which is why `declaredAt` is tracked separately.
+     */
+    readonly inverted: boolean;
+    /**
+     * Opportunistic references are dropped in silence when they do not resolve.
+     * Only deliberate ones - links, front matter, directives - are reported.
+     */
+    readonly opportunistic: boolean;
+}
+export interface ExtractedDocument {
+    readonly document: DocumentNode;
+    readonly items: readonly ItemNode[];
+    readonly references: readonly ReferenceCandidate[];
+    readonly problems: readonly ParseProblem[];
+    /** Heading slugs, for resolving `#anchor` references into this document. */
+    readonly anchors: ReadonlySet<string>;
+    readonly identity: DocumentIdentity;
+    readonly scanned: ScannedDocument;
+    /**
+     * Specifications declared inside this file, each a document in its own right.
+     *
+     * Empty for the ordinary one-file-per-decision layout, which is why nothing
+     * downstream had to change to support registers.
+     */
+    readonly subSpecifications: readonly ExtractedDocument[];
+    /**
+     * The file-level specification this one is a region of, if any.
+     *
+     * Recorded so the register's structure is a relation in the graph rather than
+     * an accident of which offsets fall inside which: "what decisions does this
+     * register hold" is a question worth being able to ask.
+     */
+    readonly containerId: string | null;
+}
+/** Headings under which a link is bookkeeping rather than a commitment. */
+declare const WEAK_SECTIONS: ReadonlySet<string>;
+/** Headings whose bullets are obligations even without a checkbox. */
+declare const OBLIGATION_SECTIONS: ReadonlySet<string>;
+export interface ExtractInput {
+    /** Repository-relative POSIX path. */
+    readonly path: string;
+    readonly text: string;
+    /**
+     * This file is a historical record: a log of what was decided, not a
+     * decision. Matched against the caller's history patterns, because deciding
+     * which files those are is a repository's business and not a guess this
+     * layer could justify making. See ADR-0011.
+     */
+    readonly record?: boolean | undefined;
+}
+/**
+ * Reads one file into graph fragments, one entry per specification in it.
+ *
+ * A file yields at least itself. It yields more when it is a register: a
+ * heading that carries an identifier *and* declares a status is a specification
+ * in its own right, with its own lifecycle, its own obligations and its own
+ * relations. See ADR-0009.
+ */
+export declare function extractSpecifications(input: ExtractInput): ExtractedDocument[];
+/** Reads a file's own specification. Returns `null` when it opts out. */
+export declare function extractDocument(input: ExtractInput): ExtractedDocument | null;
+/** The heading path enclosing an offset, outermost first. */
+declare function sectionPathAt(scanned: ScannedDocument, offset: number): string[];
+export interface Classification {
+    readonly kind: EdgeKind;
+    readonly inverted: boolean;
+}
+/**
+ * Decides what a reference means from the words around it.
+ *
+ * The nearest governing phrase within {@link VERB_WINDOW} characters wins, and
+ * the search never crosses a sentence boundary. With nothing to go on, a
+ * reference under a "See also" heading is bookkeeping and everything else is a
+ * neutral citation.
+ */
+export declare function classifyReference(text: string, start: number, end: number, section: readonly string[]): Classification;
+/** Exposed for tests and for callers that classify their own sections. */
+export { OBLIGATION_SECTIONS, sectionPathAt, WEAK_SECTIONS };