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

package/dist/commands/gherkin/gherkin.js

@@ -0,0 +1,262 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { decodeDocument, NotUtf8DocumentError } from "../../core/kernel/document-bytes.js";
+import { configOrRefuse, emitJson, emitJsonError, fail, NO_SERVICE_MESSAGE, } from "../../core/envelope/json.js";
+import { featureSpecPaths, SPEC_AXES } from "../../core/repo/paths.js";
+import { locateServicePaths } from "../../core/repo/service-target.js";
+import { listFeatures, missingFeatureMessage, resolveFeature } from "../../core/repo/repo.js";
+import { parseRequirements } from "../../core/document/parse.js";
+import {} from "../../core/document/spec.js";
+import { axisLabel, planEmission } from "../../core/gherkin/emit.js";
+import { gherkinRoot } from "../../core/gherkin/stamp.js";
+import { LOAM_VERSION } from "../../core/envelope/version.js";
+import { UnsafePathError } from "../../core/kernel/path-safety.js";
+import { recoverIfJournaled } from "../../core/staging/recovery/recover.js";
+import { commitEmission } from "./commit.js";
+import { reconcile } from "./reconcile.js";
+import { render } from "./render.js";
+import { sayRecovered } from "../policy/format.js";
+export function registerGherkin(program) {
+    program
+        .command("gherkin")
+        .argument("[featureId]", "feature id — emit its ADDED/MODIFIED requirements; omit for the full living suite")
+        .description("Emit Gherkin .feature files from spec scenarios into this service repo's <gherkinDir>/loam/")
+        .option("--service <id>", "service to emit for (defaults to the configured service)")
+        .option("--dry-run", "print the plan (writes, replacements, deletions) and write nothing — beyond first finishing a predecessor's interrupted commit, exactly as a real run would")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (featureArg, opts) => {
+        const json = opts.json === true;
+        const dryRun = opts.dryRun === true;
+        const config = await configOrRefuse(json);
+        if (config === null)
+            return;
+        const service = opts.service ?? config.service;
+        if (service === undefined) {
+            return fail(json, "invalid-option", NO_SERVICE_MESSAGE);
+        }
+        // The emission writes into the repo loam is standing in, so it can only
+        // run where that repo is this service's — vouch's refusal, verbatim logic.
+        //
+        // TWO conditions, two codes, and the split is the whole point. Both used
+        // to answer `invalid-option`, whose `loam explain` row says the
+        // invocation itself is wrong — contradictory flags, a mistyped one, a
+        // value that cannot be right. Here the invocation is perfectly correct
+        // and the REPOSITORY is the wrong one, so that code sent a user whose
+        // flags were fine off to re-read their flags, and left CI and agents
+        // unable to tell "run this in the service repo" from "you typed the flag
+        // wrong". `loam verify --record --service` already draws exactly this
+        // line for exactly this reason (see commands/verify/verify.ts); gherkin
+        // and vouch now answer the same pair, so a caller branching on
+        // `error.code` gets one answer from all three. The messages are
+        // unchanged — only the code moved.
+        if (config.service === undefined) {
+            return fail(json, "repository-unavailable", `Cannot emit gherkin for '${service}' from here: this is not a service repo. Generated .feature files land in the service's own repo — run it there.`);
+        }
+        if (config.service !== service) {
+            return fail(json, "service-mismatch", `Cannot emit gherkin for '${service}' from here: this repo is '${config.service}'. Generated .feature files land in the service's own repo — run it there.`);
+        }
+        // The repo root, not the cwd: `config.root` is the directory loam.json
+        // was actually found in, and config discovery walks upward. Taken from
+        // `process.cwd()` this emitted the whole suite into whatever directory
+        // the caller happened to stand in — `src/api/features/loam/…` inside the
+        // source tree, which the next run from the root neither finds, replaces
+        // nor deletes, and which `loam validate` grades as a suite that was never
+        // generated.
+        const repoDir = config.root ?? process.cwd();
+        let root;
+        try {
+            root = gherkinRoot(repoDir, config.gherkinDir);
+        }
+        catch (err) {
+            if (!(err instanceof UnsafePathError))
+                throw err;
+            return fail(json, "invalid-option", `Cannot emit Gherkin: ${err.message}. The output directory must stay inside the service repo.`);
+        }
+        const rel = (abs) => relative(repoDir, abs).split(/[\\/]/).join("/");
+        // A predecessor's interrupted emission is rolled forward before ANY
+        // read — and before the feature argument resolves: reconcile grades the
+        // very bytes a half-commit corrupts, and the journal's stored rerun may
+        // name a feature that has since ARCHIVED, whose recovery must still
+        // work. `new` fixed the same ordering and documented it; refusing
+        // unknown-target over a wedged root left doctor printing a repair that
+        // could never run. The lock is the emission root's own, given straight
+        // back: the slow half below runs unlocked, and `commitEmission` retakes
+        // it for the commit window.
+        const early = await recoverIfJournaled(root);
+        if (!early.ok)
+            return fail(json, early.code, early.message);
+        let recovered = early.recovered;
+        const feature = featureArg === undefined ? null : await resolveFeature(config.docsDir, featureArg, "exclude");
+        if (featureArg !== undefined && feature === null) {
+            return fail(json, "unknown-target", await missingFeatureMessage(config.docsDir, featureArg));
+        }
+        const scope = feature === null ? { mode: "living" } : { mode: "feature", featureId: feature.id };
+        // The requirement set, by scope. Feature mode takes ADDED and MODIFIED —
+        // a BASE requirement is the living state quoted, a REMOVED one is being
+        // retired, and neither is behaviour anybody is about to test. Living mode
+        // takes everything the living files hold.
+        //
+        // Read through `decodeDocument`, not `readFile(…, "utf8")`, and refused
+        // rather than degraded: a spec.md saved as UTF-16 decodes to a document
+        // with no requirements in it, which here is not merely a wrong answer but
+        // a destructive one — an empty plan makes every existing .feature under
+        // loam/ an orphan, and a living run DELETES its orphans. The whole
+        // generated suite would go because a docs file was written by PowerShell.
+        const byAxis = [];
+        const readSpec = async (path) => parseRequirements(decodeDocument(await readFile(path), path));
+        try {
+            if (feature !== null) {
+                // `config.service`, not `service`: the guard above proved they are
+                // the same id, and only the config's copy carries the load-time
+                // parse, so it is the pathable spelling — same as the else arm.
+                const paths = featureSpecPaths(feature.dir, config.service);
+                for (const axis of SPEC_AXES) {
+                    const path = paths[axis.key];
+                    const reqs = existsSync(path)
+                        ? (await readSpec(path)).filter((r) => r.kind === "ADDED" || r.kind === "MODIFIED")
+                        : [];
+                    byAxis.push({ axis, reqs });
+                }
+            }
+            else {
+                // The guard above proved `service` IS `config.service`; only the
+                // latter carries the load-time parse, so it is the pathable spelling.
+                const paths = await locateServicePaths(config.docsDir, config.service);
+                if (!existsSync(paths.spec)) {
+                    return fail(json, "unknown-target", `No living spec at ${paths.spec}. Run \`loam adopt\` for '${service}' first.`);
+                }
+                for (const axis of SPEC_AXES) {
+                    const path = paths[axis.key];
+                    const reqs = existsSync(path) ? (await readSpec(path)).filter((r) => r.kind !== "REMOVED") : [];
+                    byAxis.push({ axis, reqs });
+                }
+            }
+        }
+        catch (err) {
+            if (!(err instanceof NotUtf8DocumentError))
+                throw err;
+            return fail(json, "repository-unavailable", `Cannot emit gherkin: ${err.message}`);
+        }
+        // `service` is not decoration: it salts every `@loam-digest-…` stamp, and
+        // it is the same string `loam verify` files the matching claims under.
+        const plan = planEmission(byAxis, {
+            service,
+            featureTag: scope.mode === "feature" ? scope.featureId : undefined,
+            version: LOAM_VERSION,
+        });
+        // `Set<string>`, not the ids' own brand — core/gherkin/stale.ts's reason:
+        // it answers membership for tags read out of .feature files.
+        const activeIds = new Set((await listFeatures(config.docsDir)).map((f) => f.id));
+        let reconciled;
+        try {
+            reconciled = await reconcile(plan, { root, repoDir }, scope, activeIds);
+        }
+        catch (err) {
+            if (!(err instanceof UnsafePathError))
+                throw err;
+            return fail(json, "invalid-option", `Cannot emit Gherkin: ${err.message}.`);
+        }
+        const { actions, orphans, conflicts } = reconciled;
+        // All or nothing, and only a feature run can conflict — `./reconcile.ts`
+        // records why, where the conflicts are collected.
+        if (scope.mode === "feature" && conflicts.length > 0) {
+            const detail = conflicts
+                .map((c) => `${rel(c.path)} is @${c.owners.join(" @")} (requirement '${c.requirement.name}')`)
+                .join("; ");
+            const message = `Cannot emit gherkin for ${scope.featureId}: ${conflicts.length} file(s) belong to another feature still in flight — ${detail}. ` +
+                `A .feature file carries one feature's delta; overwriting would revert that feature's wording and destroy the digest stamps \`loam verify --results\` matches on. ` +
+                `Archive (or abandon) the owning feature first, or rename the requirement in ${scope.featureId}'s delta so the two stop sharing a file name.`;
+            if (json) {
+                emitJsonError("gherkin-conflict", message, {
+                    conflicts: conflicts.map((c) => ({
+                        path: rel(c.path),
+                        action: "conflict",
+                        requirement: c.requirement.name,
+                        inFlight: c.owners,
+                    })),
+                });
+                return;
+            }
+            return fail(json, "gherkin-conflict", message);
+        }
+        const writes = actions.filter((a) => a.action !== "kept");
+        if (!dryRun && (writes.length > 0 || orphans.length > 0)) {
+            // The commit window: locked, journaled, compared against the bytes
+            // reconcile graded. A zero-op run takes no lock and creates no root —
+            // an emission with nothing to emit must not flip the repo into
+            // "opted in", where an empty loam/ tells `loam validate` the whole
+            // living suite is missing.
+            const committed = await commitEmission({ root, service, scope }, { writes, orphans });
+            if (!committed.ok)
+                return fail(json, committed.code, committed.message);
+            recovered = committed.recovered ?? recovered;
+        }
+        if (json) {
+            emitJson({
+                command: "gherkin",
+                mode: scope.mode,
+                ...(scope.mode === "feature" ? { feature: scope.featureId } : {}),
+                service,
+                root: rel(root),
+                written: !dryRun,
+                files: actions.map((a) => ({
+                    path: rel(a.path),
+                    action: a.action,
+                    axis: axisLabel(a.axis),
+                    requirement: a.requirement.name,
+                    // A kept file's numbers describe what STAYS on disk (the in-flight
+                    // emission), not the emission that was withheld.
+                    scenarios: a.action === "kept" ? a.kept.scenarios.length : a.digests.length,
+                    digests: a.action === "kept" ? a.kept.scenarios.map((s) => s.digest) : a.digests,
+                    // `digests` is a bare array and `scenarios` a bare count, so the one
+                    // thing a consumer actually needs — which stamp belongs to which
+                    // scenario — was the one thing this payload could not say, and the
+                    // only way to learn it was to go read the generated file back off
+                    // disk. `stamped` is that pairing; `digests` stays exactly as it was
+                    // beside it, because the envelope permits adding a key and never
+                    // changing one (core/envelope/json.ts).
+                    //
+                    // The positional zip is sound because `renderFeature`
+                    // (core/gherkin/emit.ts) pushes exactly one digest per scenario, in
+                    // scenario order, inside the same loop that writes the `Scenario:`
+                    // line — but it is written to FAIL CLOSED rather than to assert
+                    // that: a scenario with no digest opposite it drops out of the
+                    // pairing instead of being published with a null one. A kept row
+                    // reads its pairs off the file that is really on disk, because its
+                    // numbers describe the in-flight emission that stayed, not the one
+                    // that was withheld.
+                    stamped: a.action === "kept"
+                        ? a.kept.scenarios.map((s) => ({ scenario: s.name, digest: s.digest }))
+                        : a.requirement.scenarios.flatMap((s, i) => {
+                            const digest = a.digests[i];
+                            return digest === undefined ? [] : [{ scenario: s.name, digest }];
+                        }),
+                    ...(a.action === "kept"
+                        ? { inFlight: a.kept.tags.filter((t) => activeIds.has(t)) }
+                        : {
+                            stepless: a.stepless,
+                            malformedExamples: a.malformedExamples,
+                            strandedBlocks: a.strandedBlocks,
+                        }),
+                })),
+                deleted: orphans.map((o) => rel(o.path)),
+                ...(recovered === null ? {} : { recovered }),
+            });
+            return;
+        }
+        if (recovered !== null)
+            console.log(`${sayRecovered(recovered)}\n`);
+        render(actions, {
+            service,
+            root: rel(root),
+            absRoot: root,
+            featureId: scope.mode === "feature" ? scope.featureId : null,
+            dryRun,
+            activeIds,
+            writes: writes.length,
+            orphans: orphans.map((o) => o.path),
+        });
+    });
+}
+//# sourceMappingURL=gherkin.js.map

