@principal-ai/subsystems-react 0.24.3 → 0.24.5

package/src/subsystem/ComponentDeclaration.tsx

@@ -66,7 +66,7 @@ export interface ComponentVerificationState {
     inlineParameters?: number;
   };
   declaration?: {
-    freshness: 'valid' | 'stale' | 'missing' | 'unanchored' | 'unchecked';
+    freshness: 'fresh' | 'stale' | 'missing' | 'unanchored' | 'unchecked';
     ref?: {
       startLine: number;
       lineHash: string;
@@ -120,6 +120,9 @@ export interface ComponentDeclarationProps {
   verification?: ComponentVerificationState | null;
   /** Start with the file path row visible (catalog / source-first views). */
   defaultShowFile?: boolean;
+  /** True while this component's file is open in the host drawer — keeps the
+   *  declaration visibly tied to the source being read. */
+  fileOpen?: boolean;
 }
 
 function verificationSummary(
@@ -259,6 +262,7 @@ export function ComponentDeclaration({
   onVerify,
   verification,
   defaultShowFile = false,
+  fileOpen = false,
 }: ComponentDeclarationProps) {
   const { theme, mode } = useTheme();
   const pierreSyntaxTheme = resolvePierreSyntaxThemeName(mode);
@@ -380,8 +384,31 @@ export function ComponentDeclaration({
     </button>
   );
   const verifyBusy = verification?.phase === 'checking';
+  const openPill = fileOpen ? (
+    <span
+      title="This declaration's file is open below"
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 4,
+        height: 18,
+        padding: '0 6px',
+        border: `1px solid ${theme.colors.accent ?? color}`,
+        borderRadius: 999,
+        color: theme.colors.accent ?? color,
+        fontFamily: theme.fonts.monospace,
+        fontSize: theme.fontSizes[0] * 0.85,
+        letterSpacing: 0.4,
+        textTransform: 'uppercase',
+        whiteSpace: 'nowrap',
+      }}
+    >
+      file open
+    </span>
+  ) : null;
   const headerActions = (
-    <span style={{ marginLeft: 'auto', display: 'flex', alignItems: 'center', gap: 2 }}>
+    <span style={{ marginLeft: 'auto', display: 'flex', alignItems: 'center', gap: 6 }}>
+      {openPill}
       {onVerify && (
         <button
           type="button"
@@ -458,7 +485,7 @@ export function ComponentDeclaration({
         'purl',
       ),
     );
-  } else if (onVerify) {
+  } else if (onVerify || fileOpen) {
     lines.push(line(headerActions, 'actions'));
   }
 

package/src/subsystem/ConstructsCatalog.tsx

@@ -88,6 +88,7 @@ export function ConstructsCatalog({
   const { theme, mode } = useTheme();
   const pierreTheme = resolvePierreSyntaxThemeName(mode);
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const accentColor = theme.colors.accent ?? theme.colors.info;
   const [visibleIds, setVisibleIds] = useState<string[]>(() =>
     components[0] ? [components[0].id] : [],
   );
@@ -121,6 +122,20 @@ export function ConstructsCatalog({
       ?.scrollIntoView({ block: 'nearest' });
   }, [visibleIds]);
 
+  // Keep the declaration whose file is open in view, so the source and its
+  // signature stay legible together.
+  useEffect(() => {
+    if (!drawer) return;
+    const match =
+      components.find(
+        (c) => c.file === drawer.file && c.declarationRef?.startLine === drawer.startLine,
+      ) ?? components.find((c) => c.file === drawer.file);
+    if (!match) return;
+    document
+      .getElementById(`construct-signature-${match.id}`)
+      ?.scrollIntoView({ block: 'nearest' });
+  }, [components, drawer]);
+
   // Drop ids that left the model; if nothing remains, show the first construct.
   useEffect(() => {
     const ids = new Set(components.map((c) => c.id));
@@ -423,6 +438,7 @@ export function ConstructsCatalog({
             );
             const role = rightBadgeLabel(c);
             const roleColor = rightBadgeColor(c);
+            const rowOpen = drawer != null && !!c.file && c.file === drawer.file;
             return (
               <li key={c.id} role="presentation">
                 <button
@@ -447,9 +463,12 @@ export function ConstructsCatalog({
                       ? theme.colors.background
                       : 'transparent',
                     cursor: 'pointer',
-                    boxShadow: visible
-                      ? `inset 0 0 0 1px ${theme.colors.border}`
-                      : undefined,
+                    boxShadow: [
+                      visible ? `inset 0 0 0 1px ${theme.colors.border}` : null,
+                      rowOpen ? `inset 2px 0 0 ${accentColor}` : null,
+                    ]
+                      .filter(Boolean)
+                      .join(', ') || undefined,
                     outline: focused && !visible ? `1px dotted ${muted}` : undefined,
                     outlineOffset: -1,
                     opacity: visible ? 1 : 0.72,
@@ -547,31 +566,36 @@ export function ConstructsCatalog({
           }}
         >
           {visibleComponents.length > 0 ? (
-            visibleComponents.map((c) => (
-              <div
-                key={c.id}
-                id={`construct-signature-${c.id}`}
-                style={{
-                  border: `1px solid ${theme.colors.border}`,
-                  borderRadius: 8,
-                  overflow: 'hidden',
-                  flexShrink: 0,
-                }}
-              >
-                <ComponentDeclaration
-                  component={c}
-                  onOpenFile={fileViewer ? onOpenFile : undefined}
-                  defaultShowFile={!!fileViewer}
-                  onRelatedSelect={onRelatedSelect}
-                  onVerify={onVerifyComponent}
-                  verification={
-                    componentVerification && focusedId === c.id
-                      ? componentVerification
-                      : undefined
-                  }
-                />
-              </div>
-            ))
+            visibleComponents.map((c) => {
+              const open = drawer != null && !!c.file && c.file === drawer.file;
+              return (
+                <div
+                  key={c.id}
+                  id={`construct-signature-${c.id}`}
+                  style={{
+                    border: `1px solid ${open ? accentColor : theme.colors.border}`,
+                    boxShadow: open ? `0 0 0 1px ${accentColor}` : undefined,
+                    borderRadius: 8,
+                    overflow: 'hidden',
+                    flexShrink: 0,
+                  }}
+                >
+                  <ComponentDeclaration
+                    component={c}
+                    onOpenFile={fileViewer ? onOpenFile : undefined}
+                    defaultShowFile={!!fileViewer}
+                    onRelatedSelect={onRelatedSelect}
+                    onVerify={onVerifyComponent}
+                    fileOpen={open}
+                    verification={
+                      componentVerification && focusedId === c.id
+                        ? componentVerification
+                        : undefined
+                    }
+                  />
+                </div>
+              );
+            })
           ) : (
             <p
               style={{

package/src/subsystem/IssueList.tsx

@@ -27,6 +27,7 @@ export type SubsystemIssueTargetKind =
   | 'relation'
   | 'module'
   | 'walkthrough'
+  | 'repo'
   | 'graph';
 
 /**
@@ -34,6 +35,7 @@ export type SubsystemIssueTargetKind =
  * constructs → static topology → runtime topology → walkthrough.
  */
 export type SubsystemIssueCategory =
+  | 'repo'
   | 'construct'
   | 'static-topology'
   | 'runtime-topology'
@@ -41,6 +43,7 @@ export type SubsystemIssueCategory =
 
 /** Layer order + display names, shared by the list and its headers. */
 export const SUBSYSTEM_ISSUE_CATEGORIES: SubsystemIssueCategory[] = [
+  'repo',
   'construct',
   'static-topology',
   'runtime-topology',
@@ -51,6 +54,7 @@ export const SUBSYSTEM_ISSUE_CATEGORY_LABEL: Record<
   SubsystemIssueCategory,
   string
 > = {
+  repo: 'Repositories',
   construct: 'Constructs',
   'static-topology': 'Static topology',
   'runtime-topology': 'Runtime topology',
@@ -60,18 +64,18 @@ export const SUBSYSTEM_ISSUE_CATEGORY_LABEL: Record<
 /** Default `kind` → layer. `boundary_*` splits by module (static) vs process (runtime). */
 const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
   missing_file: 'construct',
-  missing_symbol: 'construct',
+  symbol_ambiguous: 'construct',
+  symbol_unmatched: 'construct',
   stale_declaration: 'construct',
   construct_mismatch: 'construct',
   construct_unconfirmed: 'construct',
   signature_mismatch: 'construct',
   signature_unconfirmed: 'construct',
-  anchor: 'construct',
-  unresolved: 'construct',
+  repo_unresolved: 'repo',
+  graphify_unavailable: 'repo',
   topology_broken_endpoint: 'static-topology',
   topology_import_unconfirmed: 'static-topology',
   topology_relation_unconfirmed: 'static-topology',
-  boundary_module_without_file: 'static-topology',
   boundary_module_file_mismatch: 'static-topology',
   boundary_process_nest_disagree: 'runtime-topology',
   walkthrough: 'walkthrough',
@@ -124,27 +128,28 @@ export function humanizeIssueKind(kind: string): string {
 }
 
 /**
- * Curated short labels, trimmed of prefixes the grouping already implies
- * (`topology_`, `boundary_`) but kept unambiguous within a layer — so
- * `construct_mismatch` reads "Wrong construct", not a bare "Mismatch" that
- * would collide with `signature_mismatch`. Explicit `issue.kindLabel` wins.
+ * Curated labels. Construct-layer findings stay fully qualified ("Construct
+ * declaration file missing", "Construct type mismatch") rather than relying on
+ * the category header — this UI is new and the extra words read clearer.
+ * Topology findings drop the `topology_`/`boundary_` prefix since the layer
+ * already scopes them. Explicit `issue.kindLabel` wins.
  */
 const KIND_LABEL: Record<string, string> = {
-  missing_file: 'Missing file',
-  missing_symbol: 'Missing symbol',
-  stale_declaration: 'Stale declaration',
-  construct_mismatch: 'Wrong construct',
-  construct_unconfirmed: 'Unconfirmed construct',
-  signature_mismatch: 'Signature mismatch',
-  signature_unconfirmed: 'Signature unconfirmed',
-  anchor: 'Anchor',
-  unresolved: 'Unresolved',
-  topology_broken_endpoint: 'Broken endpoint',
+  missing_file: 'Construct declaration file missing',
+  symbol_ambiguous: 'Multiple construct symbol matches',
+  symbol_unmatched: 'Construct symbol unconfirmed',
+  stale_declaration: 'Construct declaration drift',
+  construct_mismatch: 'Construct type mismatch',
+  construct_unconfirmed: 'Construct type unconfirmed',
+  signature_mismatch: 'Construct signature mismatch',
+  signature_unconfirmed: 'Construct signature unconfirmed',
+  repo_unresolved: 'No repository clone',
+  graphify_unavailable: 'Graphify cache unavailable',
+  topology_broken_endpoint: 'Construct relationship broken',
   topology_import_unconfirmed: 'Import unconfirmed',
-  topology_relation_unconfirmed: 'Relation unconfirmed',
-  boundary_module_without_file: 'Module without file',
-  boundary_module_file_mismatch: 'Module file mismatch',
-  boundary_process_nest_disagree: 'Process nest disagree',
+  topology_relation_unconfirmed: 'Relationship unconfirmed',
+  boundary_module_file_mismatch: 'Declaration file outside module',
+  boundary_process_nest_disagree: 'Module spans multiple process contexts',
   walkthrough: 'Step issue',
 };
 
@@ -153,6 +158,44 @@ export function issueKindLabel(issue: SubsystemIssue): string {
   return issue.kindLabel ?? KIND_LABEL[issue.kind] ?? humanizeIssueKind(issue.kind);
 }
 
+/**
+ * Display order within the list, by verification pipeline — not severity.
+ * Mirrors the per-component check order (file → symbol → declaration → type →
+ * signature), then topology (integrity → corroboration → membership) and the
+ * remaining layers. Within a stage, "unconfirmed" precedes "mismatch": you
+ * reach a verdict before you can find it wrong.
+ */
+const KIND_ORDER: Record<string, number> = {
+  // Repositories — availability precondition
+  repo_unresolved: 0,
+  graphify_unavailable: 1,
+  // Constructs — file → symbol → declaration → type → signature
+  missing_file: 10,
+  symbol_unmatched: 11,
+  symbol_ambiguous: 12,
+  stale_declaration: 13,
+  construct_unconfirmed: 14,
+  construct_mismatch: 15,
+  signature_unconfirmed: 16,
+  signature_mismatch: 17,
+  // Static topology — edge integrity → corroboration → membership
+  topology_broken_endpoint: 20,
+  topology_relation_unconfirmed: 21,
+  topology_import_unconfirmed: 22,
+  boundary_module_file_mismatch: 23,
+  // Runtime topology
+  boundary_process_nest_disagree: 30,
+  // Walkthrough
+  walkthrough: 40,
+};
+
+const KIND_ORDER_FALLBACK = 100;
+
+/** Sort key for a kind; unknown kinds sort last. */
+export function issueKindOrder(kind: string): number {
+  return KIND_ORDER[kind] ?? KIND_ORDER_FALLBACK;
+}
+
 export function severityRank(severity: SubsystemIssueSeverity): number {
   return SEVERITY_RANK[severity] ?? SEVERITY_RANK.info;
 }
@@ -246,7 +289,12 @@ export function groupIssuesByCategory(
   }
   return SUBSYSTEM_ISSUE_CATEGORIES.map((category) => {
     const grouped = byCategory.get(category) ?? [];
-    grouped.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
+    // Logical pipeline order, then by target label (stable for the rest).
+    grouped.sort((a, b) => {
+      const byKind = issueKindOrder(a.kind) - issueKindOrder(b.kind);
+      if (byKind !== 0) return byKind;
+      return (a.target?.label ?? '').localeCompare(b.target?.label ?? '');
+    });
     return {
       category,
       label: SUBSYSTEM_ISSUE_CATEGORY_LABEL[category],
@@ -269,9 +317,10 @@ function severityColor(
 
 const TARGET_KIND_LABEL: Record<SubsystemIssueTargetKind, string> = {
   component: 'component',
-  relation: 'relation',
+  relation: 'relationship',
   module: 'module',
   walkthrough: 'flow',
+  repo: 'repo',
   graph: 'model',
 };
 
@@ -445,6 +494,19 @@ export function SubsystemIssueList({
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const categories = groupIssuesByCategory(issues);
+  // Collapsed categories (by id). Everything starts expanded.
+  const [collapsed, setCollapsed] = useState<Set<SubsystemIssueCategory>>(
+    () => new Set(),
+  );
+  const [hovered, setHovered] = useState<SubsystemIssueCategory | null>(null);
+  const toggleCollapsed = (category: SubsystemIssueCategory) => {
+    setCollapsed((prev) => {
+      const next = new Set(prev);
+      if (next.has(category)) next.delete(category);
+      else next.add(category);
+      return next;
+    });
+  };
 
   return (
     <div style={{ flex: 1, minHeight: 0, overflowY: 'auto' }}>
@@ -455,19 +517,39 @@ export function SubsystemIssueList({
         const accent = category.severity
           ? severityColor(category.severity, theme.colors, muted)
           : theme.colors.success;
+        const isCollapsed = collapsed.has(category.category);
+        const isHovered = hovered === category.category;
         return (
           <div key={category.category}>
-            <div
+            <button
+              type="button"
+              aria-expanded={!isCollapsed}
+              onClick={() => toggleCollapsed(category.category)}
+              onMouseEnter={() => setHovered(category.category)}
+              onMouseLeave={() => setHovered(null)}
               style={{
                 position: 'sticky',
                 top: 0,
                 zIndex: 1,
+                width: '100%',
+                boxSizing: 'border-box',
                 display: 'flex',
                 alignItems: 'center',
-                gap: 7,
-                padding: '7px 12px',
-                background: theme.colors.backgroundSecondary ?? theme.colors.background,
+                gap: 8,
+                padding: '9px 12px',
+                background: isHovered
+                  ? (theme.colors.backgroundHover ??
+                    theme.colors.backgroundSecondary ??
+                    theme.colors.background)
+                  : (theme.colors.backgroundTertiary ??
+                    theme.colors.backgroundSecondary ??
+                    theme.colors.background),
+                border: 'none',
+                borderTop: `1px solid ${theme.colors.border}`,
                 borderBottom: `1px solid ${theme.colors.border}`,
+                cursor: 'pointer',
+                textAlign: 'left',
+                fontFamily: theme.fonts.body,
               }}
             >
               <span
@@ -475,9 +557,9 @@ export function SubsystemIssueList({
                   flex: 1,
                   minWidth: 0,
                   fontSize: theme.fontSizes[1],
-                  fontWeight: 600,
+                  fontWeight: 700,
+                  letterSpacing: 0.2,
                   color: clean ? muted : theme.colors.text,
-                  fontFamily: theme.fonts.body,
                   whiteSpace: 'nowrap',
                   overflow: 'hidden',
                   textOverflow: 'ellipsis',
@@ -500,8 +582,12 @@ export function SubsystemIssueList({
                   {category.count}
                 </span>
               )}
-            </div>
+              <span style={{ display: 'inline-flex', color: muted, flexShrink: 0 }}>
+                {isCollapsed ? <ChevronRight size={14} /> : <ChevronDown size={14} />}
+              </span>
+            </button>
             {!clean &&
+              !isCollapsed &&
               category.issues.map((issue) => (
                 <SubsystemIssueCard
                   key={issue.id}

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -1993,6 +1993,11 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
               onRelatedSelect={resolveRelatedComponent}
               onVerify={onVerifyComponent}
               verification={componentVerification}
+              fileOpen={
+                drawerTarget?.kind === 'file' &&
+                !!selected.file &&
+                selected.file === drawerTarget.file
+              }
             />
           </div>
         )}

package/src/subsystem/declarationRef.ts

@@ -26,7 +26,7 @@ export interface SubsystemDeclarationRef {
 }
 
 export type DeclarationFreshness =
-  | 'valid'
+  | 'fresh'
   | 'stale'
   | 'missing'
   | 'unanchored'