Skip to content

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.

fix(ui): make the Behavior start list findable: suggestions, alphabetical, filter (A4)

Bernhard Jackiewiczedf241786fd5
diff --git a/graph-ui/src/architecture/BehaviorJourney.test.tsx b/graph-ui/src/architecture/BehaviorJourney.test.tsx
index 79bfc4b31..daa7f6e31 100644
--- a/graph-ui/src/architecture/BehaviorJourney.test.tsx
+++ b/graph-ui/src/architecture/BehaviorJourney.test.tsx
@@ -182,3 +182,46 @@ describe('behavior journeys', () => {
expect(compact.edges.map(edge => edge.pathEdge!.id)).toEqual([14, 15]);
});
});
+
+/* Hand test 2026-10-04 (A4): the "Start" list had no recognizable order, and "handle · …/loaddata.py" could not be found. */
+describe('Behavior start field', () => {
+ const LOADDATA = 'django/core/management/commands/loaddata.py';
+ const entries = [symbol(1), { ...symbol(21), name: 'handle', file_path: 'django/core/management/commands/makemigrations.py' },
+ { ...symbol(22), name: 'handle', file_path: LOADDATA }, { ...symbol(23), name: 'as_sql', file_path: 'django/db/models/fields/json.py' }];
+ const select = () => container.querySelector<HTMLSelectElement>('select[aria-label="Behavior entry point"]')!;
+ const filterField = () => container.querySelector<HTMLInputElement>('input[aria-label="Filter operations"]')!;
+ const group = (index: number) => [...select().querySelectorAll('optgroup')][index];
+ const options = (index: number) => [...group(index).querySelectorAll('option')].map(option => option.textContent);
+ async function type(value: string) {
+ await act(async () => {
+ Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!.call(filterField(), value);
+ filterField().dispatchEvent(new Event('input', { bubbles: true }));
+ });
+ }
+
+ it('A4: offers the suggestions first, then every operation alphabetically, behind a filter field', async () => {
+ await render(fixture(), { entries, suggestedEntries: [1, 22] });
+ expect(filterField().placeholder).toBe('Filter operations…');
+ expect(filterField().compareDocumentPosition(select()) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+ expect([...select().querySelectorAll('optgroup')].map(item => item.label)).toEqual(['Suggested', 'All operations · 4']);
+ expect(options(0)).toEqual(['operation1 · src/part1.ts', `handle · ${LOADDATA}`]);
+ expect(options(1)).toEqual(['as_sql · django/db/models/fields/json.py', `handle · ${LOADDATA}`,
+ 'handle · django/core/management/commands/makemigrations.py', 'operation1 · src/part1.ts']);
+ expect(select().value).toBe('1');
+ expect(select().selectedOptions[0]?.textContent).toBe('operation1 · src/part1.ts');
+ });
+
+ it('A4: narrows the list to what the filter names, keeps the chosen start, and starts the operation picked there', async () => {
+ const props = await render(fixture(), { entries, suggestedEntries: [1, 21] });
+ await type('loaddata');
+ expect(group(1).label).toBe('Matching operations · 1 of 4');
+ expect(options(1)).toEqual([`handle · ${LOADDATA}`, 'operation1 · src/part1.ts']);
+ expect(options(0)).toEqual(['operation1 · src/part1.ts']);
+ expect(select().value).toBe('1');
+ await act(async () => { select().value = '22'; select().dispatchEvent(new Event('change', { bubbles: true })); });
+ expect(props.onRequest).toHaveBeenLastCalledWith(expect.objectContaining({ id: 22, file_path: LOADDATA }), undefined, {});
+ await type('no such operation');
+ expect(options(1)).toEqual(['operation1 · src/part1.ts', 'No operation matches "no such operation"']);
+ expect(group(1).querySelector('option:last-child')?.hasAttribute('disabled')).toBe(true);
+ });
+});
diff --git a/graph-ui/src/architecture/BehaviorJourney.tsx b/graph-ui/src/architecture/BehaviorJourney.tsx
index ae02f71d8..dba8a15dc 100644
--- a/graph-ui/src/architecture/BehaviorJourney.tsx
+++ b/graph-ui/src/architecture/BehaviorJourney.tsx
@@ -8,8 +8,11 @@ import type { SystemProjection, SystemSymbol } from './system-architecture-sourc
import BehaviorSourceEvidence, { type BehaviorSourceSnapshot } from './BehaviorSourceEvidence';
import { useSelectionEvidence, type SelectionEvidenceListener } from '../galaxy/selection-evidence';
import { RefreshControl, type RefreshFeedback } from './refresh-feedback';
+import { operationChoices } from './operation-choices';
import './behavior-journey.css';
+const startText = text.behaviorStart;
+
const Scene = lazy(() => import('./SystemArchitectureScene'));
export interface BehaviorJourneyProps {
project: string; generation?: string; data?: SystemProjection; entries: SystemSymbol[];
@@ -31,6 +34,8 @@ export interface BehaviorJourneyProps {
onRefresh: () => void; onSelectSymbol: (symbol: SystemSymbol) => void;
/** What the last Refresh did, shown beside its button (hand test 2026-10-04, A3). */
refresh?: RefreshFeedback;
+ /** The automatic start and the ranked suggestions, in their order, offered first in "Start" (hand test 2026-10-04, A4). */
+ suggestedEntries?: number[];
onNavigate: (path: string, line?: number, name?: string) => void;
}
@@ -56,7 +61,7 @@ export function journeyPage(scene: SystemSceneModel, step: number, choices = fal
}
export default function BehaviorJourney({ project, generation, data, entries, targets, entryId, targetId, active, pending, error, filter,
- onRequest, onRefresh, refresh, onSelectSymbol, onNavigate, onClearSelection, onSelectionEvidence, from, place: liftedPlace, onPlace, onShownStart }: BehaviorJourneyProps) {
+ onRequest, onRefresh, refresh, suggestedEntries, onSelectSymbol, onNavigate, onClearSelection, onSelectionEvidence, from, place: liftedPlace, onPlace, onShownStart }: BehaviorJourneyProps) {
const [place, changePlace] = useLiftedPlace<JourneyPlace>(liftedPlace, onPlace, () => ({}));
const { path: pathIndex = 0, step = 0, page: branchPage = 0, planar = false } = place;
const [overview, setOverview] = useState(false);
@@ -97,7 +102,10 @@ export default function BehaviorJourney({ project, generation, data, entries, ta
const targetOptions = [...new Map([...targets, ...(journey?.choices ?? []).map(item => ({ ...item, distance: item.distance ?? 1 }))]
.filter(item => item.id !== (entryId ?? journey?.entry?.id)).map(item => [item.id, item])).values()];
const entry = journey?.entry ?? entries.find(item => item.id === entryId);
- const availableEntries = entry && !entries.some(item => item.id === entry.id) ? [entry, ...entries] : entries;
+ const availableEntries = useMemo(() => entry && !entries.some(item => item.id === entry.id) ? [entry, ...entries] : entries, [entry, entries]);
+ const [startQuery, setStartQuery] = useState('');
+ const startChoices = useMemo(() => operationChoices(availableEntries, { suggested: suggestedEntries, query: startQuery, keep: entry?.id }),
+ [availableEntries, suggestedEntries, startQuery, entry?.id]);
const reportShown = useRef(onShownStart);
reportShown.current = onShownStart;
const shownStart = entryId === undefined && !pending ? entry?.name : undefined;
@@ -165,10 +173,20 @@ export default function BehaviorJourney({ project, generation, data, entries, ta
<p>{path ? 'Follow one recorded call chain across the parts it touches.' : 'Choose a starting operation. Explore its calls, or follow a path to a destination.'}</p></div>
<RefreshControl labels={text.refreshFeedback.behavior} feedback={refresh} onRefresh={onRefresh} /></header>
<div className="behavior-requests">
- {/* The field names the operation the journey shows, also when the projection chose it. */}
- <label>Start <select aria-label="Behavior entry point" value={entry?.id ?? ''} onChange={event => request(availableEntries.find(item => item.id === Number(event.target.value)))}>
- <option value="">Choose an operation…</option>{availableEntries.map(item => <option key={item.id} value={item.id}>{item.name} · {item.file_path ?? item.qualified_name}</option>)}
- </select></label>
+ {/*
+ * The field names the operation the journey shows, also when the projection chose it. Suggestions come
+ * first, then every operation alphabetically; the filter before it narrows both (hand test 2026-10-04, A4).
+ */}
+ <label className="behavior-start">{startText.label}
+ <input type="search" aria-label={startText.filter} placeholder={startText.filterPlaceholder} value={startQuery} onChange={event => setStartQuery(event.target.value)} />
+ <select aria-label={startText.field} value={entry?.id ?? ''} onChange={event => request(availableEntries.find(item => item.id === Number(event.target.value)))}>
+ <option value="">{startText.choose}</option>
+ {startChoices.suggested.length > 0 && <optgroup label={startText.suggested}>{startChoices.suggested.map(item => <option key={item.id} value={item.id}>{item.label}</option>)}</optgroup>}
+ <optgroup label={startQuery.trim() ? startText.matching(startChoices.matching, startChoices.total) : startText.all(startChoices.total)}>
+ {startChoices.all.map(item => <option key={item.id} value={item.id}>{item.label}</option>)}
+ {startQuery.trim() && !startChoices.matching && <option disabled value="-1">{startText.none(startQuery.trim())}</option>}
+ </optgroup>
+ </select></label>
<label>Reach <select aria-label="Behavior destination" value={targetId ?? ''} disabled={!entry || pending} onChange={event => request(entry, event.target.value ? Number(event.target.value) : undefined, from)}>
<option value="">Explore immediate calls</option>{targetOptions.map(item => <option key={item.id} value={item.id}>{item.name} · {item.file_path ?? ''}</option>)}
</select></label>
diff --git a/graph-ui/src/architecture/SystemArchitecture.test.tsx b/graph-ui/src/architecture/SystemArchitecture.test.tsx
index c5b6dcbc8..a19f79dc8 100644
--- a/graph-ui/src/architecture/SystemArchitecture.test.tsx
+++ b/graph-ui/src/architecture/SystemArchitecture.test.tsx
@@ -561,8 +561,10 @@ describe('system architecture workspace', () => {
expect(flowsLoader).toHaveBeenCalledExactlyOnceWith('sample');
expect(loader.mock.calls.at(-1)?.[0]).toEqual({ project: 'sample', entryNodeId: 36163, expectedGeneration: 'g1', includeBehaviorEvidence: true });
const start = container.querySelector<HTMLSelectElement>('[aria-label="Behavior entry point"]')!;
- expect([...start.options].map(option => option.textContent)).toEqual(['Choose an operation…', 'run_tests · tests/runtests.py',
- 'handle · django/core/management/commands/runserver.py']);
+ // Alphabetical (hand test 2026-10-04, A4); with every operation suggested a Suggested group would only repeat the list.
+ expect([...start.options].map(option => option.textContent)).toEqual(['Choose an operation…',
+ 'handle · django/core/management/commands/runserver.py', 'run_tests · tests/runtests.py']);
+ expect(start.querySelectorAll('optgroup')).toHaveLength(1);
expect(start.value).toBe('36163');
const state = container.querySelector('.behavior-loading[role="status"]')!;
expect(state.textContent).toContain('The analysis returned no call evidence.');
@@ -570,7 +572,9 @@ describe('system architecture workspace', () => {
expect(state.textContent).toContain('Optional behavior evidence was omitted entirely');
await choose('Behavior entry point', '9');
expect(loader.mock.calls.at(-1)?.[0].entryNodeId).toBe(9);
- expect([...start.options].map(option => option.value)).toEqual(['', '9', '36163']);
+ // The chosen start keeps its place in the alphabetical list.
+ expect([...start.options].map(option => option.value)).toEqual(['', '36163', '9']);
+ expect(start.value).toBe('9');
});
it('does not ask for flows once the projection classifies enough entry points', async () => {
const flowsLoader = vi.fn<FlowsLoader>().mockResolvedValue([]);
@@ -586,8 +590,46 @@ describe('system architecture workspace', () => {
await render(vi.fn<SystemArchitectureLoader>().mockResolvedValue(response()), { view: 'behavior', flowsLoader });
expect(flowsLoader).toHaveBeenCalledExactlyOnceWith('sample');
const start = container.querySelector<HTMLSelectElement>('[aria-label="Behavior entry point"]')!;
- // The two classified entry points come first; the flow that repeats one of them is not listed twice.
- expect([...start.options].map(option => option.value)).toEqual(['', '1', '2', '36163']);
+ // Every operation alphabetically (hand test 2026-10-04, A4), the flow that repeats a classified entry point once.
+ // The journey's start and the two ranked flows would suggest all three, so no Suggested group repeats them.
+ expect([...start.querySelectorAll('optgroup')].map(group => [group.label, [...group.querySelectorAll('option')].map(option => option.value)]))
+ .toEqual([['All operations · 3', ['36163', '2', '1']]]);
+ });
+ it('A4: suggests the automatic start and the top ranked flows, and names look-alike flow starts by their class', async () => {
+ const MODELS = 'django/db/migrations/operations/models.py';
+ const flow = (id: number, name: string, filePath: string) => ({ id, label: name, entry: { id, name, filePath }, terminal: { id: 1, name: 'x' }, steps: 3 });
+ const flowsLoader = vi.fn<FlowsLoader>().mockResolvedValue([flow(41, 'database_backwards', MODELS), flow(42, 'database_backwards', MODELS),
+ flow(43, 'handle', 'django/core/management/commands/loaddata.py'), flow(44, 'b4', 'b.py'), flow(45, 'b5', 'b.py'), flow(46, 'b6', 'b.py')]);
+ const operationNames = vi.fn(async (_project: string, entries: SystemSymbol[]) => entries.map(entry => entry.id === 41
+ ? { ...entry, qualified_name: 'p.ops.models.CreateModel.database_backwards' } : entry.id === 42 ? { ...entry, qualified_name: 'p.ops.models.DeleteModel.database_backwards' } : entry));
+ const data = overviewFixture();
+ data.entrypoints = [{ ...data.entrypoints[0], name: 'main' }, data.entrypoints[1]];
+ await render(vi.fn<SystemArchitectureLoader>().mockResolvedValue(response(data)), { view: 'behavior', flowsLoader, operationNames });
+ expect(operationNames).toHaveBeenCalledOnce();
+ expect(operationNames.mock.calls[0]?.[1].map(entry => entry.id)).toEqual([41, 42, 43, 44, 45, 46]);
+ const start = container.querySelector<HTMLSelectElement>('[aria-label="Behavior entry point"]')!;
+ const suggested = [...start.querySelectorAll('optgroup')[0]!.querySelectorAll('option')].map(option => option.textContent);
+ // The automatic start, then the first five ranked flows in their order.
+ expect(suggested).toEqual(['main · src/api.ts', `database_backwards (CreateModel) · ${MODELS}`, `database_backwards (DeleteModel) · ${MODELS}`,
+ 'handle · django/core/management/commands/loaddata.py', 'b4 · b.py', 'b5 · b.py']);
+ expect(start.selectedOptions[0]?.textContent).toBe('main · src/api.ts');
+ });
+ it('A4: suggests the start the projection chose itself, and keeps suggesting it after another start is picked', async () => {
+ // django-demo: "main · …/manage.py-tpl" is no conventional entry for the page, the projection picks it on its own.
+ const flow = (id: number, name: string, filePath: string) => ({ id, label: name, entry: { id, name, filePath }, terminal: { id: 1, name: 'x' }, steps: 3 });
+ const flowsLoader = vi.fn<FlowsLoader>().mockResolvedValue([flow(43, 'handle', 'loaddata.py'), flow(44, 'b4', 'b.py')]);
+ const data = overviewFixture();
+ data.entrypoints = [{ ...data.entrypoints[0], name: 'main', file_path: 'conf/manage.py-tpl' }, data.entrypoints[1]];
+ // No operation requested: the server names none (0), and the journey starts at the first classified entry point.
+ data.behavior = { ...data.behavior!, source_id: 0 };
+ await render(vi.fn<SystemArchitectureLoader>().mockResolvedValue(response(data)), { view: 'behavior', flowsLoader });
+ const start = container.querySelector<HTMLSelectElement>('[aria-label="Behavior entry point"]')!;
+ const suggested = () => [...start.querySelectorAll('optgroup')[0]!.querySelectorAll('option')].map(option => option.value);
+ expect(start.value).toBe('1');
+ expect(suggested()).toEqual(['1', '43', '44']);
+ await choose('Behavior entry point', '43');
+ expect(start.value).toBe('43');
+ expect(suggested()).toEqual(['1', '43', '44']);
});
it('shows failures without retrying continuously', async () => {
vi.useFakeTimers(); const loader = vi.fn<SystemArchitectureLoader>().mockResolvedValue({ status: 'failed', generation: 'g1', error: 'Analysis budget exceeded.' });
diff --git a/graph-ui/src/architecture/SystemArchitecture.tsx b/graph-ui/src/architecture/SystemArchitecture.tsx
index 0af327d75..c08b4fdb9 100644
--- a/graph-ui/src/architecture/SystemArchitecture.tsx
+++ b/graph-ui/src/architecture/SystemArchitecture.tsx
@@ -8,9 +8,12 @@ import { connectionLoad } from '../graph/connection-load';
import { AtlasApi } from '../app/atlas-api';
import type { FlowSummary } from '../traces/trace-schemas';
import BehaviorJourney from './BehaviorJourney';
+import { defaultJourneyStart } from './behavior-journey-model';
import type { BehaviorPlace, JourneyPlace, PlaceChange, SystemPlace } from './architecture-history';
import { useLiftedPlace, useOnIdentityChange } from './lifted-place';
import { RefreshControl, useRefreshFeedback } from './refresh-feedback';
+import { nameOperations } from './operation-choices';
+import { RpcIntelligenceClient } from '../provider/rpc-client';
import './system-architecture.css';
const Scene = lazy(() => import('./SystemArchitectureScene'));
@@ -21,6 +24,8 @@ export interface SystemArchitectureProps {
onNavigate: (path: string, line?: number, name?: string) => void;
loader?: SystemArchitectureLoader;
flowsLoader?: FlowsLoader;
+ /** Fills in the qualified names of look-alike flow starts, so "Start" can tell them apart (hand test 2026-10-04, A4). */
+ operationNames?: OperationNamer;
/** Focus, expanded groups, the Behavior start and position, and both cameras, lifted to the workspace for Back and Forward (K27). */
place?: SystemPlace;
onPlace?: PlaceChange<SystemPlace>;
@@ -28,8 +33,12 @@ export interface SystemArchitectureProps {
/** Ranked call-graph flows (route handlers, call-graph roots) from /api/flows. */
export type FlowsLoader = (project: string) => Promise<FlowSummary[]>;
const loadFlows: FlowsLoader = project => new AtlasApi().flows(project);
+export type OperationNamer = (project: string, entries: SystemSymbol[]) => Promise<SystemSymbol[]>;
+const nameFlowStarts: OperationNamer = (project, entries) => nameOperations(project, entries, new RpcIntelligenceClient());
/** Below this many classified entry points the Behavior start list also offers ranked flows. */
const FEW_ENTRY_POINTS = 8;
+/** How many of the ranked flows "Start" suggests after the automatic start. */
+const RANKED_SUGGESTIONS = 5;
/** Starting operations from flows, once each. The projection supplies qualified name and component on request. */
export function flowEntries(flows: FlowSummary[]): SystemSymbol[] {
@@ -71,7 +80,7 @@ const connectionAllowed = (type: string, view: ConnectionView) => view === 'all'
|| (view === 'calls' ? ['CALLS', 'IMPORTS', 'HTTP_CALLS', 'ASYNC_CALLS'] : ['INHERITS', 'IMPLEMENTS']).includes(type);
/** Poll only while this view is active. A new request key hides stale results before its effect runs. */
-export default function SystemArchitecture({ project, generation, view, filter, active, graph, onSelect, onClearSelection, onSelectionEvidence, onNavigate, loader = loadSystemArchitecture, flowsLoader = loadFlows, place: liftedPlace, onPlace }: SystemArchitectureProps) {
+export default function SystemArchitecture({ project, generation, view, filter, active, graph, onSelect, onClearSelection, onSelectionEvidence, onNavigate, loader = loadSystemArchitecture, flowsLoader = loadFlows, operationNames = nameFlowStarts, place: liftedPlace, onPlace }: SystemArchitectureProps) {
const [place, changePlace] = useLiftedPlace<SystemPlace>(liftedPlace, onPlace, () => ({ expanded: [] }));
const entryChoice = place.behavior;
/** A start the page picks itself (the suggestion, a reset) completes the current step instead of adding one. */
@@ -171,9 +180,11 @@ export default function SystemArchitecture({ project, generation, view, filter,
useEffect(() => {
if (!needsFlows || (flows?.project === project && flows.generation === generation)) return;
let live = true;
- void flowsLoader(project).then(flowEntries, () => []).then(entries => { if (live) setFlows({ project, generation, entries }); });
+ // Look-alike flow starts get their qualified names first, so the field never relabels them later (A4).
+ void flowsLoader(project).then(flowEntries, () => []).then(entries => operationNames(project, entries).catch(() => entries))
+ .then(entries => { if (live) setFlows({ project, generation, entries }); });
return () => { live = false; };
- }, [needsFlows, flows, project, generation, flowsLoader]);
+ }, [needsFlows, flows, project, generation, flowsLoader, operationNames]);
const flowStarts = useMemo(() => flows?.project === project && flows.generation === generation ? flows.entries : [], [flows, project, generation]);
const entries = useMemo(() => {
if (!fewEntries || !flowStarts.length) return chosenEntries;
@@ -181,11 +192,24 @@ export default function SystemArchitecture({ project, generation, view, filter,
for (const item of flowStarts) if (!merged.has(item.id)) merged.set(item.id, item);
return [...merged.values()];
}, [fewEntries, flowStarts, chosenEntries]);
+ const automaticStart = useMemo(() => data ? data.entrypoints.length ? suggestedBehaviorEntry(data.entrypoints) : suggestedBehaviorEntry(flowStarts, true) : undefined, [data, flowStarts]);
useEffect(() => {
if (view !== 'behavior' || !data || (entryChoice?.project === project && entryChoice.generation === generation)) return;
- const suggested = data.entrypoints.length ? suggestedBehaviorEntry(data.entrypoints) : suggestedBehaviorEntry(flowStarts, true);
- if (suggested) setEntryChoice({ project, generation, expectedGeneration: current?.response?.generation ?? snapshot?.analysisGeneration, id: suggested.id, name: suggested.name }, true);
- }, [view, data, project, generation, entryChoice, current?.response?.generation, snapshot?.analysisGeneration, flowStarts]);
+ if (automaticStart) setEntryChoice({ project, generation, expectedGeneration: current?.response?.generation ?? snapshot?.analysisGeneration, id: automaticStart.id, name: automaticStart.name }, true);
+ }, [view, data, project, generation, entryChoice, current?.response?.generation, snapshot?.analysisGeneration, automaticStart]);
+ /*
+ * "Start" offers the automatic start first, then the best ranked flows in the server's order (hand test
+ * 2026-10-04, A4). Without a conventional entry the journey starts where the projection points
+ * (django-demo: "main · …/manage.py-tpl"); that start stays a suggestion after another one is chosen.
+ */
+ const [projectionStart, setProjectionStart] = useState<{ project: string; generation?: string; id: number }>();
+ const pickedByProjection = requestedEntry === undefined && view === 'behavior' && queryData ? defaultJourneyStart(queryData) : undefined;
+ useEffect(() => {
+ if (pickedByProjection !== undefined) setProjectionStart({ project, generation, id: pickedByProjection });
+ }, [pickedByProjection, project, generation]);
+ const shownByProjection = projectionStart?.project === project && projectionStart.generation === generation ? projectionStart.id : undefined;
+ const suggestedStarts = useMemo(() => [...new Set([...automaticStart ? [automaticStart.id] : shownByProjection !== undefined ? [shownByProjection] : [],
+ ...flowStarts.slice(0, RANKED_SUGGESTIONS).map(item => item.id)])], [automaticStart, shownByProjection, flowStarts]);
const returnedPaths = useMemo(() => {
const valid = queryData?.paths.filter(path => isContiguousPath(path)) ?? [];
if (queryData?.behavior && requestedTarget === undefined) return [];
@@ -322,7 +346,7 @@ export default function SystemArchitecture({ project, generation, view, filter,
}, automatic);
const behaviorPage = view === 'behavior' ? <BehaviorJourney project={project} generation={projectionGeneration} data={queryData}
entries={entries} targets={targets} entryId={requestedEntry} targetId={requestedTarget} active={active} pending={queryPending}
- error={error} filter={filter} onRefresh={refreshAnalysis} refresh={refresh.feedback} onNavigate={onNavigate} onSelectSymbol={selectSymbol} onClearSelection={onClearSelection} onSelectionEvidence={onSelectionEvidence}
+ error={error} filter={filter} onRefresh={refreshAnalysis} refresh={refresh.feedback} suggestedEntries={suggestedStarts} onNavigate={onNavigate} onSelectSymbol={selectSymbol} onClearSelection={onClearSelection} onSelectionEvidence={onSelectionEvidence}
from={requestedEntry !== undefined ? entryChoice?.from : undefined} place={journeyPlace} onPlace={changeJourney}
onShownStart={name => { if (name !== place.shown) changePlace({ shown: name }, true); }}
onRequest={(entry, targetId, detail) => {
diff --git a/graph-ui/src/architecture/behavior-journey-model.ts b/graph-ui/src/architecture/behavior-journey-model.ts
index b469f67a9..81e8c5b38 100644
--- a/graph-ui/src/architecture/behavior-journey-model.ts
+++ b/graph-ui/src/architecture/behavior-journey-model.ts
@@ -106,11 +106,18 @@ function corridorPath(data: SystemProjection, source: number, target: number, hi
return { entrypoint_id: source, nodes: nodes.reverse(), edges: edges.reverse() };
}
+/**
+ * The operation a journey starts from when none was requested: the server's pick, else the first classified entry
+ * point, else the first connected path. The server reports source_id 0 when no operation was requested; node IDs
+ * start at 1.
+ */
+export function defaultJourneyStart(data: SystemProjection): number | undefined {
+ return (data.behavior?.source_id || undefined) ?? data.entrypoints[0]?.id ?? data.paths.find(validPath)?.entrypoint_id;
+}
+
/** A focused static journey: positions describe hops, never catalog distance or runtime order. */
export function behaviorJourney(data: SystemProjection, options: BehaviorJourneyOptions = {}): BehaviorJourney {
- // The server reports source_id 0 when no operation was requested; node IDs start at 1.
- const entryId = options.entryId ?? (data.behavior?.source_id || undefined) ?? data.entrypoints[0]?.id
- ?? data.paths.find(validPath)?.entrypoint_id;
+ const entryId = options.entryId ?? defaultJourneyStart(data);
const scopedBehavior = data.behavior?.source_id === entryId ? data.behavior : undefined;
const dependencies = [...data.dependencies, ...(data.overview?.connections ?? [])];
const symbols = new Map<number, SystemSymbol>();
diff --git a/graph-ui/src/architecture/behavior-journey.css b/graph-ui/src/architecture/behavior-journey.css
index 6ed94e177..dca5aedc5 100644
--- a/graph-ui/src/architecture/behavior-journey.css
+++ b/graph-ui/src/architecture/behavior-journey.css
@@ -10,6 +10,10 @@
.behavior-requests label { display: flex; align-items: center; gap: 10px; font-size: 11px; color: var(--atlas-dim); flex: 1 1 270px; min-width: 0; }
.behavior-requests select { min-width: 0; width: 100%; max-width: 100%; }
.behavior-requests input { flex: 1 1 150px; min-width: 120px; background: transparent; color: var(--atlas-fg); border: 1px solid var(--journey-line); border-radius: 5px; padding: 6px 9px; font: inherit; font-size: 11px; }
+/* Hand test 2026-10-04 (A4): "Start" holds the filter and the field; it takes the larger share of the row. */
+.behavior-requests .behavior-start { flex: 2 1 460px; }
+.behavior-requests .behavior-start input { flex: 0 1 190px; }
+.behavior-requests .behavior-start select { flex: 1 1 240px; width: auto; }
.behavior-navigation { display: flex; align-items: center; flex-wrap: wrap; gap: 9px; margin: 12px 0; font-size: 11px; color: var(--atlas-dim); }
.behavior-navigation > span:first-of-type { margin-left: 4px; }
.behavior-static-badge { margin-left: auto; border: 1px solid var(--journey-line); border-radius: 20px; padding: 4px 9px; font-size: 10px; }
diff --git a/graph-ui/src/architecture/operation-choices.test.ts b/graph-ui/src/architecture/operation-choices.test.ts
new file mode 100644
index 000000000..dca192edc
--- /dev/null
+++ b/graph-ui/src/architecture/operation-choices.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from 'vitest';
+import { nameOperations, operationChoices, operationLabels } from './operation-choices';
+import type { SystemSymbol } from './system-architecture-source';
+
+/*
+ * Hand test 2026-10-04 (A4): the Behavior "Start" list of django-demo held 62 operations in the order the
+ * server returned them, with look-alikes ("database_backwards · django/db/migrations/operations/models.py" six
+ * times), and "handle · …/loaddata.py" could not be found.
+ */
+const operation = (id: number, name: string, file_path: string, more: Partial<SystemSymbol> = {}): SystemSymbol =>
+ ({ id, name, qualified_name: '', label: '', file_path, component_id: '', ...more });
+const MODELS = 'django/db/migrations/operations/models.py';
+const scouted = [
+ operation(1, 'main', 'django/conf/project_template/manage.py-tpl', { qualified_name: 'django-demo.django.conf.project_template.manage.main', start_line: 7 }),
+ operation(2, 'delete_selected', 'django/contrib/admin/actions.py'),
+ operation(3, 'handle', 'django/core/management/commands/makemigrations.py'),
+ operation(4, 'handle', 'django/core/management/commands/loaddata.py'),
+ operation(5, 'handle', 'django/core/management/commands/migrate.py'),
+ operation(6, 'database_backwards', MODELS),
+ operation(7, 'database_backwards', MODELS),
+ operation(8, 'clean', 'django/forms/models.py'),
+ operation(9, 'clean', 'django/forms/models.py'),
+ operation(10, 'as_sql', 'django/db/models/fields/json.py'),
+];
+const labels = (list: { label: string }[]) => list.map(item => item.label);
+
+describe('Behavior start choices (A4)', () => {
+ it('lists every operation alphabetically by name, then by path', () => {
+ const { all, total } = operationChoices(scouted, {});
+ expect(total).toBe(10);
+ expect(all.map(item => item.id)).toEqual([10, 8, 9, 6, 7, 2, 4, 3, 5, 1]);
+ expect(labels(all).slice(5, 9)).toEqual(['delete_selected · django/contrib/admin/actions.py', 'handle · django/core/management/commands/loaddata.py',
+ 'handle · django/core/management/commands/makemigrations.py', 'handle · django/core/management/commands/migrate.py']);
+ });
+
+ it('puts the automatic start and the ranked suggestions first, in their order, and keeps them in the full list', () => {
+ const { suggested, all } = operationChoices(scouted, { suggested: [1, 3, 4, 99] });
+ expect(labels(suggested)).toEqual(['main · django/conf/project_template/manage.py-tpl', 'handle · django/core/management/commands/makemigrations.py',
+ 'handle · django/core/management/commands/loaddata.py']);
+ expect(all).toHaveLength(10);
+ });
+
+ it('tells look-alikes apart by their class, by their line when the class is the same, and by position otherwise', () => {
+ const named = scouted.map(item => item.id === 6 ? { ...item, qualified_name: `django-demo.django.db.migrations.operations.models.CreateModel.database_backwards`, start_line: 110 }
+ : item.id === 7 ? { ...item, qualified_name: `django-demo.django.db.migrations.operations.models.DeleteModel.database_backwards`, start_line: 444 }
+ : item.id === 8 ? { ...item, qualified_name: 'django-demo.django.forms.models.BaseModelForm.clean', start_line: 437 }
+ : item.id === 9 ? { ...item, qualified_name: 'django-demo.django.forms.models.BaseModelForm.clean', start_line: 800 } : item);
+ const text = operationLabels(named);
+ // The name stays first, so the list still reads alphabetically.
+ expect(text.get(6)).toBe(`database_backwards (CreateModel) · ${MODELS}`);
+ expect(text.get(7)).toBe(`database_backwards (DeleteModel) · ${MODELS}`);
+ expect(text.get(8)).toBe('clean · django/forms/models.py:437');
+ expect(text.get(9)).toBe('clean · django/forms/models.py:800');
+ // Unique names keep their plain label.
+ expect(text.get(4)).toBe('handle · django/core/management/commands/loaddata.py');
+ // Without a qualified name or line the position still tells them apart.
+ const bare = operationLabels(scouted);
+ expect([bare.get(6), bare.get(7)]).toEqual([`database_backwards · ${MODELS} (1 of 2)`, `database_backwards · ${MODELS} (2 of 2)`]);
+ expect(new Set(bare.values()).size).toBe(bare.size);
+ // Sorted by name first, the class does not tear the look-alikes apart.
+ expect(operationChoices(named, {}).all.map(item => item.id).slice(3, 5)).toEqual([6, 7]);
+ });
+
+ it('narrows to the operations that match every word of the filter, and keeps the chosen one', () => {
+ expect(labels(operationChoices(scouted, { query: 'loaddata' }).all)).toEqual(['handle · django/core/management/commands/loaddata.py']);
+ expect(operationChoices(scouted, { query: 'handle MIGRATE' }).all.map(item => item.id)).toEqual([5]);
+ const kept = operationChoices(scouted, { query: 'loaddata', keep: 1, suggested: [1, 3] });
+ expect(kept.all.map(item => item.id)).toEqual([4, 1]);
+ expect(kept.suggested.map(item => item.id)).toEqual([1]);
+ expect(kept.matching).toBe(1);
+ // A chosen start that matches counts as a match (measured in the browser: "0 of 61" after picking loaddata).
+ expect(operationChoices(scouted, { query: 'loaddata', keep: 4 }).matching).toBe(1);
+ expect(operationChoices(scouted, { query: 'nothing like this' }).all).toEqual([]);
+ });
+});
+
+describe('qualified names for look-alike flow starts (A4)', () => {
+ it('asks the index once for the look-alikes only and fills in their qualified name and line', async () => {
+ const queryRows = vi.fn(async () => [
+ { id: '6', qualified_name: 'django-demo.django.db.migrations.operations.models.CreateModel.database_backwards', start_line: '110' },
+ { id: '7', qualified_name: 'django-demo.django.db.migrations.operations.models.DeleteModel.database_backwards', start_line: '444' },
+ { id: '70', qualified_name: 'django-demo.django.db.migrations.operations.models.RenameModel.database_backwards', start_line: '538' },
+ { id: '8', qualified_name: 'django-demo.django.forms.models.BaseModelForm.clean', start_line: '437' },
+ ]);
+ const named = await nameOperations('django-demo', scouted, { queryRows });
+ expect(queryRows).toHaveBeenCalledOnce();
+ const [project, query] = queryRows.mock.calls[0] as unknown as [string, string];
+ expect(project).toBe('django-demo');
+ expect(query).toContain('n.name IN ["database_backwards", "clean"]');
+ expect(query).toContain(`n.file_path IN ["${MODELS}", "django/forms/models.py"]`);
+ expect(query).not.toContain('handle');
+ expect(named.find(item => item.id === 6)).toMatchObject({ qualified_name: 'django-demo.django.db.migrations.operations.models.CreateModel.database_backwards', start_line: 110 });
+ expect(named.find(item => item.id === 9)?.qualified_name).toBe('');
+ expect(named.find(item => item.id === 4)).toBe(scouted[3]);
+ });
+
+ it('needs no query without look-alikes, never puts quotes or backslashes into one, and keeps the list when it fails', async () => {
+ const queryRows = vi.fn(async () => { throw new Error('index busy'); });
+ expect(await nameOperations('p', scouted.slice(0, 5), { queryRows })).toEqual(scouted.slice(0, 5));
+ expect(queryRows).not.toHaveBeenCalled();
+ const odd = [operation(1, 'run"x', 'a.py'), operation(2, 'run"x', 'a.py')];
+ expect(await nameOperations('p', odd, { queryRows })).toEqual(odd);
+ expect(queryRows).not.toHaveBeenCalled();
+ expect(await nameOperations('p', scouted, { queryRows })).toEqual(scouted);
+ });
+});
diff --git a/graph-ui/src/architecture/operation-choices.ts b/graph-ui/src/architecture/operation-choices.ts
new file mode 100644
index 000000000..8aa146efe
--- /dev/null
+++ b/graph-ui/src/architecture/operation-choices.ts
@@ -0,0 +1,117 @@
+/**
+ * The operations the Behavior "Start" field offers (hand test 2026-10-04,
+ * A4). For django-demo that were 62 entries in the order the server sent
+ * them, with look-alikes ("database_backwards · …/models.py" six times), and
+ * "handle · …/loaddata.py" could not be found. Now:
+ *
+ * - the automatic start and the ranked suggestions come first, in a group
+ * of their own and in their order;
+ * - then every operation, alphabetically by name and then by path;
+ * - look-alikes carry their class ("database_backwards (CreateModel) · …",
+ * the name first so the list still reads alphabetically), their line when
+ * the class is the same too, and their position when the index names
+ * neither;
+ * - a filter keeps the operations whose name, class or path contain every
+ * word typed, and always the chosen one, so the field can still show it.
+ */
+import type { SystemSymbol } from './system-architecture-source';
+import { architectureText } from './strings';
+
+const text = architectureText.behaviorStart;
+
+export interface OperationChoice { id: number; label: string; symbol: SystemSymbol }
+export interface OperationChoices {
+ suggested: OperationChoice[];
+ all: OperationChoice[];
+ /** How many operations there are, and how many of them match the filter (the kept one only when it matches). */
+ total: number;
+ matching: number;
+}
+
+const place = (symbol: SystemSymbol) => symbol.file_path ?? symbol.qualified_name;
+const lookAlike = (symbol: SystemSymbol) => `${symbol.name}\u0000${place(symbol) ?? ''}`;
+
+/** The segment before the name in the qualified name: the class of a method, the module of a function. */
+export function operationQualifier(symbol: SystemSymbol): string | undefined {
+ const name = symbol.qualified_name;
+ if (!name || !name.endsWith(`.${symbol.name}`)) return undefined;
+ return name.slice(0, -symbol.name.length - 1).split('.').at(-1) || undefined;
+}
+
+const collator = new Intl.Collator('en', { sensitivity: 'base', numeric: true });
+function compare(a: SystemSymbol, b: SystemSymbol): number {
+ return collator.compare(a.name, b.name) || collator.compare(place(a) ?? '', place(b) ?? '')
+ || collator.compare(operationQualifier(a) ?? '', operationQualifier(b) ?? '') || (a.start_line ?? 0) - (b.start_line ?? 0) || a.id - b.id;
+}
+
+/** One label per operation, the same with or without a filter, so the field never renames what it shows. */
+export function operationLabels(entries: SystemSymbol[]): Map<number, string> {
+ const groups = new Map<string, SystemSymbol[]>();
+ for (const entry of entries) groups.set(lookAlike(entry), [...groups.get(lookAlike(entry)) ?? [], entry]);
+ const labels = new Map<number, string>();
+ for (const group of groups.values()) {
+ const ordered = [...group].sort((a, b) => a.id - b.id);
+ const qualifiers = ordered.map(operationQualifier);
+ const distinct = (values: unknown[]) => values.every(value => value !== undefined) && new Set(values).size === values.length;
+ const byQualifier = group.length > 1 && distinct(qualifiers);
+ const byLine = group.length > 1 && !byQualifier && distinct(ordered.map(item => item.start_line));
+ ordered.forEach((entry, index) => {
+ const where = place(entry) ?? '';
+ labels.set(entry.id, group.length === 1 ? text.option(entry.name, where)
+ : byQualifier ? text.option(text.qualified(qualifiers[index]!, entry.name), where)
+ : byLine ? text.option(entry.name, text.line(where, entry.start_line!))
+ : `${text.option(entry.name, where)}${text.ordinal(index + 1, group.length)}`);
+ });
+ }
+ return labels;
+}
+
+export function operationChoices(entries: SystemSymbol[], { suggested = [], query = '', keep }: { suggested?: number[]; query?: string; keep?: number }): OperationChoices {
+ const labels = operationLabels(entries);
+ const words = query.toLocaleLowerCase().split(/\s+/).filter(Boolean);
+ const matches = (entry: SystemSymbol) => words.every(word => `${labels.get(entry.id)} ${entry.qualified_name}`.toLocaleLowerCase().includes(word));
+ const choice = (symbol: SystemSymbol): OperationChoice => ({ id: symbol.id, label: labels.get(symbol.id)!, symbol });
+ const shown = (entry: SystemSymbol) => entry.id === keep || matches(entry);
+ const byId = new Map(entries.map(entry => [entry.id, entry]));
+ const offered = [...new Set(suggested)].filter(id => byId.has(id));
+ return {
+ // Suggestions that name every operation would only repeat the list.
+ suggested: offered.length >= entries.length ? [] : offered.flatMap(id => shown(byId.get(id)!) ? [choice(byId.get(id)!)] : []),
+ all: entries.filter(shown).sort(compare).map(choice),
+ total: entries.length,
+ matching: entries.filter(matches).length,
+ };
+}
+
+/** What `nameOperations` needs of the RPC client. */
+export interface OperationNameClient { queryRows: (project: string, query: string) => Promise<Record<string, string>[]> }
+
+/* Only plain identifiers and paths enter the query text; anything with a quote or a backslash stays unnamed. */
+const PLAIN = /^[\w$<>@.\/\- ]+$/;
+
+/**
+ * Ranked flow starts carry no qualified name or line (/api/flows names only
+ * the node, its file and its id). For the look-alikes among them the index is
+ * asked once, by name and file, and the answer is matched by node id. Without
+ * an answer the list stays as it was: the position still tells them apart.
+ */
+export async function nameOperations(project: string, entries: SystemSymbol[], client: OperationNameClient): Promise<SystemSymbol[]> {
+ const groups = new Map<string, SystemSymbol[]>();
+ for (const entry of entries) groups.set(lookAlike(entry), [...groups.get(lookAlike(entry)) ?? [], entry]);
+ const unnamed = [...groups.values()].filter(group => group.length > 1).flat()
+ .filter(entry => !entry.qualified_name && entry.file_path && PLAIN.test(entry.name) && PLAIN.test(entry.file_path));
+ if (!unnamed.length) return entries;
+ const list = (values: string[]) => `[${[...new Set(values)].map(value => `"${value}"`).join(', ')}]`;
+ const query = `MATCH (n) WHERE n.name IN ${list(unnamed.map(entry => entry.name))} AND n.file_path IN ${list(unnamed.map(entry => entry.file_path!))} `
+ + 'RETURN id(n) AS id, n.qualified_name AS qualified_name, n.start_line AS start_line LIMIT 1000';
+ let rows: Record<string, string>[];
+ try { rows = await client.queryRows(project, query); } catch { return entries; }
+ const found = new Map(rows.map(row => [Number(row.id), row]));
+ const wanted = new Set(unnamed.map(entry => entry.id));
+ return entries.map(entry => {
+ const row = wanted.has(entry.id) ? found.get(entry.id) : undefined;
+ if (!row?.qualified_name) return entry;
+ const line = Number(row.start_line);
+ return { ...entry, qualified_name: row.qualified_name, ...(Number.isSafeInteger(line) && line > 0 ? { start_line: line } : {}) };
+ });
+}
diff --git a/graph-ui/src/architecture/strings.ts b/graph-ui/src/architecture/strings.ts
index 8a7410a8c..22acdf335 100644
--- a/graph-ui/src/architecture/strings.ts
+++ b/graph-ui/src/architecture/strings.ts
@@ -100,6 +100,23 @@ export const architectureText = {
openedFile: 'Opened file',
scopeMeasure: (files: number, lines?: number) => `${files.toLocaleString()} files · ${lines === undefined ? 'unknown' : lines.toLocaleString()} indexed lines`,
openedScopeHint: 'Select a part or connection to inspect it. The location above leads back to the repository.',
+ /** Behavior "Start": suggestions first, then every operation alphabetically, with a filter (hand test 2026-10-04, A4). */
+ behaviorStart: {
+ label: 'Start',
+ field: 'Behavior entry point',
+ choose: 'Choose an operation…',
+ filter: 'Filter operations',
+ filterPlaceholder: 'Filter operations…',
+ suggested: 'Suggested',
+ all: (total: number) => `All operations · ${total.toLocaleString()}`,
+ matching: (shown: number, total: number) => `Matching operations · ${shown.toLocaleString()} of ${total.toLocaleString()}`,
+ none: (query: string) => `No operation matches "${query}"`,
+ option: (name: string, place: string) => `${name} · ${place}`,
+ /** The name stays first, so the list still reads alphabetically: "database_backwards (CreateModel)". */
+ qualified: (qualifier: string, name: string) => `${name} (${qualifier})`,
+ line: (place: string, line: number) => `${place}:${line}`,
+ ordinal: (index: number, count: number) => ` (${index} of ${count})`,
+ },
/** Each Refresh button says what it did (hand test 2026-10-04, A3): busy while it runs, then when, and whether anything changed. */
refreshFeedback: {
routes: { idle: 'Refresh connections', busy: 'Refreshing connections…', done: (time: string) => `Connections refreshed at ${time}` },