Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
fix(ui): say why the system structure is empty
Bernhard Jackiewicze46f3765b494
diff --git a/graph-ui/src/architecture/SystemArchitecture.test.tsx b/graph-ui/src/architecture/SystemArchitecture.test.tsxindex 735235913..9938d14e0 100644--- a/graph-ui/src/architecture/SystemArchitecture.test.tsx+++ b/graph-ui/src/architecture/SystemArchitecture.test.tsx@@ -53,6 +53,22 @@ function corridorFixture(): SystemProjection {data.behavior = { ...data.behavior!, mode: 'corridor', target_id: 3, nodes: data.paths[0].nodes, edges: data.paths[0].edges };return data;}+/** The response the server returns when the projection exceeds its JSON memory budget (Django 5.2.7). */+function limitedEmptyFixture(): SystemProjection {+ return {+ schema_version: 1, status: 'limited', kind: 'static_projection', complete: false,+ components: [], dependencies: [], cycles: [], entrypoints: [], paths: [],+ warnings: ['Component candidates are inferred from indexed declarations and interactions; they do not establish intended responsibilities or deployment boundaries.',+ 'Paths are bounded static witnesses, not observed executions. Callback references are not invocation evidence. Index coverage gaps remain possible.',+ 'The architecture response exceeded its memory budget; narrow the requested projection.'],+ totals: { nodes: 52402, files: 4654, edges: 274549, accounted_nodes: 0, structural_nodes: 0, components: 0, dependencies: 0, entrypoints: 0, cycles: 0, relationship_edges: 0, unmodeled_edges: 0 },+ limits: { node_budget: 100000, edge_budget: 500000, omitted_components: 0, omitted_dependencies: 0, omitted_entrypoints: 0, omitted_cycles: 0, paths_truncated: false, path_depth: 10 },+ overview: { complete: false, grouping_basis: 'common_source_directory_aggregate', groups: [], components: [], connections: [],+ totals: { groups: 0, components: 0, accounted_nodes: 0, connections: 0 }, limits: { omitted_connections: 0 } },+ behavior: { mode: 'targets', source_id: 0, complete: false, corridor_complete: false, max_hops: 10, limits_hit: ['analysis_budget'],+ reachable_targets: [], nodes: [], edges: [], cycles: [], totals: { reachable_nodes: 0, corridor_nodes: 0, corridor_edges: 0 } },+ };+}function addOverviewContext(data: SystemProjection) {const extra = { id: 'context', label: 'context', basis: 'declared_module', member_count: 1, file_count: 1, representatives: [], group_id: 'g:context' };data.components.push(extra);@@ -158,6 +174,11 @@ describe('system architecture evidence', () => {const data = fixture(); data.status = 'limited'; data.complete = false; data.warnings = ['Node budget reached.'];expect(readSystemArchitecture(response(data)).result?.complete).toBe(false);});+ it('accepts the empty limited projection exactly as the server sends it', () => {+ const wire = { status: 'ready', generation: 'g1', result: { ...limitedEmptyFixture(), project: 'django-demo', elapsed_ms: 310,+ overview: { ...limitedEmptyFixture().overview, grouping_depth: 1 } } };+ expect(readSystemArchitecture(wire).result?.status).toBe('limited');+ });it('rejects projected paths whose underlying symbols do not join', () => {const data = fixture(); data.paths[0].edges[1].source_id = 99;expect(isContiguousPath(data.paths[0])).toBe(false);@@ -492,6 +513,22 @@ describe('system architecture workspace', () => {expect(container.querySelector('[data-node="store"]')).not.toBeNull();expect(container.textContent).toContain('Test code'); expect(container.textContent).toContain('3 components returned');});+ it('explains an empty limited projection with its own warning before any filter message', async () => {+ await render(vi.fn<SystemArchitectureLoader>().mockResolvedValue(response(limitedEmptyFixture())));+ const reason = () => container.querySelector('.system-scene-empty[role="status"]')?.textContent ?? '';+ expect(reason()).toContain('The analysis returned no system structure for this project.');+ expect(reason()).toContain('The architecture response exceeded its memory budget; narrow the requested projection.');+ expect(reason()).not.toContain('Component candidates are inferred');+ const cycles = [...container.querySelectorAll('label')].find(label => label.textContent?.includes('Group cycles'))!.querySelector('input')!;+ await act(async () => cycles.click());+ expect(container.textContent).not.toContain('No component cycles match');+ expect(reason()).toContain('exceeded its memory budget');+ });+ it('keeps the budget message for an empty projection that names no limit', async () => {+ const data = limitedEmptyFixture(); data.status = 'ready'; data.warnings = data.warnings.slice(0, 2);+ await render(vi.fn<SystemArchitectureLoader>().mockResolvedValue(response(data)));+ expect(container.querySelector('.system-scene-empty[role="status"]')?.textContent).toBe('No component projection is available within this analysis budget.');+ });it('shows failures without retrying continuously', async () => {vi.useFakeTimers(); const loader = vi.fn<SystemArchitectureLoader>().mockResolvedValue({ status: 'failed', generation: 'g1', error: 'Analysis budget exceeded.' });await render(loader); await act(async () => { await vi.advanceTimersByTimeAsync(5000); });diff --git a/graph-ui/src/architecture/SystemArchitecture.tsx b/graph-ui/src/architecture/SystemArchitecture.tsxindex f1513ea73..df754544b 100644--- a/graph-ui/src/architecture/SystemArchitecture.tsx+++ b/graph-ui/src/architecture/SystemArchitecture.tsx@@ -2,7 +2,8 @@ import { lazy, Suspense, useEffect, useMemo, useState } from 'react';import type { GraphData, GraphNode } from '../galaxy/types';import { useSelectionEvidence, type SelectionEvidenceListener } from '../galaxy/selection-evidence';import { loadSystemArchitecture, type SystemArchitectureLoader, type SystemArchitectureResponse, type SystemProjection, type SystemSymbol, type SystemWitness, type SystemCallEvidence } from './system-architecture-source';-import { componentBasis, isContiguousPath, systemOverviewGraph, systemComponents, type SystemSceneEdge, type SystemSceneModel } from './system-architecture-model';+import { componentBasis, isContiguousPath, projectionLimits, projectionUnavailable, systemOverviewGraph, systemComponents, type SystemSceneEdge, type SystemSceneModel } from './system-architecture-model';+import { architectureText as text } from './strings';import { connectionLoad } from '../graph/connection-load';import BehaviorJourney from './BehaviorJourney';import './system-architecture.css';@@ -16,6 +17,12 @@ export interface SystemArchitectureProps {loader?: SystemArchitectureLoader;}+/** A limited or empty projection explains itself with the warnings that limited it. */+function UnavailableProjection({ limits }: { limits: string[] }) {+ return <div className="system-scene-empty" role="status" data-limited={limits.length > 0}>+ <strong>{limits.length ? text.projectionLimited : text.projectionEmpty}</strong>{limits.map(limit => <p key={limit}>{limit}</p>)}</div>;+}+function EvidenceSource({ symbol, onOpen }: { symbol: SystemSymbol; onOpen: (symbol: SystemSymbol) => void }) {return <div className="system-source"><button disabled={!symbol.file_path} onClick={() => onOpen(symbol)} title={symbol.qualified_name}>{symbol.name}</button><small>{symbol.file_path ? `${symbol.file_path}${symbol.start_line ? `:${symbol.start_line}` : ''}` : 'Source location unavailable'}</small></div>;@@ -294,9 +301,11 @@ export default function SystemArchitecture({ project, generation, view, filter,<div className="system-view-switch" role="group" aria-label="System camera"><button aria-pressed={!planar} onClick={() => setPlanar(false)}>3D</button><button aria-pressed={planar} onClick={() => setPlanar(true)}>Plan</button></div></div><div className="system-workspace"><div className="system-map">+ {/* The reason for an empty projection outranks any filter that would also find nothing. */}{model.nodes.length ? <Suspense fallback={<div className="system-scene-empty">Preparing 3D view…</div>}><Scene model={model} selectedNode={selectedSceneNode} selectedEdge={selection?.edge}onSelectNode={selectNode} onSelectEdge={selectEdge} onExpandNode={id => { toggleGroup(id); focus(id); }} onClearSelection={clearSelection} highlightedPathIndex={view === 'behavior' ? highlightedPathIndex : undefined} resetKey={resetKey} planar={planar} active={active} showConnectionLoad={showConnectionLoad} /></Suspense>- : <div className="system-scene-empty">{view === 'behavior' ? filter ? 'No source paths match this filter. Clear it to see the entry point’s returned paths.' : 'No connected source path is available for this entry point.' : cyclesOnly ? 'No component cycles match the current filters in the returned analysis.' : filter ? 'No matching components. Try a broader filter or include unconnected components.' : data.components.length && !includeUnconnected ? 'No connected components match the current view. Change the connection filter or include unconnected components.' : 'No component projection is available within this analysis budget.'}</div>}+ : view === 'structure' && projectionUnavailable(data) ? <UnavailableProjection limits={projectionLimits(data)} />+ : <div className="system-scene-empty">{view === 'behavior' ? filter ? 'No source paths match this filter. Clear it to see the entry point’s returned paths.' : 'No connected source path is available for this entry point.' : cyclesOnly ? 'No component cycles match the current filters in the returned analysis.' : filter ? 'No matching components. Try a broader filter or include unconnected components.' : data.components.length && !includeUnconnected ? 'No connected components match the current view. Change the connection filter or include unconnected components.' : text.projectionEmpty}</div>}<div className="system-map-caption"><span>{view === 'behavior' ? 'Arrows are indexed calls, not an execution timeline.' : 'Select to inspect · expand a group for its members'}{showConnectionLoad ? ' · rings show link load' : ''}</span><button onClick={() => setResetKey(value => value + 1)}>Fit view</button></div></div><aside className="system-inspector" aria-label="System evidence inspector">diff --git a/graph-ui/src/architecture/strings.ts b/graph-ui/src/architecture/strings.tsindex 97552c13a..9bcaf201e 100644--- a/graph-ui/src/architecture/strings.ts+++ b/graph-ui/src/architecture/strings.ts@@ -75,4 +75,6 @@ export const architectureText = {focusGroup: (name: string) => `Show relationships for ${name}`,groupStats: (symbols: number) => `${symbols.toLocaleString()} symbols`,cohesion: (value: number) => `${Math.round(value * 100)}% cohesion`,+ projectionLimited: 'The analysis returned no system structure for this project.',+ projectionEmpty: 'No component projection is available within this analysis budget.',};diff --git a/graph-ui/src/architecture/system-architecture-model.test.ts b/graph-ui/src/architecture/system-architecture-model.test.tsindex 4f03b1513..d7df53b06 100644--- a/graph-ui/src/architecture/system-architecture-model.test.ts+++ b/graph-ui/src/architecture/system-architecture-model.test.ts@@ -1,5 +1,5 @@import { describe, expect, it } from 'vitest';-import { isContiguousPath, rankSystemPaths, systemBehaviorGraph, systemComponentGraph, systemOverviewGraph, systemBehaviorOverviewGraph } from './system-architecture-model';+import { isContiguousPath, projectionLimits, projectionUnavailable, rankSystemPaths, systemBehaviorGraph, systemComponentGraph, systemOverviewGraph, systemBehaviorOverviewGraph } from './system-architecture-model';import type { SystemComponent, SystemDependency, SystemPath, SystemProjection, SystemSymbol } from './system-architecture-source';const symbol = (id: number, component = 'app'): SystemSymbol => ({ id, name: `f${id}`, qualified_name: `app.f${id}`, label: 'Function', component_id: component, file_path: `src/${component}.ts`, start_line: id });@@ -21,6 +21,22 @@ const overviewProjection = (ids: string[], dependencies: SystemDependency[]): Sycomponents, connections: dependencies, totals: { groups: ids.length, components: ids.length }, limits: { omitted_connections: 0 } } };};+describe('projection limits', () => {+ it('drops only the two standing caveats and keeps every other or reworded warning', () => {+ const data = projection([component('app')]);+ data.warnings = ['Component candidates are inferred from indexed declarations and interactions.', 'Paths are bounded static witnesses, not observed executions.',+ 'Graph exceeds the node budget; no sampled architecture was inferred.', 'Component candidates may be inferred differently in a future version.'];+ expect(projectionLimits(data)).toEqual(['Graph exceeds the node budget; no sampled architecture was inferred.', 'Component candidates may be inferred differently in a future version.']);+ });+ it('treats a limited answer or one without groups as unavailable, independent of filters', () => {+ expect(projectionUnavailable(projection([component('app')]))).toBe(false);+ expect(projectionUnavailable({ ...projection([component('app')]), status: 'limited' })).toBe(true);+ expect(projectionUnavailable(projection([]))).toBe(true);+ expect(projectionUnavailable({ ...projection([component('app')]), overview: { complete: false, grouping_basis: 'common_source_directory_aggregate',+ groups: [], components: [], connections: [], totals: {}, limits: {} } })).toBe(true);+ });+});+describe('persistent system overview', () => {it('keeps directory siblings on a shared platform without assigning execution order', () => {const data = overviewProjection(['pkg/a', 'src/b', 'tools', 'src/a', 'pkg/b'], [dependency('pkg/a', 'src/a')]);diff --git a/graph-ui/src/architecture/system-architecture-model.ts b/graph-ui/src/architecture/system-architecture-model.tsindex 21ba2d5fe..c4347ba56 100644--- a/graph-ui/src/architecture/system-architecture-model.ts+++ b/graph-ui/src/architecture/system-architecture-model.ts@@ -32,6 +32,20 @@ export const componentBasis = (basis: string): string => basis === 'declared_mod: basis === 'interaction_community' ? 'Inferred collaboration' : basis === 'unassigned' ? 'Unassigned': basis === 'common_source_directory_aggregate' ? 'Source directory group' : basis === 'aggregate_remainder' ? 'Other components' : 'Inferred component';+/*+ * Every projection opens its warnings with the same two interpretation caveats+ * and appends what actually limited this answer. Only the caveats are left out;+ * an unknown or reworded warning stays visible, so a change in the server text+ * can never hide a limit.+ */+const STANDING_CAVEATS = [/^Component candidates are inferred\b/, /^Paths are bounded static witnesses\b/];+/** The warnings that explain this particular projection, without the standing caveats. */+export const projectionLimits = (data: SystemProjection): string[] =>+ data.warnings.filter(warning => !STANDING_CAVEATS.some(caveat => caveat.test(warning)));+/** A limited or empty projection has nothing to draw, whatever the current filters are. */+export const projectionUnavailable = (data: SystemProjection): boolean =>+ data.status === 'limited' || !(data.overview ? data.overview.groups.length : data.components.length);+export interface SystemOverviewOptions {expandedGroupIds?: readonly string[]; focusId?: string; relationshipTypes?: readonly string[];includeTests?: boolean; includeUnconnected?: boolean; filter?: string; cyclesOnly?: boolean; layoutKey?: string;diff --git a/graph-ui/src/architecture/system-architecture.css b/graph-ui/src/architecture/system-architecture.cssindex 82983d4d8..f44cd66e4 100644--- a/graph-ui/src/architecture/system-architecture.css+++ b/graph-ui/src/architecture/system-architecture.css@@ -73,7 +73,8 @@.system-path-list li > span { color: var(--atlas-dim); font-size: 10px; }.system-scene-empty, .system-analysis-state { display: flex; align-items: center; justify-content: center; text-align: center; flex-direction: column; gap: 12px; height: 100%; min-height: 260px; padding: 30px; color: var(--atlas-dim); }.system-analysis-state { border: 1px solid var(--atlas-line); border-radius: 12px; }-.system-analysis-state strong { color: var(--atlas-fg); font-weight: 500; }+.system-analysis-state strong, .system-scene-empty[data-limited] strong { color: var(--atlas-fg); font-weight: 500; }+.system-scene-empty[data-limited="true"] p { color: var(--atlas-fg); max-width: 560px; }.system-progress { width: 26px; height: 26px; border: 1px solid #869f9638; border-top-color: #a0b6aa; border-radius: 50%; animation: system-progress-turn 1.3s linear infinite; }@keyframes system-progress-turn { to { transform: rotate(360deg); } }.system-architecture .system-scene-node-label { display: grid; align-content: center; gap: 0; width: 96px; height: 28px; min-height: 0; box-sizing: border-box; margin: 0; background: #101816ec; color: #c0cec7; border: 1px solid #78928638; border-radius: 6px; padding: 6px 7px; text-align: center; line-height: 14px; font-family: var(--atlas-ui-font, system-ui, sans-serif); box-shadow: 0 2px 8px #0002; }