@principal-ai/subsystems-react 0.23.4 → 0.24.1

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -7,6 +7,9 @@
  * inside one labeled boundary frame; nodes without one sit outside every
  * boundary. Clicking a component invokes `onSelect`.
  *
+ * When the model has components but no topology or walkthrough edges, the
+ * canvas is a constructs catalog (list + signature) instead of a graph.
+ *
  * This is a focused fork of the package's `GraphRenderer` pipeline (same ELK
  * edge routing, delayed fitView, Background/Controls/MiniMap, node/edge type
  * injection, onNodeClick) adapted to the subsystem model — read-only.
@@ -37,18 +40,25 @@ import { IndustryMarkdownSlide } from 'themed-markdown';
 import {
   buildSubsystemGraph,
   deriveGraphEdges,
+  isConstructsOnlyModel,
+  isRelationMechanism,
+  isWalkthroughMechanism,
   MECHANISM_COLOR,
   MECHANISM_DESCRIPTIONS,
   subsystemGraphLayoutKey,
   walkthroughStepGraphEdgeId,
   type SubsystemComponentEdge,
   type SubsystemComponent,
+  type SubsystemEdgeView,
   type SubsystemEdgeMechanism,
   type SubsystemRelation,
   type SubsystemWalkthrough,
 } from './model';