package/dist/commands/gherkin/gherkin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gherkin.js","sourceRoot":"","sources":["../../../src/commands/gherkin/gherkin.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAC3F,OAAO,EACL,cAAc,EACd,QAAQ,EACR,aAAa,EACb,IAAI,EACJ,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAiB,MAAM,0BAA0B,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAoB,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAc,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAQnD,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,QAAQ,CAAC,aAAa,EAAE,mFAAmF,CAAC;SAC5G,WAAW,CACV,6FAA6F,CAC9F;SACA,MAAM,CAAC,gBAAgB,EAAE,0DAA0D,CAAC;SACpF,MAAM,CACL,WAAW,EACX,6JAA6J,CAC9J;SACA,MAAM,CAAC,QAAQ,EAAE,qDAAqD,CAAC;SACvE,MAAM,CAAC,KAAK,EAAE,UAA8B,EAAE,IAAoB,EAAE,EAAE;QACrE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC;QAEpC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC;QAC/C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;QAC1D,CAAC;QACD,wEAAwE;QACxE,2EAA2E;QAC3E,EAAE;QACF,yEAAyE;QACzE,gEAAgE;QAChE,sEAAsE;QACtE,uEAAuE;QACvE,sEAAsE;QACtE,qEAAqE;QACrE,yEAAyE;QACzE,sEAAsE;QACtE,wEAAwE;QACxE,+DAA+D;QAC/D,gEAAgE;QAChE,mCAAmC;QACnC,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACjC,OAAO,IAAI,CACT,IAAI,EACJ,wBAAwB,EACxB,4BAA4B,OAAO,kHAAkH,CACtJ,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YAC/B,OAAO,IAAI,CACT,IAAI,EACJ,kBAAkB,EAClB,4BAA4B,OAAO,8BAA8B,MAAM,CAAC,OAAO,4EAA4E,CAC5J,CAAC;QACJ,CAAC;QAED,uEAAuE;QACvE,uEAAuE;QACvE,uEAAuE;QACvE,yEAAyE;QACzE,wEAAwE;QACxE,0EAA0E;QAC1E,aAAa;QACb,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAC7C,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,eAAe,CAAC;gBAAE,MAAM,GAAG,CAAC;YACjD,OAAO,IAAI,CACT,IAAI,EACJ,gBAAgB,EAChB,wBAAwB,GAAG,CAAC,OAAO,2DAA2D,CAC/F,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAErF,oEAAoE;QACpE,wEAAwE;QACxE,wEAAwE;QACxE,oEAAoE;QACpE,kEAAkE;QAClE,uEAAuE;QACvE,uEAAuE;QACvE,wEAAwE;QACxE,4BAA4B;QAC5B,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,KAAK,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5D,IAAI,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QAEhC,MAAM,OAAO,GACX,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,cAAc,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;QAChG,IAAI,UAAU,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACjD,OAAO,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;QAC/F,CAAC;QACD,MAAM,KAAK,GACT,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;QAErF,yEAAyE;QACzE,wEAAwE;QACxE,0EAA0E;QAC1E,0CAA0C;QAC1C,EAAE;QACF,wEAAwE;QACxE,wEAAwE;QACxE,0EAA0E;QAC1E,wEAAwE;QACxE,mEAAmE;QACnE,0EAA0E;QAC1E,MAAM,MAAM,GAAmD,EAAE,CAAC;QAClE,MAAM,QAAQ,GAAG,KAAK,EAAE,IAAY,EAA0B,EAAE,CAC9D,iBAAiB,CAAC,cAAc,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QAChE,IAAI,CAAC;YACH,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,mEAAmE;gBACnE,gEAAgE;gBAChE,gEAAgE;gBAChE,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC5D,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;oBAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;oBAC7B,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;wBAC3B,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;wBACnF,CAAC,CAAC,EAAE,CAAC;oBACP,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,iEAAiE;gBACjE,sEAAsE;gBACtE,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;gBACvE,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC5B,OAAO,IAAI,CACT,IAAI,EACJ,gBAAgB,EAChB,qBAAqB,KAAK,CAAC,IAAI,6BAA6B,OAAO,UAAU,CAC9E,CAAC;gBACJ,CAAC;gBACD,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;oBAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;oBAC7B,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChG,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,oBAAoB,CAAC;gBAAE,MAAM,GAAG,CAAC;YACtD,OAAO,IAAI,CAAC,IAAI,EAAE,wBAAwB,EAAE,wBAAwB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACrF,CAAC;QAED,0EAA0E;QAC1E,uEAAuE;QACvE,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,EAAE;YAChC,OAAO;YACP,UAAU,EAAE,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;YAClE,OAAO,EAAE,YAAY;SACtB,CAAC,CAAC;QAEH,0EAA0E;QAC1E,6DAA6D;QAC7D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAS,CAAC,MAAM,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACzF,IAAI,UAAU,CAAC;QACf,IAAI,CAAC;YACH,UAAU,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QAC1E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,eAAe,CAAC;gBAAE,MAAM,GAAG,CAAC;YACjD,OAAO,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,wBAAwB,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC;QAC9E,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,UAAU,CAAC;QAEnD,yEAAyE;QACzE,kDAAkD;QAClD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrD,MAAM,MAAM,GAAG,SAAS;iBACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;iBAC7F,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,MAAM,OAAO,GACX,2BAA2B,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,MAAM,wDAAwD,MAAM,IAAI;gBACjI,mKAAmK;gBACnK,+EAA+E,KAAK,CAAC,SAAS,+CAA+C,CAAC;YAChJ,IAAI,IAAI,EAAE,CAAC;gBACT,aAAa,CAAC,kBAAkB,EAAE,OAAO,EAAE;oBACzC,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wBAC/B,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;wBACjB,MAAM,EAAE,UAAU;wBAClB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,IAAI;wBAC/B,QAAQ,EAAE,CAAC,CAAC,MAAM;qBACnB,CAAC,CAAC;iBACJ,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YACD,OAAO,IAAI,CAAC,IAAI,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QAE1D,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;YACzD,mEAAmE;YACnE,sEAAsE;YACtE,+DAA+D;YAC/D,mEAAmE;YACnE,2BAA2B;YAC3B,MAAM,SAAS,GAAG,MAAM,cAAc,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YACtF,IAAI,CAAC,SAAS,CAAC,EAAE;gBAAE,OAAO,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;YACxE,SAAS,GAAG,SAAS,CAAC,SAAS,IAAI,SAAS,CAAC;QAC/C,CAAC;QAED,IAAI,IAAI,EAAE,CAAC;YACT,QAAQ,CAAC;gBACP,OAAO,EAAE,SAAS;gBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjE,OAAO;gBACP,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC;gBACf,OAAO,EAAE,CAAC,MAAM;gBAChB,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACzB,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;oBACjB,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;oBACvB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,IAAI;oBAC/B,mEAAmE;oBACnE,iDAAiD;oBACjD,SAAS,EAAE,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM;oBAC3E,OAAO,EAAE,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO;oBAChF,qEAAqE;oBACrE,iEAAiE;oBACjE,mEAAmE;oBACnE,kEAAkE;oBAClE,qEAAqE;oBACrE,iEAAiE;oBACjE,wCAAwC;oBACxC,EAAE;oBACF,sDAAsD;oBACtD,oEAAoE;oBACpE,mEAAmE;oBACnE,gEAAgE;oBAChE,+DAA+D;oBAC/D,iEAAiE;oBACjE,mEAAmE;oBACnE,mEAAmE;oBACnE,qBAAqB;oBACrB,OAAO,EACL,CAAC,CAAC,MAAM,KAAK,MAAM;wBACjB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;wBACvE,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;4BACvC,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;4BAC5B,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;wBACpE,CAAC,CAAC;oBACR,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM;wBACrB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE;wBAC3D,CAAC,CAAC;4BACE,QAAQ,EAAE,CAAC,CAAC,QAAQ;4BACpB,iBAAiB,EAAE,CAAC,CAAC,iBAAiB;4BACtC,cAAc,EAAE,CAAC,CAAC,cAAc;yBACjC,CAAC;iBACP,CAAC,CAAC;gBACH,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;gBACxC,GAAG,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;aAC7C,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACpE,MAAM,CAAC,OAAO,EAAE;YACd,OAAO;YACP,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC;YACf,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;YAC5D,MAAM;YACN,SAAS;YACT,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SACpC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC","sourcesContent":["/**\n * `loam gherkin` — the third writer in the CLI (after archive and vouch), and\n * the only one that writes into the SERVICE repo, never the docs repo: the\n * docs state what must be true, the tests live with the code that makes it so.\n *\n * Two scopes, one emitter. `loam gherkin <FEAT>` emits the feature's ADDED and\n * MODIFIED requirements for this service — both spec axes — as the acceptance\n * skeleton to implement against, each file tagged with the feature id.\n * `loam gherkin --service <id>` (no feature) emits the full living suite from\n * spec.md + arch.spec.md: the regression skeleton a legacy service gets at\n * adoption. Either way the output is `<gherkinDir>/loam/` inside this repo,\n * a directory loam owns outright: the scope's files are rewritten, the scope's\n * orphans are deleted (and reported), and nothing outside `loam/` is touched —\n * except that a living run neither deletes NOR overwrites a file tagged with a\n * feature still in flight: it answers to that feature's delta until it\n * archives, and is reported as kept. A FEATURE run cannot keep — the file it\n * wants holds one feature's delta — so when the file it would write belongs to\n * a different feature still in flight, the whole run refuses (`gherkin-conflict`)\n * and names the owner rather than reverting it.\n *\n * It refuses to run anywhere but the service's own repo — vouch's discipline,\n * for vouch's reason: the output lands in the repo loam is standing in, and\n * from anywhere else that repo is somebody else's.\n */\nimport type { Command } from \"commander\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { decodeDocument, NotUtf8DocumentError } from \"../../core/kernel/document-bytes.js\";\nimport {\n  configOrRefuse,\n  emitJson,\n  emitJsonError,\n  fail,\n  NO_SERVICE_MESSAGE,\n} from \"../../core/envelope/json.js\";\nimport { featureSpecPaths, SPEC_AXES, type SpecAxis } from \"../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../core/repo/service-target.js\";\nimport { listFeatures, missingFeatureMessage, resolveFeature } from \"../../core/repo/repo.js\";\nimport { parseRequirements } from \"../../core/document/parse.js\";\nimport { type Requirement } from \"../../core/document/spec.js\";\nimport { axisLabel, planEmission } from \"../../core/gherkin/emit.js\";\nimport { gherkinRoot } from \"../../core/gherkin/stamp.js\";\nimport { LOAM_VERSION } from \"../../core/envelope/version.js\";\nimport { UnsafePathError } from \"../../core/kernel/path-safety.js\";\nimport { recoverIfJournaled } from \"../../core/staging/recovery/recover.js\";\nimport { commitEmission } from \"./commit.js\";\nimport { reconcile, type Scope } from \"./reconcile.js\";\nimport { render } from \"./render.js\";\nimport { sayRecovered } from \"../policy/format.js\";\n\ninterface GherkinOptions {\n  service?: string;\n  dryRun?: boolean;\n  json?: boolean;\n}\n\nexport function registerGherkin(program: Command): void {\n  program\n    .command(\"gherkin\")\n    .argument(\"[featureId]\", \"feature id — emit its ADDED/MODIFIED requirements; omit for the full living suite\")\n    .description(\n      \"Emit Gherkin .feature files from spec scenarios into this service repo's <gherkinDir>/loam/\",\n    )\n    .option(\"--service <id>\", \"service to emit for (defaults to the configured service)\")\n    .option(\n      \"--dry-run\",\n      \"print the plan (writes, replacements, deletions) and write nothing — beyond first finishing a predecessor's interrupted commit, exactly as a real run would\",\n    )\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureArg: string | undefined, opts: GherkinOptions) => {\n      const json = opts.json === true;\n      const dryRun = opts.dryRun === true;\n\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        return fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n      }\n      // The emission writes into the repo loam is standing in, so it can only\n      // run where that repo is this service's — vouch's refusal, verbatim logic.\n      //\n      // TWO conditions, two codes, and the split is the whole point. Both used\n      // to answer `invalid-option`, whose `loam explain` row says the\n      // invocation itself is wrong — contradictory flags, a mistyped one, a\n      // value that cannot be right. Here the invocation is perfectly correct\n      // and the REPOSITORY is the wrong one, so that code sent a user whose\n      // flags were fine off to re-read their flags, and left CI and agents\n      // unable to tell \"run this in the service repo\" from \"you typed the flag\n      // wrong\". `loam verify --record --service` already draws exactly this\n      // line for exactly this reason (see commands/verify/verify.ts); gherkin\n      // and vouch now answer the same pair, so a caller branching on\n      // `error.code` gets one answer from all three. The messages are\n      // unchanged — only the code moved.\n      if (config.service === undefined) {\n        return fail(\n          json,\n          \"repository-unavailable\",\n          `Cannot emit gherkin for '${service}' from here: this is not a service repo. Generated .feature files land in the service's own repo — run it there.`,\n        );\n      }\n      if (config.service !== service) {\n        return fail(\n          json,\n          \"service-mismatch\",\n          `Cannot emit gherkin for '${service}' from here: this repo is '${config.service}'. Generated .feature files land in the service's own repo — run it there.`,\n        );\n      }\n\n      // The repo root, not the cwd: `config.root` is the directory loam.json\n      // was actually found in, and config discovery walks upward. Taken from\n      // `process.cwd()` this emitted the whole suite into whatever directory\n      // the caller happened to stand in — `src/api/features/loam/…` inside the\n      // source tree, which the next run from the root neither finds, replaces\n      // nor deletes, and which `loam validate` grades as a suite that was never\n      // generated.\n      const repoDir = config.root ?? process.cwd();\n      let root: string;\n      try {\n        root = gherkinRoot(repoDir, config.gherkinDir);\n      } catch (err) {\n        if (!(err instanceof UnsafePathError)) throw err;\n        return fail(\n          json,\n          \"invalid-option\",\n          `Cannot emit Gherkin: ${err.message}. The output directory must stay inside the service repo.`,\n        );\n      }\n      const rel = (abs: string): string => relative(repoDir, abs).split(/[\\\\/]/).join(\"/\");\n\n      // A predecessor's interrupted emission is rolled forward before ANY\n      // read — and before the feature argument resolves: reconcile grades the\n      // very bytes a half-commit corrupts, and the journal's stored rerun may\n      // name a feature that has since ARCHIVED, whose recovery must still\n      // work. `new` fixed the same ordering and documented it; refusing\n      // unknown-target over a wedged root left doctor printing a repair that\n      // could never run. The lock is the emission root's own, given straight\n      // back: the slow half below runs unlocked, and `commitEmission` retakes\n      // it for the commit window.\n      const early = await recoverIfJournaled(root);\n      if (!early.ok) return fail(json, early.code, early.message);\n      let recovered = early.recovered;\n\n      const feature =\n        featureArg === undefined ? null : await resolveFeature(config.docsDir, featureArg, \"exclude\");\n      if (featureArg !== undefined && feature === null) {\n        return fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureArg));\n      }\n      const scope: Scope =\n        feature === null ? { mode: \"living\" } : { mode: \"feature\", featureId: feature.id };\n\n      // The requirement set, by scope. Feature mode takes ADDED and MODIFIED —\n      // a BASE requirement is the living state quoted, a REMOVED one is being\n      // retired, and neither is behaviour anybody is about to test. Living mode\n      // takes everything the living files hold.\n      //\n      // Read through `decodeDocument`, not `readFile(…, \"utf8\")`, and refused\n      // rather than degraded: a spec.md saved as UTF-16 decodes to a document\n      // with no requirements in it, which here is not merely a wrong answer but\n      // a destructive one — an empty plan makes every existing .feature under\n      // loam/ an orphan, and a living run DELETES its orphans. The whole\n      // generated suite would go because a docs file was written by PowerShell.\n      const byAxis: Array<{ axis: SpecAxis; reqs: Requirement[] }> = [];\n      const readSpec = async (path: string): Promise<Requirement[]> =>\n        parseRequirements(decodeDocument(await readFile(path), path));\n      try {\n        if (feature !== null) {\n          // `config.service`, not `service`: the guard above proved they are\n          // the same id, and only the config's copy carries the load-time\n          // parse, so it is the pathable spelling — same as the else arm.\n          const paths = featureSpecPaths(feature.dir, config.service);\n          for (const axis of SPEC_AXES) {\n            const path = paths[axis.key];\n            const reqs = existsSync(path)\n              ? (await readSpec(path)).filter((r) => r.kind === \"ADDED\" || r.kind === \"MODIFIED\")\n              : [];\n            byAxis.push({ axis, reqs });\n          }\n        } else {\n          // The guard above proved `service` IS `config.service`; only the\n          // latter carries the load-time parse, so it is the pathable spelling.\n          const paths = await locateServicePaths(config.docsDir, config.service);\n          if (!existsSync(paths.spec)) {\n            return fail(\n              json,\n              \"unknown-target\",\n              `No living spec at ${paths.spec}. Run \\`loam adopt\\` for '${service}' first.`,\n            );\n          }\n          for (const axis of SPEC_AXES) {\n            const path = paths[axis.key];\n            const reqs = existsSync(path) ? (await readSpec(path)).filter((r) => r.kind !== \"REMOVED\") : [];\n            byAxis.push({ axis, reqs });\n          }\n        }\n      } catch (err) {\n        if (!(err instanceof NotUtf8DocumentError)) throw err;\n        return fail(json, \"repository-unavailable\", `Cannot emit gherkin: ${err.message}`);\n      }\n\n      // `service` is not decoration: it salts every `@loam-digest-…` stamp, and\n      // it is the same string `loam verify` files the matching claims under.\n      const plan = planEmission(byAxis, {\n        service,\n        featureTag: scope.mode === \"feature\" ? scope.featureId : undefined,\n        version: LOAM_VERSION,\n      });\n\n      // `Set<string>`, not the ids' own brand — core/gherkin/stale.ts's reason:\n      // it answers membership for tags read out of .feature files.\n      const activeIds = new Set<string>((await listFeatures(config.docsDir)).map((f) => f.id));\n      let reconciled;\n      try {\n        reconciled = await reconcile(plan, { root, repoDir }, scope, activeIds);\n      } catch (err) {\n        if (!(err instanceof UnsafePathError)) throw err;\n        return fail(json, \"invalid-option\", `Cannot emit Gherkin: ${err.message}.`);\n      }\n      const { actions, orphans, conflicts } = reconciled;\n\n      // All or nothing, and only a feature run can conflict — `./reconcile.ts`\n      // records why, where the conflicts are collected.\n      if (scope.mode === \"feature\" && conflicts.length > 0) {\n        const detail = conflicts\n          .map((c) => `${rel(c.path)} is @${c.owners.join(\" @\")} (requirement '${c.requirement.name}')`)\n          .join(\"; \");\n        const message =\n          `Cannot emit gherkin for ${scope.featureId}: ${conflicts.length} file(s) belong to another feature still in flight — ${detail}. ` +\n          `A .feature file carries one feature's delta; overwriting would revert that feature's wording and destroy the digest stamps \\`loam verify --results\\` matches on. ` +\n          `Archive (or abandon) the owning feature first, or rename the requirement in ${scope.featureId}'s delta so the two stop sharing a file name.`;\n        if (json) {\n          emitJsonError(\"gherkin-conflict\", message, {\n            conflicts: conflicts.map((c) => ({\n              path: rel(c.path),\n              action: \"conflict\",\n              requirement: c.requirement.name,\n              inFlight: c.owners,\n            })),\n          });\n          return;\n        }\n        return fail(json, \"gherkin-conflict\", message);\n      }\n\n      const writes = actions.filter((a) => a.action !== \"kept\");\n\n      if (!dryRun && (writes.length > 0 || orphans.length > 0)) {\n        // The commit window: locked, journaled, compared against the bytes\n        // reconcile graded. A zero-op run takes no lock and creates no root —\n        // an emission with nothing to emit must not flip the repo into\n        // \"opted in\", where an empty loam/ tells `loam validate` the whole\n        // living suite is missing.\n        const committed = await commitEmission({ root, service, scope }, { writes, orphans });\n        if (!committed.ok) return fail(json, committed.code, committed.message);\n        recovered = committed.recovered ?? recovered;\n      }\n\n      if (json) {\n        emitJson({\n          command: \"gherkin\",\n          mode: scope.mode,\n          ...(scope.mode === \"feature\" ? { feature: scope.featureId } : {}),\n          service,\n          root: rel(root),\n          written: !dryRun,\n          files: actions.map((a) => ({\n            path: rel(a.path),\n            action: a.action,\n            axis: axisLabel(a.axis),\n            requirement: a.requirement.name,\n            // A kept file's numbers describe what STAYS on disk (the in-flight\n            // emission), not the emission that was withheld.\n            scenarios: a.action === \"kept\" ? a.kept.scenarios.length : a.digests.length,\n            digests: a.action === \"kept\" ? a.kept.scenarios.map((s) => s.digest) : a.digests,\n            // `digests` is a bare array and `scenarios` a bare count, so the one\n            // thing a consumer actually needs — which stamp belongs to which\n            // scenario — was the one thing this payload could not say, and the\n            // only way to learn it was to go read the generated file back off\n            // disk. `stamped` is that pairing; `digests` stays exactly as it was\n            // beside it, because the envelope permits adding a key and never\n            // changing one (core/envelope/json.ts).\n            //\n            // The positional zip is sound because `renderFeature`\n            // (core/gherkin/emit.ts) pushes exactly one digest per scenario, in\n            // scenario order, inside the same loop that writes the `Scenario:`\n            // line — but it is written to FAIL CLOSED rather than to assert\n            // that: a scenario with no digest opposite it drops out of the\n            // pairing instead of being published with a null one. A kept row\n            // reads its pairs off the file that is really on disk, because its\n            // numbers describe the in-flight emission that stayed, not the one\n            // that was withheld.\n            stamped:\n              a.action === \"kept\"\n                ? a.kept.scenarios.map((s) => ({ scenario: s.name, digest: s.digest }))\n                : a.requirement.scenarios.flatMap((s, i) => {\n                    const digest = a.digests[i];\n                    return digest === undefined ? [] : [{ scenario: s.name, digest }];\n                  }),\n            ...(a.action === \"kept\"\n              ? { inFlight: a.kept.tags.filter((t) => activeIds.has(t)) }\n              : {\n                  stepless: a.stepless,\n                  malformedExamples: a.malformedExamples,\n                  strandedBlocks: a.strandedBlocks,\n                }),\n          })),\n          deleted: orphans.map((o) => rel(o.path)),\n          ...(recovered === null ? {} : { recovered }),\n        });\n        return;\n      }\n\n      if (recovered !== null) console.log(`${sayRecovered(recovered)}\\n`);\n      render(actions, {\n        service,\n        root: rel(root),\n        absRoot: root,\n        featureId: scope.mode === \"feature\" ? scope.featureId : null,\n        dryRun,\n        activeIds,\n        writes: writes.length,\n        orphans: orphans.map((o) => o.path),\n      });\n    });\n}\n"]}

