boundry 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to Boundry are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versioning follows [semver](https://semver.org/).
 
+## [0.6.0] — 2026-07-22
+
+### Changed
+
+- **`boundry diff` now emits a single "proposed changes" view by default** ([#8]),
+  instead of one view per changed layer. The per-layer shape (added in 0.4.0,
+  extended per-altitude in 0.5.0) had two failure modes on real changes: it
+  multiplied views (one multi-slice change produced ~21), and its per-layer
+  `include *` collapsed deeply-nested proposals into their grey ancestor box, so a
+  nested proposed leaf silently lost its amber. The new `boundry_diff` view uses
+  `include * -> * where tag is #proposed` with **no** bare `include *`, so it pulls
+  in exactly the proposed edges and the leaf modules they touch — every change is
+  drawn at leaf level, uncollapsed and uniformly coloured, on one landing. A
+  `#proposed` box with no edge yet is included by fqn so a proposed-but-unwired
+  module still shows, and every endpoint's ancestor chain is included so each
+  change nests under its layer/system for context. `approve` still deletes the
+  derived file (0.5.0 behaviour).
+  - The per-altitude per-layer views from 0.5.0 remain available behind
+    **`boundry diff --per-layer`** — useful for a small change, opt-in.
+
+[#8]: https://github.com/makspiechota/boundry/issues/8
+
 ## [0.5.0] — 2026-07-21
 
 ### Fixed

package/README.md

@@ -293,38 +293,41 @@ this styling back out with the marker: a `#proposed` edge returns to bare, a
 `#proposed` box stays but loses its colour, a `#proposal-delete` is removed
 outright. Requires **LikeC4 ≥ 1.58** to render.
 
-### Reviewing a proposal — per-layer diff views (prototype)
+### Reviewing a proposal — the diff view (prototype)
 
-A proposal nested inside a box is invisible at a wider zoom: at the top level the
-box collapses and its inner `#proposed` edge disappears. So `diff` generates a
-**focused view for every layer that draws a pending change** — into a derived
-`boundry.diff.likec4`:
+`diff` generates a single **proposed-changes** view — every pending change on one
+landing — into a derived `boundry.diff.likec4`:
 
 ```bash
 boundry diff --arch arch              # (re)write boundry.diff.likec4
-likec4 serve arch                     # review each layer, changes coloured
+likec4 serve arch                     # open 'Boundry diff — proposed changes'
 ```
 
 The highlighting is **generated, not hand-styled** — `diff` emits the LikeC4
-style rules into the derived file, so every `#proposed` box fills amber and edge
-goes amber + solid, every `#proposal-delete` red, deterministically. That closes
-the last manual seam: `annotate` marks, `diff` colours, no agent-dependent
-styling step. Boxes are styled *in place* (never force-included), so a nested
-proposal stays in its own layer; unchanged elements keep their defaults; and the
-rules live only in the generated views, so your own views are untouched.
-
-A changed edge is drawn at **every altitude it appears**, not only the
-common-ancestor layer — so a cross-system dependency between two deeply-nested
-leaves gets a view at each endpoint's system and container as well as at the
-shared root. Open the change at whatever altitude matters (the whole system, a
-specific container) instead of being dropped at the noisy root view. `diff` emits
-only the layers that genuinely draw the edge: never above the common ancestor
-(where it collapses to an undrawn self-loop), never the leaf endpoints themselves.
+rules into the derived file, so every `#proposed` box fills amber and edge goes
+amber + solid, every `#proposal-delete` red, deterministically. That closes the
+last manual seam: `annotate` marks, `diff` colours, no agent-dependent styling
+step. Unchanged elements keep their defaults, and the rules live only in the
+generated view, so your own views are untouched.
+
+The view uses `include * -> * where tag is #proposed` (no bare `include *`), so it
+pulls in exactly the proposed edges and the leaf modules they touch — a
+deeply-nested proposal renders as its **own coloured node** instead of collapsing
+into a grey ancestor. A proposed *module* with no edge yet is included too, so a
+proposed-but-unwired box still shows. Each change nests under its layer/system for
+context.
+
+For a small change you can ask for the old per-layer shape instead — one focused
+`view … of <scope>` for every layer that draws a change:
+
+```bash
+boundry diff --arch arch --per-layer
+```
 
 The file is a **derived artifact**: overwritten every run, removed when nothing is
 proposed, so it always matches the current diagram. `approve` deletes it too, as
-part of enacting — the moment the last proposal is approved the views are stale,
-so the post-approve workspace validates clean. It reads the diagram's own markers
+part of enacting — the moment the last proposal is approved the view is stale, so
+the post-approve workspace validates clean. It reads the diagram's own markers
 (not the lock), so it frames whatever `annotate` or a human has marked. Being
 derived, it's a `.gitignore` candidate (`boundry.diff.likec4`).
 
@@ -340,7 +343,7 @@ boundry generate [--arch <dir>] [--cwd <dir>] [--out <file>]
 boundry verify   [--arch <dir>] [--cwd <dir>]
 boundry approve  [--arch <dir>] [--cwd <dir>]
 boundry annotate [--arch <dir>]
-boundry diff     [--arch <dir>]
+boundry diff     [--arch <dir>] [--per-layer]
 ```
 
 | Flag | Meaning |
@@ -348,6 +351,7 @@ boundry diff     [--arch <dir>]
 | `--arch <dir>` | LikeC4 workspace directory (all `.likec4` files in it are merged). Default `.`. |
 | `--cwd <dir>` | Repo root to check. `folder` paths are relative to it. Lets you run from anywhere. |
 | `--out <file>` | `generate` only: where to write the dependency-cruiser config. Default `.dependency-cruiser.cjs`. |
+| `--per-layer` | `diff` only: emit one focused view per layer instead of the single proposed-changes view. |
 | `sources...` | `check` only: paths to lint. Default `src`. |
 
 - **`check`** compiles the rules and runs the linter. Exits non-zero on any violation.
@@ -360,8 +364,9 @@ boundry diff     [--arch <dir>]
   removes `#proposal-delete`) and writes `boundry.lock`. For humans, not agents.
 - **`annotate`** rewrites undeclared additions as `#proposed`, diffing against
   `boundry.lock`.
-- **`diff`** generates a focused, colour-coded review view per layer that holds a
-  pending change, into a derived `boundry.diff.likec4`.
+- **`diff`** generates a single colour-coded "proposed changes" review view into a
+  derived `boundry.diff.likec4` (or, with `--per-layer`, one focused view per layer
+  that draws a change).
 
 Boundry warns (but does not fail) when a mapped folder matches **zero** files, and
 **fails outright** when a check analysed no files at all — so a passing check can

package/dist/adapters/visualizer/likec4.d.ts

@@ -46,14 +46,26 @@ export declare class LikeC4Visualizer implements VisualizerPort {
      */
     styleMarkers(): Promise<void>;
     /**
-     * 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) and writes one `view … of
-     * <scope>` per layer to a derived `boundry.diff.likec4`. A box is bucketed into
-     * its parent layer; an edge into *every* layer that draws it (see `edgeScopes`),
-     * so a cross-system dependency can be reviewed at each altitude, not only the
-     * common-ancestor layer. The file is overwritten each run and removed when
-     * nothing is proposed, so it always reflects the current diagram.
+     * Generate the review views for the diagram's pending changes, into a derived
+     * `boundry.diff.likec4`. Walks the diagram's own `#proposed` / `#proposal-delete`
+     * markers (never the lock — a `#proposal-delete` has no lock delta).
+     *
+     * By default it emits a **single `boundry_diff` view** that draws every change at
+     * once, uncollapsed and uniformly highlighted (see `renderSingleView`) — the diff
+     * landing. With `perLayer`, it instead emits one focused `view … of <scope>` for
+     * every layer that draws a change (a box in its parent layer; an edge in every
+     * layer that draws it, per `edgeScopes`) — useful for a small change, but it
+     * multiplies views and collapses deeply-nested proposals into grey ancestors on
+     * a broad `include *`, which is why the single view is the default (issue #8).
+     *
+     * The file is overwritten each run and removed when nothing is proposed, so it
+     * always reflects the current diagram.
+     */
+    emitDiffViews(perLayer?: boolean): Promise<DiffView[]>;
+    /**
+     * The `--per-layer` shape: buckets each change into every layer that draws it and
+     * renders one scoped `view … of <scope>` per layer. Kept as an opt-in to the
+     * single-view default.
      */
-    emitDiffViews(): Promise<DiffView[]>;
+    private perLayerViews;
 }

package/dist/adapters/visualizer/likec4.js

@@ -104,6 +104,61 @@ function renderDiffView(scope, highlight) {
     const lines = [`    title 'Boundry diff · ${scope ?? 'root'}'`, '    include *', ...highlight];
     return `${opener}\n${lines.join('\n')}\n  }`;
 }
+/** Every proper ancestor of an element, shallowest first — its parent chain up to (not including) the root. */
+function ancestorFqns(fqn) {
+    const parts = fqn.split('.');
+    const out = [];
+    for (let len = 1; len <= parts.length - 1; len++)
+        out.push(parts.slice(0, len).join('.'));
+    return out;
+}
+/**
+ * The single `boundry_diff` view: one landing that draws *every* pending change at
+ * once, with uniform highlighting and no empty views. It sidesteps the per-layer
+ * shape's two failure modes (issue #8):
+ *
+ *   - **No collapse.** `include * -> * where tag is #proposed` (with NO bare
+ *     `include *`) pulls in exactly the proposed edges and the leaf modules they
+ *     touch — so a deeply-nested proposed leaf renders as its own amber node
+ *     instead of collapsing into a grey ancestor, as it does under `include *`.
+ *   - **Standalone boxes.** A `#proposed` box with no edge is included by fqn, so
+ *     a proposed-but-unwired module still shows (and is coloured by the style rule).
+ *
+ * Every endpoint's and box's full ancestor chain is included too, so each change
+ * nests under its layer/system for context (verified against LikeC4 1.58). Rules
+ * are emitted only for marker tags actually in use — referencing an undeclared tag
+ * is a hard LikeC4 error.
+ */
+function renderSingleView(edges, boxes, usedTags) {
+    const lines = [`    title 'Boundry diff — proposed changes'`];
+    // Edge includes: one per marker that appears on an edge. These pull the proposed
+    // edges and their endpoint leaves in at leaf level, uncollapsed.
+    if (edges.some((e) => e.marker === '#proposed')) {
+        lines.push('    include * -> * where tag is #proposed with { color amber; line solid }');
+    }
+    if (edges.some((e) => e.marker === '#proposal-delete')) {
+        lines.push('    include * -> * where tag is #proposal-delete with { color red; line solid }');
+    }
+    // Element includes: the proposed/proposal-delete boxes themselves (so a standalone
+    // one shows), plus the full ancestor chain of every endpoint and box (so each
+    // change nests under its containers). Deterministic: sorted, de-duplicated.
+    const includeFqns = new Set();
+    for (const box of boxes)
+        includeFqns.add(box.fqn);
+    const anchors = [...edges.flatMap((e) => [e.from, e.to]), ...boxes.map((b) => b.fqn)];
+    for (const fqn of anchors)
+        for (const ancestor of ancestorFqns(fqn))
+            includeFqns.add(ancestor);
+    if (includeFqns.size) {
+        lines.push(`    include ${[...includeFqns].sort().join(', ')}`);
+    }
+    // Style rules colour the tagged boxes (edges are coloured by their include above).
+    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 }');
+    return `  view boundry_diff {\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
@@ -582,28 +637,28 @@ export class LikeC4Visualizer {
         }
     }
     /**
-     * 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) and writes one `view … of
-     * <scope>` per layer to a derived `boundry.diff.likec4`. A box is bucketed into
-     * its parent layer; an edge into *every* layer that draws it (see `edgeScopes`),
-     * so a cross-system dependency can be reviewed at each altitude, not only the
-     * common-ancestor layer. The file is overwritten each run and removed when
-     * nothing is proposed, so it always reflects the current diagram.
+     * Generate the review views for the diagram's pending changes, into a derived
+     * `boundry.diff.likec4`. Walks the diagram's own `#proposed` / `#proposal-delete`
+     * markers (never the lock — a `#proposal-delete` has no lock delta).
+     *
+     * By default it emits a **single `boundry_diff` view** that draws every change at
+     * once, uncollapsed and uniformly highlighted (see `renderSingleView`) — the diff
+     * landing. With `perLayer`, it instead emits one focused `view … of <scope>` for
+     * every layer that draws a change (a box in its parent layer; an edge in every
+     * layer that draws it, per `edgeScopes`) — useful for a small change, but it
+     * multiplies views and collapses deeply-nested proposals into grey ancestors on
+     * a broad `include *`, which is why the single view is the default (issue #8).
+     *
+     * The file is overwritten each run and removed when nothing is proposed, so it
+     * always reflects the current diagram.
      */
-    async emitDiffViews() {
+    async emitDiffViews(perLayer = false) {
         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).
+        // Lift every marked edge and box once; both view shapes are built from this.
+        const edges = [];
+        const boxes = [];
+        // Which marker tags actually appear — so the emitted 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;
@@ -619,27 +674,54 @@ export class LikeC4Visualizer {
                 if (statement?.$type === 'Relation') {
                     const from = fqnOf(endpointElement(statement.source));
                     const to = fqnOf(endpointElement(statement.target));
-                    // One view per layer that actually draws this edge, so the reviewer can
-                    // judge it at every altitude — not only the common-ancestor layer (#7).
                     if (from && to)
-                        for (const scope of edgeScopes(from, to))
-                            record(scope);
+                        edges.push({ from, to, marker });
                 }
                 else if (statement?.$type === 'Element') {
                     const fqn = fqnOf(statement);
                     if (fqn)
-                        record(parentScope(fqn));
+                        boxes.push({ fqn, marker });
                 }
             });
         }
         const diffPath = join(this.workspaceDir, DIFF_FILE);
-        if (layers.size === 0) {
+        if (edges.length === 0 && boxes.length === 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 [];
         }
+        const { header, body, views } = perLayer
+            ? this.perLayerViews(edges, boxes, usedTags)
+            : {
+                header: 'a single landing view of every pending change',
+                body: renderSingleView(edges, boxes, usedTags),
+                views: [{ id: 'boundry_diff', changes: edges.length + boxes.length }],
+            };
+        writeFileSync(diffPath, `// Generated by \`boundry diff\` — ${header}.\n` +
+            `// Derived artifact: regenerate after approve; do not hand-edit.\n` +
+            `views {\n${body}\n}\n`);
+        return views;
+    }
+    /**
+     * The `--per-layer` shape: buckets each change into every layer that draws it and
+     * renders one scoped `view … of <scope>` per layer. Kept as an opt-in to the
+     * single-view default.
+     */
+    perLayerViews(edges, boxes, usedTags) {
+        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);
+        };
+        for (const edge of edges)
+            for (const scope of edgeScopes(edge.from, edge.to))
+                record(scope);
+        for (const box of boxes)
+            record(parentScope(box.fqn));
         // Root first, then by fqn, so the output is stable across runs.
         const ordered = [...layers.values()].sort((a, b) => {
             if (!a.scope)
@@ -649,14 +731,14 @@ export class LikeC4Visualizer {
             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,
-        }));
+        return {
+            header: 'one focused view per layer with a pending change',
+            body: ordered.map((layer) => renderDiffView(layer.scope, highlight)).join('\n'),
+            views: ordered.map((layer) => ({
+                id: scopeViewId(layer.scope),
+                scope: layer.scope,
+                changes: layer.changes,
+            })),
+        };
     }
 }

package/dist/cli/index.js

@@ -4,7 +4,7 @@ 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|annotate|diff> [--arch <dir>] [--cwd <dir>] [--out <file>] [sources...]';
+const USAGE = 'usage: boundry <generate|check|approve|verify|annotate|diff> [--arch <dir>] [--cwd <dir>] [--out <file>] [--per-layer] [sources...]';
 function optValue(args, flag) {
     const i = args.indexOf(flag);
     return i >= 0 ? args[i + 1] : undefined;
@@ -139,7 +139,8 @@ async function main() {
         return;
     }
     if (command === 'diff') {
-        const views = await pipeline.diffViews();
+        const perLayer = rest.includes('--per-layer');
+        const views = await pipeline.diffViews(perLayer);
         const diffFile = join(archDir, 'boundry.diff.likec4');
         if (views.length === 0) {
             console.log('Boundry: ✓ nothing proposed — no diff views to draw');
@@ -147,10 +148,10 @@ async function main() {
         }
         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))`);
+            const where = perLayer ? `layer ${view.scope ?? 'root'}, ` : '';
+            console.log(`  ${view.id}  (${where}${view.changes} change(s))`);
         }
-        console.log('  Open the diagram in `likec4 serve` to review each layer.');
+        console.log('  Open the diagram in `likec4 serve` to review.');
         return;
     }
     console.error(USAGE);

package/dist/core/pipeline/pipeline.d.ts

@@ -60,11 +60,11 @@ export declare class Pipeline {
      */
     annotate(lock: string): Promise<AnnotateResult>;
     /**
-     * (Re)generate a focused diff view per layer that holds a pending change, so a
-     * reviewer sees each proposal in the scope where it is actually drawn — a
-     * proposal nested in a box is invisible once that box collapses at a wider
-     * view. Reads the diagram's own `#proposed` / `#proposal-delete` markers, so it
-     * composes with `annotate` (annotate marks drift, this frames it).
+     * (Re)generate the review views for the diagram's pending changes. By default a
+     * single `boundry_diff` landing view draws every `#proposed` / `#proposal-delete`
+     * change at once; with `perLayer`, one focused view per layer that draws a change.
+     * Reads the diagram's own markers, so it composes with `annotate` (annotate marks
+     * drift, this frames it).
      */
-    diffViews(): Promise<DiffView[]>;
+    diffViews(perLayer?: boolean): Promise<DiffView[]>;
 }

