@descent-vtt/spec-graph 0.4.0 → 0.6.0

package/dist/directives.js.map

@@ -1 +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"]}
+{"version":3,"file":"directives.js","sourceRoot":"","sources":["../src/directives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,KAAK,GAAwB,IAAI,GAAG,CAAgB;IACxD,WAAW;IACX,WAAW;IACX,WAAW;IACX,aAAa;IACb,cAAc;CACf,CAAC,CAAC;AAoBH,MAAM,cAAc,GAAG,wBAAwB,CAAC;AAChD,MAAM,SAAS,GAAG,0EAA0E,CAAC;AAE7F,qFAAqF;AACrF,MAAM,MAAM,GAAuD;IACjE,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC;IACzD,iEAAiE;IACjE,cAAc,EAAE,EAAE;IAClB,WAAW,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;IACtD,WAAW,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC;IAC7C,aAAa,EAAE,CAAC,QAAQ,CAAC;CAC1B,CAAC;AAEF,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAAC,QAAgC;IAC9D,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAW,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAE/B,MAAM,aAAa,GAAG,IAAqB,CAAC;QAC5C,MAAM,SAAS,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAI,IAAI,CAAC,CAAC,CAAY,CAAC,MAAM,CAAC;QACjE,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC5C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAqB,CAAC;QAChD,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;QAEtC,SAAS,CAAC,SAAS,GAAG,CAAC,CAAC;QACxB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxE,MAAM,GAAG,GAAI,CAAC,CAAC,CAAC,CAAY,CAAC,WAAW,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAClB,8DAA8D;YAC9D,MAAM,KAAK,GAAG,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC;YACvC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACjB,MAAM,WAAW,GACf,GAAG,KAAK,SAAS;gBACf,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAI,CAAC,CAAC,CAAC,CAAY,CAAC,MAAM;gBAC1C,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAI,CAAC,CAAC,CAAC,CAAY,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACtF,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;YAE3D,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC9C,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACnE,CAAC;QAED,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,aAAa;YACnB,UAAU;YACV,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,iBAAiB,EAAE,OAAO;SAC3B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,IAAI,CAAC,SAAoB,EAAE,IAAY;IACrD,MAAM,KAAK,GAAG,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;AACrG,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,QAAQ,CAAC,SAAoB,EAAE,IAAY;IACzD,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,OAAO,KAAK,CAAC,KAAK;SACf,KAAK,CAAC,SAAS,CAAC;SAChB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,UAAgC,EAChC,IAAmB,EACnB,MAAsC;AACtC,oEAAoE;AACpE,UAAkB;IAElB,IAAI,IAAI,GAAqB,IAAI,CAAC;IAClC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,CAAC,IAAI,KAAK,IAAI;YAAE,SAAS;QACtC,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,IAAI,SAAS,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC;QAC9E,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,IAAI,UAAU,CAAC;QAC1F,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK;YAAE,SAAS;QAChC,IAAI,IAAI,KAAK,IAAI,IAAI,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK;YAAE,IAAI,GAAG,SAAS,CAAC;IACtE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAwB,EACxB,UAAgC;IAEhC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;IAChF,4EAA4E;IAC5E,wCAAwC;IACxC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAEtC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC7C,4EAA4E;IAC5E,mEAAmE;IACnE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,8EAA8E;IAC9E,sBAAsB;IACtB,MAAM,SAAS,GAAG,IAAI,GAAG,EAA8B,CAAC;IACxD,IAAI,GAAuB,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC1E,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAClC,GAAG,KAAK,IAAI,CAAC,KAAK,CAAC;YACnB,SAAS;QACX,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC9B,GAAG,GAAG,SAAS,CAAC;IAClB,CAAC;IAED,6EAA6E;IAC7E,+EAA+E;IAC/E,4EAA4E;IAC5E,wDAAwD;IACxD,MAAM,IAAI,GAAe,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,CAAC,MAAc,EAAQ,EAAE;QACrC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,IAAK,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAc,CAAC,GAAG,IAAI,MAAM;YAAE,IAAI,CAAC,GAAG,EAAE,CAAC;IAC1F,CAAC,CAAC;IACF,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,CAAC;QAC/B,OAAO,IAAI,GAAG,SAAS,CAAC,MAAM,IAAK,SAAS,CAAC,IAAI,CAAc,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC;YACxF,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAa,CAAC;YACzC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChB,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;QACD,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAEvB,0EAA0E;QAC1E,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;QACrD,yEAAyE;QACzE,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAC5B,OAAO,KAAK,IAAI,CAAC,IAAK,IAAI,CAAC,KAAK,CAAc,CAAC,MAAM,IAAI,MAAM;YAAE,KAAK,IAAI,CAAC,CAAC;QAC5E,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAE3B,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,aAAa,GAAG,KAAK,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC;QACxG,IAAI,aAAa,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACxE,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,uEAAuE;QACvE,wBAAwB;QACxB,MAAM,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAChD,IAAI,OAAO,KAAK,SAAS;YAAE,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","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, ListItem, ScannedDocument } 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 *\n * It answers for one region with no view of the others, so a directive in reach\n * of two items is found for both. Extraction uses `bindItemDirectives`.\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\n/**\n * Pairs each `@spec-item` directive with the one list item it annotates.\n *\n * A directive is written for one item, so it binds to one: the item directly\n * below it, with nothing but blank lines and other comments between, or else\n * the item it is written in, the innermost where items nest. An item that\n * several bind to takes the last one written.\n *\n * A directive alone on its line is in an item only when indented further than\n * that item's marker, which is how CommonMark reads it. Indented under an item,\n * it annotates that item and not the sibling below; flush between two items, it\n * annotates the second.\n */\nexport function bindItemDirectives(\n  scanned: ScannedDocument,\n  directives: readonly Directive[],\n): Map<ListItem, Directive> {\n  const bound = new Map<ListItem, Directive>();\n  const wanted = directives.filter((directive) => directive.name === 'spec-item');\n  // Most documents carry none. Sparing them the pass over their lines changes\n  // how long this takes and nothing else.\n  if (wanted.length === 0) return bound;\n\n  const { lines, listItems, masked } = scanned;\n  // The indentation of each line holding nothing but whitespace and comments.\n  // Code is masked too, so a fence has to be told apart by its flag.\n  const quiet = new Map<number, number>();\n  // For every other line, where the run of quiet lines directly above it began,\n  // when there was one.\n  const quietFrom = new Map<number, number | undefined>();\n  let run: number | undefined;\n  for (const line of lines) {\n    if (!line.code && masked.slice(line.contentStart, line.end).trim() === '') {\n      quiet.set(line.line, line.indent);\n      run ??= line.start;\n      continue;\n    }\n    quietFrom.set(line.line, run);\n    run = undefined;\n  }\n\n  // The items whose text the cursor is in, outermost first. Items nest, so one\n  // that has ended is always on top. An item ends at the end of a line, the next\n  // thing starts on a later one, and no two things start together, so `<` and\n  // `<=` read alike in every comparison of offsets below.\n  const open: ListItem[] = [];\n  const close = (offset: number): void => {\n    while (open.length > 0 && (open[open.length - 1] as ListItem).end <= offset) open.pop();\n  };\n  let next = 0;\n  for (const directive of wanted) {\n    while (next < listItems.length && (listItems[next] as ListItem).start < directive.start) {\n      const item = listItems[next] as ListItem;\n      close(item.start);\n      open.push(item);\n      next += 1;\n    }\n    close(directive.start);\n\n    // Sharing its line with text, a directive is in whatever that text is in.\n    const indent = quiet.get(directive.line) ?? Infinity;\n    // No deeper than the scanner already went to find where these items end.\n    let depth = open.length - 1;\n    while (depth >= 0 && (open[depth] as ListItem).indent >= indent) depth -= 1;\n    const holder = open[depth];\n\n    const below = listItems[next];\n    const directlyAbove = below !== undefined && (quietFrom.get(below.line) ?? Infinity) <= directive.start;\n    if (directlyAbove && (holder === undefined || below.start < holder.end)) {\n      bound.set(below, directive);\n      continue;\n    }\n    // Flush under an item and above no other, it continues the item as any\n    // unindented line does.\n    const written = holder ?? open[open.length - 1];\n    if (written !== undefined) bound.set(written, directive);\n  }\n  return bound;\n}\n"]}

