@principal-ai/subsystems-react 0.17.0

package/src/subsystem/SubsystemFileTree.tsx

@@ -0,0 +1,190 @@
+/**
+ * SubsystemFileTree — sidebar file tree for a subsystem's components, built
+ * on @pierre/trees following the panel repo's SessionFileTreePanel pattern:
+ * init-once options + latest-value refs, and a suppress flag around
+ * programmatic selection so `onSelectionChange` echoes don't re-open files.
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+import type { CSSProperties } from 'react';
+import { FileTree, useFileTree } from '@pierre/trees/react';
+import { useTheme } from '@principal-ade/industry-theme';
+
+export interface SubsystemFileTreeProps {
+  /** Repo-root-relative file paths; duplicates are deduped. */
+  files: string[];
+  /** File to select/highlight (the drawer-open file). */
+  selectedFile?: string | null;
+  /** File to transiently highlight while its node is hovered on the graph;
+   *  falls back to `selectedFile` when null. */
+  hoveredFile?: string | null;
+  /** Called when a file row is clicked; upstream toggles the drawer. */
+  onSelectFile?: (file: string) => void;
+  /** Hide the built-in "Files N" header row — used when an upstream repo
+   *  header already labels the tree. */
+  headerless?: boolean;
+}
+
+/** Fills its parent height by design — pin it with a sized flex container. */
+export function SubsystemFileTree({ files, selectedFile, hoveredFile, onSelectFile, headerless }: SubsystemFileTreeProps) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const paths = useMemo(() => Array.from(new Set(files)).sort(), [files]);
+
+  // Latest-value refs so the stable `onSelectionChange` closure never goes
+  // stale — `useFileTree` reads its options once on init.
+  const pathSet = useMemo(() => new Set(paths), [paths]);
+  const pathSetRef = useRef(pathSet);
+  pathSetRef.current = pathSet;
+  const onSelectFileRef = useRef(onSelectFile);
+  onSelectFileRef.current = onSelectFile;
+  const selectedFileRef = useRef<string | null>(selectedFile ?? null);
+  selectedFileRef.current = selectedFile ?? null;
+  // Suppresses onSelectFile while selection is driven programmatically from
+  // the drawer state (`selectedFile`) — no synthetic open/close events.
+  const suppressSelectRef = useRef(false);
+  const initialPaths = useRef(paths);
+
+  const { model } = useFileTree({
+    paths: initialPaths.current,
+    initialExpansion: 'open',
+    onSelectionChange: (selected) => {
+      if (suppressSelectRef.current) return;
+      const raw = selected[selected.length - 1] ?? selected[0];
+      if (!raw) return;
+      // Directory rows carry a trailing slash; only emit for real files.
+      const path = raw.endsWith('/') ? raw.slice(0, -1) : raw;
+      if (!pathSetRef.current.has(path)) return;
+      // Includes re-clicks on the open row — upstream toggles it closed.
+      onSelectFileRef.current?.(path);
+    },
+  });
+
+  // Reconcile the tree's native selection with the OPEN file only. Hover is
+  // deliberately NOT folded into selection — pierre's model is single-select,
+  // so routing hover through select()/deselect() would steal the highlight
+  // from the open file. The hovered row gets its own transient marker instead.
+  const lastSyncedRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (lastSyncedRef.current === (selectedFile ?? null)) return;
+    const prev = lastSyncedRef.current;
+    lastSyncedRef.current = selectedFile ?? null;
+    suppressSelectRef.current = true;
+    try {
+      if (prev) model.getItem(prev)?.deselect();
+      if (selectedFile) {
+        model.getItem(selectedFile)?.select();
+        model.scrollToPath(selectedFile);
+      }
+    } finally {
+      suppressSelectRef.current = false;
+    }
+  }, [model, selectedFile]);
+
+  // Transient hover highlight (e.g. hovering a graph node spotlights its
+  // file), independent of selection. Pierre renders rows inside a shadow
+  // root, so we resolve the row through shadow boundaries and paint an
+  // inline background — document-level <style> tags cannot reach it.
+  const treeRef = useRef<HTMLDivElement | null>(null);
+  const hoveredRowRef = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    hoveredRowRef.current?.style.removeProperty('background');
+    hoveredRowRef.current = null;
+    const target = hoveredFile ?? null;
+    if (!target || !pathSetRef.current.has(target)) return;
+
+    // Depth-first walk across shadow roots — handles nested custom elements.
+    const roots: Array<Document | ShadowRoot> = [document];
+    while (roots.length > 0) {
+      const root = roots.shift()!;
+      const row = root.querySelector(`[data-item-path="${CSS.escape(target)}"]`);
+      if (row instanceof HTMLElement) {
+        row.style.background = 'var(--trees-theme-list-hover-bg, rgba(128, 128, 128, 0.25))';
+        hoveredRowRef.current = row;
+        return;
+      }
+      for (const el of Array.from(root.querySelectorAll('*'))) {
+        if (el.shadowRoot) roots.push(el.shadowRoot);
+      }
+    }
+  }, [hoveredFile]);
+
+  // Re-scope the tree in place when the subsystem's file set changes.
+  useEffect(() => {
+    model.resetPaths(paths);
+  }, [model, paths]);
+
+  // Pierre emits no selection change when the clicked row is already
+  // selected — detect re-clicks on the open file's row via focus and let
+  // upstream toggle the drawer closed.
+  const handleContainerClick = () => {
+    const focused = model.getFocusedPath();
+    if (!focused) return;
+    const path = focused.endsWith('/') ? focused.slice(0, -1) : focused;
+    if (path !== selectedFileRef.current) return;
+    suppressSelectRef.current = true;
+    try {
+      onSelectFileRef.current?.(path);
+    } finally {
+      suppressSelectRef.current = false;
+    }
+  };
+
+  return (
+    <div
+      ref={treeRef}
+      onClickCapture={handleContainerClick}
+      style={{
+        flex: 1,
+        minHeight: 0,
+        display: 'flex',
+        flexDirection: 'column',
+      }}
+    >
+      {!headerless && (
+        <div
+          style={{
+            padding: '10px 16px 4px',
+            display: 'flex',
+            alignItems: 'baseline',
+            gap: 6,
+            flexShrink: 0,
+          }}
+        >
+          <span
+            style={{
+              fontSize: theme.fontSizes[0] * 0.8,
+              fontFamily: theme.fonts.monospace,
+              textTransform: 'uppercase',
+              color: muted,
+              fontWeight: 600,
+            }}
+          >
+            Files
+          </span>
+          <span style={{ fontSize: theme.fontSizes[0] * 0.8, fontFamily: theme.fonts.monospace, color: muted }}>
+            {paths.length}
+          </span>
+        </div>
+      )}
+      <FileTree
+        model={model}
+        style={
+          {
+            flex: 1,
+            minHeight: 0,
+            '--trees-padding-inline-override': '8px',
+            '--trees-bg-override': 'transparent',
+            '--trees-fg-override': theme.colors.text,
+            '--trees-fg-muted-override': muted,
+            '--trees-accent-override': theme.colors.primary,
+            '--trees-font-family-override': theme.fonts.monospace,
+            '--trees-font-size-override': `${theme.fontSizes[0]}px`,
+            '--trees-theme-list-hover-bg': theme.colors.border,
+            '--trees-theme-list-active-selection-bg': theme.colors.border,
+          } as CSSProperties
+        }
+      />
+    </div>
+  );
+}

