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

package/dist/core/gherkin/stale.js

@@ -0,0 +1,234 @@
+/**
+ * What `loam validate` reports about a generated suite: which scenarios moved
+ * out from under it, and which were never generated at all.
+ *
+ * Service-repo-scoped, and silent until a suite exists — a service that never
+ * ran `loam gherkin` has not opted into the axis and is not failing it. The
+ * whole comparison is by digest rather than by name, so a reworded scenario
+ * reads as stale rather than as missing plus new.
+ */
+import { existsSync, statSync } from "node:fs";
+import { readdir, readFile, realpath } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { parseRequirements } from "../document/parse.js";
+import { SPEC_AXES } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { listFeatures } from "../repo/repo.js";
+import { UnsafePathError } from "../kernel/path-safety.js";
+import { gherkinRoot, scenarioDigest } from "./stamp.js";
+import { axisLabel } from "./emit.js";
+import { parseStampedFeature } from "./read.js";
+/**
+ * The gherkin freshness chain, service-repo-scoped like `sources.*`: it needs
+ * the repo (the suite lives there), and it stays quiet until
+ * `<gherkinDir>/loam/` exists — a service that never generated has not opted
+ * in, and silence there is honest, not vacuous.
+ *
+ * The LIVING specs are the reference, with one carve-out. A stamped file
+ * tagged with a feature still in flight answers to that feature's delta, not
+ * to the living spec its requirements have not merged into yet — so it is
+ * skipped here (its regeneration is `loam gherkin <FEAT>`), and the moment the
+ * feature archives, its requirements ARE living requirements, digests
+ * unchanged, and the same file grades current with no rewrite. A tag naming
+ * no active feature (the feature was archived, or abandoned) gets no
+ * exemption: the living spec is all there is to answer to.
+ *
+ * Three warnings, one per way the suite and the spec can disagree, judged
+ * digest-first and by requirement name second:
+ *
+ * - `gherkin.missing` — a living scenario whose digest no stamped scenario of
+ *   its axis carries: the suite has no test for these words.
+ * - `gherkin.stale` — a stamped scenario whose digest matches no living
+ *   scenario while its file's requirement still exists: the spec moved under
+ *   the generated file. (A reworded scenario therefore reports both: the old
+ *   words are stale, the new words are missing — one regeneration clears
+ *   both.)
+ * - `gherkin.orphaned` — a whole file whose requirement no longer exists in
+ *   its axis's living spec; reported once per file, because every scenario in
+ *   it is moot together.
+ *
+ * Digests are content identity within one service and one axis, deliberately:
+ * two identically-worded scenarios of one service's one axis share one digest,
+ * so one stamped copy covers both — while the axes stay separate namespaces
+ * twice over (every comparison here is axis-scoped, and the recipe salts the
+ * arch axis), and the services stay separate because the recipe salts the
+ * service too. That last salt is why a stamped file copied out of another
+ * service's repository grades `gherkin.orphaned`/`gherkin.stale` here instead
+ * of quietly counting as this service's coverage.
+ *
+ * All warnings — `--strict` is the CI escalation — plus one `ok` confirmation
+ * (`gherkin.current`, the `sources.current` pattern) when a generated suite
+ * exists and nothing disagrees.
+ */
+export async function gherkinFindings(ctx) {
+    if (ctx.repoDir === undefined)
+        return [];
+    let root;
+    try {
+        root = gherkinRoot(ctx.repoDir, ctx.gherkinDir);
+    }
+    catch (err) {
+        if (!(err instanceof UnsafePathError))
+            throw err;
+        return [
+            {
+                severity: "error",
+                code: "gherkin.path-outside",
+                subject: ctx.service,
+                message: `The configured Gherkin output is unsafe: ${err.message}. It must stay inside the service repo.`,
+            },
+        ];
+    }
+    if (!existsSync(root))
+        return [];
+    const paths = await locateServicePaths(ctx.docsDir, ctx.service, ctx.fleet);
+    const axes = new Map();
+    for (const axis of SPEC_AXES) {
+        const label = axisLabel(axis);
+        const state = { file: axis.file, reqNames: new Set(), digests: new Set(), scenarios: [] };
+        const path = paths[axis.key];
+        if (existsSync(path)) {
+            const reqs = ctx.fleet === undefined
+                ? parseRequirements(await readFile(path, "utf8"))
+                : await ctx.fleet.readRequirements(path);
+            for (const r of reqs) {
+                if (r.kind === "REMOVED")
+                    continue;
+                state.reqNames.add(r.name);
+                for (const s of r.scenarios) {
+                    const digest = scenarioDigest(ctx.service, s.lines, label);
+                    state.digests.add(digest);
+                    state.scenarios.push({ req: r.name, name: s.name, digest });
+                }
+            }
+        }
+        axes.set(label, state);
+    }
+    // The stamped side. Every stamped digest counts toward coverage — an
+    // in-flight file whose scenario matches the living words IS a test for them.
+    // `Set<string>`, not the ids' own brand: this set answers membership
+    // questions for tags read out of .feature files — document text.
+    const active = new Set((await listFeatures(ctx.docsDir, {}, ctx.fleet)).map((f) => f.id));
+    const stampedDigests = { business: new Set(), arch: new Set() };
+    const parsed = [];
+    let stampedScenarios = 0;
+    for (const abs of await featureFilesUnder(root)) {
+        const file = parseStampedFeature(await readFile(abs, "utf8"));
+        if (file === null)
+            continue;
+        const axis = file.tags.includes("architecture") ? "arch" : "business";
+        for (const s of file.scenarios)
+            stampedDigests[axis].add(s.digest);
+        stampedScenarios += file.scenarios.length;
+        parsed.push({ rel: relative(ctx.repoDir, abs).split(sep).join("/"), axis, file });
+    }
+    const findings = [];
+    const regen = `\`loam gherkin --service ${ctx.service}\``;
+    for (const [axis, state] of axes) {
+        for (const sc of state.scenarios) {
+            if (stampedDigests[axis].has(sc.digest))
+                continue;
+            findings.push({
+                severity: "warn",
+                code: "gherkin.missing",
+                subject: ctx.service,
+                message: `${ctx.service}: scenario '${sc.name}' of requirement '${sc.req}' (${state.file}) has no generated .feature scenario — the suite has no test for these words; ${regen} regenerates it`,
+            });
+        }
+    }
+    for (const { rel, axis, file } of parsed) {
+        if (file.tags.some((t) => active.has(t)))
+            continue;
+        const state = axes.get(axis);
+        if (file.featureName === null || !state.reqNames.has(file.featureName)) {
+            findings.push({
+                severity: "warn",
+                code: "gherkin.orphaned",
+                subject: ctx.service,
+                message: `${ctx.service}: ${rel}: requirement '${file.featureName ?? "(unnamed)"}' no longer exists in the living ${state.file} — the whole file is orphaned; ${regen} removes it`,
+            });
+            continue;
+        }
+        for (const s of file.scenarios) {
+            if (state.digests.has(s.digest))
+                continue;
+            findings.push({
+                severity: "warn",
+                code: "gherkin.stale",
+                subject: ctx.service,
+                message: `${ctx.service}: ${rel}: scenario '${s.name}' matches no scenario in the living ${state.file} — the spec moved under the generated file; ${regen} regenerates it`,
+            });
+        }
+    }
+    if (findings.length === 0) {
+        findings.push({
+            severity: "ok",
+            code: "gherkin.current",
+            message: `${ctx.service}: generated gherkin current (${parsed.length} file(s), ${stampedScenarios} stamped scenario(s) agree with the living specs)`,
+        });
+    }
+    return findings;
+}
+/**
+ * Every `.feature` file at or under `root`, sorted by repo-relative path —
+ * enumeration is part of the output contract, so the order cannot depend on
+ * the filesystem's. Dot-entries are skipped, like every other walk in loam.
+ *
+ * Symlinks are FOLLOWED — repo.ts's `entryIs` and brief/brief.ts's `hasMarkdown` are
+ * the same rule for the same reason. A `Dirent` from `readdir(withFileTypes)`
+ * never follows one, so `isFile()` and `isDirectory()` are both false for a
+ * symlinked `.feature`: it was invisible to the orphan scan (`loam gherkin`
+ * left it behind forever) and invisible to the staleness scan (it graded as no
+ * coverage at all). Composing a suite out of links is legitimate, so they are
+ * followed rather than refused, and a dangling one is skipped exactly as an
+ * absent file is.
+ */
+export async function featureFilesUnder(root) {
+    const out = [];
+    // Following links means a cycle is now possible; every directory is entered
+    // once by its resolved path, so a loop terminates instead of hanging.
+    const entered = new Set();
+    const walk = async (dir) => {
+        if (!existsSync(dir))
+            return;
+        let resolved;
+        try {
+            resolved = await realpath(dir);
+        }
+        catch {
+            return;
+        }
+        if (entered.has(resolved))
+            return;
+        entered.add(resolved);
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith("."))
+                continue;
+            const abs = join(dir, entry.name);
+            const what = entryKind(abs, entry);
+            if (what === "dir")
+                await walk(abs);
+            else if (what === "file" && entry.name.endsWith(".feature"))
+                out.push(abs);
+        }
+    };
+    await walk(root);
+    return out.sort((a, b) => {
+        const ra = a.split(sep).join("/");
+        const rb = b.split(sep).join("/");
+        return ra < rb ? -1 : ra > rb ? 1 : 0;
+    });
+}
+/** What an entry IS, resolving a symlink to find out. Nothing when it dangles. */
+function entryKind(abs, e) {
+    if (!e.isSymbolicLink())
+        return e.isDirectory() ? "dir" : e.isFile() ? "file" : null;
+    try {
+        const s = statSync(abs);
+        return s.isDirectory() ? "dir" : s.isFile() ? "file" : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=stale.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stale.js","sourceRoot":"","sources":["../../../src/core/gherkin/stale.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `loam validate` reports about a generated suite: which scenarios moved\n * out from under it, and which were never generated at all.\n *\n * Service-repo-scoped, and silent until a suite exists — a service that never\n * ran `loam gherkin` has not opted into the axis and is not failing it. The\n * whole comparison is by digest rather than by name, so a reworded scenario\n * reads as stale rather than as missing plus new.\n */\nimport { existsSync, statSync, type Dirent } from \"node:fs\";\nimport { readdir, readFile, realpath } from \"node:fs/promises\";\nimport { join, relative, sep } from \"node:path\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { SPEC_AXES } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { UnsafePathError } from \"../kernel/path-safety.js\";\nimport { gherkinRoot, scenarioDigest } from \"./stamp.js\";\nimport { axisLabel } from \"./emit.js\";\nimport { parseStampedFeature, type StampedFeature } from \"./read.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * The gherkin freshness chain, service-repo-scoped like `sources.*`: it needs\n * the repo (the suite lives there), and it stays quiet until\n * `<gherkinDir>/loam/` exists — a service that never generated has not opted\n * in, and silence there is honest, not vacuous.\n *\n * The LIVING specs are the reference, with one carve-out. A stamped file\n * tagged with a feature still in flight answers to that feature's delta, not\n * to the living spec its requirements have not merged into yet — so it is\n * skipped here (its regeneration is `loam gherkin <FEAT>`), and the moment the\n * feature archives, its requirements ARE living requirements, digests\n * unchanged, and the same file grades current with no rewrite. A tag naming\n * no active feature (the feature was archived, or abandoned) gets no\n * exemption: the living spec is all there is to answer to.\n *\n * Three warnings, one per way the suite and the spec can disagree, judged\n * digest-first and by requirement name second:\n *\n * - `gherkin.missing` — a living scenario whose digest no stamped scenario of\n *   its axis carries: the suite has no test for these words.\n * - `gherkin.stale` — a stamped scenario whose digest matches no living\n *   scenario while its file's requirement still exists: the spec moved under\n *   the generated file. (A reworded scenario therefore reports both: the old\n *   words are stale, the new words are missing — one regeneration clears\n *   both.)\n * - `gherkin.orphaned` — a whole file whose requirement no longer exists in\n *   its axis's living spec; reported once per file, because every scenario in\n *   it is moot together.\n *\n * Digests are content identity within one service and one axis, deliberately:\n * two identically-worded scenarios of one service's one axis share one digest,\n * so one stamped copy covers both — while the axes stay separate namespaces\n * twice over (every comparison here is axis-scoped, and the recipe salts the\n * arch axis), and the services stay separate because the recipe salts the\n * service too. That last salt is why a stamped file copied out of another\n * service's repository grades `gherkin.orphaned`/`gherkin.stale` here instead\n * of quietly counting as this service's coverage.\n *\n * All warnings — `--strict` is the CI escalation — plus one `ok` confirmation\n * (`gherkin.current`, the `sources.current` pattern) when a generated suite\n * exists and nothing disagrees.\n */\nexport async function gherkinFindings(ctx: {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service repo, when loam is standing in it. Undefined disables the chain, like sources.*. */\n  repoDir?: string;\n  gherkinDir?: string;\n  fleet?: FleetContext;\n}): Promise<Finding[]> {\n  if (ctx.repoDir === undefined) return [];\n  let root: string;\n  try {\n    root = gherkinRoot(ctx.repoDir, ctx.gherkinDir);\n  } catch (err) {\n    if (!(err instanceof UnsafePathError)) throw err;\n    return [\n      {\n        severity: \"error\",\n        code: \"gherkin.path-outside\",\n        subject: ctx.service,\n        message: `The configured Gherkin output is unsafe: ${err.message}. It must stay inside the service repo.`,\n      },\n    ];\n  }\n  if (!existsSync(root)) return [];\n\n  // The living reference, per axis: requirement names, and scenario digests.\n  interface AxisState {\n    file: string;\n    reqNames: Set<string>;\n    digests: Set<string>;\n    scenarios: Array<{ req: string; name: string; digest: string }>;\n  }\n  const paths = await locateServicePaths(ctx.docsDir, ctx.service, ctx.fleet);\n  const axes = new Map<\"business\" | \"arch\", AxisState>();\n  for (const axis of SPEC_AXES) {\n    const label = axisLabel(axis);\n    const state: AxisState = { file: axis.file, reqNames: new Set(), digests: new Set(), scenarios: [] };\n    const path = paths[axis.key];\n    if (existsSync(path)) {\n      const reqs = ctx.fleet === undefined\n        ? parseRequirements(await readFile(path, \"utf8\"))\n        : await ctx.fleet.readRequirements(path);\n      for (const r of reqs) {\n        if (r.kind === \"REMOVED\") continue;\n        state.reqNames.add(r.name);\n        for (const s of r.scenarios) {\n          const digest = scenarioDigest(ctx.service, s.lines, label);\n          state.digests.add(digest);\n          state.scenarios.push({ req: r.name, name: s.name, digest });\n        }\n      }\n    }\n    axes.set(label, state);\n  }\n\n  // The stamped side. Every stamped digest counts toward coverage — an\n  // in-flight file whose scenario matches the living words IS a test for them.\n  // `Set<string>`, not the ids' own brand: this set answers membership\n  // questions for tags read out of .feature files — document text.\n  const active = new Set<string>((await listFeatures(ctx.docsDir, {}, ctx.fleet)).map((f) => f.id));\n  const stampedDigests = { business: new Set<string>(), arch: new Set<string>() };\n  const parsed: Array<{ rel: string; axis: \"business\" | \"arch\"; file: StampedFeature }> = [];\n  let stampedScenarios = 0;\n  for (const abs of await featureFilesUnder(root)) {\n    const file = parseStampedFeature(await readFile(abs, \"utf8\"));\n    if (file === null) continue;\n    const axis = file.tags.includes(\"architecture\") ? \"arch\" : \"business\";\n    for (const s of file.scenarios) stampedDigests[axis].add(s.digest);\n    stampedScenarios += file.scenarios.length;\n    parsed.push({ rel: relative(ctx.repoDir, abs).split(sep).join(\"/\"), axis, file });\n  }\n\n  const findings: Finding[] = [];\n  const regen = `\\`loam gherkin --service ${ctx.service}\\``;\n  for (const [axis, state] of axes) {\n    for (const sc of state.scenarios) {\n      if (stampedDigests[axis].has(sc.digest)) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.missing\",\n        subject: ctx.service,\n        message: `${ctx.service}: scenario '${sc.name}' of requirement '${sc.req}' (${state.file}) has no generated .feature scenario — the suite has no test for these words; ${regen} regenerates it`,\n      });\n    }\n  }\n  for (const { rel, axis, file } of parsed) {\n    if (file.tags.some((t) => active.has(t))) continue;\n    const state = axes.get(axis)!;\n    if (file.featureName === null || !state.reqNames.has(file.featureName)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.orphaned\",\n        subject: ctx.service,\n        message: `${ctx.service}: ${rel}: requirement '${file.featureName ?? \"(unnamed)\"}' no longer exists in the living ${state.file} — the whole file is orphaned; ${regen} removes it`,\n      });\n      continue;\n    }\n    for (const s of file.scenarios) {\n      if (state.digests.has(s.digest)) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.stale\",\n        subject: ctx.service,\n        message: `${ctx.service}: ${rel}: scenario '${s.name}' matches no scenario in the living ${state.file} — the spec moved under the generated file; ${regen} regenerates it`,\n      });\n    }\n  }\n  if (findings.length === 0) {\n    findings.push({\n      severity: \"ok\",\n      code: \"gherkin.current\",\n      message: `${ctx.service}: generated gherkin current (${parsed.length} file(s), ${stampedScenarios} stamped scenario(s) agree with the living specs)`,\n    });\n  }\n  return findings;\n}\n\n/**\n * Every `.feature` file at or under `root`, sorted by repo-relative path —\n * enumeration is part of the output contract, so the order cannot depend on\n * the filesystem's. Dot-entries are skipped, like every other walk in loam.\n *\n * Symlinks are FOLLOWED — repo.ts's `entryIs` and brief/brief.ts's `hasMarkdown` are\n * the same rule for the same reason. A `Dirent` from `readdir(withFileTypes)`\n * never follows one, so `isFile()` and `isDirectory()` are both false for a\n * symlinked `.feature`: it was invisible to the orphan scan (`loam gherkin`\n * left it behind forever) and invisible to the staleness scan (it graded as no\n * coverage at all). Composing a suite out of links is legitimate, so they are\n * followed rather than refused, and a dangling one is skipped exactly as an\n * absent file is.\n */\nexport async function featureFilesUnder(root: string): Promise<string[]> {\n  const out: string[] = [];\n  // Following links means a cycle is now possible; every directory is entered\n  // once by its resolved path, so a loop terminates instead of hanging.\n  const entered = new Set<string>();\n  const walk = async (dir: string): Promise<void> => {\n    if (!existsSync(dir)) return;\n    let resolved: string;\n    try {\n      resolved = await realpath(dir);\n    } catch {\n      return;\n    }\n    if (entered.has(resolved)) return;\n    entered.add(resolved);\n    for (const entry of await readdir(dir, { withFileTypes: true })) {\n      if (entry.name.startsWith(\".\")) continue;\n      const abs = join(dir, entry.name);\n      const what = entryKind(abs, entry);\n      if (what === \"dir\") await walk(abs);\n      else if (what === \"file\" && entry.name.endsWith(\".feature\")) out.push(abs);\n    }\n  };\n  await walk(root);\n  return out.sort((a, b) => {\n    const ra = a.split(sep).join(\"/\");\n    const rb = b.split(sep).join(\"/\");\n    return ra < rb ? -1 : ra > rb ? 1 : 0;\n  });\n}\n\n/** What an entry IS, resolving a symlink to find out. Nothing when it dangles. */\nfunction entryKind(abs: string, e: Dirent): \"dir\" | \"file\" | null {\n  if (!e.isSymbolicLink()) return e.isDirectory() ? \"dir\" : e.isFile() ? \"file\" : null;\n  try {\n    const s = statSync(abs);\n    return s.isDirectory() ? \"dir\" : s.isFile() ? \"file\" : null;\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/core/gherkin/stamp.js

@@ -0,0 +1,77 @@
+/**
+ * The Gherkin emission: spec scenarios become real `.feature` files.
+ *
+ * Scenarios have been "the source for tests" since SCHEMA.md's first draft, but
+ * until now they only left the docs repo as projected markdown — prose a coding
+ * agent could paraphrase into something easier to pass. The emission closes the
+ * gap mechanically: one `.feature` file per requirement, steps taken from the
+ * scenario's own bullet lines, and a digest TAG (`@loam-digest-<16hex>`) on
+ * every scenario using the SAME body-hash recipe `loam verify` folds into its
+ * claim ids (`./digest.ts`'s scenarioBodyHash — salted by the owning service and
+ * by the spec axis, so a stamp belongs to one suite and one axis) — so the
+ * test skeleton, the claim and the spec can never quietly disagree about what
+ * a scenario says, and no two repositories can answer each other's. A tag
+ * rather than a comment because tags are what cucumber's JSON report carries
+ * per scenario: the stamp rides through the runner untouched, which is what
+ * lets `loam verify --results` match a report scenario back to its claim.
+ *
+ * The files land in the SERVICE repo — the docs repo states the questions, the
+ * tests live with the code — under `<gherkinDir>/loam/`. That `loam/`
+ * subdirectory is loam's own derived space: regeneration rewrites its scope and
+ * removes its orphans, and loam never writes or deletes a byte outside it.
+ * Everything here is deterministic on purpose: the same specs yield the same
+ * bytes, which is what lets `loam validate` grade staleness by digest instead
+ * of by guesswork.
+ */
+import { join } from "node:path";
+import { scenarioBodyHash } from "./digest.js";
+import { resolveInside } from "../kernel/path-safety.js";
+/** Where Gherkin lives in a service repo when loam.json does not say. */
+const DEFAULT_GHERKIN_DIR = "features";
+/** The subdirectory loam owns outright. Everything loam writes stays inside it. */
+const GHERKIN_SUBDIR = "loam";
+/** How much of the scenario body hash goes into a `@loam-digest-…` tag. */
+export const GHERKIN_DIGEST_LENGTH = 16;
+/** The one directory `loam gherkin` may touch: `<repo>/<gherkinDir>/loam/`. */
+export function gherkinRoot(repoDir, gherkinDir) {
+    return resolveInside(repoDir, join(gherkinDir ?? DEFAULT_GHERKIN_DIR, GHERKIN_SUBDIR), "gherkin output directory");
+}
+/**
+ * The digest stamped onto every generated scenario: verify's scenario body
+ * hash, at the sources-digest length. Content identity WITHIN one service and
+ * one axis, not provenance — two identically-worded scenarios of one service's
+ * one axis share a digest, and that is the point: the stamp answers "does this
+ * suite still contain a test for THESE words".
+ *
+ * Both salts ride in the hash (see `scenarioBodyHash`), so the namespaces stay
+ * separate all the way into a cucumber report: a business run can never answer
+ * for an arch scenario, and one service's green run can never answer another
+ * service's claim just because the two specs spell the sentence the same way.
+ * `service` is required and never defaulted — a stamp that forgot it would be
+ * a tag no claim matches, and the fleet bug it exists to close would come back
+ * silently.
+ */
+export function scenarioDigest(service, lines, axis = "business") {
+    return scenarioBodyHash(service, lines, axis).slice(0, GHERKIN_DIGEST_LENGTH);
+}
+/** The digest as the tag on the line above each `Scenario:`. */
+export function scenarioDigestTag(digest) {
+    return `@loam-digest-${digest}`;
+}
+/**
+ * A tag token carrying a scenario digest — in a generated file, or in a
+ * cucumber JSON report. The leading `@` is optional because some runners
+ * (behave) strip it from the tags they report.
+ */
+export const DIGEST_TAG_RE = /^@?loam-digest-([0-9a-f]{16})$/;
+/**
+ * Line 1 of every generated file — the AGENTS.md stamp pattern, in Gherkin
+ * comment syntax. The version records which loam wrote the file; the rest is
+ * the ownership rule in the reader's face, because `loam/` files are rewritten
+ * wholesale on regeneration and a hand edit would be silently destroyed.
+ */
+export function gherkinStampLine(version) {
+    return `# generated by loam v${version} — \`loam gherkin\`; do not hand-edit, regenerate instead`;
+}
+export const STAMP_RE = /^#\s*generated by loam v(\S+)/;
+//# sourceMappingURL=stamp.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stamp.js","sourceRoot":"","sources":["../../../src/core/gherkin/stamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAqB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,yEAAyE;AACzE,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAEvC,mFAAmF;AACnF,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,2EAA2E;AAC3E,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,+EAA+E;AAC/E,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,UAAmB;IAC9D,OAAO,aAAa,CAClB,OAAO,EACP,IAAI,CAAC,UAAU,IAAI,mBAAmB,EAAE,cAAc,CAAC,EACvD,0BAA0B,CAC3B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,KAAe,EACf,IAAI,GAAiB,UAAU;IAE/B,OAAO,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;AAChF,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,OAAO,gBAAgB,MAAM,EAAE,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,gCAAgC,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,wBAAwB,OAAO,2DAA2D,CAAC;AACpG,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,+BAA+B,CAAC","sourcesContent":["/**\n * The Gherkin emission: spec scenarios become real `.feature` files.\n *\n * Scenarios have been \"the source for tests\" since SCHEMA.md's first draft, but\n * until now they only left the docs repo as projected markdown — prose a coding\n * agent could paraphrase into something easier to pass. The emission closes the\n * gap mechanically: one `.feature` file per requirement, steps taken from the\n * scenario's own bullet lines, and a digest TAG (`@loam-digest-<16hex>`) on\n * every scenario using the SAME body-hash recipe `loam verify` folds into its\n * claim ids (`./digest.ts`'s scenarioBodyHash — salted by the owning service and\n * by the spec axis, so a stamp belongs to one suite and one axis) — so the\n * test skeleton, the claim and the spec can never quietly disagree about what\n * a scenario says, and no two repositories can answer each other's. A tag\n * rather than a comment because tags are what cucumber's JSON report carries\n * per scenario: the stamp rides through the runner untouched, which is what\n * lets `loam verify --results` match a report scenario back to its claim.\n *\n * The files land in the SERVICE repo — the docs repo states the questions, the\n * tests live with the code — under `<gherkinDir>/loam/`. That `loam/`\n * subdirectory is loam's own derived space: regeneration rewrites its scope and\n * removes its orphans, and loam never writes or deletes a byte outside it.\n * Everything here is deterministic on purpose: the same specs yield the same\n * bytes, which is what lets `loam validate` grade staleness by digest instead\n * of by guesswork.\n */\nimport { join } from \"node:path\";\nimport { scenarioBodyHash, type ScenarioAxis } from \"./digest.js\";\nimport { resolveInside } from \"../kernel/path-safety.js\";\n\n/** Where Gherkin lives in a service repo when loam.json does not say. */\nconst DEFAULT_GHERKIN_DIR = \"features\";\n\n/** The subdirectory loam owns outright. Everything loam writes stays inside it. */\nconst GHERKIN_SUBDIR = \"loam\";\n\n/** How much of the scenario body hash goes into a `@loam-digest-…` tag. */\nexport const GHERKIN_DIGEST_LENGTH = 16;\n\n/** The one directory `loam gherkin` may touch: `<repo>/<gherkinDir>/loam/`. */\nexport function gherkinRoot(repoDir: string, gherkinDir?: string): string {\n  return resolveInside(\n    repoDir,\n    join(gherkinDir ?? DEFAULT_GHERKIN_DIR, GHERKIN_SUBDIR),\n    \"gherkin output directory\",\n  );\n}\n\n/**\n * The digest stamped onto every generated scenario: verify's scenario body\n * hash, at the sources-digest length. Content identity WITHIN one service and\n * one axis, not provenance — two identically-worded scenarios of one service's\n * one axis share a digest, and that is the point: the stamp answers \"does this\n * suite still contain a test for THESE words\".\n *\n * Both salts ride in the hash (see `scenarioBodyHash`), so the namespaces stay\n * separate all the way into a cucumber report: a business run can never answer\n * for an arch scenario, and one service's green run can never answer another\n * service's claim just because the two specs spell the sentence the same way.\n * `service` is required and never defaulted — a stamp that forgot it would be\n * a tag no claim matches, and the fleet bug it exists to close would come back\n * silently.\n */\nexport function scenarioDigest(\n  service: string,\n  lines: string[],\n  axis: ScenarioAxis = \"business\",\n): string {\n  return scenarioBodyHash(service, lines, axis).slice(0, GHERKIN_DIGEST_LENGTH);\n}\n\n/** The digest as the tag on the line above each `Scenario:`. */\nexport function scenarioDigestTag(digest: string): string {\n  return `@loam-digest-${digest}`;\n}\n\n/**\n * A tag token carrying a scenario digest — in a generated file, or in a\n * cucumber JSON report. The leading `@` is optional because some runners\n * (behave) strip it from the tags they report.\n */\nexport const DIGEST_TAG_RE = /^@?loam-digest-([0-9a-f]{16})$/;\n\n/**\n * Line 1 of every generated file — the AGENTS.md stamp pattern, in Gherkin\n * comment syntax. The version records which loam wrote the file; the rest is\n * the ownership rule in the reader's face, because `loam/` files are rewritten\n * wholesale on regeneration and a hand edit would be silently destroyed.\n */\nexport function gherkinStampLine(version: string): string {\n  return `# generated by loam v${version} — \\`loam gherkin\\`; do not hand-edit, regenerate instead`;\n}\n\nexport const STAMP_RE = /^#\\s*generated by loam v(\\S+)/;\n\n"]}

package/dist/core/gherkin/steps/catalogue.js

@@ -0,0 +1,154 @@
+/**
+ * The step catalogue: which phrases somebody has DECIDED the suite defines.
+ *
+ * ## The decision this file records, because it was the open question
+ *
+ * `./inventory.ts` answers how many definitions a suite needs. It stops there on
+ * purpose — no file, no finding, no stable code — and the gap it leaves is the
+ * next ARTIFACT, not the next warning: a team reads the report, writes the glue
+ * by hand, and nothing anywhere records which phrases now have definitions, so
+ * the report is recomputed from scratch every time instead of diffed against a
+ * decision somebody made.
+ *
+ * The catalogue is **AUTHORED**, not emitted, and it lives in the DOCS repo at
+ * `services/<svc>/steps.yaml`. Four things decided it:
+ *
+ *  - It is a DECISION, not an observation. loam does not read code and must
+ *    never present a derived thing as truth (the non-goal is written down); what
+ *    a team can say is "these are the phrases we have agreed to define", and
+ *    that sentence is an authored document by construction. An emitted
+ *    catalogue would have to be derived from a step registry loam cannot read.
+ *  - `loam steps` NEEDS NO SERVICE REPO to stand in — that is its own stated
+ *    design, and it reads the living specs rather than the emitted `.feature`
+ *    files precisely so it answers the same way in a repo that has never run
+ *    `loam gherkin`. A catalogue in the service repo would make the comparison
+ *    require one, which is a different command.
+ *  - The shape rule the glossary and capability trees already settled: an entry
+ *    with prose gets a file, an entry WITHOUT prose stays a line in YAML. A
+ *    catalogue entry is a phrase and nothing else, so it is a line in YAML — the
+ *    same side of that rule `architecture/capabilities.yaml` and
+ *    `permissions.yaml` sit on.
+ *  - Nothing generated may land inside `<gherkinDir>/loam/`, which `loam
+ *    gherkin` owns and overwrites wholesale. Living in the docs repo satisfies
+ *    that by construction rather than by a rule somebody has to remember.
+ *
+ * SERVICE-SCOPED, beside `health.yaml`, because a step registry belongs to one
+ * suite and a suite belongs to one service. A fleet-level catalogue would claim
+ * one registry across services that do not share a test runner.
+ *
+ * ## What it does NOT do, and this is the other half of the decision
+ *
+ * **It gains no stable code, and `loam validate` never reads it.** A phrase
+ * written but not catalogued is a work-list row, not a breach: writing a spec
+ * ahead of the glue is the normal order, and a check that fires on it is the
+ * kind a fleet turns off — at which point the real findings beside it are turned
+ * off too. The near-duplicate groups stay a report for the same reason. So this
+ * axis costs one document kind and zero codes, and everything it produces is
+ * columns in `loam steps`.
+ *
+ * **It claims nothing about whether the glue exists.** A catalogued phrase is a
+ * phrase somebody said they would define; loam cannot see a step registry and
+ * does not pretend to. The two columns are named for what they actually mean —
+ * written-not-catalogued and catalogued-not-written — and neither says "missing
+ * definition".
+ *
+ * ## The grammar
+ *
+ * ```yaml
+ * steps:
+ *   - a payment of 100.00
+ *   - Given it is split 60/40
+ * ```
+ *
+ * A list of step TEXTS, not of keys. The key is loam's own spelling — `{n}`,
+ * `{s}`, `{p}` collapse, keyword stripped (`./phrase.ts`) — and asking an author
+ * to write it would make an internal normalisation a hand-typed contract, where
+ * one wrong brace silently catalogues nothing. So an entry is written the way a
+ * step is written, with or without its keyword, and loam keys it the same way it
+ * keys the written steps it is being compared against. Two entries that collapse
+ * onto one key are reported as such rather than merged: that is the author
+ * cataloguing one definition twice, which is exactly what the near-duplicate
+ * report exists to surface.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { isRecord } from "../../kernel/records.js";
+import { compareIds } from "../../repo/entries.js";
+import { phraseOf } from "./phrase.js";
+import {} from "./inventory.js";
+const ABSENT = { present: false, entries: [] };
+/**
+ * Read one service's catalogue.
+ *
+ * A missing file is silence, not an error: the axis's opt-in is the file's
+ * existence, exactly as `capabilities/`'s is a directory's. Anything present and
+ * unparseable is `unreadable` with the reason — never an empty catalogue, which
+ * would report every written phrase as uncatalogued and read as a work-list
+ * somebody has to do.
+ */
+export async function readStepCatalogue(path) {
+    if (!existsSync(path))
+        return ABSENT;
+    let doc;
+    try {
+        doc = parseYaml(await readFile(path, "utf8"));
+    }
+    catch (e) {
+        return { present: true, entries: [], unreadable: e instanceof Error ? e.message : String(e) };
+    }
+    if (doc === null || doc === undefined)
+        return { present: true, entries: [] };
+    if (!isRecord(doc))
+        return { present: true, entries: [], unreadable: "the document is not a mapping" };
+    const block = doc["steps"];
+    if (block === undefined)
+        return { present: true, entries: [] };
+    if (!Array.isArray(block)) {
+        return { present: true, entries: [], unreadable: "`steps` is not a list of step texts" };
+    }
+    const entries = [];
+    for (const item of block) {
+        // A non-string entry refuses the whole file rather than being skipped. A
+        // skipped entry is a phrase silently absent from the catalogue, which prints
+        // as "written but not catalogued" — a work-list row invented by a shape
+        // error, which is the wrong answer this fails closed to avoid.
+        if (typeof item !== "string") {
+            return { present: true, entries: [], unreadable: "every `steps` entry must be a step text (a string)" };
+        }
+        entries.push({ text: item, key: phraseOf(item).key });
+    }
+    return { present: true, entries };
+}
+/**
+ * Written phrases against catalogued ones.
+ *
+ * ORDER IS THE INVENTORY'S for `uncatalogued` — `inv.phrases` is already sorted
+ * count-descending then key-ascending, so the work-list comes out with the
+ * phrase that pays back most first, and stays diffable. `unwritten` and
+ * `duplicated` have no count to sort on and are sorted by key.
+ *
+ * The catalogue's own `present`/`unreadable` state is NOT consulted here: this
+ * is the comparison, and whether it was worth making is the caller's question.
+ * Handing it an unreadable catalogue would produce a full `uncatalogued` list
+ * that reads exactly like a real work-list, which is why the caller checks first.
+ */
+export function compareToCatalogue(inv, catalogue) {
+    const catalogued = new Set(catalogue.entries.map((e) => e.key));
+    const written = new Set(inv.phrases.map((p) => p.key));
+    const bySpelling = new Map();
+    for (const entry of catalogue.entries) {
+        const texts = bySpelling.get(entry.key) ?? [];
+        texts.push(entry.text);
+        bySpelling.set(entry.key, texts);
+    }
+    return {
+        uncatalogued: inv.phrases.filter((p) => !catalogued.has(p.key)).map((p) => p.key),
+        unwritten: [...catalogued].filter((key) => !written.has(key)).sort(compareIds),
+        duplicated: [...bySpelling]
+            .filter(([, texts]) => texts.length > 1)
+            .map(([key, texts]) => ({ key, texts }))
+            .sort((a, b) => compareIds(a.key, b.key)),
+    };
+}
+//# sourceMappingURL=catalogue.js.map

package/dist/core/gherkin/steps/catalogue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue.js","sourceRoot":"","sources":["../../../../src/core/gherkin/steps/catalogue.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The step catalogue: which phrases somebody has DECIDED the suite defines.\n *\n * ## The decision this file records, because it was the open question\n *\n * `./inventory.ts` answers how many definitions a suite needs. It stops there on\n * purpose — no file, no finding, no stable code — and the gap it leaves is the\n * next ARTIFACT, not the next warning: a team reads the report, writes the glue\n * by hand, and nothing anywhere records which phrases now have definitions, so\n * the report is recomputed from scratch every time instead of diffed against a\n * decision somebody made.\n *\n * The catalogue is **AUTHORED**, not emitted, and it lives in the DOCS repo at\n * `services/<svc>/steps.yaml`. Four things decided it:\n *\n *  - It is a DECISION, not an observation. loam does not read code and must\n *    never present a derived thing as truth (the non-goal is written down); what\n *    a team can say is \"these are the phrases we have agreed to define\", and\n *    that sentence is an authored document by construction. An emitted\n *    catalogue would have to be derived from a step registry loam cannot read.\n *  - `loam steps` NEEDS NO SERVICE REPO to stand in — that is its own stated\n *    design, and it reads the living specs rather than the emitted `.feature`\n *    files precisely so it answers the same way in a repo that has never run\n *    `loam gherkin`. A catalogue in the service repo would make the comparison\n *    require one, which is a different command.\n *  - The shape rule the glossary and capability trees already settled: an entry\n *    with prose gets a file, an entry WITHOUT prose stays a line in YAML. A\n *    catalogue entry is a phrase and nothing else, so it is a line in YAML — the\n *    same side of that rule `architecture/capabilities.yaml` and\n *    `permissions.yaml` sit on.\n *  - Nothing generated may land inside `<gherkinDir>/loam/`, which `loam\n *    gherkin` owns and overwrites wholesale. Living in the docs repo satisfies\n *    that by construction rather than by a rule somebody has to remember.\n *\n * SERVICE-SCOPED, beside `health.yaml`, because a step registry belongs to one\n * suite and a suite belongs to one service. A fleet-level catalogue would claim\n * one registry across services that do not share a test runner.\n *\n * ## What it does NOT do, and this is the other half of the decision\n *\n * **It gains no stable code, and `loam validate` never reads it.** A phrase\n * written but not catalogued is a work-list row, not a breach: writing a spec\n * ahead of the glue is the normal order, and a check that fires on it is the\n * kind a fleet turns off — at which point the real findings beside it are turned\n * off too. The near-duplicate groups stay a report for the same reason. So this\n * axis costs one document kind and zero codes, and everything it produces is\n * columns in `loam steps`.\n *\n * **It claims nothing about whether the glue exists.** A catalogued phrase is a\n * phrase somebody said they would define; loam cannot see a step registry and\n * does not pretend to. The two columns are named for what they actually mean —\n * written-not-catalogued and catalogued-not-written — and neither says \"missing\n * definition\".\n *\n * ## The grammar\n *\n * ```yaml\n * steps:\n *   - a payment of 100.00\n *   - Given it is split 60/40\n * ```\n *\n * A list of step TEXTS, not of keys. The key is loam's own spelling — `{n}`,\n * `{s}`, `{p}` collapse, keyword stripped (`./phrase.ts`) — and asking an author\n * to write it would make an internal normalisation a hand-typed contract, where\n * one wrong brace silently catalogues nothing. So an entry is written the way a\n * step is written, with or without its keyword, and loam keys it the same way it\n * keys the written steps it is being compared against. Two entries that collapse\n * onto one key are reported as such rather than merged: that is the author\n * cataloguing one definition twice, which is exactly what the near-duplicate\n * report exists to surface.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse as parseYaml } from \"yaml\";\nimport { isRecord } from \"../../kernel/records.js\";\nimport { compareIds } from \"../../repo/entries.js\";\nimport { phraseOf } from \"./phrase.js\";\nimport { type StepInventory } from \"./inventory.js\";\n\n/** One catalogued phrase: what the author wrote, and the key loam derived from it. */\nexport interface CatalogueEntry {\n  /** The entry exactly as `steps.yaml` spells it. */\n  text: string;\n  /** The normalized phrase — the same key `./inventory.ts` gives a written step. */\n  key: string;\n}\n\n/** What `services/<svc>/steps.yaml` says, or the honest refusal to say. */\nexport interface StepCatalogue {\n  /** False when the service has no `steps.yaml` — which is every service until one opts in. */\n  present: boolean;\n  /**\n   * Why the file could not be read, when it exists and does not parse as the\n   * grammar above. A REASON rather than a boolean, because the report prints it:\n   * \"could not look\" is only useful if it says what stopped it.\n   */\n  unreadable?: string;\n  /** The catalogued entries, in the order the file lists them. */\n  entries: CatalogueEntry[];\n}\n\nconst ABSENT: StepCatalogue = { present: false, entries: [] };\n\n/**\n * Read one service's catalogue.\n *\n * A missing file is silence, not an error: the axis's opt-in is the file's\n * existence, exactly as `capabilities/`'s is a directory's. Anything present and\n * unparseable is `unreadable` with the reason — never an empty catalogue, which\n * would report every written phrase as uncatalogued and read as a work-list\n * somebody has to do.\n */\nexport async function readStepCatalogue(path: string): Promise<StepCatalogue> {\n  if (!existsSync(path)) return ABSENT;\n  let doc: unknown;\n  try {\n    doc = parseYaml(await readFile(path, \"utf8\"));\n  } catch (e) {\n    return { present: true, entries: [], unreadable: e instanceof Error ? e.message : String(e) };\n  }\n  if (doc === null || doc === undefined) return { present: true, entries: [] };\n  if (!isRecord(doc)) return { present: true, entries: [], unreadable: \"the document is not a mapping\" };\n  const block = doc[\"steps\"];\n  if (block === undefined) return { present: true, entries: [] };\n  if (!Array.isArray(block)) {\n    return { present: true, entries: [], unreadable: \"`steps` is not a list of step texts\" };\n  }\n  const entries: CatalogueEntry[] = [];\n  for (const item of block) {\n    // A non-string entry refuses the whole file rather than being skipped. A\n    // skipped entry is a phrase silently absent from the catalogue, which prints\n    // as \"written but not catalogued\" — a work-list row invented by a shape\n    // error, which is the wrong answer this fails closed to avoid.\n    if (typeof item !== \"string\") {\n      return { present: true, entries: [], unreadable: \"every `steps` entry must be a step text (a string)\" };\n    }\n    entries.push({ text: item, key: phraseOf(item).key });\n  }\n  return { present: true, entries };\n}\n\n/** The two lists a report needs, plus the entries an author catalogued twice. */\nexport interface CatalogueComparison {\n  /** Written phrase keys the catalogue does not list, most-used first — the work-list. */\n  uncatalogued: string[];\n  /** Catalogued keys nothing in the living specs writes — a definition with nothing to match. */\n  unwritten: string[];\n  /** Keys two or more catalogue entries collapse onto, with every spelling. */\n  duplicated: Array<{ key: string; texts: string[] }>;\n}\n\n/**\n * Written phrases against catalogued ones.\n *\n * ORDER IS THE INVENTORY'S for `uncatalogued` — `inv.phrases` is already sorted\n * count-descending then key-ascending, so the work-list comes out with the\n * phrase that pays back most first, and stays diffable. `unwritten` and\n * `duplicated` have no count to sort on and are sorted by key.\n *\n * The catalogue's own `present`/`unreadable` state is NOT consulted here: this\n * is the comparison, and whether it was worth making is the caller's question.\n * Handing it an unreadable catalogue would produce a full `uncatalogued` list\n * that reads exactly like a real work-list, which is why the caller checks first.\n */\nexport function compareToCatalogue(inv: StepInventory, catalogue: StepCatalogue): CatalogueComparison {\n  const catalogued = new Set(catalogue.entries.map((e) => e.key));\n  const written = new Set(inv.phrases.map((p) => p.key));\n  const bySpelling = new Map<string, string[]>();\n  for (const entry of catalogue.entries) {\n    const texts = bySpelling.get(entry.key) ?? [];\n    texts.push(entry.text);\n    bySpelling.set(entry.key, texts);\n  }\n  return {\n    uncatalogued: inv.phrases.filter((p) => !catalogued.has(p.key)).map((p) => p.key),\n    unwritten: [...catalogued].filter((key) => !written.has(key)).sort(compareIds),\n    duplicated: [...bySpelling]\n      .filter(([, texts]) => texts.length > 1)\n      .map(([key, texts]) => ({ key, texts }))\n      .sort((a, b) => compareIds(a.key, b.key)),\n  };\n}\n"]}

package/dist/core/gherkin/steps/inventory.js

@@ -0,0 +1,98 @@
+/**
+ * The step-phrase inventory: how many DEFINITIONS a service's suite actually
+ * needs, and which written steps collapse onto each one.
+ *
+ * ## What this is for
+ *
+ * Generated `.feature` files are only a suite if somebody writes the glue, and
+ * the glue is where a generated suite dies: the step text is free prose from a
+ * spec bullet, so the same precondition gets three spellings across three
+ * requirements and the registry grows without bound until people quietly go
+ * back to hand-written tests. Nothing in loam could previously say how bad that
+ * was, which meant nobody could tell a suite that needs forty definitions from
+ * one that needs four hundred.
+ *
+ * Measured on a real twelve-scenario component-test file, 324 written steps
+ * collapse to 97 phrases, and 34 of those cover 82% of every step — so the
+ * report is not an audit, it is the work-list a team writes glue from, and the
+ * draft of any step catalogue that comes later.
+ *
+ * ## What it deliberately is NOT
+ *
+ * It emits no finding and no stable code. A near-duplicate is a judgement about
+ * writing, and a phrase-similarity WARNING is the kind of check a fleet turns
+ * off — at which point the real findings beside it are turned off too. It reads
+ * the LIVING specs rather than the emitted files, so it answers the same way in
+ * a repo that has never run `loam gherkin` and needs no service repo to stand
+ * in.
+ */
+import { scenarioGherkin } from "../../vocabulary/steps.js";
+import {} from "../../document/spec.js";
+import { keywordOf, phraseOf } from "./phrase.js";
+/**
+ * Count the phrases across both axes of one service.
+ *
+ * REMOVED requirements are skipped, exactly as every other scenario check skips
+ * them: a step nobody will run is not glue anybody owes.
+ *
+ * Ordering is count-descending then key-ascending, and that second key is what
+ * makes the report diffable — two phrases used once each must not swap places
+ * between runs because a Map happened to iterate differently.
+ */
+export function stepInventory(axes) {
+    const byKey = new Map();
+    const families = new Map();
+    let steps = 0;
+    for (const { axis, reqs } of axes) {
+        for (const r of reqs) {
+            if (r.kind === "REMOVED")
+                continue;
+            for (const s of r.scenarios) {
+                for (const st of scenarioGherkin(s.lines).steps) {
+                    steps += 1;
+                    const { key, family } = phraseOf(st.text);
+                    const row = byKey.get(key) ?? { key, count: 0, keywords: [], uses: [] };
+                    row.count += 1;
+                    const kw = keywordOf(st.text);
+                    if (kw.length > 0 && !row.keywords.includes(kw))
+                        row.keywords.push(kw);
+                    row.uses.push({ requirement: r.name, scenario: s.name, axis, text: st.text });
+                    byKey.set(key, row);
+                    const seen = families.get(family) ?? new Set();
+                    seen.add(key);
+                    families.set(family, seen);
+                }
+            }
+        }
+    }
+    const phrases = [...byKey.values()]
+        .map((row) => ({ ...row, keywords: [...row.keywords].sort() }))
+        .sort((a, b) => b.count - a.count || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const nearDuplicates = [...families.entries()]
+        .filter(([, keys]) => keys.size > 1)
+        .map(([family, keys]) => ({ family, keys: [...keys].sort() }))
+        .sort((a, b) => (a.family < b.family ? -1 : a.family > b.family ? 1 : 0));
+    return { steps, phrases, nearDuplicates };
+}
+/**
+ * How many phrases cover `share` of every written step — the one number that
+ * says whether the glue is a morning's work or a quarter's.
+ *
+ * Returns zero for an empty suite rather than dividing by it, because "0 of 0
+ * steps" is the honest reading of a service that has written no scenarios yet.
+ */
+export function coveringPhrases(inv, share = 0.8) {
+    if (inv.steps === 0)
+        return 0;
+    const target = inv.steps * share;
+    let running = 0;
+    let n = 0;
+    for (const row of inv.phrases) {
+        if (running >= target)
+            break;
+        running += row.count;
+        n += 1;
+    }
+    return n;
+}
+//# sourceMappingURL=inventory.js.map