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

package/dist/core/gate/verification.js

@@ -0,0 +1,113 @@
+/**
+ * Check 3 of `loam gate`: the verification records of every active feature
+ * touching the gated service, read through `verificationState`'s own graded
+ * verdicts — never a re-derivation of "verified" (that module's header is the
+ * contract). Split from `./checks.ts` when the four checks outgrew the line
+ * limit; this is the one check with a per-feature phase of its own, so it is
+ * the seam.
+ *
+ * Report, never fail: every finding here is a warning, by the item's own
+ * design — a deploy gate that hard-failed on unverified work would teach
+ * everyone that the cheapest way past it is an empty record.
+ */
+import { inOrder } from "../kernel/concurrency.js";
+import { verificationState } from "../status/verification.js";
+import { listFeatures } from "../repo/repo.js";
+import { featurePaths } from "../repo/paths.js";
+import { compareIds } from "../repo/entries.js";
+import { unreadableSubject } from "./report.js";
+export async function verificationCheck(req) {
+    const active = await listFeatures(req.docsDir, {}, req.fleet);
+    // "Touching" = carries a specs/<svc>/ delta — the same definition
+    // `status --service` answers with. A feature whose C4 delta merely draws an
+    // edge into the service is deliberately out: counting it needs a delta parse
+    // per active feature, and it can be added additively if a fleet asks.
+    const touching = active
+        .filter((f) => f.services.includes(req.service))
+        .sort((a, b) => compareIds(a.id, b.id));
+    // COST ACCEPTED: each touching feature with a record derives its checklist,
+    // which parses its delta. That is the per-feature cost
+    // core/status/fleet/fleet.ts refuses for the WHOLE fleet; a deploy-time
+    // command scoped to one service pays it for that service's features only —
+    // with the invocation's context threaded through `verificationState` into
+    // the derivation, so its enumerations are memo hits (one fleet walk per
+    // run, not one per feature) and the batch prefetch below genuinely seeds
+    // the delta parses. The prefetch is an accelerator only: a host that cannot
+    // batch degrades to per-feature parses with identical findings.
+    await req.fleet.prefetchLikeC4(touching.filter((f) => f.has.delta).map((f) => featurePaths(f.dir).delta));
+    // inOrder caps the workspaces in flight and keeps the rows in feature order.
+    const rows = await inOrder(touching, async (f) => {
+        try {
+            const { state, notice } = await verificationState(req.docsDir, f, req.fleet);
+            return { kind: "read", feature: f, state, notice };
+        }
+        catch (err) {
+            return { kind: "unreadable", finding: unreadableSubject("feature", f.id, err) };
+        }
+    });
+    const features = [];
+    const findings = [];
+    for (const row of rows) {
+        if (row.kind === "unreadable") {
+            findings.push(row.finding);
+            continue;
+        }
+        features.push({ id: row.feature.id, ...row.state });
+        findings.push(...featureFindings(row, req.service));
+    }
+    return { features, findings };
+}
+function featureFindings(row, service) {
+    const { feature, state, notice } = row;
+    if (state.verdict === "verified")
+        return [];
+    if (state.verdict === "attested") {
+        // attestedNotice's own words — the one notice verify, list and status all
+        // show, converted to a Finding rather than re-derived. The code string
+        // (`verify.scenario-attested`) is spelled literally at its one emit site,
+        // core/verify/record.ts, where the drift guard collects it.
+        return notice === null
+            ? []
+            : [
+                {
+                    severity: notice.severity,
+                    code: notice.code,
+                    subject: feature.id,
+                    message: notice.message,
+                    ...(notice.claims === undefined ? {} : { details: notice.claims }),
+                },
+            ];
+    }
+    const verify = `\`loam verify ${feature.id} --json\``;
+    const open = state.unconfirmed + state.unanswered;
+    const message = () => {
+        switch (state.state) {
+            case "absent":
+                return `${feature.id} touches '${service}' and has no verification record — nothing has been checked. Derive the checklist and answer it: ${verify}.`;
+            case "unreadable":
+                return `${feature.id}'s verification.yaml exists but does not read as a record — repair or delete it, then re-run ${verify}; nothing will overwrite it while it is unreadable.`;
+            case "stale":
+                return `${feature.id} moved after its record was written — the answers answer a checklist that is no longer the one being asked. Re-derive and re-answer: ${verify}.`;
+            case "recorded":
+                return state.claims === 0
+                    ? `${feature.id}'s record answers no claims at all — nothing was asked, so nothing was checked. ${verify} re-derives the checklist.`
+                    : `${open} of ${state.claims} claim(s) on ${feature.id} are open (${state.unconfirmed} unconfirmed, ${state.unanswered} unanswered) — close them with evidence: ${verify}.`;
+            default: {
+                // A fifth record state must land here as a build failure, not fall
+                // through into some rung nobody decided (verificationStatus holds the
+                // same guard for the same reason).
+                const unreachable = state.state;
+                throw new Error(`gate: no wording for verification state '${String(unreachable)}'`);
+            }
+        }
+    };
+    return [
+        {
+            severity: "warn",
+            code: "gate.feature-unverified",
+            subject: feature.id,
+            message: message(),
+        },
+    ];
+}
+//# sourceMappingURL=verification.js.map