package/dist/extract.d.ts

@@ -17,6 +17,7 @@
 import { type DocumentIdentity } from './identity.js';
 import { type ScannedDocument } from './markdown.js';
 import type { DocumentNode, EdgeKind, EdgeOrigin, ItemNode, MisreadKey, ParseProblem, SourceRef } from './types.js';
+import { type YamlEntry } from './yaml.js';
 /**
  * A relation that has been read but not yet resolved to a target node.
  *
@@ -108,6 +109,25 @@ export declare const RELATION_KEYS: Readonly<Record<string, {
  * on it would be asserting on the implementation.
  */
 export declare function foldRelationKey(key: string): string;
+/**
+ * The front matter a region inherits from the file that contains it.
+ *
+ * [ADR-0009](../docs/adr/0009-a-specification-is-a-region.md) left this open,
+ * and [ADR-0016](../docs/adr/0016-a-query-needs-a-sentence.md) made leaving it
+ * open a defect. A repository can now write `document[fm.owner!=platform]` as a
+ * rule of its own, and on a register every region answered nothing - which
+ * `!=` reads as a mismatch, because an absent value is not the value. A file
+ * whose front matter said `owner: platform` was reported twice for not being
+ * owned by platform, and the message rendered `{0.fm.owner}` as the literal
+ * placeholder. Confident, wrong, and unanswerable: the ADR-0006 failure.
+ *
+ * Two kinds of key stay behind. A relation key is a claim the file made -
+ * `supersedes:` at the top of a register supersedes on behalf of the register,
+ * not on behalf of each decision in it, and the edges were built from the
+ * file's entries before this ran. And a key the region answers itself must not
+ * be shadowed, which is {@link UNINHERITED}.
+ */
+export declare function inheritableFrontMatter(entries: readonly YamlEntry[]): Readonly<Record<string, string | readonly 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

