@milehimikey/em 1.19.7 → 1.20.0

package/dist/cli.js

@@ -14,11 +14,14 @@ import { renderDot, layoutDot, composeSvg, writeRendered, formatFromPath } from
 import { buildSliceDiagram } from "./render/sliceDiagram.js";
 import { resolveSliceArg, defaultSliceOut, defaultStorylineOut } from "./cli/render-inputs.js";
 import { buildStorylineDiagram, resolveStorylineArg } from "./render/storylineDiagram.js";
+import { embedStorylinePicker } from "./render/storylinePicker.js";
+import { resolveWatchStoryline, storylineFileFor, storylineVariants } from "./cli/watchStoryline.js";
 import { resolveSliceKey } from "./model/resolveSlice.js";
 import { serializeBuilds, watchFile } from "./render/watch.js";
 import { startLiveServer } from "./render/serve.js";
 import { formatDiagnostic, hasErrors, publicViewsWithoutInModelReader } from "./model/validate.js";
 import { buildExport, buildSliceExport, GENERATOR_VERSION } from "./emit/json.js";
+import { buildDocJsonExport } from "./emit/docJson.js";
 import { generateContract, runApiCheck, formatApiCheckText } from "./cli/api.js";
 import { buildApiCheckJson } from "./emit/apiCheckJson.js";
 import { buildValidateJson, buildShapeJson, buildSliceReadyJson, buildValidateListJson, collectMarkers } from "./emit/validateJson.js";
