@milehimikey/em 1.13.0 → 1.13.1

package/dist/cli.js

@@ -34,7 +34,7 @@ import { detectSliceDocCollisions } from "./catalog/modelCollisionValidate.js";
 import { checkLedger, readLedgerWaiverTrailers, applyLedgerWaivers } from "./cli/ledgerCheck.js";
 import { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
 import { buildLedgerJson } from "./emit/ledgerJson.js";
-import { buildCoverageReport, resolveScopedSlices } from "./cli/coverage.js";
+import { buildCoverageReport, resolveScopedSlices, resolveCoverageSliceKey } from "./cli/coverage.js";
 import { buildCoverageJson } from "./emit/coverageJson.js";
 import { resolveSliceStatusFacts, countOpenIssues, resolveConformanceEntry, aggregateInvariantTotals, buildStatusReport, formatStatusText, formatStatusMarkdown, buildStatusBadge, formatConformancePart, findSpecifyRoot, resolveModelVersionStatusEntry, resolveEmVersionStatusEntry, } from "./cli/status.js";
 import { buildStatusJson } from "./emit/statusJson.js";
@@ -646,8 +646,12 @@ slice
     .command("ratify")
     .description("flip a slice doc's frontmatter to `status: ready-to-implement` and record `ratifiedBy:`/" +
     "`ratifiedOn:` — the handoff sign-off (MIL-165, docs/process.md#the-slice-lifecycle-gates) " +
-    "that makes who ratified, and when, a first-class recorded fact. Refuses a doc that never " +
-    "passed the review gate (`em slice review`) unless --skip-review is passed. Idempotent on " +
+    "that makes who ratified, and when, a first-class recorded fact. The review gate is a check " +
+    "on the doc's current `status:`, not on whether `reviewedBy:`/`reviewedOn:` are populated: " +
+    "a doc at `reviewed` or `ready-to-implement` passes (the latter is where `em slice " +
+    "reratify` leaves a doc, so the follow-up ratify needs no --skip-review); any other status " +
+    "— a `draft` that never went through `em slice review` — is refused unless --skip-review " +
+    "is passed. Idempotent on " +
     "the same --by/--on pair; refuses to overwrite a different one already recorded; never " +
     "touches `version:` or the doc body")
     .argument("<file>", "input .em file")
@@ -697,7 +701,10 @@ slice
     .command("reratify")
     .description("bump `version:` and flip a shipped slice doc's frontmatter back to `status: " +
     "ready-to-implement` — the re-ratification mechanical edit (MIL-161, mirrors `em slice " +
-    "mark-implemented`). Only applies to a doc at `status: implemented`; clears any stale " +
+    "mark-implemented`). Applies to a doc at `status: implemented`, or (MIL-258) to a " +
+    "`ready-to-implement` doc that is ratified but not yet shipped — there it bumps `version:` " +
+    "and clears the sign-off but leaves `status:` alone; a `ready-to-implement` doc with no " +
+    "`ratifiedBy:` refuses (awaiting `em slice ratify --by`). Clears any stale " +
     "`ratifiedBy:`/`ratifiedOn:`/`reviewedBy:`/`reviewedOn:` (they describe the PRIOR version's " +
     "review and sign-off) so a follow-up `em slice ratify --by` applies cleanly — and needs no " +
     "fresh review; never touches `implementedIn:` or the doc body")
@@ -720,13 +727,20 @@ slice
     }
     // MIL-214: advisory only, never refuses — see reratify.ts's reratifyAdvisory. Both warnings
     // can fire together (a version that was never certified AND still carries unruled findings).
-    if (result.advisory.neverCertified) {
+    if (result.advisory?.neverCertified) {
         console.error(`warn: reratifying "${sliceKey}" whose v${result.newVersion - 1} was never certified`);
     }
-    if (result.advisory.unruledFindingsCount > 0) {
+    if (result.advisory && result.advisory.unruledFindingsCount > 0) {
         console.error(`warn: reratifying "${sliceKey}" has ${result.advisory.unruledFindingsCount} unruled conformance finding(s)`);
     }
-    console.log(`reratified: ${result.path} (version: ${result.newVersion}, status: ready-to-implement)`);
+    if (result.kind === "unshipped") {
+        // MIL-258: nothing was flipped — say what DID happen, and that the new version is unsigned.
+        console.log(`reratified: ${result.path} (version: ${result.newVersion - 1} -> ${result.newVersion}, sign-off cleared, ` +
+            `status unchanged: ready-to-implement) — not ratified until \`em slice ratify --by <name>\` records the new sign-off`);
+    }
+    else {
+        console.log(`reratified: ${result.path} (version: ${result.newVersion}, status: ready-to-implement)`);
+    }
     warnModelVersionDrift(dirname(file), model, refs, source, `reratifying "${sliceKey}"`);
 });
 slice
@@ -1509,9 +1523,13 @@ program
     "definition-of-done citation check; advisory by default, --strict for CI; " +
     "--include-ready also counts ready-to-implement docs (forward-looking report); a " +
     "continuation slice (an `again` view instance with no doc of its own, MIL-208) is excluded " +
