boundry 0.2.0 → 0.4.0

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

@@ -2,14 +2,25 @@
  * The single, source-agnostic representation everything in Boundry compiles
  * from. A visualizer adapter produces it; an enforcer adapter renders it.
  */
-/** A unit of architecture that maps to a folder of source code. */
+/** A unit of architecture that maps to a folder or a single file of source. */
 export interface Module {
     /** Stable id, taken from the diagram element. */
     id: string;
     /** Human-readable name for messages. */
     title: string;
-    /** Source path prefix the module owns, e.g. "src/core". */
-    folder: string;
+    /**
+     * Source path the module owns — a folder prefix (e.g. "src/core") or a single
+     * file (e.g. "src/ports/contract.ts"), per `kind`.
+     */
+    path: string;
+    /**
+     * Whether `path` is a folder (owns everything under it) or a single file
+     * (owns exactly that file). A file leaf lets a guarded contract or port sit
+     * beside its sibling sub-folders in a nested diagram, so its edges stay
+     * sibling-to-sibling — which is what keeps a deep C4 tree legal in LikeC4
+     * (ancestor↔descendant relationships are rejected) *and* enforceable.
+     */
+    kind: 'folder' | 'file';
 }
 /** A permitted dependency: modules in `from` may import modules in `to`. */
 export interface AllowedEdge {
@@ -71,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.
@@ -32,6 +37,28 @@ export declare class Pipeline {
      * protocol.
      */
     verify(base: VisualizerPort): Promise<VerifyResult>;
-    /** Approve proposed edges: strip their `#proposed` markers from the diagram. */
-    approve(): Promise<void>;
+    /**
+     * 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).
+     */
+    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.
@@ -33,8 +33,42 @@ export class Pipeline {
             exemptions: newlyExemptedImporters(baseModel, headModel),
         };
     }
-    /** 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.2.0",
+  "version": "0.4.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": {