@principal-ai/subsystems-react 0.42.0 → 0.43.1

package/dist/subsystem/model.js

@@ -15,14 +15,10 @@ import { MarkerType, } from '@xyflow/react';
 import { computeElkLayout, calculatePathLength } from '../utils/elkLayout';
 import { EDGE_LABEL_SIDE_PADDING, EDGE_ARROW_INSET } from '../utils/edgeLabel';
 import { purlOwnerName, purlRepoKey } from './paths';
-/** Stable id for a derived graph edge from a relation or walkthrough hop. */
+/** Stable id for a derived graph edge from a walkthrough hop. */
 export function derivedGraphEdgeId(from, to, mechanism) {
     return `${from}--${mechanism}-->${to}`;
 }
-/**
- * Build display edges for the graph canvas from topology relations and
- * walkthrough hops (deduped by from/to/mechanism).
- */
 /** React Flow / canvas edge id for a walkthrough hop. */
 export function walkthroughStepGraphEdgeId(step) {
     return derivedGraphEdgeId(step.from, step.to, step.mechanism);
@@ -57,18 +53,6 @@ export function reorderTargetIndex(boundary, from) {
 }
 export function deriveGraphEdges(doc) {
     const byId = new Map();
-    for (const r of doc.relations ?? []) {
-        const id = r.id || derivedGraphEdgeId(r.from, r.to, r.relationType);
-        if (!byId.has(id)) {
-            byId.set(id, {
-                id,
-                from: r.from,
-                to: r.to,
-                mechanism: r.relationType,
-                refs: r.refs,
-            });
-        }
-    }
     for (const w of doc.walkthroughs ?? []) {
         for (const step of w.steps) {
             const id = derivedGraphEdgeId(step.from, step.to, step.mechanism);
@@ -101,14 +85,20 @@ export function deriveGraphEdges(doc) {
     return [...byId.values()];
 }
 /**
- * True when the model has components but no topology or walkthrough edges.
- * Those snapshots are a catalog of declarations, not a graph.
+ * True when the model has components but no graph structure at all: no
+ * walkthrough/graphify edges AND no boundary containment (`module` / `process`)
+ * to frame. Those snapshots are a catalog of declarations, not a graph.
+ *
+ * A model that carries `module` / `process` membership still draws frames even
+ * with zero edges — that is static topology, so it is not constructs-only.
  */
 export function isConstructsOnlyModel(doc) {
     if (doc.components.length === 0)
         return false;
+    const hasBoundary = doc.components.some((c) => (c.module?.trim() ?? '') !== '' || (c.process?.trim() ?? '') !== '');
+    if (hasBoundary)
+        return false;
     return deriveGraphEdges({
-        relations: doc.relations,
         walkthroughs: doc.walkthroughs,
         graphifyRelations: doc.graphifyRelations,
     }).length === 0;
@@ -216,6 +206,20 @@ export function processGroupNodeId(processKey) {
 export function moduleGroupNodeId(moduleKey) {
     return `module:${moduleKey}`;
 }
+/** React Flow id for a directory boundary group node (path-derived nesting). */
+export function directoryGroupNodeId(dirKey) {
+    return `directory:${dirKey}`;
+}
+/** Normalize a module path to forward slashes, no trailing slash or `./`. */
+function normalizeModulePath(p) {
+    return p.trim().replace(/\\/g, '/').replace(/\/+$/, '').replace(/^\.\//, '');
+}
+/** Parent directory of a path-like key, or `''` when it has no slash. */
+function parentDirectory(path) {
+    const norm = normalizeModulePath(path);
+    const idx = norm.lastIndexOf('/');
+    return idx <= 0 ? '' : norm.slice(0, idx);
+}
 export const MODULE_BADGE_INSET = 12;
 const MODULE_BADGE_CHAR_WIDTH = 12.5;
 const MODULE_BADGE_CHROME = 16;
@@ -284,6 +288,8 @@ export function packageGroupNodeId(packageKey) {
 export function boundaryGroupNodeId(region) {
     if (region.kind === 'module')
         return moduleGroupNodeId(region.key);
+    if (region.kind === 'directory')
+        return directoryGroupNodeId(region.key);
     if (region.kind === 'package')
         return packageGroupNodeId(region.key);
     return processGroupNodeId(region.key);
@@ -379,6 +385,9 @@ function keepRegion(r, showSingletons) {
  * processes nest under a package the same way.
  */
 export function buildBoundaryLayoutGroups(doc, opts = {}) {
+    if (opts.moduleNesting === 'path') {
+        return buildBoundaryLayoutGroupsByPath(doc, opts);
+    }
     const showSingletons = opts.showSingletonFrames === true;
     const packageMode = opts.packageFrames ?? 'multi-repo';
     const byAlias = new Map(doc.components.map((c) => [c.alias, c]));
@@ -517,17 +526,246 @@ export function buildBoundaryLayoutGroups(doc, opts = {}) {
     return [...moduleGroups, ...processGroups, ...packageGroups];
 }
 /**
- * Runtime vocabulary of relation types — mirrors `SubsystemRelationType`.
- * Used to split derived display edges into their relation vs walkthrough
- * source (the two unions are disjoint).
+ * Path-nesting variant of {@link buildBoundaryLayoutGroups}.
+ *
+ * Adds directory frames derived from each component's `module` path segments
+ * (`src/session/transcript.ts` → `src` → `src/session` → module frame) and
+ * nests module frames under the deepest directory that contains them. Directory
+ * frames are kept when they hold 2+ leaves (or `showSingletonFrames`). Process
+ * and package frames nest above directories exactly as before.
+ *
+ * Module frames are unchanged (one per exact `module` string); leaves still
+ * parent to their module frame in `convertSubsystemToNodes`.
  */
-export const SUBSYSTEM_RELATION_TYPES = [
-    'extends',
-    'inherits',
-    'implements',
-    'mixes_in',
-    'method',
-];
+export function buildBoundaryLayoutGroupsByPath(doc, opts = {}) {
+    const showSingletons = opts.showSingletonFrames === true;
+    const packageMode = opts.packageFrames ?? 'multi-repo';
+    const byAlias = new Map(doc.components.map((c) => [c.alias, c]));
+    const allPackages = getSubsystemPackageRegions(doc);
+    const packageEligible = packageMode === 'always'
+        ? true
+        : packageMode === 'never'
+            ? false
+            : allPackages.length >= 2;
+    const packages = packageEligible
+        ? allPackages.filter((r) => keepRegion(r, showSingletons))
+        : [];
+    const keptPackageKeys = new Set(packages.map((r) => r.key));
+    const processes = getSubsystemRegions(doc).filter((r) => keepRegion(r, showSingletons));
+    const keptProcessKeys = new Set(processes.map((r) => r.key));
+    const modules = getSubsystemModuleRegions(doc).filter((r) => keepRegion(r, showSingletons));
+    // Directory regions: every ancestor directory of a component's module path,
+    // with the union of all aliases beneath it.
+    const dirMembers = new Map();
+    for (const c of doc.components) {
+        const m = c.module?.trim();
+        if (!m)
+            continue;
+        let d = parentDirectory(m);
+        while (d) {
+            const set = dirMembers.get(d) ?? new Set();
+            set.add(c.alias);
+            dirMembers.set(d, set);
+            d = parentDirectory(d);
+        }
+    }
+    const keptDirKeys = new Set();
+    for (const [d, members] of dirMembers) {
+        if (members.size >= 2 || showSingletons)
+            keptDirKeys.add(d);
+    }
+    // Files sitting directly in each directory (drives chain compaction below).
+    const directFileCount = new Map();
+    for (const c of doc.components) {
+        const m = c.module?.trim();
+        if (!m)
+            continue;
+        const d = parentDirectory(m);
+        if (d)
+            directFileCount.set(d, (directFileCount.get(d) ?? 0) + 1);
+    }
+    // Compact single-child directory chains, mirroring the file tree: a directory
+    // whose only child is a single subdirectory (and which holds no files
+    // directly) is merged into it. `app` → `app/book` renders one `app/book`
+    // frame, not `app` wrapping `book`.
+    let compacting = true;
+    while (compacting) {
+        compacting = false;
+        const childDirsOf = new Map();
+        for (const d of keptDirKeys) {
+            let a = parentDirectory(d);
+            while (a && !keptDirKeys.has(a))
+                a = parentDirectory(a);
+            if (!a)
+                continue;
+            const list = childDirsOf.get(a) ?? [];
+            list.push(d);
+            childDirsOf.set(a, list);
+        }
+        for (const d of [...keptDirKeys]) {
+            const childDirs = childDirsOf.get(d) ?? [];
+            if (childDirs.length === 1 && (directFileCount.get(d) ?? 0) === 0) {
+                keptDirKeys.delete(d);
+                compacting = true;
+            }
+        }
+    }
+    const nearestKeptDirAncestor = (dirKey) => {
+        let p = parentDirectory(dirKey);
+        while (p) {
+            if (keptDirKeys.has(p))
+                return p;
+            p = parentDirectory(p);
+        }
+        return undefined;
+    };
+    const dirRegions = [...keptDirKeys]
+        .sort()
+        .map((key) => {
+        // Label is the path relative to the enclosing kept directory (which
+        // already carries the prefix): `book` under `app`, or the full collapsed
+        // path `app/book` when the chain was compacted.
+        const ancestor = nearestKeptDirAncestor(key);
+        return {
+            kind: 'directory',
+            key,
+            label: ancestor ? key.slice(ancestor.length + 1) : key,
+            memberAliases: [...(dirMembers.get(key) ?? [])],
+        };
+    });
+    const moduleDirParent = (moduleKey) => {
+        let d = parentDirectory(moduleKey);
+        while (d) {
+            if (keptDirKeys.has(d))
+                return d;
+            d = parentDirectory(d);
+        }
+        return undefined;
+    };
+    const sharedProcessParent = (memberAliases) => {
+        const seen = new Set();
+        for (const alias of memberAliases) {
+            const p = byAlias.get(alias)?.process?.trim();
+            if (p)
+                seen.add(p);
+        }
+        if (seen.size !== 1)
+            return undefined;
+        const p = [...seen][0];
+        return keptProcessKeys.has(p) ? processGroupNodeId(p) : undefined;
+    };
+    const sharedPackageParent = (memberAliases) => {
+        const seen = new Set();
+        for (const alias of memberAliases) {
+            const c = byAlias.get(alias);
+            const pkg = c ? componentPackageKey(c) : undefined;
+            if (pkg)
+                seen.add(pkg);
+        }
+        if (seen.size !== 1)
+            return undefined;
+        const pkg = [...seen][0];
+        return keptPackageKeys.has(pkg) ? packageGroupNodeId(pkg) : undefined;
+    };
+    const frameParent = (memberAliases) => sharedProcessParent(memberAliases) ?? sharedPackageParent(memberAliases);
+    const moduleGroups = modules.map((r) => {
+        const dirParent = moduleDirParent(r.key);
+        const parentId = dirParent
+            ? directoryGroupNodeId(dirParent)
+            : frameParent(r.memberAliases);
+        // Relative label when nested: `app/book/actions.ts` under `app/book`
+        // reads as `actions.ts`. At the root the full module path stays.
+        const label = dirParent ? r.key.slice(dirParent.length + 1) : r.label;
+        return {
+            id: moduleGroupNodeId(r.key),
+            memberAliases: [...r.memberAliases],
+            parentId,
+            region: { ...r, label },
+        };
+    });
+    const dirGroupByKey = new Map(dirRegions.map((r) => [r.key, r]));
+    const moduleRegionByKey = new Map(modules.map((r) => [r.key, r]));
+    const dirGroups = dirRegions.map((r) => {
+        const id = directoryGroupNodeId(r.key);
+        const ancestor = nearestKeptDirAncestor(r.key);
+        const parentId = ancestor
+            ? directoryGroupNodeId(ancestor)
+            : frameParent(r.memberAliases);
+        // Immediate children: subdirectories and module frames parented here.
+        // Only child *group ids* go in the layout member list — a group's
+        // descendant leaves belong to its child groups alone, or ELK sees the
+        // same leaf in two compound parents and rejects the layout.
+        const childDirKeys = dirRegions
+            .filter((d) => nearestKeptDirAncestor(d.key) === r.key)
+            .map((d) => d.key);
+        const childModuleKeys = modules
+            .filter((m) => moduleDirParent(m.key) === r.key)
+            .map((m) => m.key);
+        const claimed = new Set();
+        for (const dk of childDirKeys) {
+            for (const a of dirGroupByKey.get(dk)?.memberAliases ?? [])
+                claimed.add(a);
+        }
+        for (const mk of childModuleKeys) {
+            for (const a of moduleRegionByKey.get(mk)?.memberAliases ?? [])
+                claimed.add(a);
+        }
+        const directLeaves = r.memberAliases.filter((a) => !claimed.has(a));
+        return {
+            id,
+            memberAliases: [
+                ...childDirKeys.map(directoryGroupNodeId),
+                ...childModuleKeys.map(moduleGroupNodeId),
+                ...directLeaves,
+            ],
+            parentId,
+            region: r,
+        };
+    });
+    const frameGroups = [...dirGroups, ...moduleGroups];
+    // Aliases owned by a module frame (singleton or not) must not become direct
+    // leaves of an enclosing process/package frame.
+    const moduleMemberAliases = new Set();
+    for (const r of modules)
+        for (const a of r.memberAliases)
+            moduleMemberAliases.add(a);
+    const processGroups = processes.map((r) => {
+        const processId = processGroupNodeId(r.key);
+        const nested = frameGroups.filter((g) => g.parentId === processId);
+        const claimed = new Set();
+        for (const g of nested)
+            for (const a of g.region.memberAliases)
+                claimed.add(a);
+        const directLeaves = r.memberAliases.filter((alias) => !claimed.has(alias) && !moduleMemberAliases.has(alias));
+        return {
+            id: processId,
+            memberAliases: [...nested.map((g) => g.id), ...directLeaves],
+            parentId: sharedPackageParent(r.memberAliases),
+            region: r,
+        };
+    });
+    const processMemberAliases = new Set();
+    for (const r of processes)
+        for (const a of r.memberAliases)
+            processMemberAliases.add(a);
+    const packageGroups = packages.map((r) => {
+        const packageId = packageGroupNodeId(r.key);
+        const nested = [...processGroups, ...frameGroups].filter((g) => g.parentId === packageId);
+        const claimed = new Set();
+        for (const g of nested)
+            for (const a of g.region.memberAliases)
+                claimed.add(a);
+        const directLeaves = r.memberAliases.filter((alias) => !claimed.has(alias) &&
+            !moduleMemberAliases.has(alias) &&
+            !processMemberAliases.has(alias));
+        return {
+            id: packageId,
+            memberAliases: [...nested.map((g) => g.id), ...directLeaves],
+            region: r,
+        };
+    });
+    return [...frameGroups, ...processGroups, ...packageGroups];
+}
 /** Runtime vocabulary of walkthrough hop mechanisms — mirrors `SubsystemWalkthroughMechanism`. */
 export const SUBSYSTEM_WALKTHROUGH_MECHANISMS = [
     'calls',
@@ -539,24 +777,14 @@ export const SUBSYSTEM_WALKTHROUGH_MECHANISMS = [
     'watches',
     'registers-into',
 ];
-const RELATION_TYPE_SET = new Set(SUBSYSTEM_RELATION_TYPES);
 const WALKTHROUGH_MECHANISM_SET = new Set(SUBSYSTEM_WALKTHROUGH_MECHANISMS);
-/** True when a mechanism belongs to the topology relation vocabulary. */
-export function isRelationMechanism(mechanism) {
-    return RELATION_TYPE_SET.has(mechanism);
-}
 /** True when a mechanism belongs to the walkthrough hop vocabulary. */
 export function isWalkthroughMechanism(mechanism) {
     return WALKTHROUGH_MECHANISM_SET.has(mechanism);
 }
 export const MECHANISM_COLOR = {
     calls: '#22c55e',
-    extends: '#b48ead',
-    inherits: '#9b6fd0',
-    implements: '#c586c0',
-    mixes_in: '#d474a8',
     uses: '#e3b341',
-    method: '#c586c0',
     feeds: '#4ec9b0',
     produces: '#a78bfa',
     writes: '#e8853a',
@@ -566,12 +794,7 @@ export const MECHANISM_COLOR = {
 };
 export const MECHANISM_STYLE = {
     calls: 'solid',
-    extends: 'dashed',
-    inherits: 'dashed',
-    implements: 'dashed',
-    mixes_in: 'dashed',
     uses: 'solid',
-    method: 'solid',
     feeds: 'solid',
     produces: 'solid',
     writes: 'solid',
@@ -718,12 +941,7 @@ export function boundaryFill(color, alpha = '1f') {
  *  directly verifiable" styling of edge labels. */
 export const MECHANISM_DESCRIPTIONS = [
     ['calls', 'function/method call (call graph edge)', true],
-    ['extends', 'class inheritance', true],
-    ['inherits', 'class inheritance', true],
-    ['implements', 'implements interface / protocol', true],
-    ['mixes_in', 'applies mixin', true],
     ['uses', 'general dependency (import, call, or reference)', false],
-    ['method', 'structural: has method / member', true],
     ['feeds', 'data flow: output feeds into input', false],
     ['produces', 'data flow: produces / outputs', false],
     ['writes', 'state access: mutates retained state', true],
@@ -731,6 +949,29 @@ export const MECHANISM_DESCRIPTIONS = [
     ['watches', 'observes retained state without owning it', false],
     ['registers-into', 'registration pattern', false],
 ];
+/**
+ * Single border/badge color for directory (folder) frames. Folders read as one
+ * kind of container, so they share a neutral hue rather than hashing per-path
+ * like modules / processes / packages. Host `boundaryColors` still overrides.
+ */
+export const FOLDER_FRAME_COLOR = '#7aa2d4';
+/**
+ * True when a boundary frame names a folder. `directory` frames always are.
+ * A `module` frame is a folder when its key looks like a directory path — the
+ * last segment has no file extension (the model has no explicit file/folder
+ * flag, so this is a heuristic; `Dockerfile`-style extensionless files read as
+ * folders).
+ */
+export function isFolderFrame(region) {
+    if (!region)
+        return false;
+    if (region.kind === 'directory')
+        return true;
+    if (region.kind !== 'module')
+        return false;
+    const last = region.key.split('/').pop() ?? '';
+    return last !== '' && !last.includes('.');
+}
 /** Package color palette (derived deterministically from the package name). */
 export function packageColor(name) {
     const palette = [
@@ -1041,8 +1282,12 @@ export function subsystemGraphLayoutKey(doc) {
  * layered with minimized crossings.
  */
 export async function buildSubsystemGraph(doc, opts = {}) {
-    const { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights, showSingletonFrames, packageFrames, graphifyRelations, orderByLine = false, } = opts;
-    const frameOpts = { showSingletonFrames, packageFrames };
+    const { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights, showSingletonFrames, packageFrames, moduleNesting, graphifyRelations, orderByLine = false, } = opts;
+    const frameOpts = {
+        showSingletonFrames,
+        packageFrames,
+        moduleNesting,
+    };
     const nodes = convertSubsystemToNodes(doc, { maxNodeWidth });
     const edges = convertSubsystemToEdges(doc, graphifyRelations);
     // Nested boundary tree: package → process → module → leaves.
@@ -1133,7 +1378,12 @@ export async function buildSubsystemGraph(doc, opts = {}) {
         try {
             const result = await computeElkLayout(nodes, edges, {
                 routingStyle: 'orthogonal',
-                direction: 'RIGHT',
+                // Edge-driven graphs flow left-to-right. With no edges (pure
+                // containment, e.g. the static-topology layer) a RIGHT layout stacks
+                // disconnected top-level frames in one vertical column; DOWN makes the
+                // layered pass place those sibling frames along the horizontal axis
+                // while each frame's members stack vertically.
+                direction: edges.length > 0 ? 'RIGHT' : 'DOWN',
                 nodeSpacing: 60,
                 edgeSpacing: 30,
                 edgeNodeSpacing: 60,
@@ -1153,7 +1403,7 @@ export async function buildSubsystemGraph(doc, opts = {}) {
                     // Modules collapse a long path to `first/…/last`, so they only need
                     // room for the collapsed badge. Processes/packages never collapse:
                     // size the frame to hold the full centered label plus padding.
-                    minWidth: g.region.kind === 'module'
+                    minWidth: g.region.kind === 'module' || g.region.kind === 'directory'
                         ? moduleMinWidthForBadge(g.region.label)
                         : boundaryMinWidthForBadge(g.region.label),
                 })),
@@ -1221,7 +1471,7 @@ export async function buildSubsystemGraph(doc, opts = {}) {
                     id: g.id,
                     type: 'subsystem-group',
                     position: { x: 0, y: 0 },
-                    width: Math.max(400, g.region.kind === 'module'
+                    width: Math.max(400, g.region.kind === 'module' || g.region.kind === 'directory'
                         ? moduleMinWidthForBadge(g.region.label)
                         : boundaryMinWidthForBadge(g.region.label)),
                     height: 300,