@principal-ai/subsystems-react 0.43.0 → 0.43.2

package/src/subsystem/model.ts

@@ -477,15 +477,23 @@ export function deriveGraphEdges(doc: {
 }
 
 /**
- * True when the model has components but no walkthrough or graphify 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: {
-  components: readonly { alias: string }[];
+  components: readonly { alias: string; module?: string; process?: string }[];
   walkthroughs?: readonly SubsystemWalkthrough[];
   graphifyRelations?: readonly SubsystemGraphifyRelation[];
 }): boolean {
   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({
     walkthroughs: doc.walkthroughs,
     graphifyRelations: doc.graphifyRelations,
@@ -608,7 +616,7 @@ export type SubsystemGraphNodeType = 'subsystem-component' | 'subsystem-group';
  */
 export interface SubsystemProcessRegion {
   /** Discriminator — which field / identity produced this region. */
-  kind: 'process' | 'module' | 'package';
+  kind: 'process' | 'module' | 'directory' | 'package';
   /** The `process` / `module` value, or purl repo key for packages. */
   key: string;
   /** Display label for the boundary frame. */
@@ -631,6 +639,15 @@ export interface BoundaryFrameOptions {
    * - `never`: no package frames
    */
   packageFrames?: 'multi-repo' | 'always' | 'never';
+  /**
+   * How module frames group.
+   * - `exact` (default): one frame per distinct `module` string.
+   * - `path`: derive directory frames from the path segments of each
+   *   component's `module`, and nest module frames under the directories that
+   *   contain them. Directory frames are interposed between process/package
+   *   and module frames.
+   */
+  moduleNesting?: 'exact' | 'path';
 }
 
 /** React Flow id for a process boundary group node. */
@@ -643,6 +660,23 @@ export function moduleGroupNodeId(moduleKey: string): string {
   return `module:${moduleKey}`;
 }
 
+/** React Flow id for a directory boundary group node (path-derived nesting). */
+export function directoryGroupNodeId(dirKey: string): string {
+  return `directory:${dirKey}`;
+}
+
+/** Normalize a module path to forward slashes, no trailing slash or `./`. */
+function normalizeModulePath(p: string): string {
+  return p.trim().replace(/\\/g, '/').replace(/\/+$/, '').replace(/^\.\//, '');
+}
+
+/** Parent directory of a path-like key, or `''` when it has no slash. */
+function parentDirectory(path: string): string {
+  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;
@@ -718,6 +752,7 @@ export function packageGroupNodeId(packageKey: string): string {
 /** React Flow id for a boundary group of any kind. */
 export function boundaryGroupNodeId(region: Pick<SubsystemProcessRegion, 'kind' | 'key'>): string {
   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);
 }
@@ -840,6 +875,9 @@ export function buildBoundaryLayoutGroups(
   doc: Pick<SubsystemModelDocument, 'components'>,
   opts: BoundaryFrameOptions = {},
 ): BoundaryLayoutGroup[] {
+  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]));
@@ -983,6 +1021,288 @@ export function buildBoundaryLayoutGroups(
   return [...moduleGroups, ...processGroups, ...packageGroups];
 }
 
+/**
+ * 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 function buildBoundaryLayoutGroupsByPath(
+  doc: Pick<SubsystemModelDocument, 'components'>,
+  opts: BoundaryFrameOptions = {},
+): BoundaryLayoutGroup[] {
+  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 nesting is SCOPED to the enclosing process (else package, else
+  // root), so module grouping stays subordinate to process boundaries. A
+  // folder that spans two processes is split per process rather than becoming
+  // a frame that belongs to neither — which would leave the process frames
+  // childless and drop them. Composite key = `${scopeKey}\0${path}`.
+  const scopeKeyFor = (c: SubsystemComponent): string => {
+    const p = c.process?.trim();
+    if (p && keptProcessKeys.has(p)) return `p:${p}`;
+    const pkg = componentPackageKey(c);
+    if (pkg && keptPackageKeys.has(pkg)) return `k:${pkg}`;
+    return 'root';
+  };
+  const scopeParentId = (scopeKey: string): string | undefined => {
+    if (scopeKey.startsWith('p:')) return processGroupNodeId(scopeKey.slice(2));
+    if (scopeKey.startsWith('k:')) return packageGroupNodeId(scopeKey.slice(2));
+    return undefined;
+  };
+  const dirGroupId = (scopeKey: string, path: string): string =>
+    scopeKey === 'root'
+      ? directoryGroupNodeId(path)
+      : `directory:${scopeKey}::${path}`;
+
+  const dirMembers = new Map<string, Set<string>>();
+  const dirPathOf = new Map<string, string>();
+  const dirScopeOf = new Map<string, string>();
+  for (const c of doc.components) {
+    const m = c.module?.trim();
+    if (!m) continue;
+    const scope = scopeKeyFor(c);
+    let d = parentDirectory(m);
+    while (d) {
+      const ck = `${scope}\0${d}`;
+      const set = dirMembers.get(ck) ?? new Set<string>();
+      set.add(c.alias);
+      dirMembers.set(ck, set);
+      dirPathOf.set(ck, d);
+      dirScopeOf.set(ck, scope);
+      d = parentDirectory(d);
+    }
+  }
+  const keptDirs = new Set<string>();
+  for (const [ck, members] of dirMembers) {
+    if (members.size >= 2 || showSingletons) keptDirs.add(ck);
+  }
+
+  // Files sitting directly in each directory (drives chain compaction below).
+  const directFileCount = new Map<string, number>();
+  for (const c of doc.components) {
+    const m = c.module?.trim();
+    if (!m) continue;
+    const d = parentDirectory(m);
+    if (!d) continue;
+    const ck = `${scopeKeyFor(c)}\0${d}`;
+    directFileCount.set(ck, (directFileCount.get(ck) ?? 0) + 1);
+  }
+  const nearestKeptDirCk = (ck: string): string | undefined => {
+    const scope = dirScopeOf.get(ck)!;
+    let a = parentDirectory(dirPathOf.get(ck)!);
+    while (a) {
+      const cand = `${scope}\0${a}`;
+      if (keptDirs.has(cand)) return cand;
+      a = parentDirectory(a);
+    }
+    return undefined;
+  };
+  // Compact single-child directory chains within a scope, mirroring the file
+  // tree: `app` → `app/book` renders one `app/book` frame, not `app` wrapping
+  // `book`.
+  let compacting = true;
+  while (compacting) {
+    compacting = false;
+    const childDirsOf = new Map<string, string[]>();
+    for (const ck of keptDirs) {
+      const a = nearestKeptDirCk(ck);
+      if (!a) continue;
+      const list = childDirsOf.get(a) ?? [];
+      list.push(ck);
+      childDirsOf.set(a, list);
+    }
+    for (const ck of [...keptDirs]) {
+      if (
+        (childDirsOf.get(ck) ?? []).length === 1 &&
+        (directFileCount.get(ck) ?? 0) === 0
+      ) {
+        keptDirs.delete(ck);
+        compacting = true;
+      }
+    }
+  }
+  const dirLabel = (ck: string): string => {
+    const path = dirPathOf.get(ck)!;
+    const ancestor = nearestKeptDirCk(ck);
+    return ancestor ? path.slice(dirPathOf.get(ancestor)!.length + 1) : path;
+  };
+
+  const moduleRegionByKey = new Map(modules.map((r) => [r.key, r]));
+  // A module's scope is uniform across its members (else undefined → root), so
+  // a module straddling processes is never forced into one.
+  const moduleScope = new Map<string, string | undefined>();
+  for (const r of modules) {
+    const scopes = new Set<string>();
+    for (const a of r.memberAliases) {
+      const c = byAlias.get(a);
+      if (c) scopes.add(scopeKeyFor(c));
+    }
+    moduleScope.set(r.key, scopes.size === 1 ? [...scopes][0] : undefined);
+  }
+  const moduleDirCk = (moduleKey: string): string | undefined => {
+    const scope = moduleScope.get(moduleKey);
+    if (scope === undefined) return undefined;
+    let d = parentDirectory(moduleKey);
+    while (d) {
+      const cand = `${scope}\0${d}`;
+      if (keptDirs.has(cand)) return cand;
+      d = parentDirectory(d);
+    }
+    return undefined;
+  };
+
+  const sharedPackageParent = (
+    memberAliases: readonly string[],
+  ): string | undefined => {
+    const seen = new Set<string>();
+    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 moduleGroups: BoundaryLayoutGroup[] = modules.map((r) => {
+    const ck = moduleDirCk(r.key);
+    const parentId = ck
+      ? dirGroupId(dirScopeOf.get(ck)!, dirPathOf.get(ck)!)
+      : scopeParentId(moduleScope.get(r.key) ?? 'root');
+    // 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 = ck ? r.key.slice(dirPathOf.get(ck)!.length + 1) : r.label;
+    return {
+      id: moduleGroupNodeId(r.key),
+      memberAliases: [...r.memberAliases],
+      parentId,
+      region: { ...r, label },
+    };
+  });
+
+  const dirGroups: BoundaryLayoutGroup[] = [...keptDirs].map((ck) => {
+    const scope = dirScopeOf.get(ck)!;
+    const path = dirPathOf.get(ck)!;
+    const ancestor = nearestKeptDirCk(ck);
+    const parentId = ancestor
+      ? dirGroupId(dirScopeOf.get(ancestor)!, dirPathOf.get(ancestor)!)
+      : scopeParentId(scope);
+    // 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 childDirCks = [...keptDirs].filter((d) => nearestKeptDirCk(d) === ck);
+    const childModuleKeys = modules
+      .filter((m) => moduleDirCk(m.key) === ck)
+      .map((m) => m.key);
+    const claimed = new Set<string>();
+    for (const d of childDirCks) {
+      for (const a of dirMembers.get(d) ?? []) claimed.add(a);
+    }
+    for (const mk of childModuleKeys) {
+      for (const a of moduleRegionByKey.get(mk)?.memberAliases ?? []) claimed.add(a);
+    }
+    const directLeaves = [...(dirMembers.get(ck) ?? [])].filter(
+      (a) => !claimed.has(a),
+    );
+    const region: SubsystemProcessRegion = {
+      kind: 'directory',
+      key: path,
+      label: dirLabel(ck),
+      memberAliases: [...(dirMembers.get(ck) ?? [])],
+    };
+    return {
+      id: dirGroupId(scope, path),
+      memberAliases: [
+        ...childDirCks.map((d) => dirGroupId(dirScopeOf.get(d)!, dirPathOf.get(d)!)),
+        ...childModuleKeys.map(moduleGroupNodeId),
+        ...directLeaves,
+      ],
+      parentId,
+      region,
+    };
+  });
+
+  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<string>();
+  for (const r of modules) for (const a of r.memberAliases) moduleMemberAliases.add(a);
+
+  const processGroups: BoundaryLayoutGroup[] = processes.map((r) => {
+    const processId = processGroupNodeId(r.key);
+    const nested = frameGroups.filter((g) => g.parentId === processId);
+    const claimed = new Set<string>();
+    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<string>();
+  for (const r of processes) for (const a of r.memberAliases) processMemberAliases.add(a);
+
+  const packageGroups: BoundaryLayoutGroup[] = packages.map((r) => {
+    const packageId = packageGroupNodeId(r.key);
+    const nested = [...processGroups, ...frameGroups].filter(
+      (g) => g.parentId === packageId,
+    );
+    const claimed = new Set<string>();
+    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];
+}
+
 export interface SubsystemGraphNodeData extends Record<string, unknown> {
   component: SubsystemComponent;
   /** Set while a file is open in the drawer: true if this node's component
@@ -1294,6 +1614,30 @@ export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][]
   ['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: { kind: string; key: string } | undefined,
+): boolean {
+  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: string): string {
   const palette = [
@@ -1709,10 +2053,15 @@ export async function buildSubsystemGraph(
     measuredHeights,
     showSingletonFrames,
     packageFrames,
+    moduleNesting,
     graphifyRelations,
     orderByLine = false,
   } = opts;
-  const frameOpts: BoundaryFrameOptions = { showSingletonFrames, packageFrames };
+  const frameOpts: BoundaryFrameOptions = {
+    showSingletonFrames,
+    packageFrames,
+    moduleNesting,
+  };
   const nodes = convertSubsystemToNodes(doc, { maxNodeWidth });
   const edges = convertSubsystemToEdges(doc, graphifyRelations);
   // Nested boundary tree: package → process → module → leaves.
@@ -1804,7 +2153,12 @@ export async function buildSubsystemGraph(
     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,
@@ -1825,7 +2179,7 @@ export async function buildSubsystemGraph(
           // 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'
+            g.region.kind === 'module' || g.region.kind === 'directory'
               ? moduleMinWidthForBadge(g.region.label)
               : boundaryMinWidthForBadge(g.region.label),
         })),
@@ -1890,7 +2244,7 @@ export async function buildSubsystemGraph(
           position: { x: 0, y: 0 },
           width: Math.max(
             400,
-            g.region.kind === 'module'
+            g.region.kind === 'module' || g.region.kind === 'directory'
               ? moduleMinWidthForBadge(g.region.label)
               : boundaryMinWidthForBadge(g.region.label),
           ),

package/src/subsystem/nodes.tsx

@@ -33,6 +33,8 @@ import {
   moduleBadgeHoverLabel,
   moduleBadgeWidth,
   packageColor,
+  FOLDER_FRAME_COLOR,
+  isFolderFrame,
   type SubsystemGraphNodeData,
   type SubsystemGroupNodeData,
   type SubsystemGraphEdge,
@@ -445,8 +447,14 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
     selected?: boolean;
   };
   const region = data.region;
-  // Explicit host override wins over the derived (hash-based) frame color.
-  const color = data.color ?? packageColor(region?.key ?? 'process');
+  // Explicit host override wins over the derived frame color. Folder frames
+  // (directory, or a module whose key names a folder) share one neutral hue;
+  // everything else hashes per key.
+  const color =
+    data.color ??
+    (isFolderFrame(region ?? undefined)
+      ? FOLDER_FRAME_COLOR
+      : packageColor(region?.key ?? 'process'));
   const dimmed = data.dimmed === true;
   const hidden = (data as { hidden?: boolean }).hidden === true;
   // Label is the region identity alone (path / process key / owner/name).
@@ -454,7 +462,9 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
   // — don't prefix `module ·` / `package ·` or the path reads twice.
   const label = region?.label ?? '';
   const [expandedLabel, setExpandedLabel] = useState<string | null>(null);
-  const isModule = region?.kind === 'module';
+  // Directory frames (path-derived nesting) render like modules — dashed,
+  // collapsible path badge.
+  const isModule = region?.kind === 'module' || region?.kind === 'directory';
   const isProcess = region?.kind === 'process';
   const expanded = isModule && expandedLabel === label;
   const availableBadgeWidth = Math.max(0, (width ?? 400) - MODULE_BADGE_INSET * 2 - 4);

package/src/utils/elkLayout.ts

@@ -759,6 +759,16 @@ export async function computeElkLayout(
     if (parentId && builtGroups.has(parentId)) continue; // nested inside parent
     elkParents.push(node);
   }
+  // Order root-level compounds by model order (the caller's `groups` array), so
+  // disconnected sibling frames lay out deterministically — e.g. `app/book`
+  // before `lib`. Without this, planCompoundGroups' bottom-up build order
+  // decides placement.
+  const groupOrder = new Map(groupDefs.map((g, i) => [g.id, i]));
+  elkParents.sort(
+    (a, b) =>
+      (groupOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) -
+      (groupOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER),
+  );
 
   // Create ELK graph
   const rootOptions = getElkOptions(options);