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

package/dist/core/document/parse.js

@@ -0,0 +1,286 @@
+/**
+ * Markdown in: headings, fences, and the one `## Requirements` cut point.
+ *
+ * The cut point is spelled once here on purpose. The archive cut, archive's
+ * stray-requirement guard and the delta-shape exemption used to spell the same
+ * invariant three different ways, and one of them was a PREFIX match that also
+ * hit `## Requirements Extra`.
+ *
+ * Fence tracking is why this is not a set of regexes at the call sites: a
+ * `### Requirement:` inside a fenced code block is prose about a requirement,
+ * not one, and every heading walk here has to agree about that.
+ */
+import { readFile } from "node:fs/promises";
+import { decodeDocument } from "../kernel/document-bytes.js";
+import { fenceTracker } from "../kernel/fences.js";
+import { BASED_ON_LINE_RE, CAPABILITY_LINE_RE, KIND_RE, REALIZES_LINE_RE, REQUIREMENT_ID_LINE_RE, } from "./spec.js";
+const REQ_RE = /^###\s+Requirement:\s*(.+?)\s*$/;
+const SCN_RE = /^####\s+Scenario:\s*(.+?)\s*$/;
+/**
+ * THE requirements section: the one H2 a living spec keeps its requirements
+ * under, the one section `loam archive` rewrites, and the one heading a delta
+ * may legally quote the living state beneath. One definition on purpose — the
+ * archive cut point, archive's stray-requirement guard, and the delta-shape
+ * exemption (core/delta/document.ts) used to spell this invariant three different ways,
+ * and the cut point's substring `indexOf("\n## Requirements")` was a PREFIX
+ * match that also hit `## Requirements Extra`. Full-line match on a trimmed
+ * heading, with KIND_RE's case and interior-whitespace tolerance.
+ */
+const REQUIREMENTS_SECTION_RE = /^##\s+Requirements\s*$/i;
+/** Is this H2 heading line (as sectionHeadings/`Requirement.section` spell it) the `## Requirements` heading? */
+export function isRequirementsHeading(heading) {
+    return REQUIREMENTS_SECTION_RE.test(heading.trim());
+}
+/**
+ * Strip a leading UTF-8 BOM (U+FEFF), which editors on Windows write unasked.
+ *
+ * It has to happen here, at the two functions that take raw markdown, rather than
+ * at each `readFile` call: those are spread across half the commands, so any one of
+ * them could forget, and the failure is invisible. One byte was enough to void an
+ * entire delta — `KIND_RE` is anchored `^##`, delta files routinely open with
+ * `## MODIFIED Requirements` on line 1, and behind a BOM that line stopped being a
+ * heading, so every requirement in the file fell back to BASE and
+ * `applyRequirementDelta` skips BASE. Archive merged nothing and said nothing.
+ * OpenSpec's own reader strips it for exactly this reason.
+ *
+ * Only at position 0: elsewhere U+FEFF is a zero-width no-break space and belongs
+ * to the author's text.
+ */
+function stripBom(md) {
+    return md.charCodeAt(0) === 0xfeff ? md.slice(1) : md;
+}
+/** Every H2 heading outside a fenced block, with its 1-based line number. */
+export function sectionHeadings(md) {
+    const fenced = fenceTracker();
+    const out = [];
+    stripBom(md).split(/\r?\n/).forEach((line, i) => {
+        if (fenced(line))
+            return;
+        if (/^##\s+/.test(line) && !line.startsWith("###"))
+            out.push({ text: line.trim(), line: i + 1 });
+    });
+    return out;
+}
+/**
+ * Split a living spec around its requirements RUN — the stretch of
+ * `### Requirement:` blocks inside the `## Requirements` section — so a merge
+ * can rewrite exactly that and nothing else. All three slices reassemble the
+ * input byte-for-byte (`head + run + tail === text`):
+ *
+ * - `head` — everything before the first requirement in the section: the
+ *   intro, the heading line itself, any prose under the heading.
+ * - `run`  — from the first `### Requirement:` line to the section's end (the
+ *   next `## ` heading, or EOF). Empty when the section holds no requirements.
+ * - `tail` — everything from the section's end onward.
+ *
+ * `requirements` is the run cut again at every `### Requirement:` heading —
+ * one raw slice per requirement, from its heading up to the next one (or the
+ * run's end), so `requirements.join("") === run`. A slice therefore carries
+ * whatever the author wrote below the requirement before the next heading,
+ * blank lines included, which is exactly the text parseRequirements attributes
+ * to that requirement. It exists so archive can keep the bytes of every
+ * requirement a delta did not touch instead of re-serializing the whole run:
+ * one ADDED requirement used to reflow every untouched requirement written
+ * without a blank line under its heading, and every one of those moves landed
+ * under the document's vouch stamp.
+ *
+ * Returns null when the document has no `## Requirements` heading at all.
+ * Only the FIRST matching heading opens the section; a caller that must not
+ * lose content behind a duplicate (archive) counts matches via
+ * sectionHeadings() and refuses. Heading detection matches parseRequirements:
+ * fenced lines are never structure, and a leading BOM hides no heading — but
+ * the slices themselves are raw bytes, BOM and CRLF included.
+ */
+export function splitRequirementsSection(text) {
+    const fenced = fenceTracker();
+    let inSection = false;
+    let sectionStart = -1;
+    const starts = [];
+    let sectionEnd = text.length;
+    let offset = 0;
+    while (offset < text.length) {
+        const nl = text.indexOf("\n", offset);
+        const lineEnd = nl === -1 ? text.length : nl + 1;
+        let line = text.slice(offset, nl === -1 ? text.length : nl);
+        if (line.endsWith("\r"))
+            line = line.slice(0, -1);
+        // Position 0 only, mirroring stripBom: elsewhere U+FEFF is content.
+        if (offset === 0 && line.charCodeAt(0) === 0xfeff)
+            line = line.slice(1);
+        if (!fenced(line)) {
+            if (/^##\s+/.test(line) && !line.startsWith("###")) {
+                if (inSection) {
+                    sectionEnd = offset;
+                    inSection = false;
+                }
+                else if (sectionStart === -1 && isRequirementsHeading(line)) {
+                    sectionStart = offset;
+                    inSection = true;
+                }
+            }
+            else if (inSection && REQ_RE.test(line)) {
+                starts.push(offset);
+            }
+        }
+        offset = lineEnd;
+    }
+    if (sectionStart === -1)
+        return null;
+    const cut = starts[0] ?? sectionEnd;
+    return {
+        head: text.slice(0, cut),
+        run: text.slice(cut, sectionEnd),
+        tail: text.slice(sectionEnd),
+        requirements: starts.map((at, i) => text.slice(at, starts[i + 1] ?? sectionEnd)),
+    };
+}
+/**
+ * A requirement document from disk as text — decoded, or refused by name.
+ *
+ * The read that belongs with the parser, because `readFile(path, "utf8")` and
+ * `parseRequirements` together are a trap: a UTF-16 spec.md decodes to a string
+ * in which no line matches `^###\s+Requirement:`, so the parser returns [] and
+ * the document grades as an empty baseline instead of an unreadable one. Every
+ * question loam asks of a spec — is it covered, does the delta merge, what does
+ * the C4 spine touch — is then answered about a file nobody read.
+ *
+ * It THROWS (`NotUtf8DocumentError`, which names the path), unlike
+ * `readFrontmatter` next door, because the two failures are not the same
+ * failure. Frontmatter is read by the fleet enumeration, where one bad file
+ * must not cost the other 119 services, so there it is a flag. A requirement
+ * document is read by ONE target, and the caller is the only one who knows what
+ * to do about it: a read-only command turns it into a finding on that target
+ * (validate's `guarded`, which names the file and keeps grading the rest), a
+ * command that writes refuses outright rather than computing over mojibake.
+ */
+export async function readRequirementsDocument(path) {
+    return decodeDocument(await readFile(path), path);
+}
+/** Parse all requirements (with their scenarios and delta kind) from a markdown doc. */
+export function parseRequirements(md) {
+    const out = [];
+    let kind = "BASE";
+    let section;
+    let req = null;
+    let scn = null;
+    const fenced = fenceTracker();
+    for (const [index, line] of stripBom(md).split(/\r?\n/).entries()) {
+        if (fenced(line)) {
+            // Fenced content, marker included: body of whatever is open, never structure.
+            if (scn)
+                scn.lines.push(line);
+            else if (req)
+                req.text.push(line);
+            continue;
+        }
+        // Any H2 heading ends the current requirement/scenario capture — section prose
+        // must not leak into the previous scenario's body.
+        if (/^##\s+/.test(line) && !line.startsWith("###")) {
+            req = null;
+            scn = null;
+            section = line.trim();
+            const mk = KIND_RE.exec(line);
+            // A non-delta H2 (## Notes, ## Requirements…) starts an unrelated section:
+            // requirements under it are plain BASE, not part of a stale delta section.
+            kind = mk ? mk[1].toUpperCase() : "BASE";
+            continue;
+        }
+        const mr = REQ_RE.exec(line);
+        if (mr) {
+            req = {
+                kind,
+                name: mr[1],
+                text: [],
+                operations: [],
+                covers: [],
+                publishes: [],
+                consumes: [],
+                requires: [],
+                capabilities: [],
+                realizes: [],
+                scenarios: [],
+                section,
+                line: index + 1,
+            };
+            out.push(req);
+            scn = null;
+            continue;
+        }
+        const ms = SCN_RE.exec(line);
+        if (ms && req) {
+            // `index + 1` is the heading's own 1-based line, exactly as the
+            // requirement capture above records its `### Requirement:` — body line
+            // `lines[i]` then sits at `line + 1 + i`, because the capture below is
+            // contiguous from here to the next heading. Purely additive: nothing in
+            // `serializeRequirements` reads it, so `requirementDigest` cannot see it
+            // and no `Based-On:` pin in any living document moves because the parser
+            // learned where a scenario starts.
+            scn = { name: ms[1], lines: [], line: index + 1 };
+            req.scenarios.push(scn);
+            continue;
+        }
+        if (scn) {
+            scn.lines.push(line);
+        }
+        else if (req) {
+            req.text.push(line);
+            const mi = REQUIREMENT_ID_LINE_RE.exec(line);
+            if (mi)
+                req.id = mi[1].trim();
+            // Same keep-last quirk as Operations:/Covers: below — a repeated line is
+            // a document problem, reported as one (`delta.baseline-invalid`), never
+            // resolved differently by whoever happens to be reading.
+            const mb = BASED_ON_LINE_RE.exec(line);
+            if (mb)
+                req.basedOn = mb[1].trim();
+            const mo = /^\s*Operations?:\s*(.+?)\s*$/i.exec(line);
+            if (mo)
+                req.operations = mo[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            // The Covers: mirror — same placement (requirement body, not a scenario),
+            // same comma grammar, and deliberately the same quirk: a second line
+            // REPLACES the first (assignment, not append), so the two lists can never
+            // drift apart in how they read a repeated line.
+            const mc = /^\s*Covers?:\s*(.+?)\s*$/i.exec(line);
+            if (mc)
+                req.covers = mc[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            // The event axis, same grammar and the same keep-last quirk again. Note
+            // what is NOT happening here: the line stays in `req.text` like every
+            // other body line (the push above is unconditional), so it round-trips
+            // through `serializeRequirements` and rides inside `requirementDigest`
+            // exactly as `Operations:` does. That is what makes this parse purely
+            // additive — no living document's digest moves, and no `Based-On:` pin
+            // goes stale because loam learned to read one more line.
+            const mp = /^\s*Publishes?:\s*(.+?)\s*$/i.exec(line);
+            if (mp)
+                req.publishes = mp[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            const mcon = /^\s*Consumes?:\s*(.+?)\s*$/i.exec(line);
+            if (mcon)
+                req.consumes = mcon[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            // The authorization axis. Same grammar, same keep-last quirk, same purely
+            // additive parse — the line rides in `req.text` and therefore inside
+            // `requirementDigest`, so no living document moves because loam learned
+            // to read it.
+            const mreq = /^\s*Requires?:\s*(.+?)\s*$/i.exec(line);
+            if (mreq)
+                req.requires = mreq[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            // The capability axis. Same grammar, same keep-last quirk, same purely
+            // additive parse as Requires: above — but note the OPT-IN differs: the
+            // vocabulary FILE (architecture/capabilities.yaml) is the opt-in for this
+            // axis, not the line, so entries parsed here grade as nothing at all
+            // until a fleet writes that file (core/capabilities/findings.ts).
+            const mcap = CAPABILITY_LINE_RE.exec(line);
+            if (mcap)
+                req.capabilities = mcap[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            // The join INTO the authored business tree: `<capability-id>#<Requirement-ID>`
+            // entries, same comma grammar and same keep-last quirk as every line
+            // above. Split into its two halves nowhere near here —
+            // `core/capabilities/realizes/join.ts` owns that, because the rollup and
+            // the grades must not be able to disagree about where the separator is.
+            const mrl = REALIZES_LINE_RE.exec(line);
+            if (mrl)
+                req.realizes = mrl[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=parse.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/core/document/parse.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Markdown in: headings, fences, and the one `## Requirements` cut point.\n *\n * The cut point is spelled once here on purpose. The archive cut, archive's\n * stray-requirement guard and the delta-shape exemption used to spell the same\n * invariant three different ways, and one of them was a PREFIX match that also\n * hit `## Requirements Extra`.\n *\n * Fence tracking is why this is not a set of regexes at the call sites: a\n * `### Requirement:` inside a fenced code block is prose about a requirement,\n * not one, and every heading walk here has to agree about that.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { decodeDocument } from \"../kernel/document-bytes.js\";\nimport { fenceTracker } from \"../kernel/fences.js\";\nimport {\n  BASED_ON_LINE_RE, CAPABILITY_LINE_RE, KIND_RE, REALIZES_LINE_RE, REQUIREMENT_ID_LINE_RE,\n  type DeltaKind, type Requirement, type Scenario,\n} from \"./spec.js\";\n\nconst REQ_RE = /^###\\s+Requirement:\\s*(.+?)\\s*$/;\nconst SCN_RE = /^####\\s+Scenario:\\s*(.+?)\\s*$/;\n\n/**\n * THE requirements section: the one H2 a living spec keeps its requirements\n * under, the one section `loam archive` rewrites, and the one heading a delta\n * may legally quote the living state beneath. One definition on purpose — the\n * archive cut point, archive's stray-requirement guard, and the delta-shape\n * exemption (core/delta/document.ts) used to spell this invariant three different ways,\n * and the cut point's substring `indexOf(\"\\n## Requirements\")` was a PREFIX\n * match that also hit `## Requirements Extra`. Full-line match on a trimmed\n * heading, with KIND_RE's case and interior-whitespace tolerance.\n */\nconst REQUIREMENTS_SECTION_RE = /^##\\s+Requirements\\s*$/i;\n\n/** Is this H2 heading line (as sectionHeadings/`Requirement.section` spell it) the `## Requirements` heading? */\nexport function isRequirementsHeading(heading: string): boolean {\n  return REQUIREMENTS_SECTION_RE.test(heading.trim());\n}\n\n/**\n * Strip a leading UTF-8 BOM (U+FEFF), which editors on Windows write unasked.\n *\n * It has to happen here, at the two functions that take raw markdown, rather than\n * at each `readFile` call: those are spread across half the commands, so any one of\n * them could forget, and the failure is invisible. One byte was enough to void an\n * entire delta — `KIND_RE` is anchored `^##`, delta files routinely open with\n * `## MODIFIED Requirements` on line 1, and behind a BOM that line stopped being a\n * heading, so every requirement in the file fell back to BASE and\n * `applyRequirementDelta` skips BASE. Archive merged nothing and said nothing.\n * OpenSpec's own reader strips it for exactly this reason.\n *\n * Only at position 0: elsewhere U+FEFF is a zero-width no-break space and belongs\n * to the author's text.\n */\nfunction stripBom(md: string): string {\n  return md.charCodeAt(0) === 0xfeff ? md.slice(1) : md;\n}\n\n/** Every H2 heading outside a fenced block, with its 1-based line number. */\nexport function sectionHeadings(md: string): Array<{ text: string; line: number }> {\n  const fenced = fenceTracker();\n  const out: Array<{ text: string; line: number }> = [];\n  stripBom(md).split(/\\r?\\n/).forEach((line, i) => {\n    if (fenced(line)) return;\n    if (/^##\\s+/.test(line) && !line.startsWith(\"###\")) out.push({ text: line.trim(), line: i + 1 });\n  });\n  return out;\n}\n\n/**\n * Split a living spec around its requirements RUN — the stretch of\n * `### Requirement:` blocks inside the `## Requirements` section — so a merge\n * can rewrite exactly that and nothing else. All three slices reassemble the\n * input byte-for-byte (`head + run + tail === text`):\n *\n * - `head` — everything before the first requirement in the section: the\n *   intro, the heading line itself, any prose under the heading.\n * - `run`  — from the first `### Requirement:` line to the section's end (the\n *   next `## ` heading, or EOF). Empty when the section holds no requirements.\n * - `tail` — everything from the section's end onward.\n *\n * `requirements` is the run cut again at every `### Requirement:` heading —\n * one raw slice per requirement, from its heading up to the next one (or the\n * run's end), so `requirements.join(\"\") === run`. A slice therefore carries\n * whatever the author wrote below the requirement before the next heading,\n * blank lines included, which is exactly the text parseRequirements attributes\n * to that requirement. It exists so archive can keep the bytes of every\n * requirement a delta did not touch instead of re-serializing the whole run:\n * one ADDED requirement used to reflow every untouched requirement written\n * without a blank line under its heading, and every one of those moves landed\n * under the document's vouch stamp.\n *\n * Returns null when the document has no `## Requirements` heading at all.\n * Only the FIRST matching heading opens the section; a caller that must not\n * lose content behind a duplicate (archive) counts matches via\n * sectionHeadings() and refuses. Heading detection matches parseRequirements:\n * fenced lines are never structure, and a leading BOM hides no heading — but\n * the slices themselves are raw bytes, BOM and CRLF included.\n */\nexport function splitRequirementsSection(\n  text: string,\n): { head: string; run: string; tail: string; requirements: string[] } | null {\n  const fenced = fenceTracker();\n  let inSection = false;\n  let sectionStart = -1;\n  const starts: number[] = [];\n  let sectionEnd = text.length;\n  let offset = 0;\n  while (offset < text.length) {\n    const nl = text.indexOf(\"\\n\", offset);\n    const lineEnd = nl === -1 ? text.length : nl + 1;\n    let line = text.slice(offset, nl === -1 ? text.length : nl);\n    if (line.endsWith(\"\\r\")) line = line.slice(0, -1);\n    // Position 0 only, mirroring stripBom: elsewhere U+FEFF is content.\n    if (offset === 0 && line.charCodeAt(0) === 0xfeff) line = line.slice(1);\n    if (!fenced(line)) {\n      if (/^##\\s+/.test(line) && !line.startsWith(\"###\")) {\n        if (inSection) {\n          sectionEnd = offset;\n          inSection = false;\n        } else if (sectionStart === -1 && isRequirementsHeading(line)) {\n          sectionStart = offset;\n          inSection = true;\n        }\n      } else if (inSection && REQ_RE.test(line)) {\n        starts.push(offset);\n      }\n    }\n    offset = lineEnd;\n  }\n  if (sectionStart === -1) return null;\n  const cut = starts[0] ?? sectionEnd;\n  return {\n    head: text.slice(0, cut),\n    run: text.slice(cut, sectionEnd),\n    tail: text.slice(sectionEnd),\n    requirements: starts.map((at, i) => text.slice(at, starts[i + 1] ?? sectionEnd)),\n  };\n}\n\n/**\n * A requirement document from disk as text — decoded, or refused by name.\n *\n * The read that belongs with the parser, because `readFile(path, \"utf8\")` and\n * `parseRequirements` together are a trap: a UTF-16 spec.md decodes to a string\n * in which no line matches `^###\\s+Requirement:`, so the parser returns [] and\n * the document grades as an empty baseline instead of an unreadable one. Every\n * question loam asks of a spec — is it covered, does the delta merge, what does\n * the C4 spine touch — is then answered about a file nobody read.\n *\n * It THROWS (`NotUtf8DocumentError`, which names the path), unlike\n * `readFrontmatter` next door, because the two failures are not the same\n * failure. Frontmatter is read by the fleet enumeration, where one bad file\n * must not cost the other 119 services, so there it is a flag. A requirement\n * document is read by ONE target, and the caller is the only one who knows what\n * to do about it: a read-only command turns it into a finding on that target\n * (validate's `guarded`, which names the file and keeps grading the rest), a\n * command that writes refuses outright rather than computing over mojibake.\n */\nexport async function readRequirementsDocument(path: string): Promise<string> {\n  return decodeDocument(await readFile(path), path);\n}\n\n/** Parse all requirements (with their scenarios and delta kind) from a markdown doc. */\nexport function parseRequirements(md: string): Requirement[] {\n  const out: Requirement[] = [];\n  let kind: DeltaKind = \"BASE\";\n  let section: string | undefined;\n  let req: Requirement | null = null;\n  let scn: Scenario | null = null;\n  const fenced = fenceTracker();\n\n  for (const [index, line] of stripBom(md).split(/\\r?\\n/).entries()) {\n    if (fenced(line)) {\n      // Fenced content, marker included: body of whatever is open, never structure.\n      if (scn) scn.lines.push(line);\n      else if (req) req.text.push(line);\n      continue;\n    }\n    // Any H2 heading ends the current requirement/scenario capture — section prose\n    // must not leak into the previous scenario's body.\n    if (/^##\\s+/.test(line) && !line.startsWith(\"###\")) {\n      req = null;\n      scn = null;\n      section = line.trim();\n      const mk = KIND_RE.exec(line);\n      // A non-delta H2 (## Notes, ## Requirements…) starts an unrelated section:\n      // requirements under it are plain BASE, not part of a stale delta section.\n      kind = mk ? (mk[1]!.toUpperCase() as DeltaKind) : \"BASE\";\n      continue;\n    }\n    const mr = REQ_RE.exec(line);\n    if (mr) {\n      req = {\n        kind,\n        name: mr[1]!,\n        text: [],\n        operations: [],\n        covers: [],\n        publishes: [],\n        consumes: [],\n        requires: [],\n        capabilities: [],\n        realizes: [],\n        scenarios: [],\n        section,\n        line: index + 1,\n      };\n      out.push(req);\n      scn = null;\n      continue;\n    }\n    const ms = SCN_RE.exec(line);\n    if (ms && req) {\n      // `index + 1` is the heading's own 1-based line, exactly as the\n      // requirement capture above records its `### Requirement:` — body line\n      // `lines[i]` then sits at `line + 1 + i`, because the capture below is\n      // contiguous from here to the next heading. Purely additive: nothing in\n      // `serializeRequirements` reads it, so `requirementDigest` cannot see it\n      // and no `Based-On:` pin in any living document moves because the parser\n      // learned where a scenario starts.\n      scn = { name: ms[1]!, lines: [], line: index + 1 };\n      req.scenarios.push(scn);\n      continue;\n    }\n    if (scn) {\n      scn.lines.push(line);\n    } else if (req) {\n      req.text.push(line);\n      const mi = REQUIREMENT_ID_LINE_RE.exec(line);\n      if (mi) req.id = mi[1]!.trim();\n      // Same keep-last quirk as Operations:/Covers: below — a repeated line is\n      // a document problem, reported as one (`delta.baseline-invalid`), never\n      // resolved differently by whoever happens to be reading.\n      const mb = BASED_ON_LINE_RE.exec(line);\n      if (mb) req.basedOn = mb[1]!.trim();\n      const mo = /^\\s*Operations?:\\s*(.+?)\\s*$/i.exec(line);\n      if (mo) req.operations = mo[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      // The Covers: mirror — same placement (requirement body, not a scenario),\n      // same comma grammar, and deliberately the same quirk: a second line\n      // REPLACES the first (assignment, not append), so the two lists can never\n      // drift apart in how they read a repeated line.\n      const mc = /^\\s*Covers?:\\s*(.+?)\\s*$/i.exec(line);\n      if (mc) req.covers = mc[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      // The event axis, same grammar and the same keep-last quirk again. Note\n      // what is NOT happening here: the line stays in `req.text` like every\n      // other body line (the push above is unconditional), so it round-trips\n      // through `serializeRequirements` and rides inside `requirementDigest`\n      // exactly as `Operations:` does. That is what makes this parse purely\n      // additive — no living document's digest moves, and no `Based-On:` pin\n      // goes stale because loam learned to read one more line.\n      const mp = /^\\s*Publishes?:\\s*(.+?)\\s*$/i.exec(line);\n      if (mp) req.publishes = mp[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      const mcon = /^\\s*Consumes?:\\s*(.+?)\\s*$/i.exec(line);\n      if (mcon) req.consumes = mcon[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      // The authorization axis. Same grammar, same keep-last quirk, same purely\n      // additive parse — the line rides in `req.text` and therefore inside\n      // `requirementDigest`, so no living document moves because loam learned\n      // to read it.\n      const mreq = /^\\s*Requires?:\\s*(.+?)\\s*$/i.exec(line);\n      if (mreq) req.requires = mreq[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      // The capability axis. Same grammar, same keep-last quirk, same purely\n      // additive parse as Requires: above — but note the OPT-IN differs: the\n      // vocabulary FILE (architecture/capabilities.yaml) is the opt-in for this\n      // axis, not the line, so entries parsed here grade as nothing at all\n      // until a fleet writes that file (core/capabilities/findings.ts).\n      const mcap = CAPABILITY_LINE_RE.exec(line);\n      if (mcap) req.capabilities = mcap[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      // The join INTO the authored business tree: `<capability-id>#<Requirement-ID>`\n      // entries, same comma grammar and same keep-last quirk as every line\n      // above. Split into its two halves nowhere near here —\n      // `core/capabilities/realizes/join.ts` owns that, because the rollup and\n      // the grades must not be able to disagree about where the separator is.\n      const mrl = REALIZES_LINE_RE.exec(line);\n      if (mrl) req.realizes = mrl[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n    }\n  }\n\n  return out;\n}\n"]}

package/dist/core/document/scenarios.js

@@ -0,0 +1,238 @@
+/**
+ * What a requirement's scenarios are MISSING, and where they contradict
+ * themselves — the coverage and shape questions `validate` asks of every spec.
+ *
+ * Separate from `./parse.ts` because these grade a parsed document rather than
+ * produce one, and separate from `./spec.ts` because they answer to
+ * `vocabulary/report.ts`: a stepless scenario is a Finding with a subject and a
+ * label, and that shape belongs to the report, not to the requirement.
+ */
+import { scenarioGherkin } from "../vocabulary/steps.js";
+import {} from "./spec.js";
+/** Requirements with no scenario — the OpenSpec coverage rule (every requirement needs ≥1). */
+export function requirementsMissingScenarios(reqs) {
+    return reqs.filter((r) => r.kind !== "REMOVED" && r.scenarios.length === 0);
+}
+/**
+ * `requirements.missing-scenarios` over the requirements the rule above
+ * returned — one spelling for `loam validate` (its `coverageFinding`) and
+ * `loam status` (`core/status/feature/feature.ts`), because status's rule is
+ * "never greener than the gates" and a second spelling of the same finding is
+ * how the two would come to disagree. `subject` names the service when the
+ * caller has one.
+ */
+export function missingScenariosFinding(label, bare, subject) {
+    return {
+        severity: "error",
+        code: "requirements.missing-scenarios",
+        ...(subject === undefined ? {} : { subject }),
+        message: `${label}: ${bare.length} requirement(s) without a scenario`,
+        details: bare.map((r) => r.name),
+    };
+}
+/**
+ * Scenarios that satisfy the coverage rule above and test nothing.
+ *
+ * `requirementsMissingScenarios` counts HEADINGS, so a `#### Scenario:` with no
+ * recognizable Given/When/Then line satisfied the fleet gate's coverage claim
+ * outright — and it is not a hypothetical shape: it is what `loam new`
+ * scaffolds and what an agent writes when it puts the criteria in prose.
+ * Downstream the same emptiness is fatal twice over: cucumber runs a stepless
+ * scenario vacuously green, and `loam verify --results` can never confirm it.
+ *
+ * The detector is `loam gherkin`'s own — `scenarioGherkin` decides what a step
+ * IS, and a second opinion here would mean the gate and the emitted suite could
+ * disagree about whether a scenario has any. That import is the one place these
+ * two modules are circular (gherkin.ts parses requirements); both sides export
+ * only function declarations, which are hoisted, so neither evaluation order
+ * can observe a half-built module.
+ */
+export function steplessScenarios(reqs) {
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const s of r.scenarios) {
+            if (scenarioGherkin(s.lines).steps.length === 0)
+                out.push({ requirement: r.name, scenario: s.name });
+        }
+    }
+    return out;
+}
+/**
+ * The stepless half of the coverage check, as findings — the missing-scenario
+ * half stays where it is (`requirementsMissingScenarios`), because the two are
+ * different states with different fixes: one requirement owes acceptance
+ * criteria, the other owes STEPS in criteria somebody has already written.
+ *
+ * `label` is the coverage check's own label (`payment-service: requirements`),
+ * so both halves of one document name it the same way.
+ */
+export function steplessFindings(label, subject, reqs) {
+    const bare = steplessScenarios(reqs);
+    if (bare.length === 0)
+        return [];
+    return [
+        {
+            severity: "error",
+            code: "requirements.stepless-scenario",
+            subject,
+            message: `${label}: ${bare.length} scenario(s) have a heading and no recognizable steps — ` +
+                `they satisfy the coverage rule and test nothing. Cucumber runs a stepless scenario vacuously green and ` +
+                `\`loam verify --results\` can never confirm it. Write the body as \`- **Given/When/Then**\` bullets.`,
+            details: bare.map((s) => `${s.requirement} — ${s.scenario}`),
+            text: { detailPrefix: "- " },
+        },
+    ];
+}
+/**
+ * Scenarios that have steps and assert NOTHING — a body of Given and When with
+ * no Then anywhere in it.
+ *
+ * The third state, and the one that survives both checks above: the requirement
+ * has a scenario, the scenario has steps, and the run can only ever confirm that
+ * the arrangement did not throw. `And`/`But` are continuations, so their meaning
+ * is decided by the keyword they follow — with no `Then` in the body there is
+ * nothing for them to continue but the setup.
+ *
+ * It matters more the more evidence rests on the suite. A stepless scenario is
+ * at least visible as an empty body; this one reads like a real test, emits real
+ * steps, runs green, and answers a `scenario.tested` claim to the same standard
+ * as a scenario that checks twenty things. Under a runner-neutral answer sheet —
+ * one `{digest, status}` entry, no steps to count — this document-side check is
+ * the only thing left that can tell the two apart.
+ */
+export function assertionlessScenarios(reqs) {
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const s of r.scenarios) {
+            const { steps } = scenarioGherkin(s.lines);
+            // Disjoint from stepless by construction: a body with no steps at all is
+            // that finding's, and reporting one scenario under both codes would offer
+            // two fixes for one defect.
+            if (steps.length > 0 && !steps.some((st) => /^Then\b/.test(st.text))) {
+                out.push({ requirement: r.name, scenario: s.name });
+            }
+        }
+    }
+    return out;
+}
+const PLACEHOLDER_RE = /<([^<>\s]+)>/g;
+/**
+ * Every `<placeholder>` a scenario's steps reach for, arguments included.
+ *
+ * Docstrings and data tables are scanned too because cucumber substitutes into
+ * them: `<fee>` inside a request payload is a real reference, and a check that
+ * read only the step lines would call its column unreferenced and invite the
+ * author to delete the column the payload depends on.
+ */
+function placeholdersUsed(steps) {
+    const used = new Set();
+    const scan = (text) => {
+        for (const m of text.matchAll(PLACEHOLDER_RE))
+            used.add(m[1]);
+    };
+    for (const st of steps) {
+        scan(st.text);
+        for (const l of st.docstring?.lines ?? [])
+            scan(l);
+        for (const row of st.table ?? [])
+            for (const cell of row)
+                scan(cell);
+    }
+    return used;
+}
+/**
+ * Scenarios whose `Examples` header and `<placeholders>` disagree.
+ *
+ * Only scenarios that HAVE an Examples table are considered, and that scoping is
+ * load-bearing twice over: a plain scenario's `<angle brackets>` are prose (a
+ * generic, a placeholder in a URL template, loam's own scaffold sentinels), and
+ * a fleet that never writes an outline must never earn a finding from this.
+ *
+ * The two halves are different defects. An UNBOUND placeholder is an error the
+ * runner cannot repair: cucumber substitutes nothing, so the step definition
+ * receives the literal text `<fee>` and either fails obscurely or — worse —
+ * matches and asserts against a string nobody meant. An UNREFERENCED column is a
+ * warning, because it is usually the fossil of a rename: the column still lists
+ * six cases, the step that used it now names something else, and the outline
+ * runs six identical passes that read as six cases of coverage.
+ */
+export function examplesMismatches(reqs) {
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const s of r.scenarios) {
+            const { steps, examples } = scenarioGherkin(s.lines);
+            if (examples === null)
+                continue;
+            const used = placeholdersUsed(steps);
+            const columns = new Set(examples.header);
+            const unbound = [...used].filter((p) => !columns.has(p)).sort();
+            const unreferenced = examples.header.filter((c) => !used.has(c));
+            if (unbound.length > 0 || unreferenced.length > 0) {
+                out.push({ requirement: r.name, scenario: s.name, unbound, unreferenced });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The Examples half, as findings — two codes rather than one with two
+ * severities, because a machine cannot branch on a severity that depends on the
+ * case, and the fixes differ: one adds a column, the other removes one or
+ * restores the reference that used to use it.
+ */
+export function examplesFindings(label, subject, reqs) {
+    const all = examplesMismatches(reqs);
+    const findings = [];
+    const unbound = all.filter((m) => m.unbound.length > 0);
+    if (unbound.length > 0) {
+        findings.push({
+            severity: "error",
+            code: "requirements.examples-unbound",
+            subject,
+            message: `${label}: ${unbound.length} scenario(s) use a \`<placeholder>\` no \`Examples\` column supplies — ` +
+                `cucumber substitutes nothing, so the step receives the literal angle-bracket text. ` +
+                `Add the column, or correct the placeholder to one the header names.`,
+            details: unbound.map((m) => `${m.requirement} — ${m.scenario}: ${m.unbound.map((p) => `<${p}>`).join(", ")}`),
+            text: { detailPrefix: "- " },
+        });
+    }
+    const dead = all.filter((m) => m.unreferenced.length > 0);
+    if (dead.length > 0) {
+        findings.push({
+            severity: "warn",
+            code: "requirements.examples-unreferenced",
+            subject,
+            message: `${label}: ${dead.length} scenario(s) declare an \`Examples\` column no step refers to — ` +
+                `usually the fossil of a rename, and the outline then runs its rows as identical passes that read as cases. ` +
+                `Reference the column from a step, or drop it.`,
+            details: dead.map((m) => `${m.requirement} — ${m.scenario}: ${m.unreferenced.join(", ")}`),
+            text: { detailPrefix: "- " },
+        });
+    }
+    return findings;
+}
+/** The assertionless half, as findings — same label and subject as its two siblings. */
+export function assertionlessFindings(label, subject, reqs) {
+    const mute = assertionlessScenarios(reqs);
+    if (mute.length === 0)
+        return [];
+    return [
+        {
+            severity: "error",
+            code: "requirements.assertionless-scenario",
+            subject,
+            message: `${label}: ${mute.length} scenario(s) have steps and no \`Then\` — ` +
+                `they arrange and act, and assert nothing. The run confirms only that the setup did not throw, ` +
+                `and the claim it answers is confirmed on that. Add the \`- **Then**\` the scenario was written for.`,
+            details: mute.map((s) => `${s.requirement} — ${s.scenario}`),
+            text: { detailPrefix: "- " },
+        },
+    ];
+}
+//# sourceMappingURL=scenarios.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scenarios.js","sourceRoot":"","sources":["../../../src/core/document/scenarios.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a requirement's scenarios are MISSING, and where they contradict\n * themselves — the coverage and shape questions `validate` asks of every spec.\n *\n * Separate from `./parse.ts` because these grade a parsed document rather than\n * produce one, and separate from `./spec.ts` because they answer to\n * `vocabulary/report.ts`: a stepless scenario is a Finding with a subject and a\n * label, and that shape belongs to the report, not to the requirement.\n */\nimport { scenarioGherkin, type EmittedStep } from \"../vocabulary/steps.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { type Requirement } from \"./spec.js\";\n\n/** Requirements with no scenario — the OpenSpec coverage rule (every requirement needs ≥1). */\nexport function requirementsMissingScenarios(reqs: Requirement[]): Requirement[] {\n  return reqs.filter((r) => r.kind !== \"REMOVED\" && r.scenarios.length === 0);\n}\n\n/**\n * `requirements.missing-scenarios` over the requirements the rule above\n * returned — one spelling for `loam validate` (its `coverageFinding`) and\n * `loam status` (`core/status/feature/feature.ts`), because status's rule is\n * \"never greener than the gates\" and a second spelling of the same finding is\n * how the two would come to disagree. `subject` names the service when the\n * caller has one.\n */\nexport function missingScenariosFinding(label: string, bare: readonly Requirement[], subject?: string): Finding {\n  return {\n    severity: \"error\",\n    code: \"requirements.missing-scenarios\",\n    ...(subject === undefined ? {} : { subject }),\n    message: `${label}: ${bare.length} requirement(s) without a scenario`,\n    details: bare.map((r) => r.name),\n  };\n}\n\n/** A `#### Scenario:` heading whose body holds nothing a runner would execute. */\nexport interface SteplessScenario {\n  requirement: string;\n  scenario: string;\n}\n\n/**\n * Scenarios that satisfy the coverage rule above and test nothing.\n *\n * `requirementsMissingScenarios` counts HEADINGS, so a `#### Scenario:` with no\n * recognizable Given/When/Then line satisfied the fleet gate's coverage claim\n * outright — and it is not a hypothetical shape: it is what `loam new`\n * scaffolds and what an agent writes when it puts the criteria in prose.\n * Downstream the same emptiness is fatal twice over: cucumber runs a stepless\n * scenario vacuously green, and `loam verify --results` can never confirm it.\n *\n * The detector is `loam gherkin`'s own — `scenarioGherkin` decides what a step\n * IS, and a second opinion here would mean the gate and the emitted suite could\n * disagree about whether a scenario has any. That import is the one place these\n * two modules are circular (gherkin.ts parses requirements); both sides export\n * only function declarations, which are hoisted, so neither evaluation order\n * can observe a half-built module.\n */\nexport function steplessScenarios(reqs: Requirement[]): SteplessScenario[] {\n  const out: SteplessScenario[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const s of r.scenarios) {\n      if (scenarioGherkin(s.lines).steps.length === 0) out.push({ requirement: r.name, scenario: s.name });\n    }\n  }\n  return out;\n}\n\n/**\n * The stepless half of the coverage check, as findings — the missing-scenario\n * half stays where it is (`requirementsMissingScenarios`), because the two are\n * different states with different fixes: one requirement owes acceptance\n * criteria, the other owes STEPS in criteria somebody has already written.\n *\n * `label` is the coverage check's own label (`payment-service: requirements`),\n * so both halves of one document name it the same way.\n */\nexport function steplessFindings(label: string, subject: string, reqs: Requirement[]): Finding[] {\n  const bare = steplessScenarios(reqs);\n  if (bare.length === 0) return [];\n  return [\n    {\n      severity: \"error\",\n      code: \"requirements.stepless-scenario\",\n      subject,\n      message:\n        `${label}: ${bare.length} scenario(s) have a heading and no recognizable steps — ` +\n        `they satisfy the coverage rule and test nothing. Cucumber runs a stepless scenario vacuously green and ` +\n        `\\`loam verify --results\\` can never confirm it. Write the body as \\`- **Given/When/Then**\\` bullets.`,\n      details: bare.map((s) => `${s.requirement} — ${s.scenario}`),\n      text: { detailPrefix: \"- \" },\n    },\n  ];\n}\n\n/**\n * Scenarios that have steps and assert NOTHING — a body of Given and When with\n * no Then anywhere in it.\n *\n * The third state, and the one that survives both checks above: the requirement\n * has a scenario, the scenario has steps, and the run can only ever confirm that\n * the arrangement did not throw. `And`/`But` are continuations, so their meaning\n * is decided by the keyword they follow — with no `Then` in the body there is\n * nothing for them to continue but the setup.\n *\n * It matters more the more evidence rests on the suite. A stepless scenario is\n * at least visible as an empty body; this one reads like a real test, emits real\n * steps, runs green, and answers a `scenario.tested` claim to the same standard\n * as a scenario that checks twenty things. Under a runner-neutral answer sheet —\n * one `{digest, status}` entry, no steps to count — this document-side check is\n * the only thing left that can tell the two apart.\n */\nexport function assertionlessScenarios(reqs: Requirement[]): SteplessScenario[] {\n  const out: SteplessScenario[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const s of r.scenarios) {\n      const { steps } = scenarioGherkin(s.lines);\n      // Disjoint from stepless by construction: a body with no steps at all is\n      // that finding's, and reporting one scenario under both codes would offer\n      // two fixes for one defect.\n      if (steps.length > 0 && !steps.some((st) => /^Then\\b/.test(st.text))) {\n        out.push({ requirement: r.name, scenario: s.name });\n      }\n    }\n  }\n  return out;\n}\n\n/** One scenario's disagreement between its `Examples` columns and its `<placeholders>`. */\nexport interface ExamplesMismatch {\n  requirement: string;\n  scenario: string;\n  /** `<placeholders>` a step uses that no column supplies. */\n  unbound: string[];\n  /** Columns no step, docstring or data-table cell refers to. */\n  unreferenced: string[];\n}\n\nconst PLACEHOLDER_RE = /<([^<>\\s]+)>/g;\n\n/**\n * Every `<placeholder>` a scenario's steps reach for, arguments included.\n *\n * Docstrings and data tables are scanned too because cucumber substitutes into\n * them: `<fee>` inside a request payload is a real reference, and a check that\n * read only the step lines would call its column unreferenced and invite the\n * author to delete the column the payload depends on.\n */\nfunction placeholdersUsed(steps: EmittedStep[]): Set<string> {\n  const used = new Set<string>();\n  const scan = (text: string): void => {\n    for (const m of text.matchAll(PLACEHOLDER_RE)) used.add(m[1]!);\n  };\n  for (const st of steps) {\n    scan(st.text);\n    for (const l of st.docstring?.lines ?? []) scan(l);\n    for (const row of st.table ?? []) for (const cell of row) scan(cell);\n  }\n  return used;\n}\n\n/**\n * Scenarios whose `Examples` header and `<placeholders>` disagree.\n *\n * Only scenarios that HAVE an Examples table are considered, and that scoping is\n * load-bearing twice over: a plain scenario's `<angle brackets>` are prose (a\n * generic, a placeholder in a URL template, loam's own scaffold sentinels), and\n * a fleet that never writes an outline must never earn a finding from this.\n *\n * The two halves are different defects. An UNBOUND placeholder is an error the\n * runner cannot repair: cucumber substitutes nothing, so the step definition\n * receives the literal text `<fee>` and either fails obscurely or — worse —\n * matches and asserts against a string nobody meant. An UNREFERENCED column is a\n * warning, because it is usually the fossil of a rename: the column still lists\n * six cases, the step that used it now names something else, and the outline\n * runs six identical passes that read as six cases of coverage.\n */\nexport function examplesMismatches(reqs: Requirement[]): ExamplesMismatch[] {\n  const out: ExamplesMismatch[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const s of r.scenarios) {\n      const { steps, examples } = scenarioGherkin(s.lines);\n      if (examples === null) continue;\n      const used = placeholdersUsed(steps);\n      const columns = new Set(examples.header);\n      const unbound = [...used].filter((p) => !columns.has(p)).sort();\n      const unreferenced = examples.header.filter((c) => !used.has(c));\n      if (unbound.length > 0 || unreferenced.length > 0) {\n        out.push({ requirement: r.name, scenario: s.name, unbound, unreferenced });\n      }\n    }\n  }\n  return out;\n}\n\n/**\n * The Examples half, as findings — two codes rather than one with two\n * severities, because a machine cannot branch on a severity that depends on the\n * case, and the fixes differ: one adds a column, the other removes one or\n * restores the reference that used to use it.\n */\nexport function examplesFindings(label: string, subject: string, reqs: Requirement[]): Finding[] {\n  const all = examplesMismatches(reqs);\n  const findings: Finding[] = [];\n  const unbound = all.filter((m) => m.unbound.length > 0);\n  if (unbound.length > 0) {\n    findings.push({\n      severity: \"error\",\n      code: \"requirements.examples-unbound\",\n      subject,\n      message:\n        `${label}: ${unbound.length} scenario(s) use a \\`<placeholder>\\` no \\`Examples\\` column supplies — ` +\n        `cucumber substitutes nothing, so the step receives the literal angle-bracket text. ` +\n        `Add the column, or correct the placeholder to one the header names.`,\n      details: unbound.map((m) => `${m.requirement} — ${m.scenario}: ${m.unbound.map((p) => `<${p}>`).join(\", \")}`),\n      text: { detailPrefix: \"- \" },\n    });\n  }\n  const dead = all.filter((m) => m.unreferenced.length > 0);\n  if (dead.length > 0) {\n    findings.push({\n      severity: \"warn\",\n      code: \"requirements.examples-unreferenced\",\n      subject,\n      message:\n        `${label}: ${dead.length} scenario(s) declare an \\`Examples\\` column no step refers to — ` +\n        `usually the fossil of a rename, and the outline then runs its rows as identical passes that read as cases. ` +\n        `Reference the column from a step, or drop it.`,\n      details: dead.map((m) => `${m.requirement} — ${m.scenario}: ${m.unreferenced.join(\", \")}`),\n      text: { detailPrefix: \"- \" },\n    });\n  }\n  return findings;\n}\n\n/** The assertionless half, as findings — same label and subject as its two siblings. */\nexport function assertionlessFindings(label: string, subject: string, reqs: Requirement[]): Finding[] {\n  const mute = assertionlessScenarios(reqs);\n  if (mute.length === 0) return [];\n  return [\n    {\n      severity: \"error\",\n      code: \"requirements.assertionless-scenario\",\n      subject,\n      message:\n        `${label}: ${mute.length} scenario(s) have steps and no \\`Then\\` — ` +\n        `they arrange and act, and assert nothing. The run confirms only that the setup did not throw, ` +\n        `and the claim it answers is confirmed on that. Add the \\`- **Then**\\` the scenario was written for.`,\n      details: mute.map((s) => `${s.requirement} — ${s.scenario}`),\n      text: { detailPrefix: \"- \" },\n    },\n  ];\n}\n"]}