boundry 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,7 +4,32 @@ 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.3.0] — unreleased
+
+Makes the "one file can be both the communication diagram and the enforcement
+model" promise hold for deep, nested C4 trees.
+
+### Added
+
+- **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.
+
+[#3]: https://github.com/makspiechota/boundry/issues/3
+
+## [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 —
@@ -284,7 +320,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.js

@@ -88,7 +88,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 +113,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 +144,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 });
             }
         }

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 {

package/package.json

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