package/dist/core/gate/verification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.js","sourceRoot":"","sources":["../../../src/core/gate/verification.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Check 3 of `loam gate`: the verification records of every active feature\n * touching the gated service, read through `verificationState`'s own graded\n * verdicts — never a re-derivation of \"verified\" (that module's header is the\n * contract). Split from `./checks.ts` when the four checks outgrew the line\n * limit; this is the one check with a per-feature phase of its own, so it is\n * the seam.\n *\n * Report, never fail: every finding here is a warning, by the item's own\n * design — a deploy gate that hard-failed on unverified work would teach\n * everyone that the cheapest way past it is an empty record.\n */\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport { verificationState } from \"../status/verification.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport { featurePaths } from \"../repo/paths.js\";\nimport { compareIds, type FeatureEntry } from \"../repo/entries.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport type { VerificationState } from \"../status/report.js\";\nimport type { VerifyNotice } from \"../verify/record.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { RawServiceId } from \"../kernel/ids/service.js\";\nimport { unreadableSubject, type GateFeature } from \"./report.js\";\n\ntype VerificationRow =\n  | { kind: \"read\"; feature: FeatureEntry; state: VerificationState; notice: VerifyNotice | null }\n  | { kind: \"unreadable\"; finding: Finding };\n\nexport interface VerificationCheckRequest {\n  docsDir: DocsDir;\n  service: RawServiceId;\n  fleet: FleetContext;\n}\n\nexport async function verificationCheck(\n  req: VerificationCheckRequest,\n): Promise<{ features: GateFeature[]; findings: Finding[] }> {\n  const active = await listFeatures(req.docsDir, {}, req.fleet);\n  // \"Touching\" = carries a specs/<svc>/ delta — the same definition\n  // `status --service` answers with. A feature whose C4 delta merely draws an\n  // edge into the service is deliberately out: counting it needs a delta parse\n  // per active feature, and it can be added additively if a fleet asks.\n  const touching = active\n    .filter((f) => f.services.includes(req.service))\n    .sort((a, b) => compareIds(a.id, b.id));\n  // COST ACCEPTED: each touching feature with a record derives its checklist,\n  // which parses its delta. That is the per-feature cost\n  // core/status/fleet/fleet.ts refuses for the WHOLE fleet; a deploy-time\n  // command scoped to one service pays it for that service's features only —\n  // with the invocation's context threaded through `verificationState` into\n  // the derivation, so its enumerations are memo hits (one fleet walk per\n  // run, not one per feature) and the batch prefetch below genuinely seeds\n  // the delta parses. The prefetch is an accelerator only: a host that cannot\n  // batch degrades to per-feature parses with identical findings.\n  await req.fleet.prefetchLikeC4(\n    touching.filter((f) => f.has.delta).map((f) => featurePaths(f.dir).delta),\n  );\n  // inOrder caps the workspaces in flight and keeps the rows in feature order.\n  const rows = await inOrder(touching, async (f): Promise<VerificationRow> => {\n    try {\n      const { state, notice } = await verificationState(req.docsDir, f, req.fleet);\n      return { kind: \"read\", feature: f, state, notice };\n    } catch (err) {\n      return { kind: \"unreadable\", finding: unreadableSubject(\"feature\", f.id, err) };\n    }\n  });\n  const features: GateFeature[] = [];\n  const findings: Finding[] = [];\n  for (const row of rows) {\n    if (row.kind === \"unreadable\") {\n      findings.push(row.finding);\n      continue;\n    }\n    features.push({ id: row.feature.id, ...row.state });\n    findings.push(...featureFindings(row, req.service));\n  }\n  return { features, findings };\n}\n\nfunction featureFindings(\n  row: { feature: FeatureEntry; state: VerificationState; notice: VerifyNotice | null },\n  service: string,\n): Finding[] {\n  const { feature, state, notice } = row;\n  if (state.verdict === \"verified\") return [];\n  if (state.verdict === \"attested\") {\n    // attestedNotice's own words — the one notice verify, list and status all\n    // show, converted to a Finding rather than re-derived. The code string\n    // (`verify.scenario-attested`) is spelled literally at its one emit site,\n    // core/verify/record.ts, where the drift guard collects it.\n    return notice === null\n      ? []\n      : [\n          {\n            severity: notice.severity,\n            code: notice.code,\n            subject: feature.id,\n            message: notice.message,\n            ...(notice.claims === undefined ? {} : { details: notice.claims }),\n          },\n        ];\n  }\n  const verify = `\\`loam verify ${feature.id} --json\\``;\n  const open = state.unconfirmed + state.unanswered;\n  const message = (): string => {\n    switch (state.state) {\n      case \"absent\":\n        return `${feature.id} touches '${service}' and has no verification record — nothing has been checked. Derive the checklist and answer it: ${verify}.`;\n      case \"unreadable\":\n        return `${feature.id}'s verification.yaml exists but does not read as a record — repair or delete it, then re-run ${verify}; nothing will overwrite it while it is unreadable.`;\n      case \"stale\":\n        return `${feature.id} moved after its record was written — the answers answer a checklist that is no longer the one being asked. Re-derive and re-answer: ${verify}.`;\n      case \"recorded\":\n        return state.claims === 0\n          ? `${feature.id}'s record answers no claims at all — nothing was asked, so nothing was checked. ${verify} re-derives the checklist.`\n          : `${open} of ${state.claims} claim(s) on ${feature.id} are open (${state.unconfirmed} unconfirmed, ${state.unanswered} unanswered) — close them with evidence: ${verify}.`;\n      default: {\n        // A fifth record state must land here as a build failure, not fall\n        // through into some rung nobody decided (verificationStatus holds the\n        // same guard for the same reason).\n        const unreachable: never = state.state;\n        throw new Error(`gate: no wording for verification state '${String(unreachable)}'`);\n      }\n    }\n  };\n  return [\n    {\n      severity: \"warn\",\n      code: \"gate.feature-unverified\",\n      subject: feature.id,\n      message: message(),\n    },\n  ];\n}\n"]}

package/dist/core/gherkin/digest.js