package/dist/commands/gherkin/reconcile.js

@@ -0,0 +1,146 @@
+/**
+ * The plan against what is already on disk: which files are orphans, which are
+ * written, replaced, kept, or owned by another feature.
+ *
+ * A module of its own because it is the only part of `loam gherkin` that
+ * DELETES, and the reasoning that makes deletion safe is all here: a candidate
+ * is an orphan only when its containing directory really resolves inside the
+ * owned root, and a root that does not resolve proves nothing about what lives
+ * beneath it, so nothing is collected. Leaving an orphan behind is
+ * self-repairing — `loam validate` grades it and the next run removes it — and a
+ * deletion taken on an unproven path is not.
+ *
+ * The in-flight exemption is here for the same reason: files are named by
+ * requirement slug in both modes, so a MODIFIED requirement's living emission
+ * always collides with the active feature's file, and replacing it reverted the
+ * delta's wording mid-flight with its digest stamps destroyed.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import {} from "../../core/gherkin/emit.js";
+import { parseStampedFeature } from "../../core/gherkin/read.js";
+import { featureFilesUnder } from "../../core/gherkin/stale.js";
+import { isPathInside, resolveInside } from "../../core/kernel/path-safety.js";
+export async function reconcile(plan, where, scope, activeIds) {
+    const { root, repoDir } = where;
+    // Orphans of THIS scope, inside loam/ and nowhere else. Feature mode owns
+    // only its own emissions: stamped files carrying this feature's tag whose
+    // file is no longer in the plan (a requirement renamed or dropped).
+    // Living mode owns the whole suite — any .feature not in the plan goes —
+    // EXCEPT files tagged with a feature still in flight: those answer to
+    // their feature's delta until it archives, and `loam gherkin <FEAT>` is
+    // their regeneration.
+    const planned = new Set(plan.map((f) => f.fileName));
+    // "Inside loam/" has to hold after the links are resolved, not merely in
+    // the spelling of the path. `featureFilesUnder` FOLLOWS symlinks and
+    // recurses with the LINK's path, so a planted `<gherkinDir>/loam/sub ->
+    // /outside` hands back candidates that read as ours while `unlink`
+    // resolves them and destroys files that were never in this repo. Planned
+    // names are flat, so nothing nested is ever spared by `planned.has(...)`,
+    // and deletion is the one irreversible thing this command does: a
+    // candidate is an orphan only when its CONTAINING directory really
+    // resolves inside the owned root. The write path below refuses the same
+    // attack for the same reason.
+    //
+    // The candidate FILE is deliberately NOT resolved. A symlinked .feature
+    // sitting directly in loam/ is loam's to remove — unlinking it takes the
+    // link and leaves its target alone — so only the directory chain has to
+    // be ours.
+    const realOrNull = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return null;
+        }
+    };
+    // A root that does not resolve — absent, dangling, or vanished mid-run —
+    // proves nothing about what lives beneath it, so nothing is collected.
+    // Leaving an orphan behind is self-repairing (`loam validate` grades it
+    // `gherkin.orphaned` and the next run removes it); a deletion taken on an
+    // unproven path is not.
+    const rootReal = realOrNull(root);
+    const orphans = [];
+    if (rootReal !== null) {
+        for (const abs of await featureFilesUnder(root)) {
+            if (planned.has(relative(root, abs).split(/[\\/]/).join("/")))
+                continue;
+            const holder = realOrNull(dirname(abs));
+            if (holder === null || !isPathInside(rootReal, holder))
+                continue;
+            const raw = await readFile(abs);
+            const stamped = parseStampedFeature(raw.toString("utf8"));
+            if (scope.mode === "feature") {
+                if (stamped !== null && stamped.tags.includes(scope.featureId))
+                    orphans.push({ path: abs, raw });
+            }
+            else {
+                if (stamped !== null && stamped.tags.some((t) => activeIds.has(t)))
+                    continue;
+                orphans.push({ path: abs, raw });
+            }
+        }
+    }
+    // The in-flight exemption guards the OVERWRITE path too, not only the
+    // orphan scan above: files are named by requirement slug in both modes,
+    // so a MODIFIED requirement's living emission always collides with the
+    // active feature's file — and replacing it reverted the delta's wording
+    // mid-flight, feature tag and new digest stamps destroyed, invisibly
+    // (the reverted file grades current against the living spec). A planned
+    // path whose existing content is stamped and tagged with a feature still
+    // in flight is KEPT and reported as such; it answers to its feature's
+    // delta until the feature archives, and then living regeneration
+    // replaces it normally.
+    //
+    // FEATURE mode has the same collision and cannot solve it by keeping:
+    // two features in flight against one requirement slug want the same
+    // file, and whichever runs second used to `replace` — silently reverting
+    // the other feature's wording, feature tag and digest stamps, so its
+    // `verify --results` could never confirm a scenario again. Nothing loam
+    // can write is right here (the file holds ONE feature's delta), so the
+    // run refuses and names the owner: the two features have to be sequenced,
+    // or the requirement renamed.
+    const actions = [];
+    for (const f of plan) {
+        // Check the final file as well as the owned root: a pre-planted
+        // `<slug>.feature` symlink must not turn writeFile into an overwrite
+        // outside the repository. The UnsafePathError is left to escape: the one
+        // caller (./gherkin.ts) refuses it as `invalid-option`, and a catch here
+        // could only rethrow it.
+        const path = resolveInside(repoDir, relative(repoDir, join(root, f.fileName)), `gherkin file '${f.fileName}'`);
+        if (!existsSync(path)) {
+            actions.push({ ...f, path, action: "written" });
+            continue;
+        }
+        const raw = await readFile(path);
+        const existing = parseStampedFeature(raw.toString("utf8"));
+        if (scope.mode === "living") {
+            if (existing !== null && existing.tags.some((t) => activeIds.has(t))) {
+                actions.push({ ...f, path, action: "kept", kept: existing });
+                continue;
+            }
+        }
+        else if (existing !== null) {
+            // An unstamped file is nobody's delta — it owns nothing, so it is
+            // replaced like any other, which is what the empty owner list used
+            // to say the long way round.
+            const owners = existing.tags.filter((t) => t !== scope.featureId && activeIds.has(t));
+            if (owners.length > 0) {
+                actions.push({ ...f, path, action: "conflict", kept: existing, owners });
+                continue;
+            }
+        }
+        actions.push({ ...f, path, action: "replaced", raw });
+    }
+    // All or nothing: one conflicting file refuses the whole emission, so a
+    // half-written suite can never be the state an agent has to reason about.
+    // Only a feature run can conflict — living mode keeps the in-flight file
+    // rather than refusing — and standing inside that scope is also how the
+    // message names the feature without asserting there is one.
+    const conflicts = scope.mode === "feature"
+        ? actions.filter((a) => a.action === "conflict")
+        : [];
+    return { orphans, actions, conflicts };
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/commands/gherkin/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../../../src/commands/gherkin/reconcile.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The plan against what is already on disk: which files are orphans, which are\n * written, replaced, kept, or owned by another feature.\n *\n * A module of its own because it is the only part of `loam gherkin` that\n * DELETES, and the reasoning that makes deletion safe is all here: a candidate\n * is an orphan only when its containing directory really resolves inside the\n * owned root, and a root that does not resolve proves nothing about what lives\n * beneath it, so nothing is collected. Leaving an orphan behind is\n * self-repairing — `loam validate` grades it and the next run removes it — and a\n * deletion taken on an unproven path is not.\n *\n * The in-flight exemption is here for the same reason: files are named by\n * requirement slug in both modes, so a MODIFIED requirement's living emission\n * always collides with the active feature's file, and replacing it reverted the\n * delta's wording mid-flight with its digest stamps destroyed.\n */\nimport { existsSync, realpathSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { dirname, join, relative } from \"node:path\";\nimport { type PlannedFeature } from \"../../core/gherkin/emit.js\";\nimport { parseStampedFeature, type StampedFeature } from \"../../core/gherkin/read.js\";\nimport { featureFilesUnder } from \"../../core/gherkin/stale.js\";\nimport { isPathInside, resolveInside } from \"../../core/kernel/path-safety.js\";\n\n/**\n * The run's scope as ONE value, not a mode with an id lying beside it that only\n * one of the modes ever fills in: the emission tag, the orphan filter, the\n * overwrite rule and the conflict refusal all want the feature id exactly when\n * the run is a feature run. A union states that; two variables could only be\n * asserted to agree.\n */\nexport type Scope = { mode: \"living\" } | { mode: \"feature\"; featureId: string };\n\nexport type Emission = PlannedFeature & { path: string };\n\n/**\n * The row's shape follows its action instead of carrying every field any action\n * might want: only a kept or a conflicting row has read the file that is\n * already there, and only a conflicting one has owners. Held as one flat row\n * with optional fields, every reader had to assert what the writer three lines\n * up already knew.\n */\nexport type ActionRow =\n  | (Emission & { action: \"written\" })\n  // A replaced row carries the exact bytes it was graded against, so the\n  // commit can prove the file did not move between the grading and the swap —\n  // planning and committing must compare the same read, or a mismatch is\n  // buried instead of refused.\n  | (Emission & { action: \"replaced\"; raw: Buffer })\n  | (Emission & { action: \"kept\"; kept: StampedFeature })\n  | (Emission & { action: \"conflict\"; kept: StampedFeature; owners: string[] });\n\nexport type Action = ActionRow[\"action\"];\n\n/** Where the suite lives: the owned root, inside the service repository. */\nexport interface EmissionRoot {\n  root: string;\n  repoDir: string;\n}\n\nexport interface Reconciliation {\n  /** Each orphan with the bytes its grading read — the commit compares them before deleting. */\n  orphans: { path: string; raw: Buffer }[];\n  actions: ActionRow[];\n  /** Non-empty only in feature mode; one entry refuses the whole emission. */\n  conflicts: Extract<ActionRow, { action: \"conflict\" }>[];\n}\n\nexport async function reconcile(\n  plan: PlannedFeature[],\n  where: EmissionRoot,\n  scope: Scope,\n  activeIds: ReadonlySet<string>,\n): Promise<Reconciliation> {\n  const { root, repoDir } = where;\n  // Orphans of THIS scope, inside loam/ and nowhere else. Feature mode owns\n  // only its own emissions: stamped files carrying this feature's tag whose\n  // file is no longer in the plan (a requirement renamed or dropped).\n  // Living mode owns the whole suite — any .feature not in the plan goes —\n  // EXCEPT files tagged with a feature still in flight: those answer to\n  // their feature's delta until it archives, and `loam gherkin <FEAT>` is\n  // their regeneration.\n  const planned = new Set(plan.map((f) => f.fileName));\n  // \"Inside loam/\" has to hold after the links are resolved, not merely in\n  // the spelling of the path. `featureFilesUnder` FOLLOWS symlinks and\n  // recurses with the LINK's path, so a planted `<gherkinDir>/loam/sub ->\n  // /outside` hands back candidates that read as ours while `unlink`\n  // resolves them and destroys files that were never in this repo. Planned\n  // names are flat, so nothing nested is ever spared by `planned.has(...)`,\n  // and deletion is the one irreversible thing this command does: a\n  // candidate is an orphan only when its CONTAINING directory really\n  // resolves inside the owned root. The write path below refuses the same\n  // attack for the same reason.\n  //\n  // The candidate FILE is deliberately NOT resolved. A symlinked .feature\n  // sitting directly in loam/ is loam's to remove — unlinking it takes the\n  // link and leaves its target alone — so only the directory chain has to\n  // be ours.\n  const realOrNull = (p: string): string | null => {\n    try {\n      return realpathSync(p);\n    } catch {\n      return null;\n    }\n  };\n  // A root that does not resolve — absent, dangling, or vanished mid-run —\n  // proves nothing about what lives beneath it, so nothing is collected.\n  // Leaving an orphan behind is self-repairing (`loam validate` grades it\n  // `gherkin.orphaned` and the next run removes it); a deletion taken on an\n  // unproven path is not.\n  const rootReal = realOrNull(root);\n  const orphans: { path: string; raw: Buffer }[] = [];\n  if (rootReal !== null) {\n    for (const abs of await featureFilesUnder(root)) {\n      if (planned.has(relative(root, abs).split(/[\\\\/]/).join(\"/\"))) continue;\n      const holder = realOrNull(dirname(abs));\n      if (holder === null || !isPathInside(rootReal, holder)) continue;\n      const raw = await readFile(abs);\n      const stamped = parseStampedFeature(raw.toString(\"utf8\"));\n      if (scope.mode === \"feature\") {\n        if (stamped !== null && stamped.tags.includes(scope.featureId)) orphans.push({ path: abs, raw });\n      } else {\n        if (stamped !== null && stamped.tags.some((t) => activeIds.has(t))) continue;\n        orphans.push({ path: abs, raw });\n      }\n    }\n  }\n\n  // The in-flight exemption guards the OVERWRITE path too, not only the\n  // orphan scan above: files are named by requirement slug in both modes,\n  // so a MODIFIED requirement's living emission always collides with the\n  // active feature's file — and replacing it reverted the delta's wording\n  // mid-flight, feature tag and new digest stamps destroyed, invisibly\n  // (the reverted file grades current against the living spec). A planned\n  // path whose existing content is stamped and tagged with a feature still\n  // in flight is KEPT and reported as such; it answers to its feature's\n  // delta until the feature archives, and then living regeneration\n  // replaces it normally.\n  //\n  // FEATURE mode has the same collision and cannot solve it by keeping:\n  // two features in flight against one requirement slug want the same\n  // file, and whichever runs second used to `replace` — silently reverting\n  // the other feature's wording, feature tag and digest stamps, so its\n  // `verify --results` could never confirm a scenario again. Nothing loam\n  // can write is right here (the file holds ONE feature's delta), so the\n  // run refuses and names the owner: the two features have to be sequenced,\n  // or the requirement renamed.\n  const actions: ActionRow[] = [];\n  for (const f of plan) {\n    // Check the final file as well as the owned root: a pre-planted\n    // `<slug>.feature` symlink must not turn writeFile into an overwrite\n    // outside the repository. The UnsafePathError is left to escape: the one\n    // caller (./gherkin.ts) refuses it as `invalid-option`, and a catch here\n    // could only rethrow it.\n    const path = resolveInside(\n      repoDir,\n      relative(repoDir, join(root, f.fileName)),\n      `gherkin file '${f.fileName}'`,\n    );\n    if (!existsSync(path)) {\n      actions.push({ ...f, path, action: \"written\" });\n      continue;\n    }\n    const raw = await readFile(path);\n    const existing = parseStampedFeature(raw.toString(\"utf8\"));\n    if (scope.mode === \"living\") {\n      if (existing !== null && existing.tags.some((t) => activeIds.has(t))) {\n        actions.push({ ...f, path, action: \"kept\", kept: existing });\n        continue;\n      }\n    } else if (existing !== null) {\n      // An unstamped file is nobody's delta — it owns nothing, so it is\n      // replaced like any other, which is what the empty owner list used\n      // to say the long way round.\n      const owners = existing.tags.filter((t) => t !== scope.featureId && activeIds.has(t));\n      if (owners.length > 0) {\n        actions.push({ ...f, path, action: \"conflict\", kept: existing, owners });\n        continue;\n      }\n    }\n    actions.push({ ...f, path, action: \"replaced\", raw });\n  }\n\n  // All or nothing: one conflicting file refuses the whole emission, so a\n  // half-written suite can never be the state an agent has to reason about.\n  // Only a feature run can conflict — living mode keeps the in-flight file\n  // rather than refusing — and standing inside that scope is also how the\n  // message names the feature without asserting there is one.\n  const conflicts = scope.mode === \"feature\"\n    ? actions.filter((a): a is Extract<ActionRow, { action: \"conflict\" }> => a.action === \"conflict\")\n    : [];\n\n  return { orphans, actions, conflicts };\n}\n"]}