package/src/subsystem/declarationRef.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  extractDeclarationLine,
+  normalizeDeclarationLine,
+  parseSourceLocation,
+} from './declarationRef';
+
+describe('parseSourceLocation', () => {
+  test('parses L-prefixed lines', () => {
+    expect(parseSourceLocation('L42')).toBe(42);
+    expect(parseSourceLocation(' L1 ')).toBe(1);
+  });
+
+  test('rejects invalid', () => {
+    expect(parseSourceLocation('42')).toBeNull();
+    expect(parseSourceLocation('')).toBeNull();
+    expect(parseSourceLocation(undefined)).toBeNull();
+  });
+});
+
+describe('normalizeDeclarationLine', () => {
+  test('trims trailing whitespace and CR', () => {
+    expect(normalizeDeclarationLine('export class Foo {\r')).toBe('export class Foo {');
+    expect(normalizeDeclarationLine('  x  ')).toBe('  x');
+  });
+});
+
+describe('extractDeclarationLine', () => {
+  test('1-based indexing', () => {
+    expect(extractDeclarationLine('a\nb\nc', 2)).toBe('b');
+    expect(extractDeclarationLine('a\nb', 3)).toBeNull();
+  });
+});

package/src/subsystem/declarationRef.ts

@@ -0,0 +1,63 @@
+/**
+ * Declaration anchoring — start-line + single-line content hash.
+ *
+ * Graphify emits `source_location: "L42"` (declaration start line). We capture
+ * that line's normalized text as a fingerprint to detect drift without end-line
+ * spans or graphify changes.
+ */
+
+/** Persisted anchor for a subsystem component's source declaration. */
+export interface SubsystemDeclarationRef {
+  /** Repo-root-relative path (matches `component.file`). */
+  file: string;
+  /** 1-based declaration start line (from graphify `source_location`). */
+  startLine: number;
+  /** SHA-256 of {@link normalizeDeclarationLine} output, truncated to 32 hex chars. */
+  lineHash: string;
+  /** Graphify node id when captured from an exact anchor. */
+  graphifyNodeId?: string;
+  /** ISO timestamp when this ref was recorded. */
+  capturedAt: string;
+  /** Repo revision at capture time (optional). */
+  revision?: {
+    headSha: string;
+    dirtyHash?: string | null;
+  };
+}
+
+export type DeclarationFreshness =
+  | 'valid'
+  | 'stale'
+  | 'missing'
+  | 'unanchored'
+  | 'unchecked';
+
+export const DECLARATION_HASH_ALGO = 'v1' as const;
+
+/** Parse graphify `source_location` (`"L42"`) → 1-based line number. */
+export function parseSourceLocation(loc: string | undefined | null): number | null {
+  if (!loc?.trim()) return null;
+  const m = /^L(\d+)$/.exec(loc.trim());
+  if (!m) return null;
+  const n = Number.parseInt(m[1]!, 10);
+  return Number.isFinite(n) && n >= 1 ? n : null;
+}
+
+/** Normalize a source line before hashing (algo v1). */
+export function normalizeDeclarationLine(line: string): string {
+  return line.replace(/\r$/, '').trimEnd();
+}
+
+/** Extract one 1-based line from file content; null when out of range. */
+export function extractDeclarationLine(content: string, lineNumber: number): string | null {
+  if (lineNumber < 1) return null;
+  const lines = content.split(/\r?\n/);
+  if (lineNumber > lines.length) return null;
+  return lines[lineNumber - 1] ?? null;
+}
+
+/** Options when opening a file in the subsystem graph drawer. */
+export interface SubsystemOpenFileOptions {
+  /** Scroll/highlight this 1-based line (declaration start). */
+  startLine?: number;
+}

