@principal-ai/subsystems-react 0.24.0 → 0.24.2

package/src/subsystem/DiagnosticToggle.tsx

@@ -0,0 +1,160 @@
+/**
+ * DiagnosticToggle — the subsystem graph's status/report chip.
+ *
+ * A compact button that lives in the sidebar title row (beside the description
+ * toggle). It carries the *status* of the graph's last verification pass in its
+ * icon color + count and, on click, opens the full report (the host owns that
+ * report; this component only surfaces state and calls `onOpen`).
+ *
+ * Status → color (theme):
+ * - `ok`      → success (green)
+ * - `issues`  → error   (red)
+ * - `gaps`    → warning (amber) — nothing failed, but some claims are unconfirmed
+ * - `unknown` → muted   (never checked)
+ *
+ * `stale` means the inputs changed since the report was produced — the color
+ * stays, a hollow ring marks it. `busy` swaps the icon for a spinner.
+ */
+
+import { useState } from 'react';
+import { Activity, Loader2 } from 'lucide-react';
+import { useTheme } from '@principal-ade/industry-theme';
+
+export type SubsystemDiagnosticStatus = 'ok' | 'issues' | 'gaps' | 'unknown';
+
+export interface SubsystemDiagnostic {
+  status: SubsystemDiagnosticStatus;
+  /** Count shown beside the icon (e.g. error + warn findings). Hidden when 0/undefined. */
+  issueCount?: number;
+  /** Inputs changed since the report was produced. */
+  stale?: boolean;
+  /** A verification pass is running right now. */
+  busy?: boolean;
+  /** Tooltip / a11y label override; otherwise derived from `status`. */
+  title?: string;
+  /** Click — open the report. */
+  onOpen?: () => void;
+}
+
+/** Resolve the status accent from the active theme. */
+export function diagnosticStatusColor(
+  status: SubsystemDiagnosticStatus,
+  colors: { success: string; error: string; warning: string },
+  muted: string,
+): string {
+  if (status === 'ok') return colors.success;
+  if (status === 'issues') return colors.error;
+  if (status === 'gaps') return colors.warning;
+  return muted;
+}
+
+/** Human tooltip for the current diagnostic state. */
+export function diagnosticTitle(diagnostic: SubsystemDiagnostic): string {
+  if (diagnostic.title) return diagnostic.title;
+  const { status, issueCount, stale, busy } = diagnostic;
+  let head: string;
+  if (status === 'ok') head = 'Diagnostics: no issues';
+  else if (status === 'issues')
+    head =
+      issueCount != null && issueCount > 0
+        ? `Diagnostics: ${issueCount} issue${issueCount === 1 ? '' : 's'}`
+        : 'Diagnostics: issues found';
+  else if (status === 'gaps')
+    head =
+      issueCount != null && issueCount > 0
+        ? `Diagnostics: ${issueCount} unconfirmed`
+        : 'Diagnostics: unconfirmed claims';
+  else head = 'Diagnostics: not checked yet';
+  if (busy) return `${head} — checking…`;
+  if (stale) return `${head} (stale) — open for details`;
+  return `${head} — open report`;
+}
+
+export interface SubsystemDiagnosticToggleProps extends SubsystemDiagnostic {
+  /** Icon size in px. @default 14 */
+  size?: number;
+}
+
+export function SubsystemDiagnosticToggle({
+  status,
+  issueCount,
+  stale = false,
+  busy = false,
+  size = 14,
+  onOpen,
+  ...rest
+}: SubsystemDiagnosticToggleProps) {
+  const { theme } = useTheme();
+  const [hover, setHover] = useState(false);
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const color = diagnosticStatusColor(status, theme.colors, muted);
+  const label = diagnosticTitle({ status, issueCount, stale, busy, ...rest });
+  const showCount = issueCount != null && issueCount > 0;
+
+  return (
+    <>
+      {busy && (
+        <style>{'@keyframes subsystem-diagnostic-spin{to{transform:rotate(360deg)}}'}</style>
+      )}
+      <button
+        type="button"
+        onClick={onOpen}
+        onMouseEnter={() => setHover(true)}
+        onMouseLeave={() => setHover(false)}
+        title={label}
+        aria-label={label}
+        aria-haspopup="dialog"
+        style={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 4,
+          height: 22,
+          padding: showCount ? '0 7px 0 6px' : '0 5px',
+          border: 'none',
+          borderRadius: 4,
+          background: hover ? theme.colors.border : 'transparent',
+          color,
+          cursor: 'pointer',
+          flexShrink: 0,
+          transition: 'background 120ms ease, opacity 120ms ease',
+          opacity: stale && !busy ? 0.55 : 1,
+        }}
+      >
+        <span style={{ position: 'relative', display: 'inline-flex' }}>
+          {busy ? (
+            <Loader2 size={size} style={{ animation: 'subsystem-diagnostic-spin 900ms linear infinite' }} />
+          ) : (
+            <Activity size={size} />
+          )}
+          {stale && !busy && (
+            <span
+              aria-hidden
+              style={{
+                position: 'absolute',
+                top: -2,
+                right: -2,
+                width: 6,
+                height: 6,
+                borderRadius: '50%',
+                border: `1.5px solid ${color}`,
+                background: theme.colors.backgroundSecondary ?? theme.colors.background,
+              }}
+            />
+          )}
+        </span>
+        {showCount && (
+          <span
+            style={{
+              fontFamily: theme.fonts.monospace,
+              fontSize: theme.fontSizes[0],
+              fontWeight: 600,
+              lineHeight: 1,
+            }}
+          >
+            {issueCount}
+          </span>
+        )}
+      </button>
+    </>
+  );
+}