package/dist/commands/gherkin/render.js

@@ -0,0 +1,77 @@
+/**
+ * The emission as a person reads it.
+ *
+ * A module of its own for `adopt/render.ts`'s reason: `--json` already carries
+ * every field below, so this decides only how they read — and the two
+ * per-scenario warnings are why that is worth separating. Both name something
+ * in a scenario body that did NOT survive into the emission, while the file
+ * that came out is valid Gherkin and the summary line counts it like any other.
+ * They are the only place those losses are visible at all, so they must not
+ * share a module with the write path that can grow past them.
+ */
+import { relative } from "node:path";
+import {} from "./reconcile.js";
+/**
+ * `conflict` never reaches the renderer — the run refuses before it — but the
+ * map is total so a future action cannot silently print `undefined`.
+ */
+const VERB = {
+    written: "write  ",
+    replaced: "replace",
+    kept: "keep   ",
+    conflict: "CONFLICT",
+};
+/** Every per-scenario loss, in one shape: what was written, and what became of it. */
+const LOSSES = [
+    {
+        of: (a) => (a.action === "kept" ? [] : a.stepless),
+        why: "has NO recognizable steps — cucumber runs it vacuously green and `verify --results` can never " +
+            "confirm it; reword its body as `- **Given/When/Then**` bullets",
+    },
+    {
+        of: (a) => (a.action === "kept" ? [] : a.malformedExamples),
+        why: "has a table loam could not read as Examples — every row must have the header's column count, " +
+            "and a header needs at least one row under it. It stayed in the description, so this scenario " +
+            "runs ONCE, not once per case",
+    },
+    {
+        of: (a) => (a.action === "kept" ? [] : a.strandedBlocks),
+        why: "wrote a fenced block or an indented table where no step precedes it, or a table loam could " +
+            "not read — it stayed in the description, so the step definition receives NO payload and no " +
+            "data table; put the block under the step it belongs to and give every row equal columns",
+    },
+];
+export function render(actions, ctx) {
+    const { service, root, dryRun, featureId } = ctx;
+    const head = featureId === null ? `${service} (living suite)` : `${featureId} · ${service}`;
+    console.log(`gherkin ${head} → ${root}/${dryRun ? "  (dry run)" : ""}\n`);
+    if (actions.length === 0) {
+        console.log(featureId === null
+            ? `  the living specs hold no requirements for ${service} — nothing to emit.`
+            : `  ${featureId} has no ADDED or MODIFIED requirements for ${service} — nothing to emit.`);
+    }
+    for (const a of actions) {
+        if (a.action === "kept") {
+            const owners = a.kept.tags.filter((t) => ctx.activeIds.has(t));
+            console.log(`  keep     ${a.fileName}  —  ${a.requirement.name}  (in flight: @${owners.join(" @")} — \`loam gherkin ${owners[0]}\` regenerates it)`);
+            continue;
+        }
+        const n = a.digests.length;
+        const arch = a.axis.key === "archSpec" ? ", arch" : "";
+        console.log(`  ${VERB[a.action]}  ${a.fileName}  —  ${a.requirement.name}  (${n} scenario${n === 1 ? "" : "s"}${arch})`);
+        for (const loss of LOSSES) {
+            for (const name of loss.of(a))
+                console.log(`      ⚠ scenario '${name}' ${loss.why}`);
+        }
+    }
+    for (const o of ctx.orphans) {
+        console.log(`  delete   ${relative(ctx.absRoot, o).split(/[\\/]/).join("/")}  —  no longer in this scope`);
+    }
+    const wrote = `${ctx.writes} file(s)`;
+    const keptNote = actions.length > ctx.writes ? `, ${actions.length - ctx.writes} kept in flight` : "";
+    const dropped = ctx.orphans.length > 0 ? `, ${ctx.orphans.length} deletion(s)` : "";
+    console.log(dryRun
+        ? `\n  ${wrote}${keptNote}${dropped} — dry run, nothing was written.`
+        : `\n  ${wrote} written${keptNote}${dropped}. Write step definitions OUTSIDE ${root}/ — regeneration rewrites it.`);
+}
+//# sourceMappingURL=render.js.map