-    "from the report — its invariants, if any, live in the originating slice's own doc")
+    "from the report — its invariants, if any, live in the originating slice's own doc; " +
+    "--slice <key> scopes the report to one slice whatever its status (MIL-255), the " +
+    "pre-merge definition-of-done check")
     .argument("<file>", "input .em file")
     .requiredOption("--tests <dir>", "directory to scan recursively for test files citing invariant IDs")
+    .option("--slice <key>", "only this slice (export key), whether ready-to-implement or implemented — no --include-ready needed; " +
+    "--strict then fails on this slice's uncited invariants, or if the slice is not in scope (draft/reviewed/unbound: nothing checked) (MIL-255)")
     .option("--strict", "exit non-zero if any invariant ID has zero citations (CI)")
     .option("--include-ready", "also count ready-to-implement docs, not just implemented (MIL-207)")
     .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
@@ -1524,11 +1542,25 @@ program
     }
     const baseDir = dirname(file);
     const includeReady = !!opts.includeReady;
+    // MIL-255: resolve --slice before anything else — an unknown key is an error (never a
+    // vacuously passing empty report), and a continuation key (MIL-208) scopes to its
+    // originating slice, which the output names (matching `em validate --slice-ready`).
+    let onlyKey;
+    let continuationOfKey = null;
+    if (opts.slice !== undefined) {
+        const target = resolveCoverageSliceKey(model, refs, opts.slice);
+        if (!target) {
+            console.error(`em coverage --slice: no slice with export key "${opts.slice}" in this model`);
+            process.exit(1);
+        }
+        onlyKey = target.key;
+        continuationOfKey = target.continuationOf;
+    }
     // MIL-207: a missing --tests dir is only a defect when something is actually in scope to
     // check — cheap to know without touching the test tree (resolveScopedSlices never reads
     // --tests). A fresh scaffold (or a doc-only ratification PR, with the MIL-207 default scope)
     // has zero implemented docs, so there's nothing yet for a test to cite.