+import { ConstructsCatalog } from './ConstructsCatalog';
 import type { SubsystemOpenFileOptions } from './declarationRef';
 import { SubsystemComponentNode, SubsystemGroupNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
+import { SubsystemDiagnosticToggle, type SubsystemDiagnostic } from './DiagnosticToggle';
+import { SubsystemIssueList, type SubsystemIssue } from './IssueList';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
 import { ComponentDeclaration } from './ComponentDeclaration';
@@ -99,6 +109,17 @@ export interface SubsystemComponentGraphProps {
   maxNodeWidth?: number;
   /** Show edge labels (mechanism names) on the graph. @default true */
   showEdgeLabels?: boolean;
+  /**
+   * Which edge vocabulary the canvas draws. The relation and walkthrough
+   * vocabularies are disjoint, so a graph carrying both shows one or the
+   * other — never both. Edges outside the view are hidden (labels go too).
+   * - `relations`: topology relation edges (`imports`, `extends`, …)
+   * - `walkthroughs`: walkthrough hop edges (`calls`, `feeds`, …), including
+   *   step numbers when a flow is focused/hovered
+   * Defaults to `walkthroughs` when the model has walkthroughs but no
+   * relations (e.g. flow-only models), otherwise `relations`.
+   */
+  edgeView?: SubsystemEdgeView;
   /** Subsystem title displayed in the sidebar. */
   title?: string;
   /**
@@ -146,6 +167,29 @@ export interface SubsystemComponentGraphProps {
   sidebarExtra?: ReactNode;
   /** Rendered in the sidebar under the description (e.g. selection inspector). */
   sidebarAfterDescription?: ReactNode;
+  /**
+   * Diagnostics status chip in the sidebar title row (beside the description
+   * toggle). Shows the last verification pass's state as an icon color + count;
+   * `onOpen` opens the full report. Omit to hide the chip.
+   */
+  diagnostic?: SubsystemDiagnostic;
+  /**
+   * Verification issues for this graph (audit findings). When diagnostics are
+   * active (see `showIssues`) the sidebar's bottom panel becomes the issue
+   * list instead of the file tree / walkthroughs.
+   */
+  issues?: SubsystemIssue[];
+  /**
+   * Force the sidebar into diagnostics mode. Defaults to `true` whenever
+   * `issues` is non-empty (and nothing else has been forced).
+   */
+  showIssues?: boolean;
+  /** Click an issue — focus its target on the graph / open detail. */
+  onSelectIssue?: (issue: SubsystemIssue) => void;
+  /** Apply an issue's deterministic fix. */
+  onApplyIssueFix?: (issue: SubsystemIssue) => void;
+  /** Hover an issue — transiently highlight its target (null on leave). */
+  onHoverIssue?: (issue: SubsystemIssue | null) => void;
   /**
    * Host-injected reader/renderer for the bottom file drawer, keyed by
    * repo-root-relative path. Opening happens on declaration/file-tree clicks.
@@ -260,7 +304,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, hideSidebar, walkthroughStepMode = 'focus', autoPlayWalkthroughs = false, walkthroughAutoPlayIntervalMs = WALKTHROUGH_PLAY_PAUSE_MS, zoomOnWalkthroughFocus = true, graphTitle, showWalkthroughTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
+function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, edgeView, title, hideSidebar, walkthroughStepMode = 'focus', autoPlayWalkthroughs = false, walkthroughAutoPlayIntervalMs = WALKTHROUGH_PLAY_PAUSE_MS, zoomOnWalkthroughFocus = true, graphTitle, showWalkthroughTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
@@ -268,6 +312,13 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
     () => deriveGraphEdges({ relations, walkthroughs }),
     [relations, walkthroughs],
   );
+  // One edge vocabulary at a time. When the caller doesn't pick, follow the
+  // model: a flow-only graph defaults to walkthrough edges rather than empty.
+  const resolvedEdgeView: SubsystemEdgeView =
+    edgeView ??
+    (relations.length === 0 && (walkthroughs?.length ?? 0) > 0
+      ? 'walkthroughs'
+      : 'relations');
   const [built, setBuilt] = useState<{ nodes: Node[]; edges: Edge[] }>({
     nodes: [],
     edges: [],
@@ -808,6 +859,13 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
         markerEnd: nextMarker,
       };
     };
+    // Edges outside the selected view are hidden entirely (labels included).
+    const edgeInView = (e: Edge): boolean => {
+      const mechanism = (e.data as { mechanism?: string } | undefined)?.mechanism ?? 'imports';
+      return resolvedEdgeView === 'relations'
+        ? isRelationMechanism(mechanism)
+        : isWalkthroughMechanism(mechanism);
+    };
     if (openedEdgeIds || focusEdgeIds || previewEdgeIds) {
       return baseEdges.map((e) => {
         const vis = flowElementVisibility({
@@ -817,13 +875,18 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
           anySelected: focusEdgeIds != null,
         });
         const dimmed = previewEdgeIds ? vis.hidden || !previewEdgeIds.has(e.id) : vis.dimmed;
-        const hidden = vis.hidden;
+        const hidden = vis.hidden || !edgeInView(e);
         return { ...paint(e, dimmed), hidden };
       });
     }
-    if (!selectedEdgeId) return baseEdges;
-    return baseEdges.map((e) => paint(e, e.id !== selectedEdgeId));
-  }, [baseEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds, previewEdgeIds]);
+    if (selectedEdgeId) {
+      return baseEdges.map((e) => ({
+        ...paint(e, e.id !== selectedEdgeId),
+        hidden: !edgeInView(e),
+      }));
+    }
+    return baseEdges.map((e) => ({ ...e, hidden: !edgeInView(e) }));
+  }, [baseEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds, previewEdgeIds, resolvedEdgeView]);
 
   const onNodesChange = useCallback(
     (changes: NodeChange[]) => {
@@ -902,6 +965,10 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   // own owner-avatar header. Clicking a header collapses that repo's tree.
   const repoGroups = useMemo(() => buildRepoGroups(components), [components]);
   const hasWalkthroughs = useMemo(() => (walkthroughs?.length ?? 0) > 0, [walkthroughs]);
+  // Diagnostics mode: the bottom panel shows the issue list instead of the
+  // file tree / walkthroughs. Explicit `showIssues` wins; otherwise any issues
+  // present turn it on.
+  const issuesActive = showIssues ?? (issues?.length ?? 0) > 0;
   const [collapsedRepos, setCollapsedRepos] = useState<Set<string>>(new Set());
   const toggleRepoCollapsed = useCallback((key: string) => {
     setCollapsedRepos((prev) => {
@@ -1325,8 +1392,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
       .filter((e) => {
         if (e.hidden) return false;
         const d = e?.data as { dimmed?: boolean } | undefined;
-        if (d?.dimmed) return false;
-        return true;
+        return !d?.dimmed;
       })
       .map((e) => {
         const d = e.data as {
@@ -1394,7 +1460,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
       {/* Sidebar: scrollable title/description on top, files or flows pinned below.
           The description hides by default so files/flows get the room; the
           title-row toggle reveals it, and the lower panel yields back to 50%. */}
-      {!hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (
+      {!hideSidebar && (title || description || diagnostic || issuesActive || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (
         <div
           style={{
             width: sidebarWidth,
@@ -1418,7 +1484,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
             }}
           >
           {sidebarExtra}
-          {(title || description) && (
+          {(title || description || diagnostic) && (
             <div style={{ display: 'flex', alignItems: 'flex-start', gap: 8 }}>
               {title && (
                 <h2
@@ -1435,34 +1501,47 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
                   {title}
                 </h2>
               )}
-              {description && (
-                <button
-                  type="button"
-                  aria-expanded={descriptionVisible}
-                  aria-label={descriptionVisible ? 'Hide description' : 'Show description'}
-                  title={descriptionVisible ? 'Hide description' : 'Show description'}
-                  onMouseEnter={() => setDescToggleHover(true)}
-                  onMouseLeave={() => setDescToggleHover(false)}
-                  onClick={() => setDescriptionVisible((v) => !v)}
-                  style={{
-                    display: 'inline-flex',
-                    alignItems: 'center',
-                    justifyContent: 'center',
-                    flexShrink: 0,
-                    width: 22,
-                    height: 22,
-                    padding: 0,
-                    border: 'none',
-                    borderRadius: 4,
-                    background: descToggleHover ? theme.colors.border : 'transparent',
-                    color: descToggleHover ? theme.colors.text : (theme.colors.textMuted ?? theme.colors.textSecondary),
-                    cursor: 'pointer',
-                    transition: 'background 120ms ease, color 120ms ease',
-                  }}
-                >
-                  {descriptionVisible ? <ChevronUp size={14} /> : <ChevronDown size={14} />}
-                </button>
-              )}
+              <div
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 4,
+                  flexShrink: 0,
+                  // Title's flex:1 already pushes this cluster right; without a
+                  // title, keep the actions flush right instead of flush-left.
+                  marginLeft: title ? undefined : 'auto',
+                }}
+              >
+                {diagnostic && <SubsystemDiagnosticToggle {...diagnostic} />}
+                {description && (
+                  <button
+                    type="button"
+                    aria-expanded={descriptionVisible}
+                    aria-label={descriptionVisible ? 'Hide description' : 'Show description'}
+                    title={descriptionVisible ? 'Hide description' : 'Show description'}
+                    onMouseEnter={() => setDescToggleHover(true)}
+                    onMouseLeave={() => setDescToggleHover(false)}
+                    onClick={() => setDescriptionVisible((v) => !v)}
+                    style={{
+                      display: 'inline-flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      flexShrink: 0,
+                      width: 22,
+                      height: 22,
+                      padding: 0,
+                      border: 'none',
+                      borderRadius: 4,
+                      background: descToggleHover ? theme.colors.border : 'transparent',
+                      color: descToggleHover ? theme.colors.text : (theme.colors.textMuted ?? theme.colors.textSecondary),
+                      cursor: 'pointer',
+                      transition: 'background 120ms ease, color 120ms ease',
+                    }}
+                  >
+                    {descriptionVisible ? <ChevronUp size={14} /> : <ChevronDown size={14} />}
+                  </button>
+                )}
+              </div>
             </div>
           )}
           {description && descriptionVisible && (
@@ -1483,7 +1562,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
           )}
           {sidebarAfterDescription}
           </div>
-          {(treeFilePaths.length > 0 || hasWalkthroughs) && (
+          {(treeFilePaths.length > 0 || hasWalkthroughs || issuesActive) && (
             <div
               style={{
                 ...(showDesc ? { height: '50%' as const } : { flex: 1, minHeight: 0 }),
@@ -1495,6 +1574,15 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
                 overflow: 'hidden',
               }}
             >
+              {issuesActive ? (
+                <SubsystemIssueList
+                  issues={issues ?? []}
+                  onSelectIssue={onSelectIssue}
+                  onApplyFix={onApplyIssueFix}
+                  onHoverIssue={onHoverIssue}
+                />
+              ) : (
+                <>
               {hasWalkthroughs && (
                 <div
                   role="tablist"
@@ -1608,13 +1696,15 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
               })}
               </>
               ) : null}
+                </>
+              )}
             </div>
           )}
         </div>
       )}
       
       {/* Drag handle between sidebar and canvas — resize the left panel. */}
-      {!hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (
+      {!hideSidebar && (title || description || diagnostic || issuesActive || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (
         <div
           onMouseDown={onSidebarResizeStart}
           aria-label="Resize sidebar"
@@ -2403,6 +2493,12 @@ export function SubsystemComponentGraph(props: SubsystemComponentGraphProps) {
     return () => ro.disconnect();
   }, []);
 
+  const constructsOnly = isConstructsOnlyModel({
+    components: props.components,
+    relations: props.relations,
+    walkthroughs: props.walkthroughs,
+  });
+
   return (
     <div
       ref={wrapRef}
@@ -2416,9 +2512,27 @@ export function SubsystemComponentGraph(props: SubsystemComponentGraphProps) {
       }}
     >
       <div style={{ flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column' }}>
-        <ReactFlowProvider>
-          <Inner {...props} measured={size} />
-        </ReactFlowProvider>
+        {constructsOnly ? (
+          <ConstructsCatalog
+            components={props.components}
+            onSelect={props.onSelect}
+            title={props.title}
+            hideSidebar={props.hideSidebar}
+            description={props.description}
+            diagnostic={props.diagnostic}
+            sidebarExtra={props.sidebarExtra}
+            sidebarAfterDescription={props.sidebarAfterDescription}
+            renderFileViewer={props.renderFileViewer}
+            renderFileView={props.renderFileView}
+            onFileSelect={props.onFileSelect}
+            onVerifyComponent={props.onVerifyComponent}
+            componentVerification={props.componentVerification}
+          />
+        ) : (
+          <ReactFlowProvider>
+            <Inner {...props} measured={size} />
+          </ReactFlowProvider>
+        )}
       </div>
     </div>
   );

package/src/subsystem/model.test.ts

@@ -13,6 +13,7 @@ import {
   buildSubsystemGraph,
   componentPackageKey,
   deriveNameFromSymbol,
+  isConstructsOnlyModel,
   constructBadgeLabel,
   constructBadgeColor,
   FRAMEWORK_BADGE_COLOR,
@@ -642,3 +643,36 @@ describe('subsystem graph model', () => {
     expect(subsystemGraphLayoutKey(base)).toBe(subsystemGraphLayoutKey(withRef));
   });
 });
+
+describe('isConstructsOnlyModel', () => {
+  test('true when components exist and there are no edges', () => {
+    expect(isConstructsOnlyModel({ components: comps, relations: [], walkthroughs: [] })).toBe(true);
+    expect(isConstructsOnlyModel({ components: comps })).toBe(true);
+  });
+
+  test('false when empty, or when relations or walkthrough hops exist', () => {
+    expect(isConstructsOnlyModel({ components: [], relations: [] })).toBe(false);
+    expect(isConstructsOnlyModel({ components: comps, relations })).toBe(false);
+    expect(
+      isConstructsOnlyModel({
+        components: comps,
+        relations: [],
+        walkthroughs: [
+          {
+            id: 'wt',
+            title: 'flow',
+            steps: [
+              {
+                from: 'transcript',
+                to: 'reader',
+                mechanism: 'calls',
+                file: 'transcript.ts',
+                line: 1,
+              },
+            ],
+          },
+        ],
+      }),
+    ).toBe(false);
+  });
+});

package/src/subsystem/model.ts

@@ -117,6 +117,14 @@ export type SubsystemEdgeMechanism =
   | SubsystemRelationType
   | SubsystemWalkthroughMechanism;
 
+/**
+ * Which edge vocabulary the canvas draws. The two vocabularies are disjoint;
+ * a view shows only edges (and their labels) from the selected source.
+ * - `relations`: only topology relation edges (`imports`, `extends`, …)
+ * - `walkthroughs`: only walkthrough hop edges (`calls`, `feeds`, …)
+ */
+export type SubsystemEdgeView = 'relations' | 'walkthroughs';
+
 /** A component node — the named unit, construct-tagged; `file` is its location. */
 export interface SubsystemComponent {
   id: string;
@@ -323,8 +331,8 @@ export function walkthroughStepGraphEdgeId(
 }
 
 export function deriveGraphEdges(doc: {
-  relations?: SubsystemRelation[];
-  walkthroughs?: SubsystemWalkthrough[];
+  relations?: readonly SubsystemRelation[];
+  walkthroughs?: readonly SubsystemWalkthrough[];
 }): SubsystemComponentEdge[] {
   const byId = new Map<string, SubsystemComponentEdge>();
   for (const r of doc.relations ?? []) {
@@ -355,6 +363,22 @@ 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.
+ */
+export function isConstructsOnlyModel(doc: {
+  components: readonly { id: string }[];
+  relations?: readonly SubsystemRelation[];
+  walkthroughs?: readonly SubsystemWalkthrough[];
+}): boolean {
+  if (doc.components.length === 0) return false;
+  return deriveGraphEdges({
+    relations: doc.relations,
+    walkthroughs: doc.walkthroughs,
+  }).length === 0;
+}
+
 /**
  * Derive a consistent display `name` from a code `symbol` + construct.
  *
@@ -747,6 +771,52 @@ export interface SubsystemGraphEdgeData extends Record<string, unknown> {
 
 export type SubsystemGraphEdge = Edge<SubsystemGraphEdgeData>;
 
+/**
+ * Runtime vocabulary of relation types — mirrors `SubsystemRelationType`.
+ * Used to split derived display edges into their relation vs walkthrough
+ * source (the two unions are disjoint).
+ */
+export const SUBSYSTEM_RELATION_TYPES = [
+  'imports',
+  'extends',
+  'inherits',
+  'implements',
+  'mixes_in',
+  'method',
+  'references',
+] as const satisfies readonly SubsystemRelationType[];
+
+/** Runtime vocabulary of walkthrough hop mechanisms — mirrors `SubsystemWalkthroughMechanism`. */
+export const SUBSYSTEM_WALKTHROUGH_MECHANISMS = [
+  'calls',
+  'uses',
+  'feeds',
+  'produces',
+  'writes',
+  'reads',
+  'watches',
+  'registers-into',
+] as const satisfies readonly SubsystemWalkthroughMechanism[];
+
+const RELATION_TYPE_SET: ReadonlySet<string> = new Set(SUBSYSTEM_RELATION_TYPES);
+const WALKTHROUGH_MECHANISM_SET: ReadonlySet<string> = new Set(
+  SUBSYSTEM_WALKTHROUGH_MECHANISMS,
+);
+
+/** True when a mechanism belongs to the topology relation vocabulary. */
+export function isRelationMechanism(
+  mechanism: string,
+): mechanism is SubsystemRelationType {
+  return RELATION_TYPE_SET.has(mechanism);
+}
+
+/** True when a mechanism belongs to the walkthrough hop vocabulary. */
+export function isWalkthroughMechanism(
+  mechanism: string,
+): mechanism is SubsystemWalkthroughMechanism {
+  return WALKTHROUGH_MECHANISM_SET.has(mechanism);
+}
+
 export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
   imports: '#0893d2', // blue
   calls: '#4ec9b0', // teal