@@ -0,0 +1,60 @@
+/**
+ * The scenario-identity digest — ONE recipe with three consumers, deliberately
+ * in one module: `verify/checklist.ts` folds it into `scenario.tested` claim
+ * ids and claim digests, and `./stamp.ts` stamps the same hex as the
+ * `@loam-digest-…` tag on every generated scenario, which is what a cucumber
+ * report carries and what `verify --results` matches on. A second spelling of
+ * the hash would silently stop every scenario claim from being answerable by a
+ * run — which is why this lives beside the stamper rather than inside either
+ * consumer.
+ */
+import { createHash } from "node:crypto";
+/**
+ * The full sha256 of a scenario's body — its lines joined and edge-trimmed,
+ * exactly as `serializeRequirements` frames them. The BODY, not the title,
+ * because rewriting the Given/When/Then under an unchanged heading is new text
+ * nobody answered for, and the promise — rewording a scenario renames its
+ * claim — has to hold for the words that actually specify the behaviour.
+ *
+ * `scenario.tested` claim ids fold in a prefix of this hex, a claim's `digest`
+ * and the `@loam-digest-<16hex>` tag `loam gherkin` stamps both take another
+ * (`verify/checklist.ts` owns those lengths, `./stamp.ts` its own) — so the
+ * claim, the stamp and the report `--results` reads can never disagree about
+ * what a scenario says.
+ *
+ * The identity is (SERVICE, AXIS, body), and both salts are there for the same
+ * reason: a digest that spans two namespaces lets one green run answer a
+ * question nobody ran a test for.
+ *
+ * - The AXIS salt keeps `spec.md` and `arch.spec.md` apart. Without it a green
+ *   BUSINESS run answered the arch claim too — an integration test nobody wrote
+ *   read as run.
+ * - The SERVICE salt keeps two repositories apart. Different services can word
+ *   "the service returns 404 for an unknown id" identically; unsalted, those
+ *   scenarios share one digest and one repository's green run can appear to
+ *   confirm claims from suites that never ran each other's tests.
+ *
+ * The service salt is what makes that case CORRECT rather than merely refused:
+ * `contestedDigests` could only decline to answer a shared digest, which left a
+ * fleet with ordinary repeated wording holding claims nothing could ever
+ * answer.
+ *
+ * Both salts renamed every claim id and every stamped tag on the day they
+ * landed, and both readings are legible rather than silent: an existing
+ * `verification.yaml` answers a checklist digest that is no longer derived and
+ * reports STALE, and an existing generated `.feature` carries digests the
+ * living spec no longer computes and reports `gherkin.stale` beside the
+ * `gherkin.missing` for the new ones. One `loam gherkin` and one re-record
+ * clear both.
+ */
+export function scenarioBodyHash(service, lines, axis = "business") {
+    // NUL-separated like claimId's tuples (verify/checklist.ts), and for its
+    // reason: no body can spell the salt in front of it, so the namespaces stay
+    // disjoint. Spelled as an escape and never as a raw NUL in the literal — a
+    // raw one makes this file read as `data` to `file(1)` and invisible to
+    // `grep`.
+    const body = lines.join("\n").trim();
+    const onAxis = axis === "arch" ? `arch.spec.md\u0000${body}` : body;
+    return createHash("sha256").update(`${service}\u0000${onAxis}`).digest("hex");
+}
+//# sourceMappingURL=digest.js.map

package/dist/core/gherkin/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../../../src/core/gherkin/digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAKzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,KAAe,EACf,IAAI,GAAiB,UAAU;IAE/B,yEAAyE;IACzE,4EAA4E;IAC5E,2EAA2E;IAC3E,uEAAuE;IACvE,UAAU;IACV,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,MAAM,GAAG,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACpE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,SAAS,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChF,CAAC","sourcesContent":["/**\n * The scenario-identity digest — ONE recipe with three consumers, deliberately\n * in one module: `verify/checklist.ts` folds it into `scenario.tested` claim\n * ids and claim digests, and `./stamp.ts` stamps the same hex as the\n * `@loam-digest-…` tag on every generated scenario, which is what a cucumber\n * report carries and what `verify --results` matches on. A second spelling of\n * the hash would silently stop every scenario claim from being answerable by a\n * run — which is why this lives beside the stamper rather than inside either\n * consumer.\n */\nimport { createHash } from \"node:crypto\";\n\n/** The axis a scenario's words live on: `spec.md` or `arch.spec.md`. */\nexport type ScenarioAxis = \"business\" | \"arch\";\n\n/**\n * The full sha256 of a scenario's body — its lines joined and edge-trimmed,\n * exactly as `serializeRequirements` frames them. The BODY, not the title,\n * because rewriting the Given/When/Then under an unchanged heading is new text\n * nobody answered for, and the promise — rewording a scenario renames its\n * claim — has to hold for the words that actually specify the behaviour.\n *\n * `scenario.tested` claim ids fold in a prefix of this hex, a claim's `digest`\n * and the `@loam-digest-<16hex>` tag `loam gherkin` stamps both take another\n * (`verify/checklist.ts` owns those lengths, `./stamp.ts` its own) — so the\n * claim, the stamp and the report `--results` reads can never disagree about\n * what a scenario says.\n *\n * The identity is (SERVICE, AXIS, body), and both salts are there for the same\n * reason: a digest that spans two namespaces lets one green run answer a\n * question nobody ran a test for.\n *\n * - The AXIS salt keeps `spec.md` and `arch.spec.md` apart. Without it a green\n *   BUSINESS run answered the arch claim too — an integration test nobody wrote\n *   read as run.\n * - The SERVICE salt keeps two repositories apart. Different services can word\n *   \"the service returns 404 for an unknown id\" identically; unsalted, those\n *   scenarios share one digest and one repository's green run can appear to\n *   confirm claims from suites that never ran each other's tests.\n *\n * The service salt is what makes that case CORRECT rather than merely refused:\n * `contestedDigests` could only decline to answer a shared digest, which left a\n * fleet with ordinary repeated wording holding claims nothing could ever\n * answer.\n *\n * Both salts renamed every claim id and every stamped tag on the day they\n * landed, and both readings are legible rather than silent: an existing\n * `verification.yaml` answers a checklist digest that is no longer derived and\n * reports STALE, and an existing generated `.feature` carries digests the\n * living spec no longer computes and reports `gherkin.stale` beside the\n * `gherkin.missing` for the new ones. One `loam gherkin` and one re-record\n * clear both.\n */\nexport function scenarioBodyHash(\n  service: string,\n  lines: string[],\n  axis: ScenarioAxis = \"business\",\n): string {\n  // NUL-separated like claimId's tuples (verify/checklist.ts), and for its\n  // reason: no body can spell the salt in front of it, so the namespaces stay\n  // disjoint. Spelled as an escape and never as a raw NUL in the literal — a\n  // raw one makes this file read as `data` to `file(1)` and invisible to\n  // `grep`.\n  const body = lines.join(\"\\n\").trim();\n  const onAxis = axis === \"arch\" ? `arch.spec.md\\u0000${body}` : body;\n  return createHash(\"sha256\").update(`${service}\\u0000${onAxis}`).digest(\"hex\");\n}\n"]}

package/dist/core/gherkin/emit.js

