boundry 0.3.0 → 0.5.0

package/dist/cli/index.js

@@ -1,12 +1,10 @@
 #!/usr/bin/env node
-import { execFileSync } from 'node:child_process';
-import { mkdtempSync, readdirSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 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>] [--cwd <dir>] [--out <file>] [sources...]';
 function optValue(args, flag) {
     const i = args.indexOf(flag);
     return i >= 0 ? args[i + 1] : undefined;
@@ -22,30 +20,6 @@ function positionals(args) {
     }
     return out;
 }
-/**
- * Materialize the architecture as of a git ref into a temp workspace, so the
- * previously-approved boundary model can be lifted and compared against HEAD.
- */
-function materializeArchAt(archDir, ref) {
-    const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
-        cwd: archDir,
-        encoding: 'utf8',
-    }).trim();
-    const workDir = mkdtempSync(join(tmpdir(), 'boundry-base-'));
-    for (const file of readdirSync(archDir).filter((f) => f.endsWith('.likec4'))) {
-        try {
-            const content = execFileSync('git', ['show', `${ref}:${relative(gitRoot, join(archDir, file))}`], {
-                cwd: gitRoot,
-                encoding: 'utf8',
-            });
-            writeFileSync(join(workDir, file), content);
-        }
-        catch {
-            // The file did not exist at `ref` — everything it declares is new.
-        }
-    }
-    return workDir;
-}
 function countGrants(granted) {
     return granted.edges.length + granted.exemptions.length;
 }
