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
/**
* The Architecture entry for Back and Forward (hand test K27): which place the
* workspace shows, without what it loaded for it.
*
* One stop is a meaningful exploration: in Overview the area or file, in
* Routes an explicitly opened route group, in System structure the focus,
* in Behavior the start, the destination, where a followed call began and where
* the journey stands. Each entry also keeps its subtab, perspective, filter,
* expanded groups and Plan or 3D setting so returning restores that context.
* Context changes update the current stop. It holds identities, names and small
* numbers only, never projections, scenes or
* cameras, so nothing grows with the session. The model behind it is the one
* Galaxy uses (src/graph/navigation-history.ts), which documents shared limits.
*/
import type { NavigationHistoryOptions } from '../graph/navigation-history';
import type { ArchitectureView } from './architecture-model';
import type { SystemSymbol } from './system-architecture-source';
import { architectureHistoryText as text, architectureText } from './strings';
export type RoutesPerspective = 'services' | 'endpoints';
/** Overview, Entry points, Hotspots and Endpoints draw the same map (SpatialArchitecture). */
export interface SpatialPlace { areaPath?: string; filePath?: string; hotspotArea?: string; planar: boolean }
/**
* Where a Behavior journey stands: the indexed path to a destination (`path`),
* the operation on that call chain (`step`) and the page of direct calls
* (`page`), all counted from 0. Another path is a step; walking the chain or
* paging is not (Previous and Next do that), but the entry keeps where it
* stood, so Back and Forward return there.
*/
export interface JourneyPosition { path?: number; step?: number; page?: number }
/**
* A Behavior start as SystemArchitecture requests it. The numeric identity
* belongs to one analysis snapshot, which `generation` and `expectedGeneration`
* guard; the names are for the tooltip. A new start begins at the top of its
* journey, because it carries no position.
*/
export interface BehaviorPlace {
project: string; generation?: string; expectedGeneration?: string;
id?: number; name?: string; targetId?: number; targetName?: string;
/** The start a followed call ("follow calls", double-click) began from; empty background returns there. */
from?: SystemSymbol;
position?: JourneyPosition;
}
export interface SystemPlace {
focus?: { id: string; label: string }; expanded: readonly string[]; behavior?: BehaviorPlace;
/** The start Behavior shows when none was requested (the server picks one, or the first entry point): for the tooltip only. */
shown?: string;
/** Plan or 3D. System structure and Behavior each keep their own camera, as they did before K27. */
structurePlanar?: boolean;
behaviorPlanar?: boolean;
}
/** What BehaviorJourney reads and reports: where it stands, and Plan or 3D. */
export interface JourneyPlace extends JourneyPosition { planar?: boolean }
export interface ArchitectureHistoryEntry {
view: ArchitectureView;
spatial: SpatialPlace;
routes: RoutesPerspective;
/** The Routes filter: typing updates context; explicitly opening a route group creates a stop. */
filter: string;
system: SystemPlace;
}
/** A part of the place handed to a view, and how it reports a change; `automatic` marks one the page made itself. */
export type PlaceChange<T> = (change: Partial<T>, automatic?: boolean) => void;
export function initialArchitecturePlace(view: ArchitectureView): ArchitectureHistoryEntry {
return { view: view === 'dependencies' ? 'overview' : view, spatial: { planar: false }, routes: 'services', filter: '', system: { expanded: [] } };
}
/** What the subtab of an entry shows, without Plan or 3D, expanded groups or the path to a destination. */
function location(entry: ArchitectureHistoryEntry): unknown[] {
const { spatial, system } = entry;
switch (entry.view) {
case 'overview': case 'dependencies': return [spatial.areaPath ?? null, spatial.filePath ?? null];
case 'hotspots': return [spatial.hotspotArea ?? null];
case 'routes': return [entry.routes, entry.filter];
case 'structure': return [system.focus?.id ?? null];
case 'behavior': return [system.behavior?.id ?? null, system.behavior?.targetId ?? null];
default: return [];
}
}
/**
* Whether the subtab of an entry shows Plan: the shared map (Overview, Entry
* points, Hotspots, Endpoints), System structure and Behavior each have a
* switch of their own; the Service map has none.
*/
function planar(entry: ArchitectureHistoryEntry): boolean {
switch (entry.view) {
case 'structure': return entry.system.structurePlanar ?? false;
case 'behavior': return entry.system.behaviorPlanar ?? false;
case 'routes': return entry.routes === 'endpoints' && entry.spatial.planar;
default: return entry.spatial.planar;
}
}
/** The indexed path a Behavior journey follows to its destination, counted from 0. */
const behaviorPath = (entry: ArchitectureHistoryEntry): number => (entry.view === 'behavior' ? entry.system.behavior?.position?.path ?? 0 : 0);
const viewOf = (entry: ArchitectureHistoryEntry): ArchitectureView => (entry.view === 'dependencies' ? 'overview' : entry.view);
export const architectureHistoryOptions: NavigationHistoryOptions<ArchitectureHistoryEntry> = {
// View, perspective and filter identify restored locations, but their controls replace the current entry.
key: (entry) => JSON.stringify([viewOf(entry), ...location(entry), behaviorPath(entry)]),
recentKey: (entry) => JSON.stringify([viewOf(entry), ...location(entry)]),
};
/** The subtab an entry stands on, as the tab names it. Entry points is a mode within Overview. */
export function architectureEntryName(entry: ArchitectureHistoryEntry): string {
return architectureText.views[viewOf(entry) === 'entryPoints' ? 'overview' : viewOf(entry)];
}
function details(entry: ArchitectureHistoryEntry): string[] {
const { spatial, system } = entry;
const parts: (string | undefined)[] = [];
switch (viewOf(entry)) {
case 'overview': parts.push(spatial.filePath ?? spatial.areaPath); break;
case 'entryPoints': parts.push(architectureText.views.entryPoints); break;
case 'hotspots': parts.push(spatial.hotspotArea); break;
case 'routes': parts.push(architectureText.routesPerspective[entry.routes], entry.filter.trim() || undefined); break;
case 'structure': parts.push(system.focus?.label, system.expanded.length ? text.groupsOpen(system.expanded.length) : undefined); break;
case 'behavior': {
const start = system.behavior?.id === undefined ? system.behavior?.name ?? system.shown : system.behavior.name;
const target = system.behavior?.targetId === undefined ? undefined : system.behavior.targetName;
parts.push(start && target ? text.reach(start, target) : start, system.behavior?.from ? text.followedFrom(system.behavior.from.name) : undefined,
behaviorPath(entry) > 0 ? text.path(behaviorPath(entry) + 1) : undefined);
break;
}
}
if (planar(entry)) parts.push(text.plan);
return parts.filter((part): part is string => Boolean(part));
}
/** What a place shows besides its subtab, for the line under the name in the Recent list. Empty at the top of a subtab. */
export function architectureEntryDetail(entry: ArchitectureHistoryEntry): string {
return details(entry).join(text.separator);
}
/** How an entry is named in a Back or Forward tooltip: "Overview · django". */
export function architectureEntryLabel(entry: ArchitectureHistoryEntry): string {
return [architectureEntryName(entry), ...details(entry)].join(text.separator);
}