package/src/subsystem/formatDeclaration.ts

@@ -0,0 +1,174 @@
+/**
+ * Generate a TypeScript declaration string from a SubsystemComponent's detail.
+ *
+ * This is the "source code" that Prettier will format. The output is valid
+ * TypeScript (except for `external`, which is handled separately). The string
+ * is intentionally simple — no indentation, no line breaks — because Prettier
+ * handles all formatting.
+ */
+
+import type { SubsystemComponent, SubsystemComponentConstruct } from './model';
+import type { GraphifyComponentDetail } from '../graphify';
+
+const TYPE_FAMILY_CONSTRUCTS: ReadonlySet<string> = new Set([
+  'interface',
+  'type_alias',
+  'enum',
+]);
+
+export function generateDeclarationString(component: SubsystemComponent): string {
+  const detail = component.detail;
+  // Type-family constructs own their rendering even when the detail payload
+  // is the shared `type` shape — the construct says which keyword is honest.
+  const construct = TYPE_FAMILY_CONSTRUCTS.has(component.construct)
+    ? component.construct
+    : detail?.kind ?? component.construct;
+  const rawName = component.symbol || component.name || 'untitled';
+  // Strip class/object prefix from dotted symbols (e.g. "SessionReader.normalize" → "normalize").
+  const name = rawName.includes('.') ? rawName.split('.').pop()! : rawName;
+
+  switch (construct) {
+    case 'class':
+      return generateClass(name, detail);
+    case 'function':
+      return generateFunction(name, detail);
+    case 'method':
+      return generateMethod(name, detail);
+    case 'interface':
+    case 'type_alias':
+    case 'enum':
+      return generateType(name, component.construct, detail);
+    case 'module':
+      return generateModule(detail);
+    case 'store':
+      return generateStore(name, detail);
+    case 'external':
+      // Not valid TypeScript — caller should handle formatting.
+      return `external '${detail?.kind === 'external' ? detail.label : name}'`;
+    default:
+      return `${construct} ${name}`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Format parameters, synthesising names for unnamed positionals. */
+function formatParams(params: { name?: string; type: string }[]): string {
+  return params
+    .map((p, i) => (p.name ? `${p.name}: ${p.type}` : `arg${i}: ${p.type}`))
+    .join(', ');
+}
+
+// ---------------------------------------------------------------------------
+// Per-construct generators
+// ---------------------------------------------------------------------------
+
+function generateClass(name: string, detail?: GraphifyComponentDetail): string {
+  const cls = detail?.kind === 'class' ? detail : undefined;
+  const parts: string[] = [`class ${name}`];
+
+  if (cls?.extends && cls.extends.length > 0) {
+    parts.push(`extends ${cls.extends.join(', ')}`);
+  }
+  if (cls?.implements && cls.implements.length > 0) {
+    parts.push(`implements ${cls.implements.join(', ')}`);
+  }
+
+  const members: string[] = [];
+
+  for (const m of cls?.methods ?? []) {
+    const ret = m.returnType ? `: ${m.returnType}` : '';
+    members.push(`  ${m.name}(${formatParams(m.parameters ?? [])})${ret};`);
+  }
+
+  for (const prop of cls?.properties ?? []) {
+    const t = prop.type ? `: ${prop.type}` : '';
+    members.push(`  ${prop.name}${t};`);
+  }
+
+  if (members.length > 0) {
+    parts.push(`{\n${members.join('\n')}\n}`);
+  } else {
+    parts.push('{}');
+  }
+
+  return parts.join(' ');
+}
+
+function generateFunction(name: string, detail?: GraphifyComponentDetail): string {
+  const fn = detail?.kind === 'function' ? detail : undefined;
+  const params = formatParams(fn?.parameters ?? []);
+  const ret = fn?.returnType ? `: ${fn.returnType}` : '';
+  return `function ${name}(${params})${ret};`;
+}
+
+function generateMethod(name: string, detail?: GraphifyComponentDetail): string {
+  const m = detail?.kind === 'method' ? detail : undefined;
+  const hostClass = m?.hostClass ?? 'Host';
+  const params = formatParams(m?.parameters ?? []);
+  const ret = m?.returnType ? `: ${m.returnType}` : '';
+  return `class ${hostClass} {\n  ${name}(${params})${ret};\n}`;
+}
+
+function generateType(
+  name: string,
+  construct: SubsystemComponentConstruct,
+  detail?: GraphifyComponentDetail,
+): string {
+  // The type-family constructs render their declaration keyword honestly —
+  // the construct itself says interface / type (alias) / enum / variable.
+  const tpe = detail?.kind === 'type' ? detail : undefined;
+  const props = (tpe?.properties ?? [])
+    .map((p) => `  ${p.name}${p.type ? `: ${p.type}` : ''};`)
+    .join('\n');
+
+  switch (construct) {
+    case 'enum':
+      return `enum ${name} { ${(tpe?.properties ?? []).map((p) => p.name).join(', ')} }`;
+    case 'type_alias':
+      return props
+        ? `type ${name} = {\n${props}\n};`
+        : `type ${name} = unknown;`;
+    default:
+      if (props) {
+        return `interface ${name} {\n${props}\n}`;
+      }
+      return `interface ${name} {}`;
+  }
+}
+
+function generateModule(detail?: GraphifyComponentDetail): string {
+  const mod = detail?.kind === 'module' ? detail : undefined;
+  if (!mod) return 'module {}';
+
+  const parts: string[] = [];
+
+  for (const imp of mod.imports ?? []) {
+    parts.push(`import '${imp.name}';`);
+  }
+
+  if ((mod.exports ?? []).length > 0) {
+    parts.push(`export { ${mod.exports!.join(', ')} };`);
+  }
+
+  return parts.join('\n') || `module {}`;
+}
+
+/**
+ * A store renders as its retained state — ambient `declare const` lines for
+ * the state members, never a class/method stub. The node's name labels the
+ * block; the access mechanism lives in separate accessor nodes.
+ */
+function generateStore(name: string, detail?: GraphifyComponentDetail): string {
+  const store = detail?.kind === 'store' ? detail : undefined;
+  const props = (store?.properties ?? [])
+    .map((p) => `declare const ${p.name}${p.type ? `: ${p.type}` : ''};`)
+    .join('\n');
+
+  if (!props) {
+    return `// store: ${name} — no captured state members`;
+  }
+  return `// store: ${name}\n${props}`;
+}