package/dist/commands/gherkin/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/commands/gherkin/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAA+B,MAAM,gBAAgB,CAAC;AAiB7D;;;GAGG;AACH,MAAM,IAAI,GAA2B;IACnC,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,SAAS;IACnB,IAAI,EAAE,SAAS;IACf,QAAQ,EAAE,UAAU;CACrB,CAAC;AAEF,sFAAsF;AACtF,MAAM,MAAM,GAAG;IACb;QACE,EAAE,EAAE,CAAC,CAAY,EAAY,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACvE,GAAG,EACD,gGAAgG;YAChG,gEAAgE;KACnE;IACD;QACE,EAAE,EAAE,CAAC,CAAY,EAAY,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC;QAChF,GAAG,EACD,+FAA+F;YAC/F,+FAA+F;YAC/F,8BAA8B;KACjC;IACD;QACE,EAAE,EAAE,CAAC,CAAY,EAAY,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;QAC7E,GAAG,EACD,6FAA6F;YAC7F,6FAA6F;YAC7F,yFAAyF;KAC5F;CACF,CAAC;AAEF,MAAM,UAAU,MAAM,CAAC,OAAoB,EAAE,GAAkB;IAC7D,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC;IACjD,MAAM,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,MAAM,OAAO,EAAE,CAAC;IAC5F,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,MAAM,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CACT,SAAS,KAAK,IAAI;YAChB,CAAC,CAAC,+CAA+C,OAAO,qBAAqB;YAC7E,CAAC,CAAC,KAAK,SAAS,8CAA8C,OAAO,qBAAqB,CAC7F,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAC/D,OAAO,CAAC,GAAG,CACT,cAAc,CAAC,CAAC,QAAQ,QAAQ,CAAC,CAAC,WAAW,CAAC,IAAI,kBAAkB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,MAAM,CAAC,CAAC,CAAC,oBAAoB,CACxI,CAAC;YACF,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QAC3B,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,OAAO,CAAC,GAAG,CACT,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,QAAQ,CAAC,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,GAAG,CAC5G,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAC1B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,cAAc,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;IAC7G,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,GAAG,CAAC,MAAM,UAAU,CAAC;IACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;IACtG,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,OAAO,CAAC,MAAM,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,OAAO,CAAC,GAAG,CACT,MAAM;QACJ,CAAC,CAAC,OAAO,KAAK,GAAG,QAAQ,GAAG,OAAO,kCAAkC;QACrE,CAAC,CAAC,OAAO,KAAK,WAAW,QAAQ,GAAG,OAAO,oCAAoC,IAAI,+BAA+B,CACrH,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The emission as a person reads it.\n *\n * A module of its own for `adopt/render.ts`'s reason: `--json` already carries\n * every field below, so this decides only how they read — and the two\n * per-scenario warnings are why that is worth separating. Both name something\n * in a scenario body that did NOT survive into the emission, while the file\n * that came out is valid Gherkin and the summary line counts it like any other.\n * They are the only place those losses are visible at all, so they must not\n * share a module with the write path that can grow past them.\n */\nimport { relative } from \"node:path\";\nimport { type Action, type ActionRow } from \"./reconcile.js\";\n\n/** What the text view needs that the plan does not carry. */\nexport interface RenderContext {\n  service: string;\n  /** Repo-relative `<gherkinDir>/loam/`. */\n  root: string;\n  /** Absolute suite root — orphan paths are printed relative to it. */\n  absRoot: string;\n  featureId: string | null;\n  dryRun: boolean;\n  /** Feature ids still in flight, for naming who owns a kept file. */\n  activeIds: Set<string>;\n  writes: number;\n  orphans: string[];\n}\n\n/**\n * `conflict` never reaches the renderer — the run refuses before it — but the\n * map is total so a future action cannot silently print `undefined`.\n */\nconst VERB: Record<Action, string> = {\n  written: \"write  \",\n  replaced: \"replace\",\n  kept: \"keep   \",\n  conflict: \"CONFLICT\",\n};\n\n/** Every per-scenario loss, in one shape: what was written, and what became of it. */\nconst LOSSES = [\n  {\n    of: (a: ActionRow): string[] => (a.action === \"kept\" ? [] : a.stepless),\n    why:\n      \"has NO recognizable steps — cucumber runs it vacuously green and `verify --results` can never \" +\n      \"confirm it; reword its body as `- **Given/When/Then**` bullets\",\n  },\n  {\n    of: (a: ActionRow): string[] => (a.action === \"kept\" ? [] : a.malformedExamples),\n    why:\n      \"has a table loam could not read as Examples — every row must have the header's column count, \" +\n      \"and a header needs at least one row under it. It stayed in the description, so this scenario \" +\n      \"runs ONCE, not once per case\",\n  },\n  {\n    of: (a: ActionRow): string[] => (a.action === \"kept\" ? [] : a.strandedBlocks),\n    why:\n      \"wrote a fenced block or an indented table where no step precedes it, or a table loam could \" +\n      \"not read — it stayed in the description, so the step definition receives NO payload and no \" +\n      \"data table; put the block under the step it belongs to and give every row equal columns\",\n  },\n];\n\nexport function render(actions: ActionRow[], ctx: RenderContext): void {\n  const { service, root, dryRun, featureId } = ctx;\n  const head = featureId === null ? `${service} (living suite)` : `${featureId} · ${service}`;\n  console.log(`gherkin ${head} → ${root}/${dryRun ? \"  (dry run)\" : \"\"}\\n`);\n  if (actions.length === 0) {\n    console.log(\n      featureId === null\n        ? `  the living specs hold no requirements for ${service} — nothing to emit.`\n        : `  ${featureId} has no ADDED or MODIFIED requirements for ${service} — nothing to emit.`,\n    );\n  }\n  for (const a of actions) {\n    if (a.action === \"kept\") {\n      const owners = a.kept.tags.filter((t) => ctx.activeIds.has(t));\n      console.log(\n        `  keep     ${a.fileName}  —  ${a.requirement.name}  (in flight: @${owners.join(\" @\")} — \\`loam gherkin ${owners[0]}\\` regenerates it)`,\n      );\n      continue;\n    }\n    const n = a.digests.length;\n    const arch = a.axis.key === \"archSpec\" ? \", arch\" : \"\";\n    console.log(\n      `  ${VERB[a.action]}  ${a.fileName}  —  ${a.requirement.name}  (${n} scenario${n === 1 ? \"\" : \"s\"}${arch})`,\n    );\n    for (const loss of LOSSES) {\n      for (const name of loss.of(a)) console.log(`      ⚠ scenario '${name}' ${loss.why}`);\n    }\n  }\n  for (const o of ctx.orphans) {\n    console.log(`  delete   ${relative(ctx.absRoot, o).split(/[\\\\/]/).join(\"/\")}  —  no longer in this scope`);\n  }\n  const wrote = `${ctx.writes} file(s)`;\n  const keptNote = actions.length > ctx.writes ? `, ${actions.length - ctx.writes} kept in flight` : \"\";\n  const dropped = ctx.orphans.length > 0 ? `, ${ctx.orphans.length} deletion(s)` : \"\";\n  console.log(\n    dryRun\n      ? `\\n  ${wrote}${keptNote}${dropped} — dry run, nothing was written.`\n      : `\\n  ${wrote} written${keptNote}${dropped}. Write step definitions OUTSIDE ${root}/ — regeneration rewrites it.`,\n  );\n}\n"]}