@@ -69,14 +43,17 @@ async function main() {
     const archDir = resolve(optValue(rest, '--arch') ?? '.');
     const outArg = optValue(rest, '--out');
     const outFile = outArg ? resolve(outArg) : undefined;
-    const baseRef = optValue(rest, '--base');
     // `--cwd` lets you check a repo without cd-ing into it. `folder` metadata is
     // relative to the target repo root, so the enforcer runs from there.
     const cwd = optValue(rest, '--cwd');
     if (cwd)
         process.chdir(resolve(cwd));
+    // The accepted-state lock lives beside the diagram it locks. `approve` writes
+    // it; `verify` and `annotate` read it — the baseline Boundry owns, decoupled
+    // from git, so "accepted" never means merely "committed".
+    const lockFile = join(archDir, 'boundry.lock');
+    const readLock = () => existsSync(lockFile) ? readFileSync(lockFile, 'utf8') : undefined;
     const pipeline = new Pipeline(new LikeC4Visualizer(archDir), new DepCruiserEnforcer());
-    const grantedSince = (ref) => pipeline.verify(new LikeC4Visualizer(materializeArchAt(archDir, ref)));
     if (command === 'generate') {
         const config = await pipeline.generate();
         const out = outFile ?? resolve(config.filename);
@@ -102,37 +79,78 @@ async function main() {
         return;
     }
     if (command === 'verify') {
-        if (!baseRef) {
-            console.error('Boundry: verify requires --base <git-ref>');
+        const lock = readLock();
+        if (!lock) {
+            console.error(`Boundry: no ${relative(process.cwd(), lockFile)} — run 'boundry approve' first to record the accepted state`);
             process.exitCode = 2;
             return;
         }
-        const granted = await grantedSince(baseRef);
+        const granted = await pipeline.verify(lock);
         if (countGrants(granted) === 0) {
-            console.log(`Boundry: ✓ nothing granted without a #proposed marker (vs ${baseRef})`);
+            console.log('Boundry: ✓ nothing granted without a #proposed marker (vs the accepted lock)');
             return;
         }
-        console.error(`Boundry: ✗ ${countGrants(granted)} grant(s) made without a #proposed marker (vs ${baseRef})`);
+        console.error(`Boundry: ✗ ${countGrants(granted)} grant(s) made without a #proposed marker (vs the accepted lock)`);
         listGrants(granted);
         process.exitCode = 1;
         return;
     }
     if (command === 'approve') {
         // Approving must never launder an edge that skipped the proposal protocol.
-        if (baseRef) {
-            const granted = await grantedSince(baseRef);
+        // The accepted lock is the baseline: a bare edge added since the last approve
+        // is in the allow-list but not the lock, so it surfaces here; a #proposed one
+        // is excluded from the allow-list, so it passes and gets enacted below. The
+        // first approve has no lock yet — it establishes the initial accepted state.
+        const lock = readLock();
+        if (lock) {
+            const granted = await pipeline.verify(lock);
             if (countGrants(granted) > 0) {
-                console.error(`Boundry: ✗ refusing to approve — ${countGrants(granted)} grant(s) were made without a #proposed marker (vs ${baseRef})`);
+                console.error(`Boundry: ✗ refusing to approve — ${countGrants(granted)} grant(s) were made without a #proposed marker (vs the accepted lock)`);
                 listGrants(granted);
                 process.exitCode = 1;
                 return;
             }
         }
         else {
-            console.error('Boundry: ⚠ no --base given — approving without verifying that every new edge was proposed');
+            console.error('Boundry: ⚠ no boundry.lock yet — approving to record the initial accepted state');
+        }
+        const nextLock = await pipeline.approve();
+        writeFileSync(lockFile, nextLock);
+        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))`);
         }
-        await pipeline.approve();
-        console.log('Boundry: ✓ approved — stripped #proposed markers from the diagram');
+        console.log('  Open the diagram in `likec4 serve` to review each layer.');
         return;
     }
     console.error(USAGE);

package/dist/core/model/boundary-model.d.ts

@@ -82,3 +82,18 @@ export declare function newlyExemptedImporters(base: BoundaryModel, head: Bounda
  * dependencies granted WITHOUT going through a proposal — i.e. self-approvals.
  */
 export declare function newlyAllowedEdges(base: BoundaryModel, head: BoundaryModel): AllowedEdge[];
+/**
+ * Modules present at `head` but not at `base`, keyed by id. A `#proposed` element
+ * stays a module (the marker is visual-only), so this reports both bare-added and
+ * already-proposed new boxes — the annotator makes marking idempotent.
+ */
+export declare function newlyAddedModules(base: BoundaryModel, head: BoundaryModel): Module[];
+/**
+ * The accepted state, written as a canonical string — the lock. `approve` records
+ * it so change detection has a baseline it OWNS, rather than trusting whatever git
+ * happens to hold. Deterministic: fields and lists are sorted, so the same model
+ * always serializes byte-for-byte the same.
+ */
+export declare function serializeModel(model: BoundaryModel): string;
+/** Read a lock back into a model. Inverse of {@link serializeModel}. */
+export declare function parseModel(text: string): BoundaryModel;

package/dist/core/model/boundary-model.js

@@ -34,3 +34,43 @@ export function newlyAllowedEdges(base, head) {
     const allowedAtBase = new Set(base.allowed.map(edgeKey));
     return head.allowed.filter((edge) => !allowedAtBase.has(edgeKey(edge)));
 }
+/**
+ * Modules present at `head` but not at `base`, keyed by id. A `#proposed` element
+ * stays a module (the marker is visual-only), so this reports both bare-added and
+ * already-proposed new boxes — the annotator makes marking idempotent.
+ */
+export function newlyAddedModules(base, head) {
+    const atBase = new Set(base.modules.map((m) => m.id));
+    return head.modules.filter((m) => !atBase.has(m.id));
+}
+/**
+ * The accepted state, written as a canonical string — the lock. `approve` records
+ * it so change detection has a baseline it OWNS, rather than trusting whatever git
+ * happens to hold. Deterministic: fields and lists are sorted, so the same model
+ * always serializes byte-for-byte the same.
+ */
+export function serializeModel(model) {
+    const canonical = {
+        modules: [...model.modules]
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map((m) => ({ id: m.id, title: m.title, path: m.path, kind: m.kind })),
+        allowed: [...model.allowed]
+            .sort((a, b) => edgeKey(a).localeCompare(edgeKey(b)))
+            .map((e) => ({ from: e.from, to: e.to })),
+        wildcards: [...model.wildcards].sort(),
+        exemptImporters: [...model.exemptImporters].sort(),
+        ...(model.governRoot ? { governRoot: model.governRoot } : {}),
+    };
+    return `${JSON.stringify(canonical, null, 2)}\n`;
+}
+/** Read a lock back into a model. Inverse of {@link serializeModel}. */
+export function parseModel(text) {
+    const raw = JSON.parse(text);
+    return {
+        modules: raw.modules ?? [],
+        allowed: raw.allowed ?? [],
+        wildcards: raw.wildcards ?? [],
+        exemptImporters: raw.exemptImporters ?? [],
+        governRoot: raw.governRoot,
+    };
+}

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

@@ -1,5 +1,10 @@
-import type { VisualizerPort, EnforcerPort, EnforcerConfig, CheckResult } from "../ports/ports.js";
-import type { AllowedEdge } from "../model/boundary-model.js";
+import type { VisualizerPort, EnforcerPort, EnforcerConfig, CheckResult, DiffView } from "../ports/ports.js";
+import type { AllowedEdge, Module } from "../model/boundary-model.js";
+/** What the annotator turned into explicit `#proposed` proposals. */
+export interface AnnotateResult {
+    edges: AllowedEdge[];
+    modules: Module[];
+}
 /**
  * What a diagram grants that the approved base did not. Both kinds of grant are
  * reported, because both let code cross a boundary that was previously closed.
@@ -26,12 +31,40 @@ export declare class Pipeline {
     /** Diagram -> boundary model -> run the linter over `sources`. */
     check(sources: string[]): Promise<CheckResult>;
     /**
-     * What this diagram grants that `base` did not — dependencies added without a
-     * `#proposed` marker, and importer exemptions added. Proposals are excluded
-     * from the allow-list, so anything reported here bypassed the approval
-     * protocol.
+     * What this diagram grants that the accepted `lock` did not — dependencies
+     * added without a `#proposed` marker, and importer exemptions added. Proposals
+     * are excluded from the allow-list, so anything reported here bypassed the
+     * approval protocol.
+     *
+     * The baseline is the lock — the accepted state `approve` records — not a git
+     * ref. The lock exists precisely to decouple "accepted" from "committed", so
+     * verify reads from it, exactly as `annotate` does; the two can never disagree
+     * about what "accepted" means. It also catches a committed-but-unapproved bare
+     * edge, which re-deriving a baseline from a git ref would silently absorb.
+     */
+    verify(lock: string): Promise<VerifyResult>;
+    /**
+     * Enact the diagram's pending proposals (strip `#proposed`, remove
+     * `#proposal-delete`), then return the resulting accepted model as a lock
+     * string. The caller persists it: that lock — written by approve, not inferred
+     * from git — is the baseline change detection compares against.
+     */
+    approve(): Promise<string>;
+    /**
+     * Compare the diagram against a previously accepted lock and rewrite every
+     * undeclared addition — a bare new edge (a self-grant) or box — into an
+     * explicit `#proposed` proposal in the source, then paints intrinsic styling on
+     * every marker so the proposal is highlighted on every LikeC4 surface. Turns
+     * silent drift into a reviewable, colourable proposal without trusting git for
+     * the baseline.
+     */
+    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).
      */
-    verify(base: VisualizerPort): Promise<VerifyResult>;
-    /** Approve proposed edges: strip their `#proposed` markers from the diagram. */
-    approve(): Promise<void>;
+    diffViews(): Promise<DiffView[]>;
 }

package/dist/core/pipeline/pipeline.js

@@ -1,4 +1,4 @@
-import { newlyAllowedEdges, newlyExemptedImporters, } from "../model/boundary-model.js";
+import { newlyAddedModules, newlyAllowedEdges, newlyExemptedImporters, parseModel, serializeModel, } from "../model/boundary-model.js";
 /**
  * The SDK's public surface. Orchestrates the two driven ports and stays blind
  * to any concrete diagram source or linter — swap adapters, this is untouched.
@@ -21,20 +21,61 @@ export class Pipeline {
         return this.enforcer.check(model, sources);
     }
     /**
-     * What this diagram grants that `base` did not — dependencies added without a
-     * `#proposed` marker, and importer exemptions added. Proposals are excluded
-     * from the allow-list, so anything reported here bypassed the approval
-     * protocol.
+     * What this diagram grants that the accepted `lock` did not — dependencies
+     * added without a `#proposed` marker, and importer exemptions added. Proposals
+     * are excluded from the allow-list, so anything reported here bypassed the
+     * approval protocol.
+     *
+     * The baseline is the lock — the accepted state `approve` records — not a git
+     * ref. The lock exists precisely to decouple "accepted" from "committed", so
+     * verify reads from it, exactly as `annotate` does; the two can never disagree
+     * about what "accepted" means. It also catches a committed-but-unapproved bare
+     * edge, which re-deriving a baseline from a git ref would silently absorb.
      */
-    async verify(base) {
-        const [baseModel, headModel] = await Promise.all([base.read(), this.visualizer.read()]);
+    async verify(lock) {
+        const base = parseModel(lock);
+        const head = await this.visualizer.read();
         return {
-            edges: newlyAllowedEdges(baseModel, headModel),
-            exemptions: newlyExemptedImporters(baseModel, headModel),
+            edges: newlyAllowedEdges(base, head),
+            exemptions: newlyExemptedImporters(base, head),
         };
     }
-    /** Approve proposed edges: strip their `#proposed` markers from the diagram. */
+    /**
+     * Enact the diagram's pending proposals (strip `#proposed`, remove
+     * `#proposal-delete`), then return the resulting accepted model as a lock
+     * string. The caller persists it: that lock — written by approve, not inferred
+     * from git — is the baseline change detection compares against.
+     */
     async approve() {
-        return this.visualizer.approve();
+        await this.visualizer.approve();
+        const accepted = await this.visualizer.read();
+        return serializeModel(accepted);
+    }
+    /**
+     * Compare the diagram against a previously accepted lock and rewrite every
+     * undeclared addition — a bare new edge (a self-grant) or box — into an
+     * explicit `#proposed` proposal in the source, then paints intrinsic styling on
+     * every marker so the proposal is highlighted on every LikeC4 surface. Turns
+     * silent drift into a reviewable, colourable proposal without trusting git for
+     * the baseline.
+     */
+    async annotate(lock) {
+        const accepted = parseModel(lock);
+        const head = await this.visualizer.read();
+        const edges = newlyAllowedEdges(accepted, head);
+        const modules = newlyAddedModules(accepted, head);
+        await this.visualizer.propose(edges, modules.map((m) => m.id));
+        await this.visualizer.styleMarkers();
+        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).
+     */
+    async diffViews() {
+        return this.visualizer.emitDiffViews();
     }
 }

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

@@ -1,4 +1,4 @@
-import type { BoundaryModel } from '../model/boundary-model.js';
+import type { AllowedEdge, BoundaryModel } from '../model/boundary-model.js';
 /** A driven port: turns some diagram source into the boundary model. */
 export interface VisualizerPort {
     read(): Promise<BoundaryModel>;
@@ -7,6 +7,42 @@ export interface VisualizerPort {
      * promoting intent edges to approved. Source-preserving; never an LLM edit.
      */
     approve(): Promise<void>;
+    /**
+     * Deterministically mark the given edges and elements `#proposed` in the
+     * source. The inverse of `approve` for additions: it rewrites an undeclared
+     * change into an explicit, colourable proposal. Idempotent — anything already
+     * marked is left alone. Source-preserving; never an LLM edit.
+     */
+    propose(edges: AllowedEdge[], moduleIds: string[]): Promise<void>;
+    /**
+     * Paint intrinsic `style { color … }` on every edge/box carrying a marker, so a
+     * proposal is highlighted on every LikeC4 surface — base views and the
+     * relationships panel, not only the generated diff views. Amber for `#proposed`,
+     * red for `#proposal-delete`. Idempotent; `approve` strips it back out.
+     * Source-preserving; never an LLM edit.
+     */
+    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
+     * each run, and removed when nothing is proposed. Returns one entry per view.
+     */
+    emitDiffViews(): 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.
+ */
+export interface DiffView {
+    /** The generated view id, e.g. `boundry_diff_root` or `boundry_diff_billing`. */
+    id: string;
+    /** The scope element's fqn, or undefined for the model root. */
+    scope?: string;
+    /** How many pending `#proposed` / `#proposal-delete` changes this layer holds. */
+    changes: number;
 }
 /** A generated linter config artifact. */
 export interface EnforcerConfig {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boundry",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Compile a C4 architecture diagram into a deterministic dependency linter. Deterministic architectural guardrails for AI agents and humans.",
   "type": "module",
   "license": "MIT",
@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "dependency-cruiser": "^16.4.0",
-    "likec4": "^1.46.0",
+    "likec4": "^1.58.0",
     "typescript": "^5.6.0"
   },
   "devDependencies": {