@@ -0,0 +1,177 @@
+/**
+ * A requirement set as a `.feature` file: what gets written where, and what the
+ * text says.
+ *
+ * The plan is separate from the render because the two answer to different
+ * owners — where a suite lands is the service repository's layout question
+ * (`./stamp.ts` owns the root), while what a scenario reads like is the
+ * requirement's. Every emitted scenario carries the digest tag the claim
+ * checklist matches on, which is why nothing here may reword a scenario body.
+ */
+import {} from "../document/spec.js";
+import { scenarioGherkin } from "../vocabulary/steps.js";
+import {} from "../repo/paths.js";
+import {} from "./digest.js";
+import { gherkinStampLine, scenarioDigest, scenarioDigestTag } from "./stamp.js";
+/** The axis label the machine contract speaks. */
+export function axisLabel(axis) {
+    return axis.key === "archSpec" ? "arch" : "business";
+}
+/**
+ * A requirement name as a file name: lowercase, every non-letter/digit run one
+ * hyphen, edges trimmed.
+ *
+ * The keep-set is `\p{L}\p{N}`, not `[a-z0-9]`, because an ASCII-only slug is
+ * not a slug of a non-Latin fleet — it is the empty string. Every requirement
+ * written in Chinese, Japanese, Korean, Greek, Cyrillic or Hebrew slugged to
+ * nothing, fell back to `requirement`, and the whole service's suite came out
+ * as `requirement.feature`, `requirement-2.feature`, … : file names that name
+ * nothing, in the one place the mapping is supposed to be legible. So letters
+ * of every script survive as themselves.
+ *
+ * Accents are folded rather than kept, and that is the reason for NFKD first:
+ * decomposing splits `é` into `e` + a combining acute, and dropping the
+ * combining marks (`\p{M}`) leaves `e`. Without the fold `émojis` and `emojis`
+ * would be two files that look identical in a directory listing — and on a
+ * filesystem that normalises names (APFS, and HFS+ before it) they would be one
+ * file, silently, with the second emission overwriting the first.
+ *
+ * A name this still leaves empty (all punctuation or emoji) falls back to
+ * "requirement" and lets the collision counter number it. Runs collapse to a
+ * SINGLE hyphen, which is what keeps the `arch--` prefix an axis marker no
+ * business slug can spell.
+ */
+export function slugOf(name) {
+    const s = name
+        .normalize("NFKD")
+        .replace(/\p{M}+/gu, "")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, "-")
+        .replace(/^-+|-+$/g, "");
+    return s.length > 0 ? s : "requirement";
+}
+/**
+ * The emission plan for one scope: one `.feature` per requirement.
+ *
+ * File naming is the mapping's contract, so it is spelled here once:
+ * `<slug>.feature` for the business axis, `arch--<slug>.feature` for the
+ * architecture axis — flat and diffable, and collision-proof across axes
+ * because slugs collapse punctuation runs to a single hyphen, so no business
+ * slug can ever begin `arch--`. Two requirements slugging identically are
+ * disambiguated in document order: the first keeps the bare slug, later ones
+ * take `-2`, `-3`, … (counting up past any name that already owns the suffix).
+ *
+ * Tags ride the `Feature:` line and are inherited by every scenario in the
+ * file: `@<FEAT>` in feature mode (living emissions carry no feature tag),
+ * `@architecture` on the arch axis.
+ *
+ * `opts.service` is the suite's owner and salts every digest stamp — the same
+ * service `loam verify` files the matching claims under. Required, not
+ * defaulted: an emission that guessed it would stamp tags no claim matches.
+ */
+export function planEmission(byAxis, opts) {
+    const used = new Set();
+    const out = [];
+    for (const { axis, reqs } of byAxis) {
+        for (const r of reqs) {
+            const base = (axis.key === "archSpec" ? "arch--" : "") + slugOf(r.name);
+            let fileName = `${base}.feature`;
+            for (let n = 2; used.has(fileName); n += 1)
+                fileName = `${base}-${n}.feature`;
+            used.add(fileName);
+            const tags = [
+                ...(opts.featureTag === undefined ? [] : [`@${opts.featureTag}`]),
+                ...(axis.key === "archSpec" ? ["@architecture"] : []),
+            ];
+            const { content, digests, stepless, malformedExamples, strandedBlocks } = renderFeature(r, { tags, version: opts.version }, opts.service, axisLabel(axis));
+            out.push({ fileName, axis, requirement: r, digests, stepless, malformedExamples, strandedBlocks, content });
+        }
+    }
+    return out;
+}
+export function renderFeature(r, stamp, service, axis = "business") {
+    const { tags, version } = stamp;
+    const lines = [gherkinStampLine(version)];
+    if (tags.length > 0)
+        lines.push(tags.join(" "));
+    lines.push(`Feature: ${r.name}`);
+    const text = r.text.join("\n").trim();
+    if (text.length > 0) {
+        lines.push("");
+        for (const l of text.split("\n"))
+            lines.push(l.length > 0 ? `  ${l}` : "");
+    }
+    const digests = [];
+    const stepless = [];
+    const malformedExamples = [];
+    const strandedBlocks = [];
+    for (const s of r.scenarios) {
+        // The digest hashes the WHOLE body, table rows included, so a changed cell
+        // is a changed scenario: `gherkin.stale` fires on an edited case exactly as
+        // it does on an edited step, and the claim it answers moves with it. It is
+        // also why a change to THIS renderer moves no digest: the hash is over the
+        // markdown source, so a suite generated before a grammar change keeps its
+        // stamps and grades `gherkin.current` until somebody regenerates it.
+        const digest = scenarioDigest(service, s.lines, axis);
+        digests.push(digest);
+        const { description, steps, examples, malformedExamples: broken, strandedBlocks: stranded } = scenarioGherkin(s.lines);
+        if (steps.length === 0)
+            stepless.push(s.name);
+        if (broken)
+            malformedExamples.push(s.name);
+        if (stranded)
+            strandedBlocks.push(s.name);
+        // The keyword is the whole difference between one case and twenty: cucumber
+        // expands an outline into one report element per row, each carrying this
+        // scenario's tag, and `runnerAnswers` confirms the claim only when every
+        // one of them passed.
+        lines.push("", `  ${scenarioDigestTag(digest)}`, `  ${examples === null ? "Scenario" : "Scenario Outline"}: ${s.name}`);
+        for (const d of description)
+            lines.push(`    ${d}`);
+        for (const st of steps) {
+            lines.push(`    ${st.text}`);
+            // Gherkin puts a step's argument UNDER the step, indented past it, and
+            // permits at most one of each kind. Docstring first, so a step carrying
+            // both reads request-then-expectation.
+            if (st.docstring !== undefined) {
+                lines.push(`      """${st.docstring.contentType ?? ""}`);
+                // A payload containing its own `"""` would close the block early and
+                // silently move the rest of the request body into the step list.
+                for (const l of st.docstring.lines)
+                    lines.push(l.length === 0 ? "" : `      ${l.replace(/"""/g, '\\"\\"\\"')}`);
+                lines.push('      """');
+            }
+            if (st.table !== undefined)
+                for (const row of st.table)
+                    lines.push(`      ${tableRow(row, st.table)}`);
+        }
+        if (examples !== null) {
+            lines.push("", "    Examples:");
+            for (const row of [examples.header, ...examples.rows])
+                lines.push(`      ${tableRow(row, [examples.header, ...examples.rows])}`);
+        }
+    }
+    return { content: lines.join("\n") + "\n", digests, stepless, malformedExamples, strandedBlocks };
+}
+/**
+ * One table row — an `Examples` case or a step's data table — with columns
+ * padded to the widest cell in that table.
+ *
+ * Padding is cosmetic to cucumber and deliberate here: these files are read in
+ * review as often as they are run, and an unaligned twenty-row matrix is where
+ * a wrong cell hides. Deterministic to the byte, like everything else the
+ * emitter writes — the widths come from the table alone.
+ *
+ * ESCAPING IS NOT COSMETIC. Gherkin's table grammar ends a cell at `|`, so a
+ * cell containing one silently becomes two cells and every row after it
+ * disagrees with the header; `\` and a literal newline are the same class. The
+ * escapes go on before the padding is measured, because the emitted width is
+ * the escaped width — measuring the raw cell produced columns that drifted by
+ * one character per escape.
+ */
+function tableRow(row, all) {
+    const esc = (c) => c.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\n/g, "\\n");
+    const widths = row.map((_, i) => Math.max(...all.map((r) => esc(r[i] ?? "").length)));
+    return `| ${row.map((c, i) => esc(c).padEnd(widths[i])).join(" | ")} |`;
+}
+//# sourceMappingURL=emit.js.map

