boundry 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,7 +4,88 @@ 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.2.0] — unreleased
+## [0.4.0] — 2026-07-17
+
+Makes the "one file can be both the communication diagram and the enforcement
+model" promise hold for deep, nested C4 trees, and makes a proposed change
+highlight itself — deterministically, on every LikeC4 surface.
+
+### Added
+
+- **Accepted-state lock + `annotate` (prototype).** `approve` now records the
+  accepted model to `boundry.lock` beside the diagram — a baseline Boundry
+  **owns**, rather than inferring it from whatever git happens to hold, so
+  "approved" is decoupled from "committed". `boundry annotate` diffs the diagram
+  against that lock and rewrites every undeclared addition — a bare new edge (a
+  self-grant) or box — into an explicit `#proposed` proposal in the source,
+  deterministically and idempotently. Turns silent drift into a reviewable,
+  colourable proposal. (Additive only; deletions are reported, not round-tripped
+  back into the DSL — re-materialising a removed box would resurrect it as an
+  enforced module.)
+  - **Cross-surface highlighting** ([#5]). `annotate` also paints each marker with
+    an intrinsic `style { color amber }` (`#proposed`) / `style { color red }`
+    (`#proposal-delete`) on the element itself. Intrinsic style is the only styling
+    LikeC4 renders on **every** surface — base views *and* the "relationships of X"
+    panel — so a proposal is highlighted wherever a reviewer looks, not just inside
+    the diff views (whose view-scoped rules stop at the view boundary). Idempotent,
+    and `approve` strips the styling back out with the marker: a `#proposed` edge
+    returns to bare, a `#proposed` box loses its colour, a `#proposal-delete` is
+    removed outright. Needs LikeC4 ≥ 1.58 to render.
+- **Per-layer diff views — `boundry diff` (prototype).** Generates a focused
+  LikeC4 view for every layer that holds a pending change — an edge or box tagged
+  `#proposed` or `#proposal-delete` — scoped to the tightest element that draws
+  it, into a derived `boundry.diff.likec4`. This matters because a proposal nested
+  inside a box is invisible once that box collapses at a wider zoom, so a single
+  all-up view hides it; one view per layer surfaces every change in the scope
+  where it renders. It reads the diagram's own markers, not the lock, so it frames
+  whatever `annotate` or a human marked. The file is derived — overwritten each
+  run, removed when nothing is proposed — so it always reflects the current
+  diagram; regenerate after `approve`.
+  - **Deterministic highlighting** ([#4]). `diff` emits the LikeC4 style rules
+    into the derived file, so a `#proposed` box fills amber and its edge goes
+    amber + solid, a `#proposal-delete` red — with no hand-styling. Boxes are
+    styled in place (`style element.tag`, never force-included), so a nested
+    proposal stays in its layer; the rules live only in the generated views, so
+    user-authored views are untouched. Rules are emitted only for marker tags
+    actually in use (referencing an undeclared tag is a hard LikeC4 error).
+- **`#proposal-delete` — the deletion half of the approval lifecycle.** Tag an
+  edge or a box `#proposal-delete` to propose retiring it. The marker colours it
+  red; a pending deletion changes nothing (the edge stays allowed, the box stays
+  enforced), so proposing a removal never breaks the build. On `approve`, the
+  marked edge or box is removed from the diagram outright — deterministically, by
+  splicing the LikeC4 CST — where `#proposed` only strips its own marker and
+  leaves the edge behind. `#proposed` (amber, additive) and `#proposal-delete`
+  (red, subtractive) are now the two halves of every change.
+- **File-level mapping — `metadata { file 'src/x.ts' }`** ([#3]). An element maps
+  to a single file instead of a folder. A file module owns exactly its file; a
+  folder module owns its subtree minus any mapped descendants — nested folders
+  and file leaves alike.
+  - This is what lets a deep nested diagram stay legal *and* enforceable. A
+    guarded contract or port that sits beside sibling sub-folders can be a file
+    leaf rather than collapsing into its parent folder. Collapsed, its edges
+    become ancestor↔descendant, which LikeC4 rejects with
+    `Invalid parent-child relationship`; as a leaf they stay sibling-to-sibling.
+  - Declaring both `folder` and `file` on one element is an error.
+
+### Changed
+
+- **`Module.folder: string` → `Module.path: string` + `Module.kind: 'folder' | 'file'`.**
+  SDK-breaking; the diagram surface and CLI are unaffected.
+- **`likec4` floor raised to `^1.58.0`.** The diff-view style-rule syntax Boundry
+  emits is verified against LikeC4 1.58; rendering the coloured views needs a
+  renderer at least that new.
+
+[#3]: https://github.com/makspiechota/boundry/issues/3
+[#4]: https://github.com/makspiechota/boundry/issues/4
+[#5]: https://github.com/makspiechota/boundry/issues/5
+
+## [0.3.0] — 2026-07-16 — superseded by 0.4.0
+
+Published early from a pre-feature snapshot (≈ 0.2.0 plus the `#anything`
+wildcard) and never carried the work now listed under 0.4.0. npm versions are
+immutable, so it stays on the registry; use **0.4.0**.
+
+## [0.2.0] — 2026-07-16
 
 The release that makes the diagram a *governed* artifact rather than just a
 source of rules. An agent can now be handed the diagram without being handed the

package/README.md

@@ -18,8 +18,9 @@ diagram (LikeC4)  ──►  boundary model  ──►  dependency-cruiser rules
 
 ## How it works
 
-1. You annotate each element in your diagram with the folder it owns:
-   `metadata { folder 'src/domain' }`.
+1. You annotate each element in your diagram with the source it owns — a folder,
+   `metadata { folder 'src/domain' }`, or a single file,
+   `metadata { file 'src/ports/contract.ts' }`.
 2. Every relationship you draw (`a -> b`) is an **allowed** dependency.
    Anything you don't draw is **forbidden**.
 3. Boundry lifts the diagram into a source-agnostic boundary model, compiles a
@@ -51,6 +52,41 @@ A mapped folder claims its **entire subtree**, so the abstraction level stays
 yours: one box on `src/domain` covers everything beneath it. You add finer boxes
 where you want finer *rules*, not to satisfy the coverage check.
 
+### Mapping a single file (deep nested diagrams)
+
+A rich C4 model nests: `application` › `metrics` › `ports` › `story-points-read`
+› `stub`, with a drill-down view at each level. Sometimes a *file* is the guarded
+thing — a contract, a port, a single repository — sitting beside its sibling
+sub-folders. Map it to a file instead of a folder:
+
+```likec4
+component ports 'ports' {
+  metadata { folder 'src/ports' }
+
+  component store 'in-memory-store' {
+    metadata { file 'src/ports/in-memory-store.ts' }   // a leaf, not a folder
+  }
+  component read 'story-points-read' {
+    metadata { folder 'src/ports/story-points-read' }
+    component stub 'stub' {
+      metadata { folder 'src/ports/story-points-read/stub' }
+    }
+  }
+}
+
+stub -> store   // a legal cross-subtree edge
+```
+
+This is what lets a deep tree be **both** the documentation and the enforcement
+model. Collapse that file into its parent folder and the edge becomes
+`stub -> ports` — a descendant importing its ancestor, which LikeC4 rejects with
+`Invalid parent-child relationship`. As a file leaf, `store` is a sibling, so the
+edge is legal *and* Boundry governs the file exactly: only `stub` may import it,
+and the surrounding `ports` folder no longer owns it.
+
+A file module owns exactly its file; a folder module owns its subtree minus any
+mapped descendants — nested folders and file leaves alike.
+
 ### Exempting test files and ambient declarations
 
 Every file under a mapped folder is governed as a rule *source* by default —
@@ -201,10 +237,86 @@ the allow-list, the newly-allowed set is exactly the set of self-approvals — n
 diff engine required. `approve --base` runs the same gate first, so it won't
 launder a self-granted edge into an approved one.
 
+**To retire an edge or a box, propose its removal** with `#proposal-delete`
+instead of deleting it. The marker colours it red; a pending deletion changes
+nothing (the edge stays allowed, the box stays enforced) so it never breaks the
+build. Then `approve` removes the marked edge or box outright:
+
+```likec4
+  module legacy 'Legacy' {
+    #proposal-delete
+    metadata { folder 'src/legacy' }
+  }
+  api -> legacy #proposal-delete
+```
+
+So `#proposed` and `#proposal-delete` are the two halves of a change — an amber
+addition that `approve` makes permanent, and a red removal that `approve` takes
+away — each a visible mark on the diagram until a human acts.
+
 Point your agents at
 [`.claude/skills/define-architecture-boundaries`](.claude/skills/define-architecture-boundaries/SKILL.md)
 and they'll follow this protocol.
 
+### Catching drift — the lock and `annotate` (prototype)
+
+`verify --base` trusts git for the baseline, which conflates *approved* with
+*committed*. If you'd rather Boundry own that baseline: `approve` records the
+accepted model to **`boundry.lock`** beside the diagram, and `annotate` compares
+against it — no git ref required.
+
+```bash
+boundry approve  --arch arch          # enact proposals AND write boundry.lock
+boundry annotate --arch arch          # rewrite undeclared additions as #proposed
+```
+
+`annotate` finds every edge or box that drifted past the lock without a marker —
+a self-grant — and rewrites it in place as a `#proposed` proposal. That's not
+cosmetic: a `#proposed` edge leaves the allow-list, so the silent grant becomes a
+red-again check and a highlighted box on the diagram, awaiting a real approval. It
+handles additions only; a removal is reported, not re-drawn (re-adding a deleted
+box would resurrect it as an enforced module).
+
+It also **paints the markers** — every `#proposed` edge/box gets an intrinsic
+`style { color amber }`, every `#proposal-delete` a `style { color red }`, written
+onto the element itself. Intrinsic style is the one styling LikeC4 renders on
+*every* surface — base views **and the "relationships of X" panel** — so a
+proposal shows up highlighted wherever a reviewer looks, not only in the generated
+diff views (whose view-scoped rules stop at the view boundary). `approve` strips
+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)
+
+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 holds a pending change** — the tightest scope
+that actually draws it — into a derived `boundry.diff.likec4`:
+
+```bash
+boundry diff --arch arch              # (re)write boundry.diff.likec4
+likec4 serve arch                     # review each layer, changes coloured
+```
+
+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.
+
+The file is a **derived artifact**: overwritten every run, removed when nothing is
+proposed, so it always matches the current diagram — regenerate it after
+`approve`. 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`).
+
+> Rendering the coloured diff views needs **LikeC4 ≥ 1.58** (the style-rule syntax
+> Boundry emits). Boundry itself depends on that floor; the tool you review with
+> (`likec4 serve`, the CLI, or the IDE extension) has to meet it too.
+
 ## CLI
 
 ```
@@ -212,6 +324,8 @@ boundry check    [--arch <dir>] [--cwd <dir>] [sources...]
 boundry generate [--arch <dir>] [--cwd <dir>] [--out <file>]
 boundry verify   [--arch <dir>] [--cwd <dir>] --base <git-ref>
 boundry approve  [--arch <dir>] [--cwd <dir>] [--base <git-ref>]
+boundry annotate [--arch <dir>]
+boundry diff     [--arch <dir>]
 ```
 
 | Flag | Meaning |
@@ -226,7 +340,12 @@ boundry approve  [--arch <dir>] [--cwd <dir>] [--base <git-ref>]
 - **`generate`** just emits the dependency-cruiser config so you can commit it or
   run `depcruise` yourself.
 - **`verify`** rejects dependencies granted without a proposal.
-- **`approve`** strips `#proposed` markers. For humans, not agents.
+- **`approve`** enacts markers (strips `#proposed`, 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`.
 
 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
@@ -284,7 +403,7 @@ without touching the core.
 
 Current limitations:
 
-- One element maps to exactly one folder.
+- One element maps to exactly one path — a folder or a single file.
 - Nesting is supported: you can map a parent folder *and* its children. A
   parent's edges govern only the parent's own files — a child never inherits
   them and must be permitted explicitly.

package/dist/adapters/enforcer/depcruiser.js

@@ -1,18 +1,35 @@
 import * as dependencyCruiser from 'dependency-cruiser';
-import { unconstrainedModules } from '../../core/model/boundary-model.js';
+import { unconstrainedModules, } from '../../core/model/boundary-model.js';
 // dependency-cruiser ships CommonJS; reach `cruise` through either interop shape.
 const cruise = dependencyCruiser.cruise ?? dependencyCruiser.default?.cruise;
-function folderPrefix(folder) {
-    return folder.replace(/\/+$/, '');
+function normalizePath(path) {
+    return path.replace(/\/+$/, '');
 }
-function folderToRegex(folder) {
-    const escaped = folderPrefix(folder).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    return `^${escaped}/`;
+function escapeRegex(path) {
+    return normalizePath(path).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-/** True if `child` is a folder strictly nested under `parent`. */
-function isDescendantFolder(child, parent) {
-    const c = folderPrefix(child);
-    const p = folderPrefix(parent);
+/**
+ * The regex matching exactly the sources a module owns: everything under a
+ * folder (`^src/core/`), or a single file exactly (`^src/x.ts$`).
+ */
+function moduleScopeRegex(m) {
+    return m.kind === 'file' ? `^${escapeRegex(m.path)}$` : `^${escapeRegex(m.path)}/`;
+}
+/** True if `source` (a file path) belongs to module `m`, ignoring descendants. */
+function ownsSource(m, source) {
+    const p = normalizePath(m.path);
+    return m.kind === 'file' ? source === p : source.startsWith(`${p}/`);
+}
+/**
+ * True if module `child` is nested strictly under module `parent`. Only a folder
+ * can contain anything; a file (or a folder equal to the child) contains nothing.
+ * A folder nesting a file leaf counts — that is the whole point of file mapping.
+ */
+function isNestedUnder(child, parent) {
+    if (parent.kind === 'file')
+        return false;
+    const c = normalizePath(child.path);
+    const p = normalizePath(parent.path);
     return c !== p && c.startsWith(`${p}/`);
 }
 /**
@@ -29,15 +46,17 @@ function buildForbiddenRules(model) {
         allowedTargets.set(m.id, new Set([m.id]));
     for (const edge of model.allowed)
         allowedTargets.get(edge.from)?.add(edge.to);
-    // Each module's scope: its folder, carving out any mapped descendant folders.
+    // Each module's scope: its path, carving out any mapped descendants (a nested
+    // folder OR a mapped file leaf living inside it — both belong to their own,
+    // more-specific module).
     const scopeOf = new Map();
     for (const m of model.modules) {
         const descendants = model.modules
-            .filter((other) => isDescendantFolder(other.folder, m.folder))
-            .map((other) => folderToRegex(other.folder));
+            .filter((other) => isNestedUnder(other, m))
+            .map((other) => moduleScopeRegex(other));
         scopeOf.set(m.id, descendants.length
-            ? { path: folderToRegex(m.folder), pathNot: descendants }
-            : { path: folderToRegex(m.folder) });
+            ? { path: moduleScopeRegex(m), pathNot: descendants }
+            : { path: moduleScopeRegex(m) });
     }
     // Exemptions apply to the `from` side only: matched files may import freely,
     // but every module's scope still governs them as a *target*, so importing a
@@ -72,7 +91,8 @@ function buildForbiddenRules(model) {
     // module claims is forbidden, not free. Additive — the pair rules above still
     // decide every mapped-to-mapped edge on their own.
     if (model.governRoot) {
-        const claimed = model.modules.map((m) => folderToRegex(m.folder));
+        const rootAsFolder = { id: '', title: '', path: model.governRoot, kind: 'folder' };
+        const claimed = model.modules.map(moduleScopeRegex);
         for (const from of model.modules) {
             if (unconstrained.has(from.id))
                 continue;
@@ -81,7 +101,7 @@ function buildForbiddenRules(model) {
                 comment: `${from.title} may not depend on code under '${model.governRoot}' that no module claims`,
                 severity: 'error',
                 from: asImporter(from.id),
-                to: { path: folderToRegex(model.governRoot), pathNot: claimed },
+                to: { path: moduleScopeRegex(rootAsFolder), pathNot: claimed },
             });
         }
     }
@@ -115,7 +135,7 @@ module.exports = {
         const violations = raw
             .filter((v) => v.rule?.severity === 'error')
             .map((v) => ({ from: v.from, to: v.to, rule: v.rule?.name ?? 'unknown' }));
-        // A module whose folder matched no source files enforces nothing — the
+        // A module whose path matched no source files enforces nothing — the
         // "green but inert" trap. Surface it so a passing check can't hide it.
         const seen = (output?.modules ?? []).map((m) => String(m.source));
         // A guardrail that analysed nothing must never report success. Seeing zero
@@ -127,9 +147,8 @@ module.exports = {
         }
         const warnings = [];
         for (const mod of model.modules) {
-            const prefix = `${mod.folder.replace(/\/+$/, '')}/`;
-            if (!seen.some((source) => source.startsWith(prefix))) {
-                warnings.push(`module '${mod.title}' maps to '${mod.folder}', which matched 0 source files`);
+            if (!seen.some((source) => ownsSource(mod, source))) {
+                warnings.push(`module '${mod.title}' maps to '${mod.path}', which matched 0 source files`);
             }
         }
         // An exemption is a grant, so a dead one is worth knowing about: it means
@@ -152,13 +171,12 @@ module.exports = {
         // claims. The model not covering the code is as much a gap as the code not
         // backing the model.
         if (model.governRoot) {
-            const rootPrefix = `${folderPrefix(model.governRoot)}/`;
-            const claimed = model.modules.map((m) => `${folderPrefix(m.folder)}/`);
+            const rootPrefix = `${normalizePath(model.governRoot)}/`;
             const unclaimed = new Set();
             for (const source of seen) {
                 if (!source.startsWith(rootPrefix))
                     continue;
-                if (claimed.some((prefix) => source.startsWith(prefix)))
+                if (model.modules.some((m) => ownsSource(m, source)))
                     continue;
                 // Exempt code is deliberately outside the architecture; asking a module
                 // to claim it would defeat the point of exempting it.

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

@@ -1,5 +1,5 @@
-import type { VisualizerPort } from '../../core/ports/ports.js';
-import type { BoundaryModel } from '../../core/model/boundary-model.js';
+import type { VisualizerPort, DiffView } from '../../core/ports/ports.js';
+import type { BoundaryModel, AllowedEdge } from '../../core/model/boundary-model.js';
 /**
  * First visualizer adapter. Reads a LikeC4 workspace and lifts it into the
  * boundary model: any element carrying a `folder` metadata key becomes a
@@ -11,10 +11,40 @@ export declare class LikeC4Visualizer implements VisualizerPort {
     constructor(workspaceDir: string);
     read(): Promise<BoundaryModel>;
     /**
-     * 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.
      */
     approve(): Promise<void>;
+    /**
+     * 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.
+     */
+    propose(edges: AllowedEdge[], moduleIds: string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    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), 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.
+     */
+    emitDiffViews(): Promise<DiffView[]>;
 }