package/src/subsystem/IssueList.tsx

@@ -0,0 +1,519 @@
+/**
+ * SubsystemIssueList — the diagnostics sidebar list.
+ *
+ * A catalogue of verification issues (audit findings), grouped by *target* so
+ * every broken component / relation / module / flow clusters together. Each
+ * card is severity-colored, names its kind, states the message, and offers the
+ * deterministic fix inline when one exists.
+ *
+ * The list is presentation-only: it owns no verification logic. Hosts map their
+ * findings into `SubsystemIssue[]` and handle `onSelectIssue` / `onApplyFix`
+ * (e.g. focus the node on the graph, or apply the fix in the report).
+ */
+
+import { useState } from 'react';
+import {
+  ChevronDown,
+  ChevronRight,
+  CircleCheck,
+  Wrench,
+} from 'lucide-react';
+import { useTheme } from '@principal-ade/industry-theme';
+
+export type SubsystemIssueSeverity = 'error' | 'warn' | 'info';
+
+export type SubsystemIssueTargetKind =
+  | 'component'
+  | 'relation'
+  | 'module'
+  | 'walkthrough'
+  | 'graph';
+
+/**
+ * The four verification layers, in order. Mirrors the docs' progression:
+ * constructs → static topology → runtime topology → walkthrough.
+ */
+export type SubsystemIssueCategory =
+  | 'construct'
+  | 'static-topology'
+  | 'runtime-topology'
+  | 'walkthrough';
+
+/** Layer order + display names, shared by the list and its headers. */
+export const SUBSYSTEM_ISSUE_CATEGORIES: SubsystemIssueCategory[] = [
+  'construct',
+  'static-topology',
+  'runtime-topology',
+  'walkthrough',
+];
+
+export const SUBSYSTEM_ISSUE_CATEGORY_LABEL: Record<
+  SubsystemIssueCategory,
+  string
+> = {
+  construct: 'Constructs',
+  'static-topology': 'Static topology',
+  'runtime-topology': 'Runtime topology',
+  walkthrough: 'Walkthrough',
+};
+
+/** Default `kind` → layer. `boundary_*` splits by module (static) vs process (runtime). */
+const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
+  missing_file: 'construct',
+  missing_symbol: 'construct',
+  stale_declaration: 'construct',
+  construct_mismatch: 'construct',
+  construct_unconfirmed: 'construct',
+  signature_mismatch: 'construct',
+  signature_unconfirmed: 'construct',
+  anchor: 'construct',
+  unresolved: 'construct',
+  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',
+};
+
+/**
+ * Verification layer for an issue. An explicit `category` wins; otherwise the
+ * audit `kind` is mapped, defaulting to `construct` (the base layer).
+ */
+export function issueCategory(issue: SubsystemIssue): SubsystemIssueCategory {
+  return issue.category ?? KIND_CATEGORY[issue.kind] ?? 'construct';
+}
+
+export interface SubsystemIssueTarget {
+  kind: SubsystemIssueTargetKind;
+  /** Stable id used to group and to focus the target on the graph. */
+  id?: string;
+  /** Display label (component name, `from → to`, module path, flow title). */
+  label: string;
+  /** Optional sub-label (relation type, step number, …). */
+  detail?: string;
+}
+
+/** One issue to surface in the sidebar (and later, on the graph). */
+export interface SubsystemIssue {
+  id: string;
+  severity: SubsystemIssueSeverity;
+  /** Machine kind, e.g. `missing_file`. Drives the label when `kindLabel` is absent. */
+  kind: string;
+  /** Human label override for the kind. */
+  kindLabel?: string;
+  message: string;
+  target?: SubsystemIssueTarget;
+  /** Verification layer override; defaults from `kind`. */
+  category?: SubsystemIssueCategory;
+  /** Deterministic fix the user can apply without an agent. */
+  fix?: { label: string };
+}
+
+const SEVERITY_RANK: Record<SubsystemIssueSeverity, number> = {
+  error: 0,
+  warn: 1,
+  info: 2,
+};
+
+/** `missing_file` → `Missing file`. */
+export function humanizeIssueKind(kind: string): string {
+  const spaced = kind.replace(/[_-]+/g, ' ').trim();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+/**
+ * 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.
+ */
+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',
+  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',
+  walkthrough: 'Step issue',
+};
+
+/** Label for an issue's kind. Explicit `kindLabel` wins; unknown kinds humanize. */
+export function issueKindLabel(issue: SubsystemIssue): string {
+  return issue.kindLabel ?? KIND_LABEL[issue.kind] ?? humanizeIssueKind(issue.kind);
+}
+
+export function severityRank(severity: SubsystemIssueSeverity): number {
+  return SEVERITY_RANK[severity] ?? SEVERITY_RANK.info;
+}
+
+/** Worst (most severe) severity in a list; `info` for an empty list. */
+export function worstSeverity(
+  issues: SubsystemIssue[],
+): SubsystemIssueSeverity {
+  let worst: SubsystemIssueSeverity = 'info';
+  for (const issue of issues) {
+    if (severityRank(issue.severity) < severityRank(worst)) worst = issue.severity;
+  }
+  return worst;
+}
+
+export interface SubsystemIssueGroup {
+  key: string;
+  kind: SubsystemIssueTargetKind;
+  label: string;
+  detail?: string;
+  issues: SubsystemIssue[];
+  severity: SubsystemIssueSeverity;
+}
+
+function targetKey(issue: SubsystemIssue): string {
+  const t = issue.target;
+  if (!t) return 'graph';
+  return `${t.kind}:${t.id ?? t.label}`;
+}
+
+/**
+ * Group issues by their target, worst-severity first, then by label. Within a
+ * group, issues are ordered error → warn → info (stable for ties).
+ */
+export function groupIssuesByTarget(
+  issues: SubsystemIssue[],
+): SubsystemIssueGroup[] {
+  const byKey = new Map<string, SubsystemIssueGroup>();
+  for (const issue of issues) {
+    const key = targetKey(issue);
+    let group = byKey.get(key);
+    if (!group) {
+      group = {
+        key,
+        kind: issue.target?.kind ?? 'graph',
+        label: issue.target?.label ?? 'Model',
+        detail: issue.target?.detail,
+        issues: [],
+        severity: 'info',
+      };
+      byKey.set(key, group);
+    }
+    group.issues.push(issue);
+  }
+  const groups = [...byKey.values()];
+  for (const group of groups) {
+    group.issues.sort(
+      (a, b) => severityRank(a.severity) - severityRank(b.severity),
+    );
+    group.severity = worstSeverity(group.issues);
+  }
+  groups.sort((a, b) => {
+    const bySeverity = severityRank(a.severity) - severityRank(b.severity);
+    if (bySeverity !== 0) return bySeverity;
+    return a.label.localeCompare(b.label);
+  });
+  return groups;
+}
+
+export interface SubsystemIssueCategoryGroup {
+  category: SubsystemIssueCategory;
+  label: string;
+  issues: SubsystemIssue[];
+  /** Worst severity present; `null` when the layer is clean. */
+  severity: SubsystemIssueSeverity | null;
+  count: number;
+}
+
+/**
+ * Group issues into the four verification layers — always all four, in order,
+ * so a clean layer can render its "happy" state. Issues within a layer are
+ * ordered error → warn → info (stable for ties).
+ */
+export function groupIssuesByCategory(
+  issues: SubsystemIssue[],
+): SubsystemIssueCategoryGroup[] {
+  const byCategory = new Map<SubsystemIssueCategory, SubsystemIssue[]>();
+  for (const category of SUBSYSTEM_ISSUE_CATEGORIES) byCategory.set(category, []);
+  for (const issue of issues) {
+    byCategory.get(issueCategory(issue))?.push(issue);
+  }
+  return SUBSYSTEM_ISSUE_CATEGORIES.map((category) => {
+    const grouped = byCategory.get(category) ?? [];
+    grouped.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
+    return {
+      category,
+      label: SUBSYSTEM_ISSUE_CATEGORY_LABEL[category],
+      issues: grouped,
+      severity: grouped.length > 0 ? worstSeverity(grouped) : null,
+      count: grouped.length,
+    };
+  });
+}
+
+function severityColor(
+  severity: SubsystemIssueSeverity,
+  colors: { error: string; warning: string; info: string },
+  muted: string,
+): string {
+  if (severity === 'error') return colors.error ?? '#e5534b';
+  if (severity === 'warn') return colors.warning ?? '#d4a017';
+  return colors.info ?? muted;
+}
+
+const TARGET_KIND_LABEL: Record<SubsystemIssueTargetKind, string> = {
+  component: 'component',
+  relation: 'relation',
+  module: 'module',
+  walkthrough: 'flow',
+  graph: 'model',
+};
+
+export interface SubsystemIssueCardProps {
+  issue: SubsystemIssue;
+  onSelect?: (issue: SubsystemIssue) => void;
+  onApplyFix?: (issue: SubsystemIssue) => void;
+  onHover?: (issue: SubsystemIssue | null) => void;
+}
+
+export function SubsystemIssueCard({
+  issue,
+  onSelect,
+  onApplyFix,
+  onHover,
+}: SubsystemIssueCardProps) {
+  const { theme } = useTheme();
+  const [hover, setHover] = useState(false);
+  // Every issue is collapsed to its kind by default so the list scans as a
+  // catalogue of problems; clicking a card reveals the message and any fix.
+  const [expanded, setExpanded] = useState(false);
+  const showDetail = expanded;
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const color = severityColor(issue.severity, theme.colors, muted);
+  const activate = () => {
+    setExpanded((v) => !v);
+    onSelect?.(issue);
+  };
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      aria-expanded={expanded}
+      onClick={activate}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          activate();
+        }
+      }}
+      onMouseEnter={() => {
+        setHover(true);
+        onHover?.(issue);
+      }}
+      onMouseLeave={() => {
+        setHover(false);
+        onHover?.(null);
+      }}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 5,
+        padding: '9px 12px 10px',
+        borderBottom: `1px solid ${theme.colors.border}`,
+        background: hover ? theme.colors.background : 'transparent',
+        cursor: 'pointer',
+        transition: 'background 120ms ease',
+        fontFamily: theme.fonts.body,
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'flex-start', gap: 6, minWidth: 0 }}>
+        <div
+          style={{
+            flex: 1,
+            minWidth: 0,
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 1,
+          }}
+        >
+          <span
+            style={{
+              fontFamily: theme.fonts.monospace,
+              fontSize: theme.fontSizes[0],
+              fontWeight: 600,
+              letterSpacing: 0.3,
+              textTransform: 'uppercase',
+              color,
+              whiteSpace: 'nowrap',
+            }}
+          >
+            {issueKindLabel(issue)}
+          </span>
+          {issue.target && (
+            <span
+              style={{
+                minWidth: 0,
+                fontFamily: theme.fonts.monospace,
+                fontSize: theme.fontSizes[0],
+                color: theme.colors.text,
+                whiteSpace: 'nowrap',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+              }}
+              title={`${TARGET_KIND_LABEL[issue.target.kind]} · ${issue.target.label}`}
+            >
+              {issue.target.label}
+            </span>
+          )}
+        </div>
+        <span
+          style={{
+            display: 'inline-flex',
+            color: muted,
+            flexShrink: 0,
+            marginTop: 1,
+          }}
+        >
+          {expanded ? <ChevronDown size={13} /> : <ChevronRight size={13} />}
+        </span>
+      </div>
+      {showDetail && (
+        <div
+          style={{
+            fontSize: theme.fontSizes[0],
+            color: theme.colors.text,
+            lineHeight: 1.45,
+            overflowWrap: 'anywhere',
+          }}
+        >
+          {issue.message}
+        </div>
+      )}
+      {showDetail && issue.fix && (
+        <div style={{ display: 'flex', marginTop: 1 }}>
+          <button
+            type="button"
+            onClick={(e) => {
+              e.stopPropagation();
+              onApplyFix?.(issue);
+            }}
+            disabled={onApplyFix == null}
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              gap: 5,
+              padding: '3px 8px',
+              border: `1px solid ${theme.colors.primary}`,
+              borderRadius: 4,
+              background: 'transparent',
+              color: theme.colors.primary,
+              fontFamily: theme.fonts.monospace,
+              fontSize: theme.fontSizes[0],
+              cursor: onApplyFix == null ? 'default' : 'pointer',
+              opacity: onApplyFix == null ? 0.5 : 1,
+            }}
+          >
+            <Wrench size={12} />
+            {issue.fix.label}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export interface SubsystemIssueListProps {
+  issues: SubsystemIssue[];
+  onSelectIssue?: (issue: SubsystemIssue) => void;
+  onApplyFix?: (issue: SubsystemIssue) => void;
+  onHoverIssue?: (issue: SubsystemIssue | null) => void;
+}
+
+export function SubsystemIssueList({
+  issues,
+  onSelectIssue,
+  onApplyFix,
+  onHoverIssue,
+}: SubsystemIssueListProps) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const categories = groupIssuesByCategory(issues);
+
+  return (
+    <div style={{ flex: 1, minHeight: 0, overflowY: 'auto' }}>
+      {categories.map((category) => {
+        // A layer with no findings renders its happy state: a green check in
+        // the header, no count, no cards.
+        const clean = category.count === 0;
+        const accent = category.severity
+          ? severityColor(category.severity, theme.colors, muted)
+          : theme.colors.success;
+        return (
+          <div key={category.category}>
+            <div
+              style={{
+                position: 'sticky',
+                top: 0,
+                zIndex: 1,
+                display: 'flex',
+                alignItems: 'center',
+                gap: 7,
+                padding: '7px 12px',
+                background: theme.colors.backgroundSecondary ?? theme.colors.background,
+                borderBottom: `1px solid ${theme.colors.border}`,
+              }}
+            >
+              <span
+                style={{
+                  flex: 1,
+                  minWidth: 0,
+                  fontSize: theme.fontSizes[1],
+                  fontWeight: 600,
+                  color: clean ? muted : theme.colors.text,
+                  fontFamily: theme.fonts.body,
+                  whiteSpace: 'nowrap',
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                }}
+              >
+                {category.label}
+              </span>
+              {clean ? (
+                <CircleCheck size={13} color={accent} style={{ flexShrink: 0 }} />
+              ) : (
+                <span
+                  style={{
+                    fontFamily: theme.fonts.monospace,
+                    fontSize: theme.fontSizes[0],
+                    fontWeight: 600,
+                    color: accent,
+                    flexShrink: 0,
+                  }}
+                >
+                  {category.count}
+                </span>
+              )}
+            </div>
+            {!clean &&
+              category.issues.map((issue) => (
+                <SubsystemIssueCard
+                  key={issue.id}
+                  issue={issue}
+                  onSelect={onSelectIssue}
+                  onApplyFix={onApplyFix}
+                  onHover={onHoverIssue}
+                />
+              ))}
+          </div>
+        );
+      })}
+    </div>
+  );
+}