@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/document/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../../src/core/document/apply.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A feature's ADDED/MODIFIED/REMOVED requirements folded onto a living set.\n *\n * The one thing `loam archive` does to a spec, and a module of its own because\n * it is where a requirement stops being a delta: `asLiving` drops the\n * `Based-On:` pin, which is a claim about which living version this was written\n * against — meaningless once it IS the living version, and poison for the next\n * feature's baseline, which would otherwise hash the previous feature's pin.\n *\n * It is also where the merge says what it TAKES AWAY (`replacementsOf`,\n * `droppedParts`), because only the algebra knows which living requirement a\n * delta requirement selects: a MODIFIED carries its full new text and replaces\n * the living requirement whole, so every scenario and every join line it does\n * not restate is gone after the archive — and a second reading of \"which one\n * does this select\" anywhere else would be a second answer free to disagree.\n */\nimport { requirementIdProblems, splitRealizesPin, withoutBaseline, type DeltaKind, type Requirement } from \"./spec.js\";\n\n/**\n * A delta requirement as it lands in the living document, with the bookkeeping\n * that belongs to the DELTA left behind: the `Based-On:` pin (a claim about\n * which living version this was written against — meaningless once it IS the\n * living version, and poison for the next feature's baseline, which would then\n * hash the previous feature's pin) and the line it was parsed from.\n */\nfunction asLiving(d: Requirement): Requirement {\n  const { line: _dropped, ...rest } = withoutBaseline(d);\n  return { ...rest, kind: \"BASE\" };\n}\n\n/** One living requirement a delta requirement takes the place of, or takes away. */\nexport interface Replacement {\n  /**\n   * What the delta did to it, NET: MODIFIED or REMOVED — or ADDED, when it lands on a\n   * requirement that already exists. A requirement the delta selects twice keeps\n   * one record, REMOVED if its last step removed it.\n   */\n  kind: Exclude<DeltaKind, \"BASE\">;\n  /** The living requirement as it stood before the merge. */\n  living: Requirement;\n  /** What lands in its place, or null for a removal. */\n  merged: Requirement | null;\n}\n\n/**\n * Apply a feature's ADDED/MODIFIED/REMOVED requirements onto a living requirement set.\n *\n * A living requirement the delta does not touch comes back as the SAME object\n * it went in as (a living spec's requirements are already BASE), and that\n * identity is load-bearing: archive keys each requirement's raw bytes on it, so\n * an untouched requirement is written back exactly as its author wrote it and\n * only the ones this function replaced or added are serialized.\n */\nexport function applyRequirementDelta(living: Requirement[], delta: Requirement[]): Requirement[] {\n  return foldDelta(living, delta).merged;\n}\n\n/**\n * Every living requirement the delta replaces or removes, in delta order — the\n * walk `applyRequirementDelta` takes, so the two cannot disagree about which\n * requirement a MODIFIED selected. Throws exactly when the merge would.\n */\nexport function replacementsOf(living: Requirement[], delta: Requirement[]): Replacement[] {\n  return foldDelta(living, delta).replaced;\n}\n\nfunction foldDelta(living: Requirement[], delta: Requirement[]): { merged: Requirement[]; replaced: Replacement[] } {\n  const malformed = [...requirementIdProblems(living), ...requirementIdProblems(delta)];\n  if (malformed.length > 0) {\n    throw new Error(\"cannot merge requirements with invalid, repeated, or duplicate Requirement-ID declarations\");\n  }\n  let result: Requirement[] = living.map((r) => (r.kind === \"BASE\" ? r : { ...r, kind: \"BASE\" as DeltaKind }));\n  const replaced: Replacement[] = [];\n  // What each requirement the fold has PRODUCED stands for: the replacement\n  // record it belongs to, or null for one this delta added. A delta may select\n  // one requirement twice (nothing refuses a repeated heading in a delta), and\n  // without this the second step reported the first step's text as \"living\" —\n  // a drop the merge never makes. With it every record stays pre-merge to\n  // post-merge, so what `droppedParts` reads is the net change.\n  const born = new Map<Requirement, Replacement | null>();\n  const record = (kind: Replacement[\"kind\"], previous: Requirement, merged: Requirement | null): void => {\n    const earlier = born.get(previous);\n    if (earlier === undefined) {\n      const entry: Replacement = { kind, living: previous, merged };\n      replaced.push(entry);\n      if (merged !== null) born.set(merged, entry);\n    } else if (earlier === null) {\n      // Added by this delta, so nothing living is replaced by rewriting it.\n      if (merged !== null) born.set(merged, null);\n    } else {\n      earlier.merged = merged;\n      if (merged === null) earlier.kind = \"REMOVED\";\n      else born.set(merged, earlier);\n    }\n  };\n  const add = (merged: Requirement): void => {\n    born.set(merged, null);\n    result.push(merged);\n  };\n  for (const d of delta) {\n    // BASE is not a delta kind — a requirement outside an ADDED/MODIFIED/REMOVED\n    // section (e.g. quoted under ## Notes) is documentation, not a change.\n    if (d.kind === \"BASE\") continue;\n    const kind = d.kind;\n    if (d.id !== undefined) {\n      const idMatches = result\n        .map((r, i) => (r.id === d.id ? i : -1))\n        .filter((i) => i >= 0);\n      const nameMatches = result\n        .map((r, i) => (r.name === d.name ? i : -1))\n        .filter((i) => i >= 0);\n      const otherNameMatches = nameMatches.filter((i) => !idMatches.includes(i));\n      if (idMatches.length > 1 || otherNameMatches.length > 0) {\n        throw new Error(\n          `ambiguous requirement identity for '${d.name}' (${d.id}): Requirement-ID and heading select different living requirements`,\n        );\n      }\n      if (d.kind === \"REMOVED\") {\n        const selected = new Set(idMatches);\n        for (const i of idMatches) record(kind, result[i]!, null);\n        result = result.filter((_, i) => !selected.has(i));\n      } else {\n        const merged: Requirement = asLiving(d);\n        const at = idMatches[0];\n        if (at === undefined) add(merged);\n        else {\n          record(kind, result[at]!, merged);\n          result[at] = merged;\n        }\n      }\n    } else if (d.kind === \"REMOVED\") {\n      for (const r of result) if (r.name === d.name) record(kind, r, null);\n      result = result.filter((r) => r.name !== d.name);\n    } else {\n      const i = result.findIndex((r) => r.name === d.name);\n      // A legacy delta may still modify an ID-bearing living requirement by\n      // its exact heading. Keep the identity while the repository migrates.\n      const inheritedId = i >= 0 ? result[i]!.id : undefined;\n      const merged: Requirement = {\n        ...asLiving(d),\n        ...(inheritedId === undefined ? {} : { id: inheritedId }),\n      };\n      if (i < 0) add(merged);\n      else {\n        record(kind, result[i]!, merged);\n        result[i] = merged;\n      }\n    }\n  }\n  return { merged: result, replaced };\n}\n\n/**\n * The join lines a requirement carries, keyed by `Requirement` field and\n * spelled as the body line writes them — every list the parser reads out of a\n * requirement's text, in one order, so the archive plan, `loam delta` and their\n * `--json` rows name a dropped entry the same way.\n */\nexport const DIRECTIVE_LINES = {\n  operations: \"Operations\",\n  covers: \"Covers\",\n  requires: \"Requires\",\n  capabilities: \"Capability\",\n  realizes: \"Realizes\",\n  publishes: \"Publishes\",\n  consumes: \"Consumes\",\n} as const;\n\nexport type DirectiveKey = keyof typeof DIRECTIVE_LINES;\n\n/** What one replacement takes out of the living documents. */\nexport interface DroppedParts {\n  /** Living scenario names the replacement does not carry — every one of them, for a removal. */\n  scenarios: string[];\n  /** Per join line, the living entries the replacement does not restate. Only lines that lose something are present. */\n  directives: Partial<Record<DirectiveKey, string[]>>;\n}\n\n/**\n * What a replacement drops: the living scenarios its new text does not carry,\n * by name, and each join-line entry it does not restate, verbatim.\n *\n * VERBATIM AND BY NAME, and that is a reading, not a judgement — with one\n * exception for bookkeeping: a `Realizes:` entry is compared, and reported, by\n * the target it names, its `@<digest>` pin set aside. A scenario\n * renamed is reported dropped, and a `Covers:` entry respelled from an element\n * id to the service name is reported dropped too, though either may mean the\n * same thing — this lists what the living text says that the merged text does\n * not, and the author decides. What it must never be again is the old answer,\n * which was nothing: a MODIFIED that restated one of two scenarios merged, and\n * the second vanished under the archive's exit 0.\n */\nexport function droppedParts(replacement: Replacement): DroppedParts {\n  const { living, merged } = replacement;\n  const keptScenarios = new Set((merged?.scenarios ?? []).map((s) => s.name));\n  const directives: Partial<Record<DirectiveKey, string[]>> = {};\n  for (const key of Object.keys(DIRECTIVE_LINES) as DirectiveKey[]) {\n    // A `Realizes:` entry is compared by the target it names: the `@<digest>`\n    // pin `loam rebase --living` writes is bookkeeping, and a replacement that\n    // restates the target unpinned has kept the join, not dropped it.\n    const spell = key === \"realizes\" ? (entry: string): string => splitRealizesPin(entry).target : (entry: string): string => entry;\n    const kept = new Set((merged?.[key] ?? []).map(spell));\n    const gone = [...new Set(living[key].map(spell))].filter((entry) => !kept.has(entry));\n    if (gone.length > 0) directives[key] = gone;\n  }\n  return { scenarios: living.scenarios.map((s) => s.name).filter((name) => !keptScenarios.has(name)), directives };\n}\n\n/** Does this replacement take anything away at all? */\nexport function dropsAnything(parts: DroppedParts): boolean {\n  return parts.scenarios.length > 0 || Object.keys(parts.directives).length > 0;\n}\n\n/** One replacement that takes something away, as both the archive plan and `loam delta` report it. */\nexport interface DroppedRow extends DroppedParts {\n  kind: Replacement[\"kind\"];\n  /** The LIVING requirement's heading and id — what a reader finds in the file today. */\n  requirement: string;\n  id?: string;\n}\n\n/**\n * Every replacement that takes something away: a removal always (the\n * requirement itself is what goes), a MODIFIED or a landing ADDED whenever its\n * new text restates less than the living one held.\n */\nexport function droppedBy(living: Requirement[], delta: Requirement[]): DroppedRow[] {\n  return replacementsOf(living, delta).flatMap((replacement) => {\n    const parts = droppedParts(replacement);\n    if (replacement.kind !== \"REMOVED\" && !dropsAnything(parts)) return [];\n    const { name, id } = replacement.living;\n    return [{ kind: replacement.kind, requirement: name, ...(id === undefined ? {} : { id }), ...parts }];\n  });\n}\n\n/** One dropped row in words — the line the archive plan and `loam delta` both print. */\nexport function droppedSentence(row: DroppedRow): string {\n  const who = row.id === undefined ? `'${row.requirement}'` : `${row.id} '${row.requirement}'`;\n  const lost = [\n    ...(row.scenarios.length === 0 ? [] : [`scenario ${row.scenarios.map((s) => `'${s}'`).join(\", \")}`]),\n    ...(Object.keys(DIRECTIVE_LINES) as DirectiveKey[]).flatMap((key) => {\n      const gone = row.directives[key];\n      return gone === undefined ? [] : [`${DIRECTIVE_LINES[key]}: ${gone.join(\", \")}`];\n    }),\n  ];\n  if (row.kind === \"REMOVED\") return lost.length === 0 ? `${who} is removed` : `${who} is removed, and with it ${lost.join(\"; \")}`;\n  return `${who} is replaced whole, and its new text does not carry ${lost.join(\"; \")}`;\n}\n"]}

package/dist/core/{frontmatter.js → document/frontmatter.js}

@@ -6,10 +6,11 @@
  * are the only deterministic tie to reality: everything else loam checks is
  * internal consistency, which a fluent enough fiction satisfies perfectly.
  */
+import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { isMap, parse, parseDocument } from "yaml";
-import { decodeDocument, NotUtf8DocumentError } from "./document-bytes.js";
+import { decodeDocument, NotUtf8DocumentError } from "../kernel/document-bytes.js";
 /**
  * Drop a leading byte-order mark.
  *
@@ -132,8 +133,24 @@ export function listField(fm, key) {
  * A document with no frontmatter gets one, and the text that was there becomes
  * the body. A header that does not parse (or is not a mapping) is replaced
  * rather than merged into — it cannot be edited without guessing what it meant.
+ *
+ * Keys named in `remove` are DELETED. That is not a convenience: `loam vouch`
+ * stamps `vouch_scope` when a person read only a sample of the document, and
+ * a full vouch afterwards has to take that claim back out. Left behind, a
+ * stale scope would keep a fully-read document reading as sampled forever —
+ * on `loam list`, in `loam validate`'s `sources.sampled-vouch`, and in the
+ * frontmatter a person opens — which is the same class of lie as a stamp with
+ * nothing behind it, pointing the other way.
+ *
+ * Deletion is a separate LIST rather than a null value in `fields`, and the
+ * difference is the compiler's: `string | null` is the most common field shape
+ * in this codebase (`stringField(fm, k) ?? null` appears in a dozen readers),
+ * so a writer that stamped a field it had just read back — `{ owner }` — would
+ * silently delete `owner` on every document that never had one, where today
+ * that line does not compile. Clearing a key is something a call site says,
+ * never something a value happens to be.
  */
-export function withFrontmatterFields(source, fields) {
+export function withFrontmatterFields(source, fields, remove = []) {
     // Stamping a BOM-prefixed document drops the BOM. It sits above the header, so
     // the promise about the body still holds — and leaving it would re-break the
     // file for every parser anchored at position 0, including ours.
@@ -144,6 +161,15 @@ export function withFrontmatterFields(source, fields) {
     const doc = editable ? parsed : parseDocument("");
     for (const [key, value] of Object.entries(fields))
         doc.set(key, value);
+    // Guarded, not because a missing key is a problem — deleting one that is not
+    // there is a no-op — but because yaml's `Document.delete` THROWS ("Expected
+    // a YAML collection as document contents") when the document has no mapping
+    // at all: the empty header of a document that had none, and the replacement
+    // built for a header that would not parse. Both are states this writer
+    // reaches on purpose, and in both there is nothing to clear.
+    if (isMap(doc.contents))
+        for (const key of remove)
+            doc.delete(key);
     const yamlText = doc.toString();
     if (at === null)
         return `---\n${yamlText}---\n\n${md}`;
@@ -163,6 +189,60 @@ export function rawBody(source) {
     const at = bounds(md);
     return at === null ? md : md.slice(at.bodyStart);
 }
+/**
+ * The stamp `loam vouch` writes into `content_digest`: sha256 of the
+ * document's own BODY — every byte after the frontmatter block (below the
+ * closing `---` line and its newline; `rawBody` is the one definition of that
+ * cut) — first 16 hex characters, the sources recipe's length.
+ *
+ * Byte-exact, no normalization. Body-only is load-bearing: vouch itself
+ * rewrites the frontmatter as it stamps, and a later frontmatter-only edit
+ * (another vouch, a corrected owner) must not read as the document moving.
+ *
+ * It lived in core/provenance/stamp.ts beside the sources recipe until the
+ * fleet ENUMERATION needed it: `loam list` and `loam status` read a document
+ * edited under its vouch off `ServiceEntry` (core/repo/repo.ts), and core/repo
+ * cannot import core/provenance — that package resolves service paths through
+ * core/repo. Here, beside the cut it hashes, both can reach it.
+ */
+export function contentDigest(source) {
+    return createHash("sha256").update(rawBody(source), "utf8").digest("hex").slice(0, 16);
+}
+/**
+ * The `content_digest` a document's body is held to, or undefined when there
+ * is nothing to hold it to — `content.stale`'s precondition, spelled ONCE so
+ * the validate finding (core/provenance/findings.ts) and the fleet enumeration
+ * cannot disagree about which documents are stamped.
+ *
+ * Only a `verified` document: a draft's words are nobody's vouch yet. And a
+ * verified document with no stamp predates the field — quiet on purpose: the
+ * fix is re-vouching, and grading years of pre-feature vouches as suspect would
+ * drown the fleet in warnings nobody chose.
+ *
+ * Split from `movedUnderVouch` below so a reader that has only the header in
+ * hand — the fleet enumeration — can learn there is nothing to compare before
+ * it pays for reading the body.
+ */
+export function contentStamp(fm) {
+    return stringField(fm, "status") === "verified" ? stringField(fm, "content_digest") : undefined;
+}
+/**
+ * The one condition `content.stale` fires on: a `verified` document whose body
+ * no longer hashes to the `content_digest` its vouch stamped.
+ *
+ * One spelling for three readers that must give the same answer. `loam
+ * validate` grades it (core/provenance/findings.ts); the fleet enumeration
+ * reads it off every service (core/repo/repo.ts) so `loam list` and `loam
+ * status` cannot call fresh a document validate calls stale; and `loam archive`
+ * asks it of the document it is ABOUT to write, before the bytes exist, so it
+ * can name every vouched spec its merge moves under the stamp — and whose owner
+ * then owes a re-vouch. Two spellings would let the archive's list, the listing
+ * and the next validate disagree about which documents went stale.
+ */
+export function movedUnderVouch(fm, raw) {
+    const stamped = contentStamp(fm);
+    return stamped !== undefined && contentDigest(raw) !== stamped;
+}
 /**
  * Read a markdown file's frontmatter; a missing file reads as absent.
  *
@@ -196,4 +276,25 @@ export async function readFrontmatter(path) {
 /** The statuses each kind of artifact may carry. */
 export const SERVICE_STATUSES = ["draft", "verified"];
 export const FEATURE_STATUSES = ["proposed", "in_progress", "built", "done"];
+/**
+ * A document's prose with any leading frontmatter block dropped — what
+ * `loam delta` and `loam context` print as a feature's intent.
+ *
+ * Moved verbatim from `commands/delta/slices.ts` when the context pack became
+ * its second caller. It deliberately keeps its own, looser fence rule
+ * (`\n---` as a substring, not `bounds()`'s line-exact match) rather than
+ * delegating to `parseFrontmatter(md).body`: the two agree on every header
+ * loam writes, but the delta brief's output is pinned byte-for-byte by its
+ * tests, and unifying the rules is a behaviour change to make deliberately,
+ * not as a side effect of a move.
+ */
+export function stripFrontmatter(md) {
+    if (!md.startsWith("---"))
+        return md;
+    const close = md.indexOf("\n---", 3);
+    if (close === -1)
+        return md;
+    const nl = md.indexOf("\n", close + 1);
+    return nl === -1 ? "" : md.slice(nl + 1).trimStart();
+}
 //# sourceMappingURL=frontmatter.js.map

package/dist/core/document/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../../src/core/document/frontmatter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * YAML frontmatter — the provenance of an artifact.\n *\n * `status` says whether a human has vouched for the document, `sources` says\n * which code it was written from. When the prose is written by an agent, these\n * are the only deterministic tie to reality: everything else loam checks is\n * internal consistency, which a fluent enough fiction satisfies perfectly.\n */\nimport { createHash } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { isMap, parse, parseDocument } from \"yaml\";\nimport { decodeDocument, NotUtf8DocumentError } from \"../kernel/document-bytes.js\";\n\nexport interface Frontmatter {\n  /** True when a terminated `---` block was found, even if it was empty. */\n  present: boolean;\n  /**\n   * True when the block was found but its YAML cannot be read as a mapping —\n   * a parse error, or a scalar/sequence document. `data` is then {}, which is\n   * NOT the same fact as an empty header: the fields are unreadable, not\n   * absent, and a checker that grades them \"missing\" sends the author adding\n   * lines to a block YAML refuses to parse. Validate turns this flag into\n   * `frontmatter.malformed`; the writer (withFrontmatterFields) has its own\n   * replace-don't-merge rule for the same state.\n   */\n  malformed: boolean;\n  /**\n   * Why the FILE could not be read as text at all, or absent when it could —\n   * set only by `readFrontmatter`, since a caller that already holds a string\n   * has nothing left to decode.\n   *\n   * A third state, not a shade of the other two: `present: false` here means\n   * nobody could look, where everywhere else it means nobody wrote a header.\n   * A checker must ask this first, or it reports \"owner/status/sources missing\"\n   * over a file whose lines are right there — the same false cascade\n   * `malformed` exists to stop, one layer lower down.\n   */\n  unreadable?: string;\n  /** The parsed mapping, or {} when absent or malformed. */\n  data: Record<string, unknown>;\n  /** The document with the frontmatter removed. */\n  body: string;\n}\n\n/** Where the header sits in the raw text. */\ninterface Bounds {\n  /** First character of the YAML text. */\n  start: number;\n  /** One past its last character — the newline before the closing fence included. */\n  end: number;\n  /** First character of the body. */\n  bodyStart: number;\n}\n\n/**\n * Drop a leading byte-order mark.\n *\n * With one in front, the opening `---` is no longer at position 0, so the whole\n * header reads as absent: a documented artifact silently becomes an\n * undocumented one — no owner, no status, no `sources` — and nothing says why.\n * The same blindness `spec.ts` had at `^##`.\n *\n * Only at position 0: elsewhere U+FEFF is a zero-width no-break space and is the\n * author's content. Callers strip before measuring, so the offsets `bounds`\n * returns index the same string the caller then slices.\n */\nfunction stripBom(text: string): string {\n  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;\n}\n\n/**\n * A fence is a LINE of exactly three dashes. Trailing whitespace is tolerated\n * (`\\s` also swallows the CR of a CRLF file), trailing text is not: `--- title`\n * is prose, `----` is a horizontal rule. Matching the substring `---` instead —\n * as this used to — made both of those fences, so a stray rule closed the\n * header early and a `--- note` closer silently ate its own trailing text.\n */\nconst FENCE_RE = /^---\\s*$/;\n\n/**\n * Locate the frontmatter block. The opener is the very first line, the closer\n * the first subsequent fence line — a later horizontal rule is body, not a\n * second fence. No closer means an unterminated opener: not frontmatter at all.\n *\n * The reader and the writer both go through this, so they can never disagree\n * about which bytes are the header — the writer's promise to leave the body\n * untouched depends on that being one decision, not two.\n */\nfunction bounds(md: string): Bounds | null {\n  const firstNl = md.indexOf(\"\\n\");\n  if (!FENCE_RE.test(firstNl === -1 ? md : md.slice(0, firstNl))) return null;\n  // A lone `---` with nothing after it is an unterminated opener.\n  if (firstNl === -1) return null;\n  const start = firstNl + 1;\n  for (let lineStart = start; ; ) {\n    const nl = md.indexOf(\"\\n\", lineStart);\n    const line = nl === -1 ? md.slice(lineStart) : md.slice(lineStart, nl);\n    if (FENCE_RE.test(line)) {\n      // An empty block (`---\\n---`) has no text between the fences: start === end.\n      return { start, end: lineStart, bodyStart: nl === -1 ? md.length : nl + 1 };\n    }\n    if (nl === -1) return null;\n    lineStart = nl + 1;\n  }\n}\n\n/**\n * Split a markdown document into its frontmatter and body. A document with no\n * frontmatter is returned whole rather than truncated.\n */\nexport function parseFrontmatter(source: string): Frontmatter {\n  const md = stripBom(source);\n  const at = bounds(md);\n  if (at === null) return { present: false, malformed: false, data: {}, body: md };\n\n  const yamlText = md.slice(at.start, at.end);\n  const body = md.slice(at.bodyStart).trimStart();\n\n  let data: Record<string, unknown> = {};\n  let malformed = false;\n  try {\n    const parsed: unknown = parse(yamlText);\n    if (parsed && typeof parsed === \"object\" && !Array.isArray(parsed)) {\n      data = parsed as Record<string, unknown>;\n    } else if (parsed !== null) {\n      // A scalar or sequence header holds no fields to read — as unreadable as\n      // broken YAML. null is the empty block (`---\\n---`): legal, and empty.\n      malformed = true;\n    }\n  } catch {\n    // A bad header must not make the document unreadable (the body is still the\n    // body, and never crashes a command) — but the failure travels as a flag,\n    // so the caller can say `frontmatter.malformed` instead of the false\n    // cascade \"owner/status missing\" the silent {} used to produce.\n    malformed = true;\n  }\n  return { present: true, malformed, data, body };\n}\n\n/** A field as text. Non-string scalars (a bare date, a number) are stringified. */\nexport function stringField(fm: Frontmatter, key: string): string | undefined {\n  const v = fm.data[key];\n  if (v === undefined || v === null) return undefined;\n  if (typeof v === \"string\") return v;\n  if (typeof v === \"number\" || typeof v === \"boolean\") return String(v);\n  if (v instanceof Date) return v.toISOString().slice(0, 10);\n  return undefined;\n}\n\n/** A field as a list. A lone scalar counts as a list of one. */\nexport function listField(fm: Frontmatter, key: string): string[] {\n  const v = fm.data[key];\n  if (v === undefined || v === null) return [];\n  if (Array.isArray(v)) return v.map((x) => String(x)).filter((s) => s.length > 0);\n  const one = stringField(fm, key);\n  return one === undefined ? [] : [one];\n}\n\n/**\n * Return `md` with these frontmatter fields set and everything below the closing\n * fence byte-identical.\n *\n * The header is edited through yaml's document model rather than rebuilt from\n * the parsed data: keys keep their order and their comments, fields nobody named\n * are left exactly as they were, and a value that would read back as something\n * else — a digest of all digits, say — gets quoted for us. Stamping a document\n * is not a licence to reformat it: the diff a reviewer sees should be the lines\n * that changed, and nothing else.\n *\n * A document with no frontmatter gets one, and the text that was there becomes\n * the body. A header that does not parse (or is not a mapping) is replaced\n * rather than merged into — it cannot be edited without guessing what it meant.\n *\n * Keys named in `remove` are DELETED. That is not a convenience: `loam vouch`\n * stamps `vouch_scope` when a person read only a sample of the document, and\n * a full vouch afterwards has to take that claim back out. Left behind, a\n * stale scope would keep a fully-read document reading as sampled forever —\n * on `loam list`, in `loam validate`'s `sources.sampled-vouch`, and in the\n * frontmatter a person opens — which is the same class of lie as a stamp with\n * nothing behind it, pointing the other way.\n *\n * Deletion is a separate LIST rather than a null value in `fields`, and the\n * difference is the compiler's: `string | null` is the most common field shape\n * in this codebase (`stringField(fm, k) ?? null` appears in a dozen readers),\n * so a writer that stamped a field it had just read back — `{ owner }` — would\n * silently delete `owner` on every document that never had one, where today\n * that line does not compile. Clearing a key is something a call site says,\n * never something a value happens to be.\n */\nexport function withFrontmatterFields(\n  source: string,\n  fields: Record<string, string>,\n  remove: readonly string[] = [],\n): string {\n  // Stamping a BOM-prefixed document drops the BOM. It sits above the header, so\n  // the promise about the body still holds — and leaving it would re-break the\n  // file for every parser anchored at position 0, including ours.\n  const md = stripBom(source);\n  const at = bounds(md);\n  const parsed = parseDocument(at === null ? \"\" : md.slice(at.start, at.end));\n  const editable = parsed.errors.length === 0 && (parsed.contents === null || isMap(parsed.contents));\n  const doc = editable ? parsed : parseDocument(\"\");\n\n  for (const [key, value] of Object.entries(fields)) doc.set(key, value);\n  // Guarded, not because a missing key is a problem — deleting one that is not\n  // there is a no-op — but because yaml's `Document.delete` THROWS (\"Expected\n  // a YAML collection as document contents\") when the document has no mapping\n  // at all: the empty header of a document that had none, and the replacement\n  // built for a header that would not parse. Both are states this writer\n  // reaches on purpose, and in both there is nothing to clear.\n  if (isMap(doc.contents)) for (const key of remove) doc.delete(key);\n  const yamlText = doc.toString();\n\n  if (at === null) return `---\\n${yamlText}---\\n\\n${md}`;\n  return md.slice(0, at.start) + yamlText + md.slice(at.end);\n}\n\n/**\n * The document's body, byte-exact: everything after the frontmatter block —\n * the closing `---` line and its newline belong to the HEADER, every byte\n * after them (blank lines included) is body. A document with no frontmatter is\n * all body. This is what `content_digest` hashes, and it deliberately does NOT\n * go through `parseFrontmatter` (whose `body` is trimmed for callers that want\n * text): the digest's writer and its checker must slice the same bytes, so\n * both go through here.\n */\nexport function rawBody(source: string): string {\n  const md = stripBom(source);\n  const at = bounds(md);\n  return at === null ? md : md.slice(at.bodyStart);\n}\n\n/**\n * The stamp `loam vouch` writes into `content_digest`: sha256 of the\n * document's own BODY — every byte after the frontmatter block (below the\n * closing `---` line and its newline; `rawBody` is the one definition of that\n * cut) — first 16 hex characters, the sources recipe's length.\n *\n * Byte-exact, no normalization. Body-only is load-bearing: vouch itself\n * rewrites the frontmatter as it stamps, and a later frontmatter-only edit\n * (another vouch, a corrected owner) must not read as the document moving.\n *\n * It lived in core/provenance/stamp.ts beside the sources recipe until the\n * fleet ENUMERATION needed it: `loam list` and `loam status` read a document\n * edited under its vouch off `ServiceEntry` (core/repo/repo.ts), and core/repo\n * cannot import core/provenance — that package resolves service paths through\n * core/repo. Here, beside the cut it hashes, both can reach it.\n */\nexport function contentDigest(source: string): string {\n  return createHash(\"sha256\").update(rawBody(source), \"utf8\").digest(\"hex\").slice(0, 16);\n}\n\n/**\n * The `content_digest` a document's body is held to, or undefined when there\n * is nothing to hold it to — `content.stale`'s precondition, spelled ONCE so\n * the validate finding (core/provenance/findings.ts) and the fleet enumeration\n * cannot disagree about which documents are stamped.\n *\n * Only a `verified` document: a draft's words are nobody's vouch yet. And a\n * verified document with no stamp predates the field — quiet on purpose: the\n * fix is re-vouching, and grading years of pre-feature vouches as suspect would\n * drown the fleet in warnings nobody chose.\n *\n * Split from `movedUnderVouch` below so a reader that has only the header in\n * hand — the fleet enumeration — can learn there is nothing to compare before\n * it pays for reading the body.\n */\nexport function contentStamp(fm: Frontmatter): string | undefined {\n  return stringField(fm, \"status\") === \"verified\" ? stringField(fm, \"content_digest\") : undefined;\n}\n\n/**\n * The one condition `content.stale` fires on: a `verified` document whose body\n * no longer hashes to the `content_digest` its vouch stamped.\n *\n * One spelling for three readers that must give the same answer. `loam\n * validate` grades it (core/provenance/findings.ts); the fleet enumeration\n * reads it off every service (core/repo/repo.ts) so `loam list` and `loam\n * status` cannot call fresh a document validate calls stale; and `loam archive`\n * asks it of the document it is ABOUT to write, before the bytes exist, so it\n * can name every vouched spec its merge moves under the stamp — and whose owner\n * then owes a re-vouch. Two spellings would let the archive's list, the listing\n * and the next validate disagree about which documents went stale.\n */\nexport function movedUnderVouch(fm: Frontmatter, raw: string): boolean {\n  const stamped = contentStamp(fm);\n  return stamped !== undefined && contentDigest(raw) !== stamped;\n}\n\n/**\n * Read a markdown file's frontmatter; a missing file reads as absent.\n *\n * Bytes in, decoded through `decodeDocument`, because `readFile(path, \"utf8\")`\n * turns a UTF-16 spec.md into mojibake whose opening `---` is no longer at\n * position 0 — so the header reads as ABSENT, and `status`, `owner` and\n * `sources` all come back missing over a file that spells every one of them.\n * The same blindness `stripBom` exists to stop, one encoding wider.\n *\n * The failure travels as a FLAG rather than an exception, which is how every\n * reader here degrades (`readOpenapi`'s `unreadable`) and is load-bearing at\n * exactly this call: this is the read behind the fleet ENUMERATION\n * (repo.ts `listServices`), so throwing would turn one PowerShell-saved file\n * into a `loam list` that reports nothing about the other 119 services.\n * Parsers never diagnose; a checker grades the flag.\n */\nexport async function readFrontmatter(path: string): Promise<Frontmatter> {\n  if (!existsSync(path)) return { present: false, malformed: false, data: {}, body: \"\" };\n  let text: string;\n  try {\n    text = decodeDocument(await readFile(path), path);\n  } catch (err) {\n    if (!(err instanceof NotUtf8DocumentError)) throw err;\n    return { present: false, malformed: false, unreadable: err.message, data: {}, body: \"\" };\n  }\n  return parseFrontmatter(text);\n}\n\n/** The statuses each kind of artifact may carry. */\nexport const SERVICE_STATUSES = [\"draft\", \"verified\"] as const;\nexport const FEATURE_STATUSES = [\"proposed\", \"in_progress\", \"built\", \"done\"] as const;\n\n/**\n * A document's prose with any leading frontmatter block dropped — what\n * `loam delta` and `loam context` print as a feature's intent.\n *\n * Moved verbatim from `commands/delta/slices.ts` when the context pack became\n * its second caller. It deliberately keeps its own, looser fence rule\n * (`\\n---` as a substring, not `bounds()`'s line-exact match) rather than\n * delegating to `parseFrontmatter(md).body`: the two agree on every header\n * loam writes, but the delta brief's output is pinned byte-for-byte by its\n * tests, and unifying the rules is a behaviour change to make deliberately,\n * not as a side effect of a move.\n */\nexport function stripFrontmatter(md: string): string {\n  if (!md.startsWith(\"---\")) return md;\n  const close = md.indexOf(\"\\n---\", 3);\n  if (close === -1) return md;\n  const nl = md.indexOf(\"\\n\", close + 1);\n  return nl === -1 ? \"\" : md.slice(nl + 1).trimStart();\n}\n"]}

package/dist/core/document/grammar/directives.js

@@ -0,0 +1,143 @@
+/**
+ * The requirement BODY-LINE grammar, and what a key nearly was.
+ *
+ * Split out of `commands/validate/service/specs.ts`, which reads and grades a
+ * service's two spec axes — a different subject: that module is about one
+ * service's documents, this one is about the shape of a requirement body
+ * wherever it appears. Nothing here touches the filesystem or knows what a
+ * service is, which is what lets it sit in `core/` beside the parser whose
+ * patterns it borrows.
+ *
+ * Its sibling is `../scenarios.ts`: same shape (requirements in, findings out,
+ * no I/O), one level down the document — that one grades a scenario's steps,
+ * this one grades the keys in the body above them.
+ */
+import {} from "../../vocabulary/report.js";
+import { BASED_ON_LINE_RE, CAPABILITY_LINE_RE, REALIZES_LINE_RE, REQUIREMENT_ID_LINE_RE, } from "../spec.js";
+/**
+ * Every body-line directive the requirement grammar recognises, as the patterns
+ * that recognise them.
+ *
+ * The REGEXES are the recognition half and they are not a copy: three are the
+ * exported constants `core/document/spec.ts` owns, and the rest are the same
+ * literals `core/document/parse.ts` matches with. Recognition therefore cannot
+ * drift into calling a real directive unknown.
+ *
+ * The NAMES below are the did-you-mean half, and they are the half that could
+ * drift — so `test/spec-unknown-directive.test.ts` asserts that every name here,
+ * spelled as a line, is matched by one of the patterns above it. A name that
+ * stops being a directive fails that test rather than going on being suggested.
+ */
+const DIRECTIVE_PATTERNS = [
+    REQUIREMENT_ID_LINE_RE,
+    BASED_ON_LINE_RE,
+    CAPABILITY_LINE_RE,
+    REALIZES_LINE_RE,
+    /^\s*Operations?:\s*(.+?)\s*$/i,
+    /^\s*Covers?:\s*(.+?)\s*$/i,
+    /^\s*Publishes?:\s*(.+?)\s*$/i,
+    /^\s*Consumes?:\s*(.+?)\s*$/i,
+    /^\s*Requires?:\s*(.+?)\s*$/i,
+];
+/** The canonical spelling of each directive — what a near miss is measured against. */
+export const DIRECTIVE_NAMES = [
+    "Requirement-ID",
+    "Based-On",
+    "Capabilities",
+    "Realizes",
+    "Operations",
+    "Covers",
+    "Publishes",
+    "Consumes",
+    "Requires",
+];
+/** A body line that LOOKS like a directive: a short capitalised key, a colon, a value. */
+const CANDIDATE_LINE_RE = /^\s*([A-Za-z][A-Za-z-]{2,30}):\s*\S/;
+/**
+ * A fenced block's opening or closing line — three or more backticks or
+ * tildes, optionally indented, optionally with an info string.
+ *
+ * A requirement body legitimately holds a fenced example, and inside one
+ * `Realises:` is a sample value rather than a misspelled directive. Grading it
+ * would make the check fire on documents that are exactly right, which is the
+ * one thing a near-miss guard may never do — a warning nobody can act on is
+ * worse than no warning. Tables need no equivalent: a `| Realises: |` cell
+ * begins with the pipe, so `CANDIDATE_LINE_RE` never matches it.
+ */
+const FENCE_LINE_RE = /^\s*(`{3,}|~{3,})/;
+/**
+ * Levenshtein distance, capped — a local one rather than `closeIds`, and the
+ * difference matters here.
+ *
+ * `closeIds` accepts a shared three-character prefix, which is right for ids
+ * drawn from a known vocabulary the author was aiming at. Applied to arbitrary
+ * prose keys it fires on words that merely start alike: `Context:` would be
+ * reported as a near miss for `Consumes:`, in a check whose whole value is that
+ * it does not cry wolf. Edit distance separates the two cleanly — `Context` is
+ * five edits from `Consumes`, `Realises` is one from `Realizes`.
+ */
+function editDistance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = row;
+    }
+    return prev[b.length];
+}
+/**
+ * `spec.unknown-directive` — a body line whose key is one or two characters
+ * away from a directive and is not one.
+ *
+ * THE ONE PLACE THE CORPUS IS QUIETER THAN IT LOOKS. Every join in the product
+ * is an existence check on a parsed value, so a line the parser did not
+ * recognise produces no value, no join, and therefore no finding: `Realises:`,
+ * `Capabilties:` and `Require:` all read as ordinary prose, and every check
+ * downstream stays green because there is nothing to fail. This is the same
+ * judgement `obligation.unknown` already makes one axis over — "a mistyped tag
+ * reads exactly like a rule" — applied to the keys themselves.
+ *
+ * A WARNING, not an error, and the threshold is deliberately mean. A body line
+ * is free prose and a fleet may legitimately write `Owner:` or `Context:` in
+ * one; the check only speaks when the key is within two edits of a directive,
+ * which is close enough that a typo is far likelier than a coincidence. It
+ * gates nothing.
+ */
+export function unknownDirectiveFindings(reqs, target) {
+    const findings = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        let inFence = false;
+        for (const line of r.text) {
+            if (FENCE_LINE_RE.test(line)) {
+                inFence = !inFence;
+                continue;
+            }
+            if (inFence)
+                continue;
+            const candidate = CANDIDATE_LINE_RE.exec(line);
+            if (candidate === null)
+                continue;
+            if (DIRECTIVE_PATTERNS.some((re) => re.test(line)))
+                continue;
+            const key = candidate[1];
+            const near = DIRECTIVE_NAMES.filter((name) => editDistance(key.toLowerCase(), name.toLowerCase()) <= 2);
+            if (near.length === 0)
+                continue;
+            findings.push({
+                severity: "warn",
+                code: "spec.unknown-directive",
+                subject: target.subject,
+                message: `${target.where}: requirement '${r.name}' has a line beginning '${key}:', which is not a directive loam reads — ` +
+                    `did you mean ${near.map((n) => `\`${n}:\``).join(" or ")}? ` +
+                    "A key loam does not recognise is prose: the join it looks like simply does not exist, and every check over it " +
+                    "stays green because there is nothing to fail. Correct the spelling, or reword the line so it does not read as a directive",
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=directives.js.map

package/dist/core/document/grammar/directives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.js","sourceRoot":"","sources":["../../../../src/core/document/grammar/directives.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The requirement BODY-LINE grammar, and what a key nearly was.\n *\n * Split out of `commands/validate/service/specs.ts`, which reads and grades a\n * service's two spec axes — a different subject: that module is about one\n * service's documents, this one is about the shape of a requirement body\n * wherever it appears. Nothing here touches the filesystem or knows what a\n * service is, which is what lets it sit in `core/` beside the parser whose\n * patterns it borrows.\n *\n * Its sibling is `../scenarios.ts`: same shape (requirements in, findings out,\n * no I/O), one level down the document — that one grades a scenario's steps,\n * this one grades the keys in the body above them.\n */\nimport { type Finding } from \"../../vocabulary/report.js\";\nimport {\n  BASED_ON_LINE_RE,\n  CAPABILITY_LINE_RE,\n  REALIZES_LINE_RE,\n  REQUIREMENT_ID_LINE_RE,\n  type Requirement,\n} from \"../spec.js\";\n\n/**\n * Every body-line directive the requirement grammar recognises, as the patterns\n * that recognise them.\n *\n * The REGEXES are the recognition half and they are not a copy: three are the\n * exported constants `core/document/spec.ts` owns, and the rest are the same\n * literals `core/document/parse.ts` matches with. Recognition therefore cannot\n * drift into calling a real directive unknown.\n *\n * The NAMES below are the did-you-mean half, and they are the half that could\n * drift — so `test/spec-unknown-directive.test.ts` asserts that every name here,\n * spelled as a line, is matched by one of the patterns above it. A name that\n * stops being a directive fails that test rather than going on being suggested.\n */\nconst DIRECTIVE_PATTERNS: readonly RegExp[] = [\n  REQUIREMENT_ID_LINE_RE,\n  BASED_ON_LINE_RE,\n  CAPABILITY_LINE_RE,\n  REALIZES_LINE_RE,\n  /^\\s*Operations?:\\s*(.+?)\\s*$/i,\n  /^\\s*Covers?:\\s*(.+?)\\s*$/i,\n  /^\\s*Publishes?:\\s*(.+?)\\s*$/i,\n  /^\\s*Consumes?:\\s*(.+?)\\s*$/i,\n  /^\\s*Requires?:\\s*(.+?)\\s*$/i,\n];\n\n/** The canonical spelling of each directive — what a near miss is measured against. */\nexport const DIRECTIVE_NAMES: readonly string[] = [\n  \"Requirement-ID\",\n  \"Based-On\",\n  \"Capabilities\",\n  \"Realizes\",\n  \"Operations\",\n  \"Covers\",\n  \"Publishes\",\n  \"Consumes\",\n  \"Requires\",\n];\n\n/** A body line that LOOKS like a directive: a short capitalised key, a colon, a value. */\nconst CANDIDATE_LINE_RE = /^\\s*([A-Za-z][A-Za-z-]{2,30}):\\s*\\S/;\n\n/**\n * A fenced block's opening or closing line — three or more backticks or\n * tildes, optionally indented, optionally with an info string.\n *\n * A requirement body legitimately holds a fenced example, and inside one\n * `Realises:` is a sample value rather than a misspelled directive. Grading it\n * would make the check fire on documents that are exactly right, which is the\n * one thing a near-miss guard may never do — a warning nobody can act on is\n * worse than no warning. Tables need no equivalent: a `| Realises: |` cell\n * begins with the pipe, so `CANDIDATE_LINE_RE` never matches it.\n */\nconst FENCE_LINE_RE = /^\\s*(`{3,}|~{3,})/;\n\n/**\n * Levenshtein distance, capped — a local one rather than `closeIds`, and the\n * difference matters here.\n *\n * `closeIds` accepts a shared three-character prefix, which is right for ids\n * drawn from a known vocabulary the author was aiming at. Applied to arbitrary\n * prose keys it fires on words that merely start alike: `Context:` would be\n * reported as a near miss for `Consumes:`, in a check whose whole value is that\n * it does not cry wolf. Edit distance separates the two cleanly — `Context` is\n * five edits from `Consumes`, `Realises` is one from `Realizes`.\n */\nfunction editDistance(a: string, b: string): number {\n  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);\n  for (let i = 1; i <= a.length; i++) {\n    const row = [i];\n    for (let j = 1; j <= b.length; j++) {\n      row[j] = Math.min(\n        prev[j]! + 1,\n        row[j - 1]! + 1,\n        prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),\n      );\n    }\n    prev = row;\n  }\n  return prev[b.length]!;\n}\n\n/**\n * `spec.unknown-directive` — a body line whose key is one or two characters\n * away from a directive and is not one.\n *\n * THE ONE PLACE THE CORPUS IS QUIETER THAN IT LOOKS. Every join in the product\n * is an existence check on a parsed value, so a line the parser did not\n * recognise produces no value, no join, and therefore no finding: `Realises:`,\n * `Capabilties:` and `Require:` all read as ordinary prose, and every check\n * downstream stays green because there is nothing to fail. This is the same\n * judgement `obligation.unknown` already makes one axis over — \"a mistyped tag\n * reads exactly like a rule\" — applied to the keys themselves.\n *\n * A WARNING, not an error, and the threshold is deliberately mean. A body line\n * is free prose and a fleet may legitimately write `Owner:` or `Context:` in\n * one; the check only speaks when the key is within two edits of a directive,\n * which is close enough that a typo is far likelier than a coincidence. It\n * gates nothing.\n */\nexport function unknownDirectiveFindings(\n  reqs: readonly Requirement[],\n  target: { where: string; subject: string },\n): Finding[] {\n  const findings: Finding[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    let inFence = false;\n    for (const line of r.text) {\n      if (FENCE_LINE_RE.test(line)) {\n        inFence = !inFence;\n        continue;\n      }\n      if (inFence) continue;\n      const candidate = CANDIDATE_LINE_RE.exec(line);\n      if (candidate === null) continue;\n      if (DIRECTIVE_PATTERNS.some((re) => re.test(line))) continue;\n      const key = candidate[1]!;\n      const near = DIRECTIVE_NAMES.filter(\n        (name) => editDistance(key.toLowerCase(), name.toLowerCase()) <= 2,\n      );\n      if (near.length === 0) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"spec.unknown-directive\",\n        subject: target.subject,\n        message:\n          `${target.where}: requirement '${r.name}' has a line beginning '${key}:', which is not a directive loam reads — ` +\n          `did you mean ${near.map((n) => `\\`${n}:\\``).join(\" or \")}? ` +\n          \"A key loam does not recognise is prose: the join it looks like simply does not exist, and every check over it \" +\n          \"stays green because there is nothing to fail. Correct the spelling, or reword the line so it does not read as a directive\",\n      });\n    }\n  }\n  return findings;\n}\n"]}