@milehimikey/em 1.6.1 → 1.7.0

package/dist/cli/skillVersionCheck.js

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+// MIL-92's version-stamp release gate: checks that package.json's `version` and SKILL.md's
+// `em-version:` frontmatter stamp move together across two revisions. Repo-internal — unlike
+// `em ledger` (MIL-89, src/cli/ledgerCheck.ts), which consumer repos run against their own
+// slice docs, this checks *this repo's own* package version against *this repo's own* bundled
+// skill, so it's never a shipped `em` subcommand — see scripts/check-skill-version-stamp.ts for
+// the thin CLI shim, and docs/ci.md's precedent framing for why a version/content-agreement
+// check needs two revisions rather than being folded into `em validate`.
+//
+// Both sides here are version strings compared for "did it move," not ledger's version-vs-
+// freeform-content comparison — the meaningful case is package.json's version changing without
+// the stamp following it (`skill-version-stamp-not-bumped`). Two more are flagged as cheap extra
+// coverage: a stray stamp edit with no matching package.json move (`-stray-bump`), and the
+// stamp being deleted outright (`-removed`, unconditional — regardless of whether package.json
+// also changed, since losing the mechanism entirely is a problem on its own; a code review on
+// this very PR caught an earlier version that silently skipped the pkgChanged+deleted-stamp
+// combination). The one case that stays clean rather than becoming a finding: the stamp's
+// first-ever introduction (no prior value to compare against) — the normal one-time bootstrap
+// of the field, not a stray edit (this check's own introducing PR, confirmed on CI, first).
+import { readFileSync } from "node:fs";
+import { realGit, resolveRevision } from "./diff-inputs.js";
+/** `to: null` reads the working tree directly (fs); a revision string resolves via git — same
+ *  `to: null` = working-tree convention `em diff`/`em ledger` use. */
+function readAt(path, rev, runGit) {
+    if (rev === null) {
+        try {
+            return { ok: true, content: readFileSync(path, "utf8") };
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+    const result = resolveRevision(path, rev, runGit);
+    return result.ok ? { ok: true, content: result.content } : { ok: false };
+}
+function extractPkgVersion(content) {
+    try {
+        const parsed = JSON.parse(content);
+        const version = parsed?.version;
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Pull `em-version: X` out of a `---\n...\n---` frontmatter block. Minimal and single-purpose
+ *  — SKILL.md's frontmatter is two plain scalar keys plus a folded `description:` block, not
+ *  the richer schema src/catalog/sliceDoc.ts parses, so this doesn't reuse that parser.
+ *  Exported for reuse by src/cli/skillCheck.ts (MIL-93), which needs the same extraction to
+ *  compare a vendored copy's stamp against the installed em's own version — no reason to
+ *  duplicate the regex a second time. */
+export function extractEmVersionStamp(content) {
+    const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatter)
+        return null;
+    const line = frontmatter[1].split("\n").find((l) => /^em-version:\s*/.test(l));
+    if (!line)
+        return null;
+    return line
+        .replace(/^em-version:\s*/, "")
+        .trim()
+        .replace(/^["']|["']$/g, "");
+}
+/**
+ * Compare `pkgJsonPath`'s version and `skillMdPath`'s `em-version:` stamp between revisions
+ * `from` and `to` (`to: null` = current working tree, matching `em diff`/`em ledger`). Pure
+ * aside from the injected `GitRunner` and fs reads — no process.exit, no console.
+ */
+export function checkSkillVersionStamp(pkgJsonPath, skillMdPath, from, to, runGit = realGit) {
+    const oldPkg = readAt(pkgJsonPath, from, runGit);
+    const newPkg = readAt(pkgJsonPath, to, runGit);
+    if (!oldPkg.ok || !newPkg.ok)
+        return { finding: null, skipped: "package-json-unreadable" };
+    const oldPkgVersion = extractPkgVersion(oldPkg.content);
+    const newPkgVersion = extractPkgVersion(newPkg.content);
+    if (oldPkgVersion === null || newPkgVersion === null)
+        return { finding: null, skipped: "package-json-unreadable" };
+    const oldSkill = readAt(skillMdPath, from, runGit);
+    const newSkill = readAt(skillMdPath, to, runGit);
+    if (!oldSkill.ok || !newSkill.ok)
+        return { finding: null, skipped: "skill-md-unreadable" };
+    const oldStamp = extractEmVersionStamp(oldSkill.content);
+    const newStamp = extractEmVersionStamp(newSkill.content);
+    // Never adopted anywhere in this revision span — nothing to compare. Distinct from the stamp
+    // being *removed* below: that's a regression, this is simply "the field doesn't exist yet."
+    if (oldStamp === null && newStamp === null)
+        return { finding: null, skipped: "stamp-missing" };
+    // The stamp's first-ever introduction (no em-version: key at `from`, one at `to`) has nothing
+    // to compare against either — not a stray edit, the normal one-time bootstrap of the field
+    // itself (e.g. this very check landing). Treat it as clean rather than a permanent
+    // false-positive on whichever PR happens to add the key.
+    if (oldStamp === null)
+        return { finding: null, skipped: null };
+    const pkgChanged = oldPkgVersion !== newPkgVersion;
+    // The stamp existed and is now gone entirely — a stronger signal than merely "left stale"
+    // (below), and one a naive "newStamp === null -> skip" early-out would otherwise swallow
+    // silently, including the worst case: package.json bumped in the very same change that
+    // deleted the stamp (caught in code review, MIL-92 PR #85 — no prior test combined
+    // pkgChanged: true with a deleted stamp). Always a finding, regardless of pkgChanged: removing
+    // the mechanism entirely is a problem on its own, not just when it coincides with a release.
+    if (newStamp === null) {
+        return {
+            skipped: null,
+            finding: {
+                code: "skill-version-stamp-removed",
+                message: pkgChanged
+                    ? `SKILL.md's em-version: stamp (was ${oldStamp}) was removed entirely while package.json bumped ${oldPkgVersion} -> ${newPkgVersion}`
+                    : `SKILL.md's em-version: stamp (was ${oldStamp}) was removed entirely`,
+                oldPkgVersion,
+                newPkgVersion,
+                oldStamp,
+                newStamp: null,
+            },
+        };
+    }
+    const stampChanged = oldStamp !== newStamp;
+    if (pkgChanged && !stampChanged) {
+        return {
+            skipped: null,
+            finding: {
+                code: "skill-version-stamp-not-bumped",
+                message: `package.json bumped ${oldPkgVersion} -> ${newPkgVersion} but SKILL.md's em-version: stamp stayed at ${newStamp}`,
+                oldPkgVersion,
+                newPkgVersion,
+                oldStamp,
+                newStamp,
+            },
+        };
+    }
+    if (!pkgChanged && stampChanged) {
+        return {
+            skipped: null,
+            finding: {
+                code: "skill-version-stamp-stray-bump",
+                message: `SKILL.md's em-version: stamp changed (${oldStamp ?? "(none)"} -> ${newStamp}) but package.json's version didn't move (still ${newPkgVersion})`,
+                oldPkgVersion,
+                newPkgVersion,
+                oldStamp,
+                newStamp,
+            },
+        };
+    }
+    return { finding: null, skipped: null };
+}
+//# sourceMappingURL=skillVersionCheck.js.map

package/dist/cli/skillVersionCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillVersionCheck.js","sourceRoot":"","sources":["../../src/cli/skillVersionCheck.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-export {};
+import { Command } from "commander";
+declare const program: Command;
+export { program };

package/dist/cli.js

@@ -6,6 +6,7 @@ import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { compile } from "./pipeline.js";
+import { isMainModule } from "./util/isMainModule.js";
 import { ParseError } from "./parser/parser.js";
 import { renderDot, layoutDot, composeSvg, writeRendered, formatFromPath } from "./render/render.js";
 import { buildSliceDiagram } from "./render/sliceDiagram.js";
@@ -16,7 +17,16 @@ import { formatDiagnostic, hasErrors } from "./model/validate.js";
 import { buildExport } from "./emit/json.js";
 import { buildDiffJson } from "./emit/diffJson.js";
 import { diffModels, formatModelDiff, hasChanges } from "./model/diff.js";
-import { planDiffArgs, resolveRevision } from "./cli/diff-inputs.js";
+import { planDiffArgs, resolveRevision, resolveDocAtRevision } from "./cli/diff-inputs.js";
+import { readSliceDoc } from "./catalog/readSliceDoc.js";
+import { validateLineage } from "./catalog/lineageValidate.js";
+import { validateFrontmatterCoherence } from "./catalog/frontmatterCoherenceValidate.js";
+import { validateSliceReady } from "./catalog/sliceReadyValidate.js";
+import { checkLedger } from "./cli/ledgerCheck.js";
+import { buildLedgerJson } from "./emit/ledgerJson.js";
+import { planSkillSync, applySkillSync } from "./cli/skillSync.js";
+import { checkSkillSync } from "./cli/skillCheck.js";
+import { buildSkillCheckJson } from "./emit/skillCheckJson.js";
 import { buildGlossary, detectKindConflicts, detectFieldTypeConflicts, hasConflicts, formatGlossarySummary, formatConflictLine, } from "./model/glossary.js";
 import { buildGlossaryJson } from "./emit/glossaryJson.js";
 import { planGlossaryArgs } from "./cli/glossary-inputs.js";
@@ -110,14 +120,14 @@ program
     .argument("<file>", "input .em file")
     .option("-o, --out <path>", "write to a file instead of stdout")
     .action((file, opts) => {
-    const { model, diagnostics, source } = compileFile(file);
+    const { model, refs, diagnostics, source } = compileFile(file);
     printDiagnostics(diagnostics);
     if (hasErrors(diagnostics)) {
         console.error("not exporting: fix the errors above");
         process.exit(1);
     }
-    const exported = buildExport(model, diagnostics, source, file);
-    printDiagnostics(exported.diagnostics.filter((d) => !diagnostics.includes(d)));
+    const exported = buildExport(model, refs, diagnostics, source, file);
+    printDiagnostics(newDiagnostics(exported.diagnostics, diagnostics));
     if (opts.out) {
         writeFileSync(opts.out, exported.text + "\n");
         console.log(`wrote ${opts.out}`);
@@ -144,14 +154,22 @@ program
     if (plan.form === "files") {
         const oldSource = readFileOrExit(plan.oldFile);
         const newSource = readFileOrExit(plan.newFile);
-        runDiff(oldSource, plan.oldFile, newSource, plan.newFile, opts.exitCode, opts.json);
+        const lineage = {
+            oldDoc: (key) => readSliceDoc(dirname(plan.oldFile), key),
+            newDoc: (key) => readSliceDoc(dirname(plan.newFile), key),
+        };
+        runDiff(oldSource, plan.oldFile, newSource, plan.newFile, opts.exitCode, opts.json, lineage);
         return;
     }
     const oldSource = readAtRevision(plan.file, plan.from);
     const oldLabel = `${plan.file}@${plan.from}`;
     const newSource = plan.to ? readAtRevision(plan.file, plan.to) : readFileOrExit(plan.file);
     const newLabel = plan.to ? `${plan.file}@${plan.to}` : plan.file;
-    runDiff(oldSource, oldLabel, newSource, newLabel, opts.exitCode, opts.json);
+    const lineage = {
+        oldDoc: (key) => resolveDocAtRevision(plan.file, key, plan.from),
+        newDoc: (key) => plan.to ? resolveDocAtRevision(plan.file, key, plan.to) : readSliceDoc(dirname(plan.file), key),
+    };
+    runDiff(oldSource, oldLabel, newSource, newLabel, opts.exitCode, opts.json, lineage);
 });
 program
     .command("glossary")
@@ -226,14 +244,20 @@ program
         process.exit(1);
     }
     const inputs = [];
+    // Tracked so the post-buildCatalog print below can skip diagnostics already printed
+    // here (ref-collision warnings now live in compileFile()'s own `diagnostics`, and
+    // buildCatalog() forwards those same, reference-identical objects rather than
+    // recomputing them — printing both lists unfiltered would double-print them).
+    const diagnosticsByFile = new Map();
     let anyErrors = false;
     for (const file of files) {
-        const { dot, model, grid, diagnostics } = compileFile(file, { keepEmptyLanes: opts.keepEmptyLanes });
+        const { dot, model, grid, diagnostics, refs } = compileFile(file, { keepEmptyLanes: opts.keepEmptyLanes });
         printDiagnosticsFor(file, diagnostics);
+        diagnosticsByFile.set(file, diagnostics);
         warnMissingNotes(file, model);
         if (hasErrors(diagnostics))
             anyErrors = true;
-        inputs.push({ file, model, grid, dot });
+        inputs.push({ file, model, grid, dot, refs });
     }
     if (anyErrors) {
         console.error("not building catalog: fix the errors above");
@@ -245,8 +269,10 @@ program
         title: opts.title,
         keepEmptyLanes: opts.keepEmptyLanes,
     });
-    for (const d of result.diagnostics)
-        printDiagnosticsFor(d.file, d.diagnostics);
+    for (const d of result.diagnostics) {
+        const already = diagnosticsByFile.get(d.file) ?? [];
+        printDiagnosticsFor(d.file, newDiagnostics(d.diagnostics, already));
+    }
     const modelWord = result.models === 1 ? "model" : "models";
     const sliceWord = result.slices === 1 ? "slice" : "slices";
     console.log(`wrote ${opts.out}/ (${result.models} ${modelWord}, ${result.slices} ${sliceWord})`);
@@ -331,31 +357,109 @@ program
     .argument("<file>", "input .em file")
     .option("--list-issues", "print only open `issue` diagnostics (slice, element, line, text)")
     .option("--list-divergences", "print only accepted-divergence annotations (slice, element, line, text) — never fails the build")
-    .option("--list-public", "print only events marked `public` (slice, name, line) — an integration-surface audit, never fails the build")
+    .option("--list-public", "print only events and views marked `public` (slice, kind, name, line) — an integration-surface audit, never fails the build")
     .option("--fail-on-issues", "exit non-zero if the model has any open `issue`s (opt-in — issues are warnings and don't block by default)")
+    .option("--slice-ready <key>", "readiness gate for one slice (export key): status ready-to-implement, doc resolvable via " +
+    "note binding, zero unchecked Open Questions — exits non-zero if not ready (MIL-87)")
     .action((file, opts) => {
-    const { model, diagnostics } = compileFile(file);
+    const { model, diagnostics, refs } = compileFile(file);
+    // Lineage-ref resolution (MIL-84) and frontmatter-coherence (MIL-85) are validate's
+    // fs-aware rules — every other check above is a pure function of the .em source. Both
+    // read slices/*.md alongside the model.
+    const allDiagnostics = [
+        ...diagnostics,
+        ...validateLineage(model, refs, dirname(file)),
+        ...validateFrontmatterCoherence(model, refs, dirname(file)),
+    ];
+    if (opts.sliceReady) {
+        // MIL-87: a targeted, single-slice readiness gate, not part of the unconditional
+        // diagnostic set above (see sliceReadyValidate.ts's header for why). Folds in MIL-85's
+        // frontmatter-coherence findings for free by filtering allDiagnostics' own refs, rather
+        // than re-deriving that classification here.
+        //
+        // "Concerns this slice" means a ref that either IS the bare slice key (lineage,
+        // frontmatter-coherence, and this module's own diagnostics all tag that way) OR starts
+        // with `<sliceKey>/` (every element-level ref from computeRefs()/model/validate.ts,
+        // e.g. an unknown-event error on a view inside this slice). An earlier version gated on
+        // "any error anywhere in the model," which silently failed the check — with zero
+        // diagnostics printed — on an unrelated slice's breakage; scoping to this slice alone
+        // matches the ticket's own scenario (check one slice while the rest of a large model is
+        // still WIP) and this module's own "single-slice" framing.
+        const readyDiagnostics = validateSliceReady(model, refs, dirname(file), opts.sliceReady);
+        const combined = [...allDiagnostics, ...readyDiagnostics];
+        const key = opts.sliceReady;
+        const scoped = combined.filter((d) => d.refs?.some((r) => r === key || r.startsWith(`${key}/`)));
+        printDiagnostics(scoped);
+        const ready = scoped.length === 0;
+        console.log(ready ? `slice "${key}" is ready-to-implement` : `slice "${key}" is NOT ready-to-implement`);
+        if (!ready)
+            process.exit(1);
+        return;
+    }
     if (opts.listIssues || opts.listDivergences || opts.listPublic) {
         if (opts.listIssues)
             printIssues(model);
         if (opts.listDivergences)
             printDivergences(model);
         if (opts.listPublic)
-            printPublicEvents(model);
+            printPublicElements(model);
         // Errors still fail the run below — surface them rather than exiting
         // non-zero with nothing but the list on screen.
-        printDiagnostics(diagnostics.filter((d) => d.severity === "error"));
+        printDiagnostics(allDiagnostics.filter((d) => d.severity === "error"));
     }
     else {
-        printDiagnostics(diagnostics);
-        if (diagnostics.length === 0)
+        printDiagnostics(allDiagnostics);
+        if (allDiagnostics.length === 0)
             console.log("ok — no issues");
     }
-    if (hasErrors(diagnostics))
+    if (hasErrors(allDiagnostics))
         process.exit(1);
     if (opts.failOnIssues && model.elements.some((el) => el.issue))
         process.exit(1);
 });
+program
+    .command("ledger")
+    .description("check slice docs' version: field agrees with their content across two git revisions " +
+    "(opt-in CI check, MIL-89 — never part of `em validate`, see docs/ci.md)")
+    .argument("<file>", "anchor .em file — locates slices/ relative to it; never parsed")
+    .option("--from <rev>", "baseline revision")
+    .option("--to <rev>", "compare revision (default: current working tree)")
+    .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .action((file, opts) => {
+    if (!opts.from) {
+        console.error("em ledger: --from <rev> is required");
+        process.exit(1);
+    }
+    const to = opts.to ?? null;
+    const result = checkLedger(file, opts.from, to);
+    if (opts.json) {
+        process.stdout.write(buildLedgerJson(result, opts.from, to) + "\n");
+    }
+    else {
+        for (const f of result.findings)
+            console.log(f.message);
+        if (result.findings.length === 0) {
+            console.log(`ok — ledger agrees (${result.checkedCount} slice doc(s) checked)`);
+        }
+        else {
+            console.log(`${result.findings.length} ledger mismatch(es)`);
+        }
+    }
+    // Set the code rather than process.exit(): same rationale as em diff/em glossary — stdout
+    // to a pipe (a --json document) shouldn't risk truncation.
+    if (result.findings.length > 0)
+        process.exitCode = 1;
+});
+// Shared by install/sync/check: the skill directory bundled with whatever em package is
+// actually running (works whether em was installed from npm or run from a checkout, and
+// regardless of a symlinked global install — see pkgDir's own resolution above for
+// PKG_VERSION) and the skill directory a consumer repo vendors it into.
+function packagedSkillDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", ".claude", "skills", "event-modeling");
+}
+function vendoredSkillDir(repoRoot) {
+    return join(resolve(repoRoot), ".claude", "skills", "event-modeling");
+}
 const skill = program
     .command("skill")
     .description("manage Claude Code skills bundled with em");
@@ -364,9 +468,8 @@ skill
     .description("copy the event-modeling skill into .claude/skills/event-modeling/")
     .option("-f, --force", "overwrite an existing installation")
     .action(async (opts) => {
-    const pkgDir = dirname(fileURLToPath(import.meta.url));
-    const src = join(pkgDir, "..", ".claude", "skills", "event-modeling");
-    const dest = join(process.cwd(), ".claude", "skills", "event-modeling");
+    const src = packagedSkillDir();
+    const dest = vendoredSkillDir(process.cwd());
     if (existsSync(dest) && !opts.force) {
         console.log(`skill already installed at ${dest}`);
         console.log("re-run with --force to overwrite");
@@ -377,10 +480,59 @@ skill
     console.log(`installed event-modeling skill → ${dest}`);
     console.log("in Claude Code, run /event-modeling to start a guided session");
 });
-program.parseAsync().catch((e) => {
-    reportError(e);
-    process.exit(1);
+skill
+    .command("sync")
+    .description("update the vendored .claude/skills/event-modeling/ copy in [path] to match the installed " +
+    "em package (overwrites unconditionally; local edits are never merged, MIL-93)")
+    .argument("[path]", "consumer repo root", ".")
+    .action(async (path) => {
+    const packagedDir = packagedSkillDir();
+    const vendoredDir = vendoredSkillDir(path);
+    const plan = planSkillSync(packagedDir, vendoredDir);
+    if (plan.changes.length === 0) {
+        console.log(`up to date — ${vendoredDir} already matches the installed skill (${plan.unchangedCount} file(s))`);
+        return;
+    }
+    applySkillSync(plan, packagedDir, vendoredDir);
+    for (const c of plan.changes)
+        console.log(`${c.kind}: ${c.relPath}`);
+    console.log(`synced ${vendoredDir} — ${plan.changes.length} file(s) changed, ${plan.unchangedCount} unchanged`);
+});
+skill
+    .command("check")
+    .description("check the vendored .claude/skills/event-modeling/ copy in [path] for drift against the " +
+    "installed em package; exits non-zero on any mismatch (CI-ready, MIL-93)")
+    .argument("[path]", "consumer repo root", ".")
+    .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .action((path, opts) => {
+    const packagedDir = packagedSkillDir();
+    const vendoredDir = vendoredSkillDir(path);
+    const result = checkSkillSync(packagedDir, vendoredDir, PKG_VERSION);
+    if (opts.json) {
+        process.stdout.write(buildSkillCheckJson(result, vendoredDir, PKG_VERSION) + "\n");
+    }
+    else {
+        for (const f of result.findings)
+            console.log(f.message);
+        console.log(result.ok ? `ok — vendored skill matches em ${PKG_VERSION}` : `${result.findings.length} mismatch(es)`);
+    }
+    // Set the code rather than process.exit(): same rationale as em ledger/em diff — stdout to
+    // a pipe (a --json document) shouldn't risk truncation.
+    if (!result.ok)
+        process.exitCode = 1;
 });
+// Exported so dev tooling (e.g. scripts/generate-skill-docs.ts) can introspect the registered
+// commands/options without triggering a real CLI run. Guarded the same way Node's CJS
+// `require.main === module` used to: only actually parse argv when this file is the process's
+// entry module, not merely `import`ed. See util/isMainModule.ts for why this has to
+// realpath-resolve argv[1] — a naive path comparison breaks the `npm i -g` symlink case.
+export { program };
+if (isMainModule(import.meta.url)) {
+    program.parseAsync().catch((e) => {
+        reportError(e);
+        process.exit(1);
+    });
+}
 // ---- helpers ----
 function compileFile(file, opts = {}) {
     let source;
@@ -448,27 +600,32 @@ function readAtRevision(file, rev) {
  */
 function buildChangelogDoc(file, repoRoot, commits) {
     const models = [];
+    const refsList = [];
     const errors = [];
     for (const c of commits) {
         const rev = readFileAtCommit(repoRoot, c);
         if (!rev.ok) {
             models.push(null);
+            refsList.push(null);
             errors.push(rev.message);
             continue;
         }
         try {
-            const { model, diagnostics } = compile(rev.content);
+            const { model, refs, diagnostics } = compile(rev.content);
             if (hasErrors(diagnostics)) {
                 models.push(null);
+                refsList.push(null);
                 errors.push(`validation errors at ${c.shortHash} — fix with \`em validate\` at that revision`);
             }
             else {
                 models.push(model);
+                refsList.push(refs);
                 errors.push(null);
             }
         }
         catch (e) {
             models.push(null);
+            refsList.push(null);
             errors.push(e instanceof ParseError ? `parse error: ${e.message}` : e instanceof Error ? e.message : String(e));
         }
     }
@@ -486,7 +643,10 @@ function buildChangelogDoc(file, repoRoot, commits) {
             entries.push({ ...base, diff: null, error: `no earlier parseable revision to diff against (${commits[0].shortHash}: ${errors[0]})` });
         }
         else {
-            entries.push({ ...base, diff: diffModels(models[prevParseable], models[i]) });
+            entries.push({
+                ...base,
+                diff: diffModels(models[prevParseable], models[i], refsList[prevParseable], refsList[i]),
+            });
         }
         if (models[i])
             prevParseable = i;
@@ -498,7 +658,7 @@ function buildChangelogDoc(file, repoRoot, commits) {
     return buildChangelog(entries, decisions, { file, intro, introError });
 }
 /** Shared body for both `em diff` forms: compile both sides, gate on errors, print, exit-code. */
-function runDiff(oldSource, oldLabel, newSource, newLabel, exitCode, json) {
+function runDiff(oldSource, oldLabel, newSource, newLabel, exitCode, json, lineage) {
     const oldResult = compileSource(oldSource, oldLabel);
     const newResult = compileSource(newSource, newLabel);
     printDiagnostics(oldResult.diagnostics);
@@ -507,7 +667,7 @@ function runDiff(oldSource, oldLabel, newSource, newLabel, exitCode, json) {
         console.error("not diffing: fix the errors above");
         process.exit(1);
     }
-    const diff = diffModels(oldResult.model, newResult.model);
+    const diff = diffModels(oldResult.model, newResult.model, oldResult.refs, newResult.refs, lineage);
     if (json) {
         const oldSide = { label: oldLabel, source: oldSource, diagnostics: oldResult.diagnostics };
         const newSide = { label: newLabel, source: newSource, diagnostics: newResult.diagnostics };
@@ -561,18 +721,25 @@ function printDivergences(model) {
         console.log(`  divergence :${el.line} slice "${slice.name}" ${el.kind} "${el.name}": ${el.divergence}`);
     }
 }
-/** Print only events marked `public`: slice, name, line — for an integration-surface audit. */
-function printPublicEvents(model) {
-    const pub = model.elements.filter((el) => el.kind === "event" && el.public);
+/** Print only elements marked `public`: slice, kind, name, line — for an integration-surface audit. */
+function printPublicElements(model) {
+    const pub = model.elements.filter((el) => el.public && (el.kind === "event" || el.kind === "view"));
     if (pub.length === 0) {
-        console.log("no public events");
+        console.log("no public elements");
         return;
     }
     for (const el of pub) {
         const slice = model.slices[el.sliceIndex];
-        console.log(`  public :${el.line} slice "${slice.name}" event "${el.name}"`);
+        console.log(`  public :${el.line} slice "${slice.name}" ${el.kind} "${el.name}"`);
     }
 }
+/** Diagnostics in `all` not already present (by reference identity) in `already` — avoids
+ *  double-printing diagnostic objects forwarded unchanged from an earlier compile step (e.g.
+ *  ref-collision warnings `buildExport()`/`buildCatalog()` fold in from the same `RefsResult`
+ *  `compileFile()` already printed once). */
+function newDiagnostics(all, already) {
+    return all.filter((d) => !already.includes(d));
+}
 function printDiagnostics(diags) {
     if (diags.length === 0)
         return;