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
import { useEffect, useRef, useState } from 'react';
import type { RpcIntelligenceClient } from '../provider/rpc-client';
import type { CodeSnippetResult } from '../provider/rpc-schemas';
import type { GraphData } from '../galaxy/types';
import { COLUMNS, fileNodeForPath, moduleForFile } from '../provider/cypher';
import './source-evidence.css';
export interface SourceEvidenceTarget { filePath: string; line?: number; name?: string; kind?: 'callsite' | 'declaration' | 'file' }
const PAGE_LINES = 160;
/* Hand test K13: a disabled "Next lines" at the last page read like a fault. The page says where the file ends. */
const END_OF_FILE = ' · end of file';
const endOfFileTitle = (line: number) => `Line ${line} is the last line of this file.`;
const validLine = (value: number | undefined): value is number => value !== undefined && Number.isSafeInteger(value) && value > 0;
export function fileQualifiedName(graph: GraphData | undefined, path: string): string | undefined {
// File nodes may carry 0..0 and only return the first source fragment.
// Module nodes own the whole-file range used by the source paging API.
return graph?.nodes.find(node => node.file_path === path && node.label === 'Module' && node.qualified_name)?.qualified_name
?? graph?.nodes.find(node => node.file_path === path && node.label === 'File' && node.qualified_name)?.qualified_name;
}
/** Source stays next to its referring map/analysis. No external resources are loaded. */
export default function SourceEvidenceDrawer({ project, target, graph, client, onClose, onExplore }: {
project: string; target: SourceEvidenceTarget; graph?: GraphData;
client: Pick<RpcIntelligenceClient, 'getCodeSnippet' | 'queryRows'>; onClose: () => void;
onExplore: (target: SourceEvidenceTarget) => void;
}) {
const qualifiedName = fileQualifiedName(graph, target.filePath);
const requestedLine = validLine(target.line) ? target.line : undefined;
const initialStart = Math.max(1, (requestedLine ?? 1) - 8);
const targetKey = JSON.stringify([project, target.filePath, requestedLine, qualifiedName]);
const [pageWindow, setPageWindow] = useState<{ key: string; start: number }>();
const start = pageWindow?.key === targetKey ? pageWindow.start : initialStart;
const [refresh, setRefresh] = useState(0);
const readKey = JSON.stringify([targetKey, start, refresh]);
const activeKey = useRef(readKey); activeKey.current = readKey;
const [reading, setReading] = useState<{ key: string; source?: CodeSnippetResult; error?: string }>();
// A new target can render before its effect. Never relabel old file contents.
const current = reading?.key === readKey ? reading : undefined;
const [copiedKey, setCopiedKey] = useState('');
const [copyError, setCopyError] = useState<{ key: string; message: string }>();
const closeRef = useRef<HTMLButtonElement>(null);
const selectedRef = useRef<HTMLSpanElement>(null);
const sourceRef = useRef<HTMLPreElement>(null);
const restoreFocus = useRef(true);
useEffect(() => {
const previous = document.activeElement;
closeRef.current?.focus();
return () => {
if (restoreFocus.current && previous instanceof HTMLElement && previous.isConnected
&& !previous.closest('[hidden], [inert]')) previous.focus({ preventScroll: true });
};
}, []);
useEffect(() => {
let alive = true;
const fail = (error: unknown) => {
if (alive) setReading({ key: readKey, error: error instanceof Error ? error.message : String(error) });
};
if (!project || !target.filePath || /[\x00-\x1f\x7f]/.test(target.filePath)) {
fail('Select a project and a valid repository file to inspect source evidence.');
return;
}
void (async () => {
let resolvedName = qualifiedName;
if (!resolvedName) {
// Evidence can originate in Explore or a bounded impact result,
// before the user has ever loaded the architecture snapshot.
const modules = await client.queryRows(project, moduleForFile(target.filePath));
if (!alive) return;
resolvedName = modules[0]?.[COLUMNS.moduleForFile[0]] || undefined;
if (!resolvedName) {
const files = await client.queryRows(project, fileNodeForPath(target.filePath));
if (!alive) return;
resolvedName = files[0]?.[COLUMNS.fileNode[0]] || undefined;
}
}
if (!resolvedName) throw new Error('No indexed Module or File declaration was found for this project and path. Check index diagnostics or choose another source location.');
const source = await client.getCodeSnippet(project, resolvedName, { startLine: start, maxLines: PAGE_LINES });
if (!alive) return;
if (source.qualified_name && source.qualified_name !== resolvedName) throw new Error('The source reply identifies a different indexed file. Refresh the map before following this evidence.');
const returnedPath = source.file_path?.replace(/\\/g, '/');
if (returnedPath && returnedPath !== target.filePath && !returnedPath.endsWith(`/${target.filePath}`))
throw new Error('The source reply identifies a different file path.');
if (!validLine(source.start_line) || !validLine(source.end_line) || source.end_line < source.start_line)
throw new Error('The source reply has no usable line range. No source location can be verified.');
if (source.source_mode && source.source_mode !== 'full') throw new Error('The daemon returned an outline instead of source. Open Explore to inspect the available file information.');
if (source.source.trim() === '(source not available)') throw new Error('The daemon could not read the current local source.');
setReading({ key: readKey, source });
})().catch(fail);
return () => { alive = false; };
}, [project, qualifiedName, start, client, readKey]);
const source = current?.source;
const lines = source ? source.source.split('\n') : [];
// A complete Module range may include its empty EOF line. A clipped page
// instead ends in a separator after its last reported line. The explicit
// source range distinguishes these cases; never accept other count gaps.
const reportedLines = source && validLine(source.start_line) && validLine(source.end_line)
? source.end_line - source.start_line + 1 : undefined;
if (lines.at(-1) === '' && lines.length - 1 === reportedLines) lines.pop();
const firstLine = source?.start_line;
const lastLine = validLine(firstLine) ? firstLine + lines.length - 1 : undefined;
const rangeMatches = source && lastLine === source.end_line;
const more = source?.source_truncated === true || source?.source_clipped === true;
const next = source?.next_start_line;
const canNext = Boolean(more && validLine(next) && validLine(lastLine) && next === lastLine + 1 && rangeMatches);
const atEnd = Boolean(source && !more && rangeMatches && validLine(lastLine));
// The Module range counts the empty segment after the final line break; the file's last line is the one before it.
const endSegment = atEnd && lines.length > 1 && lines.at(-1) === '';
const lastFileLine = endSegment ? lastLine! - 1 : lastLine;
// Review of K13: range text, drawn lines and title all stop at that line, not at the empty segment after it.
const shownLines = endSegment ? lines.slice(0, -1) : lines;
const locationVisible = requestedLine !== undefined && validLine(firstLine) && validLine(lastLine)
&& requestedLine >= firstLine && requestedLine <= lastLine && rangeMatches;
useEffect(() => {
const panel = sourceRef.current, selected = selectedRef.current;
if (!panel) return;
panel.scrollTop = 0;
if (selected) {
// Scroll only this code pane; preserve the referring map's viewport.
panel.scrollTop = Math.max(0, selected.getBoundingClientRect().top - panel.getBoundingClientRect().top - panel.clientHeight / 2);
}
}, [source]);
const moveTo = (line: number) => setPageWindow({ key: targetKey, start: line });
const copy = async () => {
try {
await navigator.clipboard.writeText(`${target.filePath}:${requestedLine ?? firstLine ?? 1}`);
if (activeKey.current === readKey) { setCopiedKey(readKey); setCopyError(undefined); }
} catch {
if (activeKey.current === readKey) setCopyError({ key: readKey, message: 'Copy unavailable. Select the location above to copy it manually.' });
}
};
return <aside className="source-evidence-drawer" role="dialog" aria-modal="false" aria-label="Source evidence" onKeyDown={event => {
if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); onClose(); }
}}>
<header><div><span>Source evidence</span><h2>{target.name ?? target.filePath.split('/').at(-1)}</h2></div>
<button ref={closeRef} onClick={onClose} aria-label="Close source evidence">Close</button></header>
<p className="source-evidence-location">{target.filePath}{requestedLine ? `:${requestedLine}` : ''}</p>
<p className="source-evidence-note">{target.kind === 'callsite' ? 'Indexed call site' : target.kind === 'declaration' ? 'Indexed declaration' : 'Requested source location'}.
{' '}Current local source may have changed since indexing. The map stays open.</p>
<div className="source-evidence-actions"><button onClick={() => void copy()}>{copiedKey === readKey ? 'Copied location' : 'Copy location'}</button>
<button onClick={() => setRefresh(value => value + 1)}>Refresh source</button>
<button onClick={() => { restoreFocus.current = false; onExplore(target); }}>Open in Explore</button></div>
{copyError?.key === readKey && <p role="status">{copyError.message}</p>}
{current?.error ? <p role="alert">{current.error}</p> : !source ? <p role="status">Reading local source…</p> : <>
{!rangeMatches && <p role="alert">Source text does not match the reported line range. Line numbers and highlighting are unavailable.</p>}
{requestedLine && !locationVisible && rangeMatches && <p role="status" className="source-evidence-notice">Requested line {requestedLine} is outside this returned window.
{start === initialStart ? ' The index or requested source window may be stale.' : <button onClick={() => moveTo(initialStart)}>Return to requested location</button>}</p>}
<pre ref={sourceRef} tabIndex={0} aria-label="Source lines" className="source-evidence-lines"><code>{shownLines.map((line, index) => {
const number = (firstLine ?? 1) + index;
const selected = rangeMatches && number === requestedLine;
return <span key={number} data-selected={selected} ref={selected ? selectedRef : undefined}>
<span className="source-evidence-line-number" aria-hidden="true">{rangeMatches ? number : ''}</span>{line || ' '}<br /></span>;
})}</code></pre>
{lines.length === 0 && <p role="status">No source text was returned.</p>}
{more && !canNext && <p role="status">The source is truncated, but no valid next page was supplied. Refresh or open Explore to inspect the available source.</p>}
<nav aria-label="Source pages"><button disabled={!rangeMatches || !firstLine || firstLine <= 1} onClick={() => moveTo(Math.max(1, firstLine! - PAGE_LINES))}>Previous lines</button>
<span>{rangeMatches ? `Lines ${firstLine} to ${lastFileLine}` : 'Unverified line range'}{source.original_end_line ? ` · reported end ${source.original_end_line}` : ''}{atEnd ? END_OF_FILE : ''}</span>
<button disabled={!canNext} title={atEnd ? endOfFileTitle(lastFileLine!) : undefined} onClick={() => moveTo(next!)}>Next lines</button></nav>
</>}
</aside>;
}