package/dist/core/gherkin/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","sourceRoot":"","sources":["../../../src/core/gherkin/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAoB,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAiB,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAqB,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEjF,kDAAkD;AAClD,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,OAAO,IAAI,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,MAAM,CAAC,GAAG,IAAI;SACX,SAAS,CAAC,MAAM,CAAC;SACjB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,WAAW,EAAE;SACb,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC;SAChC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC3B,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;AAC1C,CAAC;AAmCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAsD,EACtD,IAA+D;IAE/D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;QACpC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACxE,IAAI,QAAQ,GAAG,GAAG,IAAI,UAAU,CAAC;YACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC;gBAAE,QAAQ,GAAG,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC;YAC9E,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACnB,MAAM,IAAI,GAAG;gBACX,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;gBACjE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;aACtD,CAAC;YACF,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,cAAc,EAAE,GAAG,aAAa,CACrF,CAAC,EACD,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAC/B,IAAI,CAAC,OAAO,EACZ,SAAS,CAAC,IAAI,CAAC,CAChB,CAAC;YACF,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,CAAC;QAC9G,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAqBD,MAAM,UAAU,aAAa,CAC3B,CAAc,EACd,KAAY,EACZ,OAAe,EACf,IAAI,GAAiB,UAAU;IAE/B,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAChC,MAAM,KAAK,GAAa,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,iBAAiB,GAAa,EAAE,CAAC;IACvC,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;QAC5B,2EAA2E;QAC3E,4EAA4E;QAC5E,2EAA2E;QAC3E,2EAA2E;QAC3E,0EAA0E;QAC1E,qEAAqE;QACrE,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACtD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACvH,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,MAAM;YAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,QAAQ;YAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1C,4EAA4E;QAC5E,yEAAyE;QACzE,yEAAyE;QACzE,sBAAsB;QACtB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,iBAAiB,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,kBAAkB,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACxH,KAAK,MAAM,CAAC,IAAI,WAAW;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACpD,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;YAC7B,uEAAuE;YACvE,wEAAwE;YACxE,uCAAuC;YACvC,IAAI,EAAE,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC/B,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,SAAS,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC,CAAC;gBACzD,qEAAqE;gBACrE,iEAAiE;gBACjE,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,KAAK;oBAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;gBAChH,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAC1B,CAAC;YACD,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS;gBAAE,KAAK,MAAM,GAAG,IAAI,EAAE,CAAC,KAAK;oBAAE,KAAK,CAAC,IAAI,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACzG,CAAC;QACD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC;YAChC,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;QACnI,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;AACpG,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,QAAQ,CAAC,GAAa,EAAE,GAAwB;IACvD,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACxG,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACtF,OAAO,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;AAC3E,CAAC","sourcesContent":["/**\n * A requirement set as a `.feature` file: what gets written where, and what the\n * text says.\n *\n * The plan is separate from the render because the two answer to different\n * owners — where a suite lands is the service repository's layout question\n * (`./stamp.ts` owns the root), while what a scenario reads like is the\n * requirement's. Every emitted scenario carries the digest tag the claim\n * checklist matches on, which is why nothing here may reword a scenario body.\n */\nimport { type Requirement } from \"../document/spec.js\";\nimport { scenarioGherkin } from \"../vocabulary/steps.js\";\nimport { type SpecAxis } from \"../repo/paths.js\";\nimport { type ScenarioAxis } from \"./digest.js\";\nimport { gherkinStampLine, scenarioDigest, scenarioDigestTag } from \"./stamp.js\";\n\n/** The axis label the machine contract speaks. */\nexport function axisLabel(axis: SpecAxis): \"business\" | \"arch\" {\n  return axis.key === \"archSpec\" ? \"arch\" : \"business\";\n}\n\n/**\n * A requirement name as a file name: lowercase, every non-letter/digit run one\n * hyphen, edges trimmed.\n *\n * The keep-set is `\\p{L}\\p{N}`, not `[a-z0-9]`, because an ASCII-only slug is\n * not a slug of a non-Latin fleet — it is the empty string. Every requirement\n * written in Chinese, Japanese, Korean, Greek, Cyrillic or Hebrew slugged to\n * nothing, fell back to `requirement`, and the whole service's suite came out\n * as `requirement.feature`, `requirement-2.feature`, … : file names that name\n * nothing, in the one place the mapping is supposed to be legible. So letters\n * of every script survive as themselves.\n *\n * Accents are folded rather than kept, and that is the reason for NFKD first:\n * decomposing splits `é` into `e` + a combining acute, and dropping the\n * combining marks (`\\p{M}`) leaves `e`. Without the fold `émojis` and `emojis`\n * would be two files that look identical in a directory listing — and on a\n * filesystem that normalises names (APFS, and HFS+ before it) they would be one\n * file, silently, with the second emission overwriting the first.\n *\n * A name this still leaves empty (all punctuation or emoji) falls back to\n * \"requirement\" and lets the collision counter number it. Runs collapse to a\n * SINGLE hyphen, which is what keeps the `arch--` prefix an axis marker no\n * business slug can spell.\n */\nexport function slugOf(name: string): string {\n  const s = name\n    .normalize(\"NFKD\")\n    .replace(/\\p{M}+/gu, \"\")\n    .toLowerCase()\n    .replace(/[^\\p{L}\\p{N}]+/gu, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n  return s.length > 0 ? s : \"requirement\";\n}\n\nexport interface PlannedFeature {\n  /** File name under `<gherkinDir>/loam/` — flat, never a subdirectory. */\n  fileName: string;\n  axis: SpecAxis;\n  requirement: Requirement;\n  /** One digest per scenario, in scenario order — what the stamps say. */\n  digests: string[];\n  /**\n   * Names of scenarios that yielded ZERO steps — numbered-step or prose-only\n   * legacy bodies. Their `Scenario:` blocks are description-only: cucumber\n   * runs them vacuously green, while `--results` (which requires at least one\n   * passed step) can never confirm them — so the emission must say so out\n   * loud, and the fix is rewording the spec bullets, never editing the file.\n   */\n  stepless: string[];\n  /**\n   * Names of scenarios whose markdown table could not be read as `Examples` —\n   * see `ScenarioGherkin.malformedExamples`. The table stays in the description\n   * and the file is valid Gherkin, so nothing downstream can notice: the\n   * emission is the only place this is visible at all.\n   */\n  malformedExamples: string[];\n  /**\n   * Names of scenarios that wrote a fenced block or an indented table where it\n   * could not become a step argument — see `ScenarioGherkin.strandedBlocks`.\n   * The text survives as description, so the file is valid Gherkin and the\n   * document still reads correctly; what is gone is the ARGUMENT, and a step\n   * definition that expected a payload or a table receives nothing.\n   */\n  strandedBlocks: string[];\n  content: string;\n}\n\n/**\n * The emission plan for one scope: one `.feature` per requirement.\n *\n * File naming is the mapping's contract, so it is spelled here once:\n * `<slug>.feature` for the business axis, `arch--<slug>.feature` for the\n * architecture axis — flat and diffable, and collision-proof across axes\n * because slugs collapse punctuation runs to a single hyphen, so no business\n * slug can ever begin `arch--`. Two requirements slugging identically are\n * disambiguated in document order: the first keeps the bare slug, later ones\n * take `-2`, `-3`, … (counting up past any name that already owns the suffix).\n *\n * Tags ride the `Feature:` line and are inherited by every scenario in the\n * file: `@<FEAT>` in feature mode (living emissions carry no feature tag),\n * `@architecture` on the arch axis.\n *\n * `opts.service` is the suite's owner and salts every digest stamp — the same\n * service `loam verify` files the matching claims under. Required, not\n * defaulted: an emission that guessed it would stamp tags no claim matches.\n */\nexport function planEmission(\n  byAxis: Array<{ axis: SpecAxis; reqs: Requirement[] }>,\n  opts: { service: string; featureTag?: string; version: string },\n): PlannedFeature[] {\n  const used = new Set<string>();\n  const out: PlannedFeature[] = [];\n  for (const { axis, reqs } of byAxis) {\n    for (const r of reqs) {\n      const base = (axis.key === \"archSpec\" ? \"arch--\" : \"\") + slugOf(r.name);\n      let fileName = `${base}.feature`;\n      for (let n = 2; used.has(fileName); n += 1) fileName = `${base}-${n}.feature`;\n      used.add(fileName);\n      const tags = [\n        ...(opts.featureTag === undefined ? [] : [`@${opts.featureTag}`]),\n        ...(axis.key === \"archSpec\" ? [\"@architecture\"] : []),\n      ];\n      const { content, digests, stepless, malformedExamples, strandedBlocks } = renderFeature(\n        r,\n        { tags, version: opts.version },\n        opts.service,\n        axisLabel(axis),\n      );\n      out.push({ fileName, axis, requirement: r, digests, stepless, malformedExamples, strandedBlocks, content });\n    }\n  }\n  return out;\n}\n\n/**\n * One requirement as one `.feature` file: `Feature:` is the requirement name,\n * its body text (Operations:/Covers: lines included — they are part of what\n * the requirement says) becomes the feature description, and each scenario\n * renders under its `@loam-digest-…` tag — the tag line sits directly above\n * the `Scenario:` keyword, where Gherkin puts scenario-level tags, so the\n * runner attaches it to the scenario and carries it into the JSON report.\n * Deterministic to the byte.\n *\n * `service` is the owner of the suite being written, and it salts every digest\n * — the same service `loam verify` files the matching claims under. The two\n * have to be the same string or the stamps this writes match no claim at all.\n */\n/** What the emitted file is stamped with, beside the requirement it renders. */\nexport interface Stamp {\n  tags: string[];\n  version: string;\n}\n\nexport function renderFeature(\n  r: Requirement,\n  stamp: Stamp,\n  service: string,\n  axis: ScenarioAxis = \"business\",\n): { content: string; digests: string[]; stepless: string[]; malformedExamples: string[]; strandedBlocks: string[] } {\n  const { tags, version } = stamp;\n  const lines: string[] = [gherkinStampLine(version)];\n  if (tags.length > 0) lines.push(tags.join(\" \"));\n  lines.push(`Feature: ${r.name}`);\n  const text = r.text.join(\"\\n\").trim();\n  if (text.length > 0) {\n    lines.push(\"\");\n    for (const l of text.split(\"\\n\")) lines.push(l.length > 0 ? `  ${l}` : \"\");\n  }\n  const digests: string[] = [];\n  const stepless: string[] = [];\n  const malformedExamples: string[] = [];\n  const strandedBlocks: string[] = [];\n  for (const s of r.scenarios) {\n    // The digest hashes the WHOLE body, table rows included, so a changed cell\n    // is a changed scenario: `gherkin.stale` fires on an edited case exactly as\n    // it does on an edited step, and the claim it answers moves with it. It is\n    // also why a change to THIS renderer moves no digest: the hash is over the\n    // markdown source, so a suite generated before a grammar change keeps its\n    // stamps and grades `gherkin.current` until somebody regenerates it.\n    const digest = scenarioDigest(service, s.lines, axis);\n    digests.push(digest);\n    const { description, steps, examples, malformedExamples: broken, strandedBlocks: stranded } = scenarioGherkin(s.lines);\n    if (steps.length === 0) stepless.push(s.name);\n    if (broken) malformedExamples.push(s.name);\n    if (stranded) strandedBlocks.push(s.name);\n    // The keyword is the whole difference between one case and twenty: cucumber\n    // expands an outline into one report element per row, each carrying this\n    // scenario's tag, and `runnerAnswers` confirms the claim only when every\n    // one of them passed.\n    lines.push(\"\", `  ${scenarioDigestTag(digest)}`, `  ${examples === null ? \"Scenario\" : \"Scenario Outline\"}: ${s.name}`);\n    for (const d of description) lines.push(`    ${d}`);\n    for (const st of steps) {\n      lines.push(`    ${st.text}`);\n      // Gherkin puts a step's argument UNDER the step, indented past it, and\n      // permits at most one of each kind. Docstring first, so a step carrying\n      // both reads request-then-expectation.\n      if (st.docstring !== undefined) {\n        lines.push(`      \"\"\"${st.docstring.contentType ?? \"\"}`);\n        // A payload containing its own `\"\"\"` would close the block early and\n        // silently move the rest of the request body into the step list.\n        for (const l of st.docstring.lines) lines.push(l.length === 0 ? \"\" : `      ${l.replace(/\"\"\"/g, '\\\\\"\\\\\"\\\\\"')}`);\n        lines.push('      \"\"\"');\n      }\n      if (st.table !== undefined) for (const row of st.table) lines.push(`      ${tableRow(row, st.table)}`);\n    }\n    if (examples !== null) {\n      lines.push(\"\", \"    Examples:\");\n      for (const row of [examples.header, ...examples.rows]) lines.push(`      ${tableRow(row, [examples.header, ...examples.rows])}`);\n    }\n  }\n  return { content: lines.join(\"\\n\") + \"\\n\", digests, stepless, malformedExamples, strandedBlocks };\n}\n\n/**\n * One table row — an `Examples` case or a step's data table — with columns\n * padded to the widest cell in that table.\n *\n * Padding is cosmetic to cucumber and deliberate here: these files are read in\n * review as often as they are run, and an unaligned twenty-row matrix is where\n * a wrong cell hides. Deterministic to the byte, like everything else the\n * emitter writes — the widths come from the table alone.\n *\n * ESCAPING IS NOT COSMETIC. Gherkin's table grammar ends a cell at `|`, so a\n * cell containing one silently becomes two cells and every row after it\n * disagrees with the header; `\\` and a literal newline are the same class. The\n * escapes go on before the padding is measured, because the emitted width is\n * the escaped width — measuring the raw cell produced columns that drifted by\n * one character per escape.\n */\nfunction tableRow(row: string[], all: readonly string[][]): string {\n  const esc = (c: string): string => c.replace(/\\\\/g, \"\\\\\\\\\").replace(/\\|/g, \"\\\\|\").replace(/\\n/g, \"\\\\n\");\n  const widths = row.map((_, i) => Math.max(...all.map((r) => esc(r[i] ?? \"\").length)));\n  return `| ${row.map((c, i) => esc(c).padEnd(widths[i]!)).join(\" | \")} |`;\n}\n"]}