@@ -14,7 +14,7 @@
  * they do not resolve, because the alternative is reporting `SHA-256` as a
  * broken reference to specification 256.
  */
-import { attr, attrList, directiveFor, parseDirectives } from './directives.js';
+import { attr, attrList, bindItemDirectives, parseDirectives } from './directives.js';
 import { identify, isDocumentTarget, isExternal, looksLikePath, normaliseRef, parsePrefixedRef, withinOneEdit, ID_KEYS, } from './identity.js';
 import { isStatusHeading, phaseFromPath, phaseOf, STATUS_KEYS, supersessionTargetsIn } from './lifecycle.js';
 import { scanMarkdown, slugify } from './markdown.js';
@@ -158,6 +158,35 @@ const RELATION_INDEX = new Map(Object.entries(RELATION_KEYS).map(([canonical, re
     foldRelationKey(canonical),
     { ...relation, canonical },
 ]));
+/**
+ * Keys a region must answer for itself, so the file's answer cannot shadow one.
+ *
+ * Identity and status and title are the three things a register exists to vary
+ * row by row. The rest of the file's front matter describes the file, and a
+ * decision inside the file is described by it too.
+ */
+const UNINHERITED = new Set([...ID_KEYS, ...STATUS_KEYS, 'title', 'alias', 'aliases']);
+/**
+ * The front matter a region inherits from the file that contains it.
+ *
+ * [ADR-0009](../docs/adr/0009-a-specification-is-a-region.md) left this open,
+ * and [ADR-0016](../docs/adr/0016-a-query-needs-a-sentence.md) made leaving it
+ * open a defect. A repository can now write `document[fm.owner!=platform]` as a
+ * rule of its own, and on a register every region answered nothing - which
+ * `!=` reads as a mismatch, because an absent value is not the value. A file
+ * whose front matter said `owner: platform` was reported twice for not being
+ * owned by platform, and the message rendered `{0.fm.owner}` as the literal
+ * placeholder. Confident, wrong, and unanswerable: the ADR-0006 failure.
+ *
+ * Two kinds of key stay behind. A relation key is a claim the file made -
+ * `supersedes:` at the top of a register supersedes on behalf of the register,
+ * not on behalf of each decision in it, and the edges were built from the
+ * file's entries before this ran. And a key the region answers itself must not
+ * be shadowed, which is {@link UNINHERITED}.
+ */
+export function inheritableFrontMatter(entries) {
+    return toRecord(entries.filter((entry) => !UNINHERITED.has(entry.key) && !RELATION_INDEX.has(foldRelationKey(entry.key))));
+}
 /**
  * Phrases that give a link its meaning, longest-matching-nearest wins.
  *
@@ -459,6 +488,7 @@ export function extractDocument(input) {
     const byKey = new Map();
     for (const entry of entries)
         byKey.set(entry.key, entry);
+    const inherited = inheritableFrontMatter(entries);
     const h1 = scanned.headings.find((h) => h.level === 1) ?? null;
     const frontMatterId = firstValue(byKey, ID_KEYS) ?? null;
     const identityOf = (declaredId, directive) => identify({
@@ -525,6 +555,7 @@ export function extractDocument(input) {
         file,
         pathPhase,
         record,
+        inherited,
     }));
     const ownerAt = (offset) => {
         const region = regionAt(regions, offset);
@@ -593,12 +624,13 @@ function belongsTo(reference, documentId, items) {
  * It produces exactly the `DocumentNode` a whole file produces, which is the
  * reason every rule, query and reporter works on registers without knowing they
  * exist. The only deliberate differences: the node is anchored at its heading
- * rather than at line one, it carries no front matter of its own, and it does
- * not claim the file's path as an alias - the file already does, and two nodes
- * answering to one path would make every link to that file ambiguous.
+ * rather than at line one, it carries the file's front matter rather than front
+ * matter of its own, and it does not claim the file's path as an alias - the
+ * file already does, and two nodes answering to one path would make every link
+ * to that file ambiguous.
  */
 function buildRegion(context) {
-    const { region, input, scanned, index, file, pathPhase, record } = context;
+    const { region, input, scanned, index, file, pathPhase, record, inherited } = context;
     const at = (start, end) => refOf(file, index, start, end);
     const identity = identify({
         path: input.path,
@@ -629,7 +661,7 @@ function buildRegion(context) {
         phase: record ? 'record' : declaredPhase !== 'unknown' ? declaredPhase : pathPhase,
         rawStatus,
         statusAt,
-        frontMatter: {},
+        frontMatter: inherited,
     };
     const anchors = new Set(scanned.headings.filter((h) => h.start >= region.start && h.start < region.end).map((h) => h.slug));
     // Relations a table declares by column, typed by the header the author wrote.
@@ -651,7 +683,8 @@ function buildRegion(context) {
             items: [],
             references,
             problems: [],
-            // A region has no front matter of its own to misread.
+            // The file has already reported anything misread at the top of it, and
+            // there is one file however many regions it holds.
             misreadKeys: [],
             anchors,
             identity,
@@ -731,10 +764,11 @@ function extractItems(context) {
     const { scanned, directives, ownerAt, file, index } = context;
     const out = [];
     const ordinals = new Map();
+    const bound = bindItemDirectives(scanned, directives);
     for (const item of scanned.listItems) {
         const section = sectionPathAt(scanned, item.start);
         const inObligationSection = section.some((heading) => OBLIGATION_SECTIONS.has(normaliseHeading(heading)));
-        const directive = directiveFor(directives, 'spec-item', { start: item.start, end: item.end }, 200);
+        const directive = bound.get(item) ?? null;
         if (!isObligation(item, inObligationSection, directive))
             continue;
         const documentId = ownerAt(item.start);
@@ -759,6 +793,7 @@ function extractItems(context) {
             kind: 'item',
             title: (directive ? attr(directive, 'title')?.value : null) ?? summarise(item.firstLine),
             at: refOf(file, index, item.start, item.end),
+            declared: declaredId !== null && declaredId !== undefined,
             document: documentId,
             section,
             text: summarise(item.firstLine),