package/dist/core/pipeline/pipeline.js

@@ -69,13 +69,13 @@ export class Pipeline {
         return { edges, modules };
     }
     /**
-     * (Re)generate a focused diff view per layer that holds a pending change, so a
-     * reviewer sees each proposal in the scope where it is actually drawn — a
-     * proposal nested in a box is invisible once that box collapses at a wider
-     * view. Reads the diagram's own `#proposed` / `#proposal-delete` markers, so it
-     * composes with `annotate` (annotate marks drift, this frames it).
+     * (Re)generate the review views for the diagram's pending changes. By default a
+     * single `boundry_diff` landing view draws every `#proposed` / `#proposal-delete`
+     * change at once; with `perLayer`, one focused view per layer that draws a change.
+     * Reads the diagram's own markers, so it composes with `annotate` (annotate marks
+     * drift, this frames it).
      */
-    async diffViews() {
-        return this.visualizer.emitDiffViews();
+    async diffViews(perLayer = false) {
+        return this.visualizer.emitDiffViews(perLayer);
     }
 }

package/dist/core/ports/ports.d.ts

@@ -23,25 +23,26 @@ export interface VisualizerPort {
      */
     styleMarkers(): Promise<void>;
     /**
-     * (Re)generate a focused diff view for every layer that holds a pending
-     * change — an edge or box tagged `#proposed` or `#proposal-delete`. Each view
-     * is scoped to the tightest element that contains the change (the model root
-     * for a top-level one), because a proposal nested inside a box is invisible
-     * once that box collapses at a wider scope. A derived artifact: overwritten
+     * (Re)generate the review views for the diagram's pending changes — edges and
+     * boxes tagged `#proposed` or `#proposal-delete`. By default a single
+     * `boundry_diff` landing view draws every change at once, uncollapsed and
+     * uniformly highlighted. With `perLayer`, one focused `view … of <scope>` is
+     * emitted per layer that draws a change instead. A derived artifact: overwritten
      * each run, and removed when nothing is proposed. Returns one entry per view.
      */
-    emitDiffViews(): Promise<DiffView[]>;
+    emitDiffViews(perLayer?: boolean): Promise<DiffView[]>;
 }
 /**
- * One emitted diff view: a single layer (element scope) that holds at least one
- * pending change, and how many changes fall in it.
+ * One emitted diff view. For the default single view there is one entry
+ * (`boundry_diff`) counting every pending change; in `perLayer` mode there is one
+ * per layer, each scoped to an element and counting the changes that fall in it.
  */
 export interface DiffView {
-    /** The generated view id, e.g. `boundry_diff_root` or `boundry_diff_billing`. */
+    /** The generated view id — `boundry_diff`, or `boundry_diff_<scope>` per layer. */
     id: string;
-    /** The scope element's fqn, or undefined for the model root. */
+    /** perLayer only: the scope element's fqn, or undefined for the model root. */
     scope?: string;
-    /** How many pending `#proposed` / `#proposal-delete` changes this layer holds. */
+    /** How many pending `#proposed` / `#proposal-delete` changes this view holds. */
     changes: number;
 }
 /** A generated linter config artifact. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boundry",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Compile a C4 architecture diagram into a deterministic dependency linter. Deterministic architectural guardrails for AI agents and humans.",
   "type": "module",
   "license": "MIT",