package/dist/core/gherkin/read.js

@@ -0,0 +1,76 @@
+/**
+ * A generated `.feature` file read back — the stamp, the tags, the scenarios.
+ *
+ * The parser is deliberately shallow and forgiving in one direction only: a file
+ * without loam's stamp is not loam's to grade, and returns null rather than a
+ * partially understood suite. Anything that IS stamped is loam's output, so the
+ * digests inside it are trusted to be the ones `./emit.ts` wrote.
+ */
+import { DIGEST_TAG_RE, STAMP_RE } from "./stamp.js";
+/**
+ * Parse a `.feature` file for its loam stamps. Null when line 1 is not the
+ * stamp — an unstamped file is not loam's writing, and no staleness judgment
+ * may be built on it. Tag lines above `Feature:` are the file's tags; a tag
+ * line after it that carries a `@loam-digest-…` token binds that digest to the
+ * immediately following `Scenario:` line (tag lines stack, as Gherkin's do,
+ * without breaking the bond); any other non-blank line between them breaks it.
+ *
+ * DOCSTRING BODIES ARE SKIPPED WHOLE, and that is a correctness requirement
+ * rather than tidiness. Since a step may carry a `"""` payload, a request body
+ * containing a line that reads `Scenario: …` or begins with `@` would otherwise
+ * be read here as a real scenario or a real tag — and every staleness verdict
+ * (`gherkin.stale`, `gherkin.missing`, `gherkin.orphaned`) plus the tag that
+ * decides whether an in-flight feature's file may be replaced rests on this
+ * parse. The payload would be quietly deciding what the suite promises.
+ */
+export function parseStampedFeature(text) {
+    const lines = text.split(/\r?\n/);
+    const m = STAMP_RE.exec(lines[0] ?? "");
+    if (!m)
+        return null;
+    const tags = [];
+    let featureName = null;
+    const scenarios = [];
+    let pending = null;
+    let inDocString = false;
+    for (const line of lines.slice(1)) {
+        // `"""` opens and closes; nothing between the two is structure. The emitter
+        // escapes an inner `"""` as `\"\"\"`, so an unescaped one here is always a
+        // real delimiter.
+        if (/^\s*"""/.test(line)) {
+            inDocString = !inDocString;
+            continue;
+        }
+        if (inDocString)
+            continue;
+        if (/^\s*@/.test(line)) {
+            for (const t of line.trim().split(/\s+/)) {
+                if (featureName === null) {
+                    if (t.startsWith("@"))
+                        tags.push(t.slice(1));
+                    continue;
+                }
+                const d = DIGEST_TAG_RE.exec(t);
+                if (d)
+                    pending = d[1];
+            }
+            continue;
+        }
+        const f = /^\s*Feature:\s*(.*)$/.exec(line);
+        if (f && featureName === null) {
+            featureName = f[1].trim();
+            continue;
+        }
+        const s = /^\s*Scenario(?: Outline)?:\s*(.*)$/.exec(line);
+        if (s) {
+            if (pending !== null)
+                scenarios.push({ name: s[1].trim(), digest: pending });
+            pending = null;
+            continue;
+        }
+        if (pending !== null && line.trim().length > 0)
+            pending = null;
+    }
+    return { version: m[1], tags, featureName, scenarios };
+}
+//# sourceMappingURL=read.js.map

package/dist/core/gherkin/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../src/core/gherkin/read.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAmBrD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,MAAM,SAAS,GAAsB,EAAE,CAAC;IACxC,IAAI,OAAO,GAAkB,IAAI,CAAC;IAClC,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,4EAA4E;QAC5E,2EAA2E;QAC3E,kBAAkB;QAClB,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,WAAW,GAAG,CAAC,WAAW,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,IAAI,WAAW;YAAE,SAAS;QAC1B,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzC,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;oBACzB,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;wBAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC7C,SAAS;gBACX,CAAC;gBACD,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAChC,IAAI,CAAC;oBAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;YACzB,CAAC;YACD,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YAC9B,WAAW,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,oCAAoC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,CAAC,EAAE,CAAC;YACN,IAAI,OAAO,KAAK,IAAI;gBAAE,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YAC9E,OAAO,GAAG,IAAI,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,GAAG,IAAI,CAAC;IACjE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AAC1D,CAAC","sourcesContent":["/**\n * A generated `.feature` file read back — the stamp, the tags, the scenarios.\n *\n * The parser is deliberately shallow and forgiving in one direction only: a file\n * without loam's stamp is not loam's to grade, and returns null rather than a\n * partially understood suite. Anything that IS stamped is loam's output, so the\n * digests inside it are trusted to be the ones `./emit.ts` wrote.\n */\nimport { DIGEST_TAG_RE, STAMP_RE } from \"./stamp.js\";\n\nexport interface StampedScenario {\n  name: string;\n  digest: string;\n}\n\n/** A generated file as the staleness checks see it. */\nexport interface StampedFeature {\n  /** The version in the stamp line — which loam wrote the file. */\n  version: string;\n  /** Tag tokens (without `@`) from tag lines above `Feature:`. */\n  tags: string[];\n  /** The `Feature:` line's text — the requirement name, by the mapping. */\n  featureName: string | null;\n  /** Scenarios carrying a `@loam-digest-…` tag. A hand-added scenario has none and is invisible here. */\n  scenarios: StampedScenario[];\n}\n\n/**\n * Parse a `.feature` file for its loam stamps. Null when line 1 is not the\n * stamp — an unstamped file is not loam's writing, and no staleness judgment\n * may be built on it. Tag lines above `Feature:` are the file's tags; a tag\n * line after it that carries a `@loam-digest-…` token binds that digest to the\n * immediately following `Scenario:` line (tag lines stack, as Gherkin's do,\n * without breaking the bond); any other non-blank line between them breaks it.\n *\n * DOCSTRING BODIES ARE SKIPPED WHOLE, and that is a correctness requirement\n * rather than tidiness. Since a step may carry a `\"\"\"` payload, a request body\n * containing a line that reads `Scenario: …` or begins with `@` would otherwise\n * be read here as a real scenario or a real tag — and every staleness verdict\n * (`gherkin.stale`, `gherkin.missing`, `gherkin.orphaned`) plus the tag that\n * decides whether an in-flight feature's file may be replaced rests on this\n * parse. The payload would be quietly deciding what the suite promises.\n */\nexport function parseStampedFeature(text: string): StampedFeature | null {\n  const lines = text.split(/\\r?\\n/);\n  const m = STAMP_RE.exec(lines[0] ?? \"\");\n  if (!m) return null;\n  const tags: string[] = [];\n  let featureName: string | null = null;\n  const scenarios: StampedScenario[] = [];\n  let pending: string | null = null;\n  let inDocString = false;\n  for (const line of lines.slice(1)) {\n    // `\"\"\"` opens and closes; nothing between the two is structure. The emitter\n    // escapes an inner `\"\"\"` as `\\\"\\\"\\\"`, so an unescaped one here is always a\n    // real delimiter.\n    if (/^\\s*\"\"\"/.test(line)) {\n      inDocString = !inDocString;\n      continue;\n    }\n    if (inDocString) continue;\n    if (/^\\s*@/.test(line)) {\n      for (const t of line.trim().split(/\\s+/)) {\n        if (featureName === null) {\n          if (t.startsWith(\"@\")) tags.push(t.slice(1));\n          continue;\n        }\n        const d = DIGEST_TAG_RE.exec(t);\n        if (d) pending = d[1]!;\n      }\n      continue;\n    }\n    const f = /^\\s*Feature:\\s*(.*)$/.exec(line);\n    if (f && featureName === null) {\n      featureName = f[1]!.trim();\n      continue;\n    }\n    const s = /^\\s*Scenario(?: Outline)?:\\s*(.*)$/.exec(line);\n    if (s) {\n      if (pending !== null) scenarios.push({ name: s[1]!.trim(), digest: pending });\n      pending = null;\n      continue;\n    }\n    if (pending !== null && line.trim().length > 0) pending = null;\n  }\n  return { version: m[1]!, tags, featureName, scenarios };\n}\n"]}