@descent-vtt/spec-graph 0.2.3 → 0.3.0

package/dist/config.js

@@ -106,6 +106,12 @@ function readFields(raw, source) {
         else
             config.strict = raw['strict'];
     }
+    if (raw['ratchet'] !== undefined) {
+        if (typeof raw['ratchet'] !== 'boolean')
+            problems.push(`${source}: "ratchet" must be true or false`);
+        else
+            config.ratchet = raw['ratchet'];
+    }
     if (raw['maxRelated'] !== undefined) {
         const value = raw['maxRelated'];
         if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
@@ -150,6 +156,7 @@ const KNOWN_KEYS = new Set([
     'ignoreFamilies',
     'historyPatterns',
     'baseline',
+    'ratchet',
     'severities',
     'strict',
     'maxRelated',

package/dist/config.js.map

@@ -1 +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"]}
+{"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  /** Fail when a baseline entry no longer occurs. See ADR-0012. */\n  readonly ratchet?: boolean | 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['ratchet'] !== undefined) {\n    if (typeof raw['ratchet'] !== 'boolean') problems.push(`${source}: \"ratchet\" must be true or false`);\n    else config.ratchet = raw['ratchet'];\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  'ratchet',\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/extract.d.ts

@@ -16,7 +16,7 @@
  */
 import { type DocumentIdentity } from './identity.js';
 import { type ScannedDocument } from './markdown.js';
-import type { DocumentNode, EdgeKind, EdgeOrigin, ItemNode, ParseProblem, SourceRef } from './types.js';
+import type { DocumentNode, EdgeKind, EdgeOrigin, ItemNode, MisreadKey, ParseProblem, SourceRef } from './types.js';
 /**
  * A relation that has been read but not yet resolved to a target node.
  *
@@ -50,6 +50,13 @@ export interface ExtractedDocument {
     readonly items: readonly ItemNode[];
     readonly references: readonly ReferenceCandidate[];
     readonly problems: readonly ParseProblem[];
+    /**
+     * Front-matter keys that read as relations and declared none.
+     *
+     * Kept apart from `problems` because a problem is about the text and this is
+     * about the graph: the edge the author wrote down is not in it.
+     */
+    readonly misreadKeys: readonly MisreadKey[];
     /** Heading slugs, for resolving `#anchor` references into this document. */
     readonly anchors: ReadonlySet<string>;
     readonly identity: DocumentIdentity;
@@ -70,6 +77,47 @@ export interface ExtractedDocument {
      */
     readonly containerId: string | null;
 }
+/**
+ * Front-matter keys that declare a relation, and what they mean.
+ *
+ * Every directional kind is spelled in **both** directions. A register that
+ * records `depends-on` but not `depended-on-by` is not a smaller vocabulary, it
+ * is a trap: the author writes the inverse, the key means nothing, and the edge
+ * they declared is missing from a graph that reports itself as consistent. Which
+ * half of a pair a repository writes is a filing convention, and a filing
+ * convention is not something a linter gets to have an opinion about.
+ *
+ * `relates-to` is the exception, and it is not one: the relation is symmetric,
+ * so it has no other direction to spell. `contains` is structural and never
+ * written by hand. `tests/parsing.test.ts` holds both facts to the fire.
+ */
+export declare const RELATION_KEYS: Readonly<Record<string, {
+    kind: EdgeKind;
+    inverted: boolean;
+}>>;
+/**
+ * True when two folded keys are one edit apart.
+ *
+ * One edit, not two, and a transposition counts as one: `supercedesby` for
+ * `supercededby` is a slip of the finger, `categories` for `dependencies` is a
+ * different word. Written out rather than as a distance matrix because the
+ * answer is a yes or a no and the bound is one - the general algorithm would be
+ * more code, not less.
+ */
+export declare function withinOneEdit(a: string, b: string): boolean;
+/**
+ * Folds a front-matter key to its lookup form.
+ *
+ * `depends-on`, `depends_on`, `dependsOn` and `Depends On` are one key written
+ * four ways, and which one a repository uses is decided by whatever wrote the
+ * front matter first. Dropping every separator collapses them - the YAML reader
+ * has already lower-cased the key, which is what makes camel case fold too.
+ *
+ * Which case this folds to is arbitrary and no test pins it: both sides of every
+ * comparison come through here, so upper would work exactly as well. Asserting
+ * on it would be asserting on the implementation.
+ */
+export declare function foldRelationKey(key: string): string;
 /** 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. */

package/dist/extract.js

@@ -15,7 +15,7 @@
  * broken reference to specification 256.
  */
 import { attr, attrList, directiveFor, parseDirectives } from './directives.js';
-import { identify, isExternal, normaliseRef, ID_KEYS } from './identity.js';
+import { identify, isDocumentTarget, isExternal, looksLikePath, normaliseRef, parsePrefixedRef, ID_KEYS, } from './identity.js';
 import { isStatusHeading, phaseFromPath, phaseOf, STATUS_KEYS, supersessionTargetsIn } from './lifecycle.js';
 import { scanMarkdown, slugify } from './markdown.js';
 import { findSpecificationRegions, regionAt } from './sections.js';
@@ -25,34 +25,176 @@ import { parseFrontMatter, toRecord, valuesOf } from './yaml.js';
 /* -------------------------------------------------------------------------- */
 /* Vocabulary                                                                 */
 /* -------------------------------------------------------------------------- */
-/** Front-matter keys that declare a relation, and what they mean. */
-const RELATION_KEYS = {
+/**
+ * Front-matter keys that declare a relation, and what they mean.
+ *
+ * Every directional kind is spelled in **both** directions. A register that
+ * records `depends-on` but not `depended-on-by` is not a smaller vocabulary, it
+ * is a trap: the author writes the inverse, the key means nothing, and the edge
+ * they declared is missing from a graph that reports itself as consistent. Which
+ * half of a pair a repository writes is a filing convention, and a filing
+ * convention is not something a linter gets to have an opinion about.
+ *
+ * `relates-to` is the exception, and it is not one: the relation is symmetric,
+ * so it has no other direction to spell. `contains` is structural and never
+ * written by hand. `tests/parsing.test.ts` holds both facts to the fire.
+ */
+export const RELATION_KEYS = {
     supersedes: { kind: 'supersedes', inverted: false },
     supercedes: { kind: 'supersedes', inverted: false },
     replaces: { kind: 'supersedes', inverted: false },
     obsoletes: { kind: 'supersedes', inverted: false },
+    deprecates: { kind: 'supersedes', inverted: false },
     'superseded-by': { kind: 'supersedes', inverted: true },
     'superceded-by': { kind: 'supersedes', inverted: true },
     'replaced-by': { kind: 'supersedes', inverted: true },
     'obsoleted-by': { kind: 'supersedes', inverted: true },
+    'deprecated-by': { kind: 'supersedes', inverted: true },
+    'rolled-into': { kind: 'supersedes', inverted: true },
     amends: { kind: 'amends', inverted: false },
     extends: { kind: 'amends', inverted: false },
+    refines: { kind: 'amends', inverted: false },
+    clarifies: { kind: 'amends', inverted: false },
+    revises: { kind: 'amends', inverted: false },
     'amended-by': { kind: 'amends', inverted: true },
+    'extended-by': { kind: 'amends', inverted: true },
+    'refined-by': { kind: 'amends', inverted: true },
+    'clarified-by': { kind: 'amends', inverted: true },
+    'revised-by': { kind: 'amends', inverted: true },
     'depends-on': { kind: 'depends-on', inverted: false },
+    'dependent-on': { kind: 'depends-on', inverted: false },
     dependencies: { kind: 'depends-on', inverted: false },
     requires: { kind: 'depends-on', inverted: false },
+    'builds-on': { kind: 'depends-on', inverted: false },
+    'relies-on': { kind: 'depends-on', inverted: false },
+    'depended-on-by': { kind: 'depends-on', inverted: true },
+    'required-by': { kind: 'depends-on', inverted: true },
+    dependents: { kind: 'depends-on', inverted: true },
     assumes: { kind: 'assumes', inverted: false },
+    'assumed-by': { kind: 'assumes', inverted: true },
     'blocked-by': { kind: 'blocked-by', inverted: false },
+    'blocked-on': { kind: 'blocked-by', inverted: false },
+    'waiting-on': { kind: 'blocked-by', inverted: false },
+    'waiting-for': { kind: 'blocked-by', inverted: false },
+    'gated-on': { kind: 'blocked-by', inverted: false },
+    'gated-by': { kind: 'blocked-by', inverted: false },
     blocks: { kind: 'blocked-by', inverted: true },
     'delegates-to': { kind: 'delegates-to', inverted: false },
     'delegated-to': { kind: 'delegates-to', inverted: false },
+    'deferred-to': { kind: 'delegates-to', inverted: false },
     'tracked-in': { kind: 'delegates-to', inverted: false },
+    'tracked-by': { kind: 'delegates-to', inverted: false },
+    'continued-in': { kind: 'delegates-to', inverted: false },
+    'delegated-from': { kind: 'delegates-to', inverted: true },
     related: { kind: 'relates-to', inverted: false },
     'relates-to': { kind: 'relates-to', inverted: false },
+    'related-to': { kind: 'relates-to', inverted: false },
     'see-also': { kind: 'relates-to', inverted: false },
     references: { kind: 'references', inverted: false },
+    reference: { kind: 'references', inverted: false },
     refs: { kind: 'references', inverted: false },
+    'referenced-by': { kind: 'references', inverted: true },
 };
+/**
+ * True when two folded keys are one edit apart.
+ *
+ * One edit, not two, and a transposition counts as one: `supercedesby` for
+ * `supercededby` is a slip of the finger, `categories` for `dependencies` is a
+ * different word. Written out rather than as a distance matrix because the
+ * answer is a yes or a no and the bound is one - the general algorithm would be
+ * more code, not less.
+ */
+export function withinOneEdit(a, b) {
+    if (a === b)
+        return false;
+    if (a.length === b.length) {
+        let first = -1;
+        for (let i = 0; i < a.length; i += 1) {
+            if (a[i] === b[i])
+                continue;
+            if (first === -1) {
+                first = i;
+                continue;
+            }
+            // A second difference is allowed only if the two are a swapped pair, and
+            // only if there is no third.
+            return first === i - 1 && a[first] === b[i] && a[i] === b[first] && a.slice(i + 1) === b.slice(i + 1);
+        }
+        return true;
+    }
+    const [short, long] = a.length < b.length ? [a, b] : [b, a];
+    if (long.length - short.length !== 1)
+        return false;
+    for (let i = 0; i < short.length; i += 1) {
+        if (short[i] === long[i])
+            continue;
+        return short.slice(i) === long.slice(i + 1);
+    }
+    return true;
+}
+/**
+ * True when a front-matter value is shaped like a citation.
+ *
+ * The second half of the gate on {@link misreadRelationKeys}, and the half that
+ * does the work. `sidebar_position: 4` and `ref: main` are a hair away from a
+ * relation key by spelling alone; neither carries anything that could name a
+ * document, and reporting them would make the rule an irritation rather than a
+ * catch (ADR-0006).
+ */
+function looksLikeCitation(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return false;
+    if (parsePrefixedRef(trimmed) !== null)
+        return true;
+    return looksLikePath(trimmed) && isDocumentTarget(trimmed) && !isExternal(trimmed);
+}
+/**
+ * Front-matter keys that read as relations and declare none.
+ *
+ * Front matter is an open vocabulary and most of what lives there is nobody
+ * else's business, so the bar is deliberately high: the key has to be one edit
+ * from a relation key *and* carry something that could name a document. Both
+ * conditions together are what separates `dependson: ADR-0001`, which is an edge
+ * the author believes exists, from `description: ...`, which is a title.
+ */
+function misreadRelationKeys(byKey, from, at) {
+    const out = [];
+    for (const [key, entry] of byKey) {
+        const folded = foldRelationKey(key);
+        if (folded.length === 0 || RELATION_INDEX.has(folded))
+            continue;
+        if (!valuesOf(entry).some(looksLikeCitation))
+            continue;
+        const near = [...RELATION_INDEX.values()]
+            .filter((relation) => withinOneEdit(folded, foldRelationKey(relation.canonical)))
+            .map((relation) => relation.canonical);
+        if (near.length === 0)
+            continue;
+        out.push({ key, suggestion: near.join(', '), from, at: at(entry.start, entry.end) });
+    }
+    return out;
+}
+/**
+ * Folds a front-matter key to its lookup form.
+ *
+ * `depends-on`, `depends_on`, `dependsOn` and `Depends On` are one key written
+ * four ways, and which one a repository uses is decided by whatever wrote the
+ * front matter first. Dropping every separator collapses them - the YAML reader
+ * has already lower-cased the key, which is what makes camel case fold too.
+ *
+ * Which case this folds to is arbitrary and no test pins it: both sides of every
+ * comparison come through here, so upper would work exactly as well. Asserting
+ * on it would be asserting on the implementation.
+ */
+export function foldRelationKey(key) {
+    return key.replace(/[^a-z0-9]/gi, '').toLowerCase();
+}
+/** The vocabulary above, indexed by folded key. */
+const RELATION_INDEX = new Map(Object.entries(RELATION_KEYS).map(([canonical, relation]) => [
+    foldRelationKey(canonical),
+    { ...relation, canonical },
+]));
 /**
  * Phrases that give a link its meaning, longest-matching-nearest wins.
  *
@@ -432,6 +574,7 @@ export function extractDocument(input) {
     // Hand each region the items and references that fall inside it.
     const ownItems = allItems.filter((item) => item.document === identity.id);
     const ownReferences = allReferences.filter((reference) => belongsTo(reference, identity.id, allItems));
+    const misreadKeys = misreadRelationKeys(byKey, identity.id, at);
     const anchors = new Set(scanned.headings.map((h) => h.slug));
     const filled = subSpecifications.map((spec) => ({
         ...spec.extracted,
@@ -448,6 +591,7 @@ export function extractDocument(input) {
         items: ownItems,
         references: ownReferences,
         problems,
+        misreadKeys,
         anchors,
         identity,
         scanned,
@@ -526,6 +670,8 @@ function buildRegion(context) {
             items: [],
             references,
             problems: [],
+            // A region has no front matter of its own to misread.
+            misreadKeys: [],
             anchors,
             identity,
             scanned,
@@ -717,10 +863,12 @@ function extractReferences(context) {
     const { scanned, directives, document, documentAt, items, byKey, status, claimed, file, index } = context;
     const out = [];
     const at = (start, end) => refOf(file, index, start, end);
-    // Front matter.
-    for (const [key, relation] of Object.entries(RELATION_KEYS)) {
-        const entry = byKey.get(key) ?? byKey.get(key.replace(/-/g, '_'));
-        if (!entry)
+    // Front matter, walked in the order it was written rather than in the order
+    // the vocabulary happens to be listed: a key the table does not know still has
+    // to be looked at, and only the document knows which those are.
+    for (const [key, entry] of byKey) {
+        const relation = RELATION_INDEX.get(foldRelationKey(key));
+        if (!relation)
             continue;
         for (const value of valuesOf(entry)) {
             const target = cleanTarget(value);
@@ -1081,7 +1229,7 @@ function renderLink(link) {
             return `<${link.target}>`;
         case 'reference':
         case 'shortcut':
-            return `[${link.text}][${link.target}]`;
+            return `[${link.text}][${link.label ?? ''}]`;
         default:
             return `[${link.text}](${link.target})`;
     }