boundry 0.2.0 → 0.4.0

package/dist/adapters/visualizer/likec4.js

@@ -1,5 +1,69 @@
 import { LikeC4 } from 'likec4';
-import { readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** The generated, derived file holding Boundry's per-layer diff views. */
+const DIFF_FILE = 'boundry.diff.likec4';
+/** The generated view id for a scope — `boundry_diff_root` or `boundry_diff_<fqn>`. */
+function scopeViewId(scope) {
+    return scope ? `boundry_diff_${scope.replace(/\./g, '_')}` : 'boundry_diff_root';
+}
+/**
+ * The tightest layer that draws an edge between two elements: the deepest
+ * element that contains both, i.e. the common prefix of their fqns (undefined =
+ * the model root). An edge nested inside a box shows there, not at a wider scope
+ * where the box has collapsed — which is exactly why each layer needs its own view.
+ */
+function commonScope(from, to) {
+    const a = from.split('.');
+    const b = to.split('.');
+    const shared = [];
+    for (let i = 0; i < Math.min(a.length, b.length) && a[i] === b[i]; i++) {
+        shared.push(a[i]);
+    }
+    return shared.length ? shared.join('.') : undefined;
+}
+/** The layer that draws a box: its parent element (undefined = the model root). */
+function parentScope(fqn) {
+    const parts = fqn.split('.');
+    parts.pop();
+    return parts.length ? parts.join('.') : undefined;
+}
+/**
+ * Deterministic highlight rules for the marker tags actually in use. Referencing
+ * an undeclared tag is a hard LikeC4 error, and a tag can only be *used* if it is
+ * declared — so emitting rules only for seen tags is always safe.
+ *
+ * Boxes use a style-only `style element.tag` rule: a tagged box is coloured where
+ * it already sits and never force-included into a wider view (which would drag a
+ * nested proposal out of its collapsed parent, defeating the per-layer framing).
+ * Edges use `include … where … with`, coloured and made *solid* so they stand out
+ * against LikeC4's dashed default. Amber = addition, red = removal. Verified
+ * against LikeC4 1.58.
+ */
+function highlightLines(usedTags) {
+    const lines = [];
+    if (usedTags.has('proposed')) {
+        lines.push('    style element.tag = #proposed { color amber }');
+    }
+    if (usedTags.has('proposal-delete')) {
+        lines.push('    style element.tag = #proposal-delete { color red }');
+    }
+    if (usedTags.has('proposed')) {
+        lines.push('    include * -> * where tag is #proposed with { color amber; line solid }');
+    }
+    if (usedTags.has('proposal-delete')) {
+        lines.push('    include * -> * where tag is #proposal-delete with { color red; line solid }');
+    }
+    return lines;
+}
+/** One `view … { include * }` block, scoped with `of <element>` unless it is root. */
+function renderDiffView(scope, highlight) {
+    const opener = scope
+        ? `  view ${scopeViewId(scope)} of ${scope} {`
+        : `  view ${scopeViewId(scope)} {`;
+    const lines = [`    title 'Boundry diff · ${scope ?? 'root'}'`, '    include *', ...highlight];
+    return `${opener}\n${lines.join('\n')}\n  }`;
+}
 /**
  * An exemption pattern has to be a usable regex before it reaches the linter. A
  * broken or empty one would otherwise be a silent hole: it exempts files from
@@ -24,15 +88,57 @@ function assertUsableRegex(pattern, elementId) {
     }
     return pattern;
 }
-/** A `#proposed` marker in the source — on an element or a relationship alike. */
-function isProposedTag(node, text) {
-    return (node.$type === 'TagRef' &&
-        node.$cstNode &&
-        text.slice(node.$cstNode.offset, node.$cstNode.end) === '#proposed');
+/**
+ * Walk the AST through CONTAINMENT only — descending into a property solely when
+ * the child names this node as its `$container`. That skips cross-references (a
+ * relation's endpoint links to the element it names), so a node is never reached
+ * through another's reference to it, and traversal never leaves this document.
+ */
+function walkContained(root, visit) {
+    const go = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        visit(node);
+        for (const key of Object.keys(node)) {
+            if (key.startsWith('$'))
+                continue;
+            const child = node[key];
+            for (const kid of Array.isArray(child) ? child : [child]) {
+                if (kid && typeof kid === 'object' && kid.$container === node)
+                    go(kid);
+            }
+        }
+    };
+    go(root);
+}
+/**
+ * The fully-qualified id of an element AST node — its own name and every
+ * enclosing element's, joined by '.'. Matches the id the computed model assigns,
+ * for nested elements as well as flat ones.
+ */
+function fqnOf(astElement) {
+    if (!astElement)
+        return undefined;
+    const parts = [];
+    for (let n = astElement; n; n = n.$container) {
+        if (n.$type === 'Element' && n.name)
+            parts.unshift(n.name);
+    }
+    return parts.length ? parts.join('.') : undefined;
+}
+/** The element an `a -> b` endpoint (FqnRef) resolves to, or undefined. */
+function endpointElement(fqnRef) {
+    return fqnRef?.value?.ref;
+}
+/** The literal source text of a TagRef node, or undefined if it is not one. */
+function tagRefText(node, text) {
+    if (node.$type !== 'TagRef' || !node.$cstNode)
+        return undefined;
+    return text.slice(node.$cstNode.offset, node.$cstNode.end);
 }
 /**
- * The source to remove for one marker. A marker alone on its line takes the
- * whole line (so approving leaves no blank gap); an inline one takes just the
+ * The source to remove for a `#proposed` marker. A marker alone on its line takes
+ * the whole line (so approving leaves no blank gap); an inline one takes just the
  * token and the space before it. The `tag proposed` declaration in the
  * specification is untouched — the vocabulary stays for the next proposal.
  */
@@ -50,28 +156,150 @@ function proposedRemovalRange(tag, text) {
         start--;
     return { start, end };
 }
-function collectProposedRanges(root, text) {
-    const ranges = [];
-    const seen = new Set();
-    const walk = (node) => {
-        if (!node || typeof node !== 'object' || seen.has(node))
-            return;
-        seen.add(node);
-        if (Array.isArray(node)) {
-            for (const item of node)
-                walk(item);
-            return;
+/**
+ * The nearest relationship or element the marker sits in, found via the AST
+ * `$container` chain — the true syntactic parent. A plain object-graph walk would
+ * follow the cross-reference from a relation's endpoint into the element it names
+ * and mis-attribute an element's marker to a relation; `$container` never does.
+ */
+function enclosingStatement(tagRef) {
+    for (let n = tagRef.$container; n; n = n.$container) {
+        if (n.$type === 'Relation' || n.$type === 'Element')
+            return n;
+    }
+    return undefined;
+}
+/**
+ * The whole-statement range for a `#proposal-delete` marker: the entire relation
+ * or element block, from the start of its first line through its trailing
+ * newline, so approving the deletion removes the edge/box and leaves no gap.
+ */
+function statementRemovalRange(statement, text) {
+    const { offset, end } = statement.$cstNode;
+    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
+    const nl = text.indexOf('\n', end);
+    return { start: lineStart, end: nl === -1 ? text.length : nl + 1 };
+}
+/** amber for `#proposed`, red for `#proposal-delete` — the intrinsic colour annotate paints. */
+const MARKER_COLOR = {
+    '#proposed': 'amber',
+    '#proposal-delete': 'red',
+};
+/** The canonical intrinsic style annotate injects for a colour. */
+function canonicalStyle(color) {
+    return `style { color ${color} }`;
+}
+/** The direct `*Body` child (ElementBody / RelationBody) of a statement, if any. */
+function statementBody(stmt) {
+    for (const key of Object.keys(stmt)) {
+        if (key.startsWith('$'))
+            continue;
+        const child = stmt[key];
+        for (const kid of Array.isArray(child) ? child : [child]) {
+            if (kid && typeof kid === 'object' && kid.$container === stmt &&
+                typeof kid.$type === 'string' && kid.$type.endsWith('Body')) {
+                return kid;
+            }
+        }
+    }
+    return undefined;
+}
+/** The direct `*StyleProperty` children of a body. */
+function styleProperties(body) {
+    const out = [];
+    for (const key of Object.keys(body)) {
+        if (key.startsWith('$'))
+            continue;
+        const child = body[key];
+        for (const kid of Array.isArray(child) ? child : [child]) {
+            if (kid && typeof kid === 'object' && kid.$container === body &&
+                typeof kid.$type === 'string' && kid.$type.endsWith('StyleProperty')) {
+                out.push(kid);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The style node in `body` whose source is EXACTLY the canonical `style { color
+ * <c> }` annotate writes — matched by whitespace-normalised text, so a richer
+ * user-authored style (`style { color amber; icon none }`) is never mistaken for
+ * ours and never stripped.
+ */
+function canonicalStyleNode(body, color, text) {
+    const want = canonicalStyle(color);
+    return styleProperties(body).find((s) => s.$cstNode &&
+        text.slice(s.$cstNode.offset, s.$cstNode.end).replace(/\s+/g, ' ').trim() === want);
+}
+/** True when `node` is the body's only property — nothing else would survive removing it. */
+function bodyHasOnly(body, node) {
+    for (const key of Object.keys(body)) {
+        if (key.startsWith('$'))
+            continue;
+        const child = body[key];
+        for (const kid of Array.isArray(child) ? child : [child]) {
+            if (kid && typeof kid === 'object' && kid.$container === body && kid !== node)
+                return false;
         }
-        if (isProposedTag(node, text)) {
+    }
+    return true;
+}
+/** A node's whole line, trailing newline included — for stripping a box's style line. */
+function lineRemovalRange(node, text) {
+    const { offset, end } = node.$cstNode;
+    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
+    const nl = text.indexOf('\n', end);
+    return { start: lineStart, end: nl === -1 ? text.length : nl + 1 };
+}
+/** A relation body in full, plus the whitespace before its `{` — turns `a -> b { … }` back into `a -> b`. */
+function bodyRemovalRange(body, text) {
+    let start = body.$cstNode.offset;
+    while (start > 0 && (text[start - 1] === ' ' || text[start - 1] === '\t'))
+        start--;
+    return { start, end: body.$cstNode.end };
+}
+/**
+ * Every source range to splice out to approve a diagram. A `#proposed` marker
+ * strips to its token (the edge/box stays and becomes permanent) AND takes with
+ * it any intrinsic `style { color amber }` annotate painted on — for a box, that
+ * style's line; for an edge, its whole (now-empty) body, so the edge goes back to
+ * bare. A `#proposal-delete` marker takes its whole enclosing statement (the
+ * edge/box, and any style on it, are removed outright). Ranges are collected via
+ * a containment-only walk — descending solely into true children
+ * (`child.$container === node`), never cross-references — so one marker is never
+ * counted through another element's reference to it, and no range ever escapes
+ * into a different document's text.
+ */
+function collectApprovalRanges(root, text) {
+    const ranges = [];
+    walkContained(root, (node) => {
+        const marker = tagRefText(node, text);
+        if (marker === '#proposed') {
             ranges.push(proposedRemovalRange(node, text));
+            // Strip the intrinsic amber style annotate paints, so an approved box does
+            // not stay amber forever and an approved edge goes back to bare.
+            const statement = enclosingStatement(node);
+            const body = statement && statementBody(statement);
+            const style = body && canonicalStyleNode(body, MARKER_COLOR['#proposed'], text);
+            if (style) {
+                if (statement.$type === 'Relation' && bodyHasOnly(body, style)) {
+                    ranges.push(bodyRemovalRange(body, text));
+                }
+                else {
+                    ranges.push(lineRemovalRange(style, text));
+                }
+            }
         }
-        for (const key of Object.keys(node)) {
-            if (!key.startsWith('$'))
-                walk(node[key]);
+        else if (marker === '#proposal-delete') {
+            const statement = enclosingStatement(node);
+            if (statement?.$cstNode)
+                ranges.push(statementRemovalRange(statement, text));
         }
-    };
-    walk(root);
-    return ranges;
+    });
+    // A whole-statement removal can contain a `#proposed` token range inside it
+    // (a box being deleted that also carried a proposed edge). Drop any range that
+    // another wholly contains, so back-to-front splicing never double-cuts.
+    return ranges.filter((r) => !ranges.some((o) => o !== r && o.start <= r.start && o.end >= r.end && o.end - o.start > r.end - r.start));
 }
 /**
  * First visualizer adapter. Reads a LikeC4 workspace and lifts it into the
@@ -88,7 +316,7 @@ export class LikeC4Visualizer {
         const likec4 = await LikeC4.fromWorkspace(this.workspaceDir);
         const model = await likec4.computedModel();
         const modules = [];
-        const folderIds = new Set();
+        const moduleIds = new Set();
         const wildcardIds = new Set();
         const exemptImporters = new Set();
         let governRoot;
@@ -113,12 +341,25 @@ export class LikeC4Visualizer {
                 wildcardIds.add(String(el.id));
                 continue;
             }
-            const meta = el.getMetadata('folder');
-            const folder = Array.isArray(meta) ? meta[0] : meta;
-            if (folder) {
+            // An element maps to a folder (owns its subtree) or a single file (owns
+            // exactly itself). A file leaf keeps a guarded contract sitting beside its
+            // sibling sub-folders, so a deep nested diagram stays legal AND enforceable.
+            const folderMeta = el.getMetadata('folder');
+            const fileMeta = el.getMetadata('file');
+            const folder = Array.isArray(folderMeta) ? folderMeta[0] : folderMeta;
+            const file = Array.isArray(fileMeta) ? fileMeta[0] : fileMeta;
+            if (folder && file) {
+                throw new Error(`element '${String(el.id)}' declares both 'folder' and 'file' — a module maps to one path`);
+            }
+            if (folder || file) {
                 const id = String(el.id);
-                modules.push({ id, title: el.title, folder });
-                folderIds.add(id);
+                modules.push({
+                    id,
+                    title: el.title,
+                    path: (folder ?? file),
+                    kind: folder ? 'folder' : 'file',
+                });
+                moduleIds.add(id);
             }
         }
         const allowed = [];
@@ -131,8 +372,8 @@ export class LikeC4Visualizer {
             const to = String(rel.target.id);
             // An edge into a wildcard is kept like any other grant, so `verify` sees a
             // self-granted `#anything` exemption as the newly-allowed edge it is.
-            const targetGoverned = folderIds.has(to) || wildcardIds.has(to);
-            if (from !== to && folderIds.has(from) && targetGoverned) {
+            const targetGoverned = moduleIds.has(to) || wildcardIds.has(to);
+            if (from !== to && moduleIds.has(from) && targetGoverned) {
                 allowed.push({ from, to });
             }
         }
@@ -145,17 +386,20 @@ export class LikeC4Visualizer {
         };
     }
     /**
-     * Deterministically strip `#proposed` markers from the diagram source,
-     * promoting intent edges to approved. Source-preserving; never an LLM edit —
-     * it locates each marked relationship in the LikeC4 CST and splices out its
-     * proposal decoration, leaving all other formatting intact.
+     * Deterministically enact a diagram's pending proposals. Source-preserving,
+     * never an LLM edit — it walks the LikeC4 CST and splices ranges directly:
+     *   - `#proposed` markers are stripped, promoting their intent edges to
+     *     approved (the edge/box stays, permanently allowed);
+     *   - `#proposal-delete` markers take their whole edge or box with them, so
+     *     approving a proposed removal actually removes it.
+     * All other formatting is left intact.
      */
     async approve() {
         const likec4 = await LikeC4.fromWorkspace(this.workspaceDir);
         for (const doc of likec4.LangiumDocuments.all) {
             const filePath = doc.uri.fsPath;
             const text = doc.textDocument?.getText?.() ?? readFileSync(filePath, 'utf8');
-            const ranges = collectProposedRanges(doc.parseResult?.value, text);
+            const ranges = collectApprovalRanges(doc.parseResult?.value, text);
             if (ranges.length === 0)
                 continue;
             let next = text;
@@ -165,4 +409,194 @@ export class LikeC4Visualizer {
             writeFileSync(filePath, next);
         }
     }
+    /**
+     * Deterministically mark the given edges and elements `#proposed`. The inverse
+     * of `approve` for additions: an undeclared new edge (a self-grant) or box is
+     * rewritten into an explicit, colourable proposal. It locates each target's
+     * relation/element in the CST by its resolved ids and injects the marker,
+     * skipping anything already marked, so it is idempotent.
+     */
+    async propose(edges, moduleIds) {
+        if (edges.length === 0 && moduleIds.length === 0)
+            return;
+        const wantEdge = new Set(edges.map((e) => `${e.from} -> ${e.to}`));
+        const wantModule = new Set(moduleIds);
+        const likec4 = await LikeC4.fromWorkspace(this.workspaceDir);
+        for (const doc of likec4.LangiumDocuments.all) {
+            const filePath = doc.uri.fsPath;
+            if (!filePath.endsWith('.likec4'))
+                continue;
+            const text = doc.textDocument?.getText?.() ?? readFileSync(filePath, 'utf8');
+            const inserts = [];
+            walkContained(doc.parseResult?.value, (node) => {
+                if (node.$type === 'Relation' && node.$cstNode) {
+                    const from = fqnOf(endpointElement(node.source));
+                    const to = fqnOf(endpointElement(node.target));
+                    if (from && to && wantEdge.has(`${from} -> ${to}`)) {
+                        const { offset, end } = node.$cstNode;
+                        if (!text.slice(offset, end).includes('#proposed')) {
+                            inserts.push({ at: end, text: ' #proposed' });
+                        }
+                    }
+                }
+                else if (node.$type === 'Element' && node.$cstNode) {
+                    const id = fqnOf(node);
+                    const body = node.body;
+                    if (id && wantModule.has(id) && body?.$cstNode) {
+                        const braceStart = body.$cstNode.offset;
+                        const bodyText = text.slice(braceStart, body.$cstNode.end);
+                        if (!bodyText.includes('#proposed')) {
+                            // Insert as the body's first line, matching the indentation of the
+                            // line that already follows the opening brace.
+                            const afterBrace = text.indexOf('{', braceStart) + 1;
+                            const nextLine = text.indexOf('\n', afterBrace) + 1;
+                            const indent = (text.slice(nextLine).match(/^[ \t]*/) ?? [''])[0];
+                            inserts.push({ at: afterBrace, text: `\n${indent}#proposed` });
+                        }
+                    }
+                }
+            });
+            if (inserts.length === 0)
+                continue;
+            let next = text;
+            for (const { at, text: fragment } of inserts.sort((a, b) => b.at - a.at)) {
+                next = next.slice(0, at) + fragment + next.slice(at);
+            }
+            writeFileSync(filePath, next);
+        }
+    }
+    /**
+     * Paint intrinsic style on every marked edge and box, so a proposal is
+     * highlighted on *every* LikeC4 surface — base views and the "relationships of
+     * X" panel, not just the generated diff views (which only carry view-scoped
+     * rules). A `#proposed` edge/box gets `style { color amber }`, a
+     * `#proposal-delete` `style { color red }`. Source-preserving and idempotent —
+     * anything already carrying the canonical style is left alone. `approve` strips
+     * this styling back out when it enacts the marker.
+     */
+    async styleMarkers() {
+        const likec4 = await LikeC4.fromWorkspace(this.workspaceDir);
+        for (const doc of likec4.LangiumDocuments.all) {
+            const filePath = doc.uri.fsPath;
+            if (!filePath.endsWith('.likec4') || filePath.endsWith(DIFF_FILE))
+                continue;
+            const text = doc.textDocument?.getText?.() ?? readFileSync(filePath, 'utf8');
+            const inserts = [];
+            walkContained(doc.parseResult?.value, (node) => {
+                const marker = tagRefText(node, text);
+                if (marker !== '#proposed' && marker !== '#proposal-delete')
+                    return;
+                const color = MARKER_COLOR[marker];
+                const statement = enclosingStatement(node);
+                if (!statement)
+                    return;
+                const body = statementBody(statement);
+                if (body && canonicalStyleNode(body, color, text))
+                    return; // already styled
+                if (body?.$cstNode) {
+                    // Style on the line right after the marker, at the marker's indent. It
+                    // must go AFTER the marker: a body lists its tags before its style
+                    // properties, so a style ahead of the `#proposed` tag is a parse error.
+                    const markerEnd = node.$cstNode.end;
+                    const lineStart = text.lastIndexOf('\n', markerEnd - 1) + 1;
+                    const indent = (text.slice(lineStart).match(/^[ \t]*/) ?? [''])[0];
+                    const nl = text.indexOf('\n', markerEnd);
+                    inserts.push({
+                        at: nl === -1 ? markerEnd : nl,
+                        text: `\n${indent}${canonicalStyle(color)}`,
+                    });
+                }
+                else {
+                    // An inline-marked edge (`a -> b #proposed`) has no body — give it one,
+                    // indented one level past the relation's own line.
+                    const lineStart = text.lastIndexOf('\n', statement.$cstNode.offset - 1) + 1;
+                    const indent = (text.slice(lineStart).match(/^[ \t]*/) ?? [''])[0];
+                    inserts.push({
+                        at: statement.$cstNode.end,
+                        text: ` {\n${indent}  ${canonicalStyle(color)}\n${indent}}`,
+                    });
+                }
+            });
+            if (inserts.length === 0)
+                continue;
+            let next = text;
+            for (const { at, text: fragment } of inserts.sort((a, b) => b.at - a.at)) {
+                next = next.slice(0, at) + fragment + next.slice(at);
+            }
+            writeFileSync(filePath, next);
+        }
+    }
+    /**
+     * Generate a focused diff view for every layer that holds a pending change.
+     * Walks the diagram's own `#proposed` / `#proposal-delete` markers (never the
+     * lock — a `#proposal-delete` has no lock delta), buckets each change into the
+     * tightest scope that draws it, and writes one `view … of <scope>` per bucket
+     * to a derived `boundry.diff.likec4`. The file is overwritten each run and
+     * removed when nothing is proposed, so it always reflects the current diagram.
+     */
+    async emitDiffViews() {
+        const likec4 = await LikeC4.fromWorkspace(this.workspaceDir);
+        // scopeViewId -> { scope, changes } — deterministic key, so the same diagram
+        // always yields the same set of views.
+        const layers = new Map();
+        const record = (scope) => {
+            const key = scopeViewId(scope);
+            const layer = layers.get(key) ?? { scope, changes: 0 };
+            layer.changes += 1;
+            layers.set(key, layer);
+        };
+        // Which marker tags actually appear — so the emitted highlight rules only ever
+        // reference declared tags (an undeclared tag reference is a hard LikeC4 error).
+        const usedTags = new Set();
+        for (const doc of likec4.LangiumDocuments.all) {
+            const filePath = doc.uri.fsPath;
+            if (!filePath.endsWith('.likec4') || filePath.endsWith(DIFF_FILE))
+                continue;
+            const text = doc.textDocument?.getText?.() ?? readFileSync(filePath, 'utf8');
+            walkContained(doc.parseResult?.value, (node) => {
+                const marker = tagRefText(node, text);
+                if (marker !== '#proposed' && marker !== '#proposal-delete')
+                    return;
+                usedTags.add(marker.slice(1)); // drop the leading '#'
+                const statement = enclosingStatement(node);
+                if (statement?.$type === 'Relation') {
+                    const from = fqnOf(endpointElement(statement.source));
+                    const to = fqnOf(endpointElement(statement.target));
+                    if (from && to)
+                        record(commonScope(from, to));
+                }
+                else if (statement?.$type === 'Element') {
+                    const fqn = fqnOf(statement);
+                    if (fqn)
+                        record(parentScope(fqn));
+                }
+            });
+        }
+        const diffPath = join(this.workspaceDir, DIFF_FILE);
+        if (layers.size === 0) {
+            // Nothing proposed — clear any stale views so `serve` never renders a diff
+            // that no longer exists (and never dangles a reference to an approved-away box).
+            if (existsSync(diffPath))
+                rmSync(diffPath);
+            return [];
+        }
+        // Root first, then by fqn, so the output is stable across runs.
+        const ordered = [...layers.values()].sort((a, b) => {
+            if (!a.scope)
+                return -1;
+            if (!b.scope)
+                return 1;
+            return a.scope.localeCompare(b.scope);
+        });
+        const highlight = highlightLines(usedTags);
+        const body = ordered.map((layer) => renderDiffView(layer.scope, highlight)).join('\n');
+        writeFileSync(diffPath, `// Generated by \`boundry diff\` — one focused view per layer with a pending\n` +
+            `// change. Derived artifact: regenerate after approve; do not hand-edit.\n` +
+            `views {\n${body}\n}\n`);
+        return ordered.map((layer) => ({
+            id: scopeViewId(layer.scope),
+            scope: layer.scope,
+            changes: layer.changes,
+        }));
+    }
 }

package/dist/cli/index.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import { execFileSync } from 'node:child_process';
-import { mkdtempSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, relative, resolve } from 'node:path';
 import { Pipeline } from '../core/pipeline/pipeline.js';
 import { LikeC4Visualizer } from '../adapters/visualizer/likec4.js';
 import { DepCruiserEnforcer } from '../adapters/enforcer/depcruiser.js';
-const USAGE = 'usage: boundry <generate|check|approve|verify> [--arch <dir>] [--base <git-ref>] [--cwd <dir>] [--out <file>] [sources...]';
+const USAGE = 'usage: boundry <generate|check|approve|verify|annotate|diff> [--arch <dir>] [--base <git-ref>] [--cwd <dir>] [--out <file>] [sources...]';
 function optValue(args, flag) {
     const i = args.indexOf(flag);
     return i >= 0 ? args[i + 1] : undefined;
@@ -75,6 +75,9 @@ async function main() {
     const cwd = optValue(rest, '--cwd');
     if (cwd)
         process.chdir(resolve(cwd));
+    // The accepted-state lock lives beside the diagram it locks. `approve` writes
+    // it; `annotate` reads it — the baseline Boundry owns, not one inferred from git.
+    const lockFile = join(archDir, 'boundry.lock');
     const pipeline = new Pipeline(new LikeC4Visualizer(archDir), new DepCruiserEnforcer());
     const grantedSince = (ref) => pipeline.verify(new LikeC4Visualizer(materializeArchAt(archDir, ref)));
     if (command === 'generate') {
@@ -131,8 +134,43 @@ async function main() {
         else {
             console.error('Boundry: ⚠ no --base given — approving without verifying that every new edge was proposed');
         }
-        await pipeline.approve();
-        console.log('Boundry: ✓ approved — stripped #proposed markers from the diagram');
+        const lock = await pipeline.approve();
+        writeFileSync(lockFile, lock);
+        console.log('Boundry: ✓ approved — enacted the diagram and wrote', relative(process.cwd(), lockFile));
+        return;
+    }
+    if (command === 'annotate') {
+        if (!existsSync(lockFile)) {
+            console.error(`Boundry: no ${relative(process.cwd(), lockFile)} — run 'boundry approve' first to record an accepted state`);
+            process.exitCode = 2;
+            return;
+        }
+        const { edges, modules } = await pipeline.annotate(readFileSync(lockFile, 'utf8'));
+        if (edges.length === 0 && modules.length === 0) {
+            console.log('Boundry: ✓ nothing to annotate — the diagram matches the accepted lock');
+            return;
+        }
+        console.log(`Boundry: ✎ marked ${edges.length} edge(s) and ${modules.length} box(es) #proposed:`);
+        for (const edge of edges)
+            console.log(`  ${edge.from} → ${edge.to}`);
+        for (const mod of modules)
+            console.log(`  [${mod.title}]`);
+        console.log('  Review the highlighted diagram, then approve or revert.');
+        return;
+    }
+    if (command === 'diff') {
+        const views = await pipeline.diffViews();
+        const diffFile = join(archDir, 'boundry.diff.likec4');
+        if (views.length === 0) {
+            console.log('Boundry: ✓ nothing proposed — no diff views to draw');
+            return;
+        }
+        console.log(`Boundry: ✎ wrote ${views.length} diff view(s) to ${relative(process.cwd(), diffFile)}:`);
+        for (const view of views) {
+            const layer = view.scope ?? 'root';
+            console.log(`  ${view.id}  (layer ${layer}, ${view.changes} change(s))`);
+        }
+        console.log('  Open the diagram in `likec4 serve` to review each layer.');
         return;
     }
     console.error(USAGE);