-    const anyInScope = resolveScopedSlices(model, refs, baseDir, includeReady).some((s) => s.inScope);
+    const anyInScope = resolveScopedSlices(model, refs, baseDir, includeReady, onlyKey).some((s) => s.inScope);
     if (!existsSync(opts.tests)) {
         if (anyInScope) {
             console.error(`em coverage: --tests directory not found: ${opts.tests}`);
@@ -1540,17 +1572,36 @@ program
         console.error(`em coverage: --tests is not a directory: ${opts.tests}`);
         process.exit(1);
     }
-    const report = buildCoverageReport(model, refs, baseDir, opts.tests, includeReady);
+    const report = buildCoverageReport(model, refs, baseDir, opts.tests, includeReady, onlyKey);
+    // MIL-255: a scoped slice whose doc is draft/reviewed/unbound/unusable is out of scope — the
+    // same way the unscoped report treats it — but under --strict "nothing was checked" must not
+    // exit 0, or the pre-merge check passes vacuously (the very bug --slice exists to fix). So:
+    // advisory (no --strict) prints the note on stdout and exits 0; --strict prints it on stderr
+    // and exits 1 (also in --json mode, whose document shape is unchanged — consumers read the
+    // slice's `inScope` alongside `ok`). An in-scope doc with zero invariants stays a pass.
+    const unchecked = onlyKey === undefined ? undefined : report.slices.find((sl) => !sl.inScope);
+    const uncheckedNote = unchecked
+        ? `slice "${unchecked.key}" is not in scope (${unchecked.status ?? unchecked.docReason ?? "no doc"}) — nothing checked; only ready-to-implement/implemented docs are checked`
+        : null;
+    if (uncheckedNote !== null && (opts.strict || !opts.json)) {
+        (opts.strict ? console.error : console.log)(uncheckedNote);
+    }
     if (opts.json) {
-        process.stdout.write(buildCoverageJson(file, opts.tests, report, includeReady) + "\n");
+        const sliceScope = opts.slice === undefined ? null : { requested: opts.slice, continuationOf: continuationOfKey };
+        process.stdout.write(buildCoverageJson(file, opts.tests, report, includeReady, sliceScope) + "\n");
     }
     else {
+        if (continuationOfKey !== null) {
+            console.log(`slice "${opts.slice}" is a continuation of "${continuationOfKey}" — checking "${continuationOfKey}"`);
+        }
         for (const slice of report.slices) {
             if (!slice.inScope)
                 continue;
             console.log(`slice "${slice.key}" (${slice.status}):`);
             if (slice.invariants.length === 0) {
-                console.log(`  (no INV-* invariant IDs found in the doc body)`);
+                // MIL-255: said as "checked" so an in-scope doc defining zero invariants (a legitimate
+                // pass) is distinguishable from the "not in scope — nothing checked" case above.
+                console.log(`  (checked — the doc defines 0 INV-* invariant IDs)`);
                 continue;
             }
             for (const inv of slice.invariants) {
@@ -1569,7 +1620,7 @@ program
     // Advisory by default (exit 0 even with uncovered IDs) — --strict is the opt-in CI gate,
     // same "set exitCode, don't truncate stdout" rationale as em ledger/em diff for the --json
     // form, and consistent for the text form too.
-    if (opts.strict && report.uncoveredCount > 0)
+    if (opts.strict && (report.uncoveredCount > 0 || uncheckedNote !== null))
         process.exitCode = 1;
 });
 program
@@ -2115,7 +2166,7 @@ ci.command("init")
     "idempotent, --check for CI self-verification (MIL-166, see docs/ci.md)")
     .argument("<model>", "anchor .em file the coverage/ledger/slice-index/status steps point at")
     .option("--tests <dir>", "test directory the coverage/status steps scan for INV-* citations", "test")
-    .option("-f, --force", "replace an existing workflow file that has no GENERATED markers")
+    .option("-f, --force", "replace an existing workflow file that has no GENERATED markers, or a managed block generated for a different model")
     .option("--check", "verify both files match the current preset; exit non-zero on drift without writing (CI)")
     .action((model, opts) => {
     const unsafe = findUnsafeCiInitArg(model) ?? findUnsafeCiInitArg(opts.tests);
@@ -2137,10 +2188,17 @@ ci.command("init")
             planCiFile(conformPath, buildConformWorkflowFile(model, PKG_VERSION), conformManagedBody(model, PKG_VERSION), CONFORM_WORKFLOW_MARKER, !!opts.force),
         ],
     ];
+    // MIL-256 (#174): the managed block is single-model (multi-model: MIL-233). Another model's
+    // block is its own condition - never `stale`, never silently replaced.
+    const otherModel = (previous, path) => `${path} was generated for ${previous}, not ${model} - the managed block is single-model until multi-model support lands (MIL-233)`;
     if (opts.check) {
         let drift = false;
         for (const [path, status] of files) {
-            if (status.kind === "create") {
+            if (status.kind === "other-model" || status.kind === "replace-model") {
+                console.log(`different model: ${otherModel(status.previous, path)} (re-run \`em ci init ${model} --force\` to replace it)`);
+                drift = true;
+            }
+            else if (status.kind === "create") {
                 console.log(`missing: ${path} — run \`em ci init ${model}\` to create it`);
                 drift = true;
             }
@@ -2161,10 +2219,22 @@ ci.command("init")
             process.exitCode = 1;
         return;
     }
+    // Refuse before writing anything, so a refusal on one file never leaves the other updated.
+    const refused = files.filter(([, s]) => s.kind === "other-model");
+    if (refused.length > 0) {
+        for (const [path, status] of refused) {
+            if (status.kind === "other-model")
+                console.error(`em ci init: ${otherModel(status.previous, path)}; re-run with --force to replace it`);
+        }
+        process.exitCode = 1;
+        return;
+    }
     mkdirSync(dirname(ciPath), { recursive: true });
     for (const [path, status] of files) {
         applyCiFile(path, status);
-        if (status.kind === "create")
+        if (status.kind === "replace-model")
+            console.log(`replaced ${path} (--force; was generated for ${status.previous})`);
+        else if (status.kind === "create")
             console.log(`installed ${path}`);
         else if (status.kind === "stale")
             console.log(`updated ${path}`);
@@ -2185,7 +2255,7 @@ program
     "makes one git commit per applicable step, refusing on a dirty working tree")
     .argument("<file>", "input .em model file")
     .option("--apply", "apply every applicable mechanical step, one git commit each, then a final `Em version:` commit")
-    .option("--check", "exit non-zero only on a hard incompatibility (unparseable state file, an un-migratable .em shape) — writes nothing; what CI runs")
+    .option("--check", "exit non-zero only on a hard incompatibility (an existing but unparseable state file, an un-migratable .em shape) — writes nothing; what CI runs; the final line says why")
     .option("--json", "print a JSON document instead of text (dry-run/--check only, never with --apply)")
     .action((file, opts) => {
     if (opts.apply && opts.check) {
@@ -2223,14 +2293,15 @@ program
         refs,
     };
     if (opts.check) {
-        const { ok, report } = checkUpgrade(ctx);
+        const { ok, report, reasons } = checkUpgrade(ctx);
         console.error(`em upgrade --check: from ${report.from.version}${report.from.inferred ? ` (inferred: ${report.from.basis})` : ""} → to ${report.to}`);
         for (const s of report.steps) {
             console.error(`  [${s.applicable ? "x" : " "}] ${s.id} (since ${s.sinceVersion}): ${s.reason}`);
         }
         for (const h of report.human)
             console.error(`  human: ${h.id}: ${h.reason}`);
-        console.error(ok ? "ok — no hard incompatibility" : "em upgrade --check: hard incompatibility found");
+        // MIL-257: the final line always says why (previously visible only via --json).
+        console.error(ok ? "ok — no hard incompatibility" : `em upgrade --check: hard incompatibility found: ${reasons.join("; ")}`);
         if (!ok)
             process.exitCode = 1;
         return;