@@ -50,7 +53,7 @@ import { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
 import { buildLedgerJson } from "./emit/ledgerJson.js";
 import { buildRefsJson } from "./emit/refsJson.js";
 import { buildShapeReport, formatShapeText } from "./cli/shape.js";
-import { applyRefWaivers, checkRefs, readWaiveFile } from "./cli/refsCheck.js";
+import { applyRefWaivers, checkRatificationOrder, checkRefs, readWaiveFile } from "./cli/refsCheck.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";
@@ -89,7 +92,7 @@ import { listModelCommits } from "./cli/changelog-git.js";
 import { buildChangelogDoc } from "./cli/changelogBuild.js";
 import { runRevise } from "./cli/revise.js";
 import { runDefer, runDeferFromIssue } from "./cli/defer.js";
-import { runSliceConform, resolveFindingsForReport, findingsFilesOf, unruledAcrossFiles } from "./cli/sliceConform.js";
+import { runSliceConform, runSliceConformPreview, writePreviewFindings, resolveFindingsForReport, findingsFilesOf, unruledAcrossFiles, } from "./cli/sliceConform.js";
 import { checkPrdTriage, buildCheckPrdTriageJson, renderPrdTriageMarkdown, validatePrdTriage } from "./cli/prdTriage.js";
 import { checkFindingsFile, buildCheckFindingsJson, FINDING_LOCI } from "./cli/findings.js";
 import { STATE_FILE_NAME, PHASES, isPhase, loadStateFile, parseState, setPhase, setConformance, setModelVersion, setCertified, setEmVersion, setReview, isValidDateString, modelPathMismatch, } from "./cli/stateFile.js";
@@ -283,9 +286,35 @@ program
     .option("--slice <key>", "export only this slice's object (pattern/fields/doc) instead of the whole model (export " +
     "key, MIL-128) — refuses only if THIS slice has an error; an unrelated slice's breakage " +
     "elsewhere in the model doesn't block it (see docs/cli.md)")
+    .option("--doc-json", "emit the structured slice-doc export (GH #401) instead of the model snapshot: per slice the " +
+    "frontmatter join plus the parsed sections as data (fields, invariants, scenarios, error " +
+    "flows, open questions) and a model-level invariant catalog. Own schema version; whole " +
+    "model only (does not combine with --slice)")
+    .option("--include-html", "with --doc-json, include each slice doc's rendered HTML body (excluded by default; the " +
+    "authored body never appears in a plain export)")
     .action((file, opts) => {
     const { model, refs, diagnostics, source } = compileFile(file);
     printDiagnostics(diagnostics);
+    if (opts.docJson) {
+        if (opts.slice) {
+            console.error("em export --doc-json: exports the whole model and does not combine with --slice");
+            process.exit(1);
+        }
+        if (hasErrors(diagnostics)) {
+            console.error("not exporting: fix the errors above");
+            process.exit(1);
+        }
+        const exportedDoc = buildDocJsonExport(model, refs, diagnostics, source, file, { includeHtml: opts.includeHtml });
+        printDiagnostics(newDiagnostics(exportedDoc.diagnostics, diagnostics));
+        if (opts.out) {
+            writeFileSync(opts.out, exportedDoc.text + "\n");
+            console.log(`wrote ${opts.out}`);
+        }
+        else {
+            process.stdout.write(exportedDoc.text + "\n");
+        }
+        return;
+    }
     if (opts.slice) {
         // Scoped export deliberately does NOT reuse the whole-model error guard below: the
         // ticket's own motivation for `--slice` is an agent implementing one already-ratified
@@ -1088,7 +1117,10 @@ slice
     "later re-certification is normal — there's no way for em to tell 'later' from 'earlier' " +
     "for an arbitrary revision string, so there's no --force to reach for). Refuses when the " +
     "conformance/<date>[-<name>]-findings.json file matching --at still has an unruled finding in scope " +
-    "for this slice; --skip-findings-check overrides with a loud notice.")
+    "for this slice; --skip-findings-check overrides with a loud notice. GH #400: --preview runs the " +
+    "same doc-resolution and findings-check read for a slice that hasn't shipped yet — the shipped/" +
+    "implementedIn gates are waived and NOTHING is ever written to the doc; output is ephemeral " +
+    "(text or --json) unless --write-findings opts into persisting a normal findings file.")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
     .requiredOption("--at <rev>", "the target-repo revision this certification sweep diffed against — or, when what was exercised is not a commit " +
@@ -1096,12 +1128,31 @@ slice
     "`<kind>:<id>` such as build:1234 or deploy:eu-1-2026-10-15 (GH #261); recorded verbatim, skipped by git-reachability checks")
     .option("--on <date>", "certification date, YYYY-MM-DD (default: today, local date)")
     .option("--skip-findings-check", "certify even with unruled findings in scope — prints a loud notice on stderr")
+    .option("--preview", "GH #400: pre-ship advisory mode — waives the shipped-status/`implementedIn:` gates, writes NOTHING to the " +
+    "doc (no conformedVersion/conformedAt/conformedOn, ever); ephemeral by default, --write-findings opts " +
+    "into persisting a normal findings file. --skip-findings-check has no effect in this mode (preview " +
+    "never refuses on findings)")
+    .option("--write-findings", "with --preview: persist the preview's own unruled findings as conformance/<on>-<slice-key>-preview-findings.json")
+    .option("--json", "with --preview: print a JSON document instead of the text report")
     .action((file, sliceKey, opts) => {
+    if (opts.writeFindings === true && opts.preview !== true) {
+        console.error("em slice conform: --write-findings only applies with --preview");
+        process.exit(1);
+    }
+    if (opts.json === true && opts.preview !== true) {
+        console.error("em slice conform: --json only applies with --preview");
+        process.exit(1);
+    }
+    if (opts.preview === true && opts.skipFindingsCheck === true) {
+        console.error("em slice conform: --skip-findings-check has no effect with --preview (preview never blocks on findings)");
+        process.exit(1);
+    }
     const { model, refs, diagnostics } = compileFile(file);
     printDiagnostics(diagnostics);
     sliceKey = resolveSliceOrExit("em slice conform", model, refs, sliceKey);
     // Scoped the same way `em slice ratify`/`em slice revise`/`em slice mark-implemented` are:
-    // only an error concerning THIS slice refuses.
+    // only an error concerning THIS slice refuses. Not waived by --preview — an erroring model
+    // isn't a fact worth previewing against either.
     const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === sliceKey || r.startsWith(`${sliceKey}/`)));
     if (scopedErrors.length > 0) {
         console.error(`em slice conform: slice "${sliceKey}" has errors — fix them first`);
@@ -1113,6 +1164,44 @@ slice
         console.error(`em slice conform: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
         process.exit(1);
     }
+    if (opts.preview === true) {
+        const baseDir = dirname(file);
+        const result = runSliceConformPreview(model, refs, baseDir, sliceKey, opts.at);
+        if (!result.ok) {
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, message: result.message }, null, 2));
+            }
+            else {
+                console.error(`em slice conform --preview: ${result.message}`);
+            }
+            process.exit(1);
+        }
+        const writtenTo = opts.writeFindings === true ? writePreviewFindings(baseDir, file, sliceKey, result.at, on, result.unruledFindings) : null;
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                preview: true,
+                slice: sliceKey,
+                path: result.path,
+                status: result.status,
+                version: result.version,
+                at: result.at,
+                findingsFiles: result.findingsFiles,
+                unruledFindings: result.unruledFindings,
+                writtenTo,
+            }, null, 2));
+        }
+        else {
+            const findingsNote = result.unruledFindings.length === 0
+                ? result.findingsFiles.length === 0
+                    ? `no conformance findings file matches --at ${result.at} (conformance/<date>[-<name>]-findings.json with that revision)`
+                    : `no unruled conformance findings in scope (checked: ${result.findingsFiles.join(", ")})`
+                : `${result.unruledFindings.length} unruled conformance finding(s) in scope (id ${result.unruledFindings.map((f) => f.id).join(", ")}) in ${result.findingsFiles.join(", ")}`;
+            console.log(`preview: ${result.path} (status: ${result.status ?? "(empty)"}) @ ${result.at} — ${findingsNote}`);
+            console.log(writtenTo !== null ? `wrote: ${writtenTo}` : "ephemeral — nothing written; pass --write-findings to persist a snapshot");
+        }
+        return;
+    }
     const result = runSliceConform(model, refs, dirname(file), sliceKey, opts.at, on, opts.skipFindingsCheck === true);
     if (!result.ok) {
         console.error(`em slice conform: ${result.message}`);
@@ -1638,10 +1727,24 @@ program
     .option("--keep-empty-lanes", "keep the API lane even when empty")
     .option("--serve", "serve a live viewer with instant push-reload (no polling)")
     .option("--port <n>", "port for --serve (default 5173)", (v) => parseInt(v, 10))
+    .option("--storyline <name>", "GH #309 (deferred from #277): filter the live view to one storyline's subset — the same " +
+    "subset `em render --storyline` draws (its own slices in order, plus dimmed stub columns " +
+    "for what they read from outside it and the `after` end state). Whenever the model " +
+    "declares any storylines the viewer also offers a picker to switch to the full model or " +
+    "another declared storyline, live, without restarting. An unknown name errors, listing " +
+    "the declared storylines; requires --serve")
     .action(async (file, opts) => {
     const out = opts.out ?? defaultOut(file, opts.format ?? "svg");
     const fmt = opts.format ?? formatFromPath(out);
+    if (opts.storyline !== undefined && !opts.serve) {
+        console.error("em watch: --storyline applies only with --serve");
+        process.exit(1);
+    }
     let server;
+    // The file the printed live-view URL points at — basename(out) (the full model) unless
+    // --storyline resolves, in which case build() below points it at that storyline's own
+    // subset file instead (GH #309).
+    let liveFile = basename(out);
     // serializeBuilds: chokidar can fire several events for one save (and an
     // editor's write can land while a slow png/pdf render is still in flight) —
     // overlapping builds would race each other writing the same output file.
@@ -1662,7 +1765,40 @@ program
                 server?.notifyError(first ? formatDiagnostic(first).trim() : "model has errors — see terminal");
                 return;
             }
-            await renderDot(dot, model, grid, out, fmt, dirname(file));
+            // GH #309: --storyline is validated on every build, same as `em render --storyline`
+            // (resolveWatchStoryline shares findStoryline's resolution) — a save that renames or
+            // drops the storyline must not kill the watcher.
+            const resolved = resolveWatchStoryline(model, opts.storyline);
+            if ("error" in resolved) {
+                console.error(resolved.error);
+                server?.notifyError(resolved.error);
+                return;
+            }
+            if (opts.serve && fmt === "svg") {
+                const baseDir = dirname(file);
+                const outDir = dirname(out);
+                const outFile = basename(out);
+                liveFile = "storyline" in resolved ? storylineFileFor(resolved.storyline.name) : outFile;
+                // The full model, always rendered to `out` (unchanged default) — carries the
+                // storyline-picker metadata (a no-op when the model declares none) so the viewer can
+                // offer it regardless of whether --storyline was passed.
+                const fullRaw = await layoutDot(dot);
+                const fullSvg = embedStorylinePicker(composeSvg(fullRaw, model, grid, baseDir, outDir), storylineVariants(model, outFile, liveFile));
+                await writeRendered(fullSvg, out, "svg");
+                // Every declared storyline's own subset (GH #277's `em render --storyline` subset,
+                // reused verbatim) — rendered alongside the full model on every build, independent of
+                // --storyline, so the viewer's picker always has somewhere to navigate to.
+                for (const st of model.storylines ?? []) {
+                    const sub = buildStorylineDiagram(model, st, { keepEmptyLanes: opts.keepEmptyLanes });
+                    const subFile = storylineFileFor(st.name);
+                    const subRaw = await layoutDot(sub.dot);
+                    const subSvg = embedStorylinePicker(composeSvg(subRaw, sub.model, sub.grid, baseDir, outDir), storylineVariants(model, outFile, subFile));
+                    await writeRendered(subSvg, join(outDir, subFile), "svg");
+                }
+            }
+            else {
+                await renderDot(dot, model, grid, out, fmt, dirname(file));
+            }
             console.log(`rendered ${out} (${Date.now() - started}ms)`);
             server?.notify();
         }
@@ -1680,7 +1816,7 @@ program
             // The viewer inlines SVG only — for png/pdf watches there's nothing
             // live to embed, so don't print a ?svg= URL that can't work.
             if (fmt === "svg") {
-                console.log(`→ live view: ${server.url}/?svg=${encodeURIComponent(basename(out))}`);
+                console.log(`→ live view: ${server.url}/?svg=${encodeURIComponent(liveFile)}`);
                 console.log("  open it in a browser and share your screen");
             }
             else {
@@ -1938,6 +2074,10 @@ program
     .requiredOption("--reachable-from <rev>", "the branch or commit every ref must be an ancestor of (e.g. origin/main)")
     .option("--waive <slice-key>", "excuse this slice's non-ancestor/unresolved/undecidable results from the exit code (repeatable); still reported", (value, previous) => [...previous, value], [])
     .option("--waive-file <path>", "a baseline file of slice keys to waive, one per line (`#` comments allowed); missing file = no waivers")
+    .option("--check-order", "advisory-only (GH #399): for every slice doc with a ratifiedRef, report whether a commit between the branch's " +
+    "fork point and ratifiedRef already touched code other than the doc itself — a retrofit signal for inline " +
+    "ratification (spec written to describe code that already exists). History is rewritable, so this NEVER " +
+    "affects the exit code or `ok`, and is never a validate gate — see docs/process.md's inline-ratification section")
     .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
     .action((file, opts) => {
     const { model, refs } = compileFile(file);
@@ -1953,8 +2093,11 @@ program
     }
     if (result.shallow)
         console.error("warn: shallow clone — every ref is undecidable; check out with fetch-depth: 0");
+    // GH #399: computed only with --check-order, and never folded into `result`/`result.ok` —
+    // it is a sibling report, not a new ref field, and must never move the exit code (R5).
+    const orderResults = opts.checkOrder ? checkRatificationOrder(model, refs, dirname(file), result.target, result.shallow) : null;
     if (opts.json) {
-        process.stdout.write(buildRefsJson(result, file) + "\n");
+        process.stdout.write(buildRefsJson(result, file, orderResults) + "\n");
     }
     else {
         for (const r of result.results) {
@@ -1971,8 +2114,19 @@ program
         else {
             console.log(`${bad} ref(s) not reachable from ${opts.reachableFrom} (${result.checkedRefs} checked on ${result.checkedDocs} doc(s)${waivedNote})`);
         }
+        if (orderResults) {
+            console.log("");
+            console.log("ratification order (advisory — never affects exit code):");
+            if (orderResults.length === 0) {
+                console.log("  no slice doc carries a ratifiedRef to check");
+            }
+            for (const o of orderResults) {
+                console.log(`  ${o.status.padEnd(23)} ${o.sliceKey} ratifiedRef: ${o.ratifiedRef}${o.detail ? ` — ${o.detail}` : ""}`);
+            }
+        }
     }
     // Set the code rather than process.exit(): stdout to a pipe shouldn't risk truncation.
+    // `orderResults` never participates — advisory only, per R5.
     if (!result.ok)
         process.exitCode = 1;
 });