codegraph-java 0.1.0

package/dist/ui-server/api/flow.d.ts

@@ -0,0 +1,226 @@
+/**
+ * `GET /api/flow` — the call path between two symbols, as cards.
+ *
+ * The Flow strip answers "how does A reach B" (design spec §3.5): one card per
+ * hop, each opened at the exact line that makes the next call, with the
+ * synthesized dynamic-dispatch hops drawn dashed and carrying the site they
+ * were wired at. This endpoint produces that path and the source windows for
+ * it; the geometry is a pure function in the viewer (`ui/src/lib/flow-model.ts`).
+ *
+ * **The path finder is not ours.** It is `resolveNamedSymbolFlow` in
+ * `src/graph/named-symbol-flow.ts` — literally the search `codegraph_explore`
+ * leads its answer with, extracted so both callers ride one implementation.
+ * A viewer that drew a different path from the one the MCP tool describes would
+ * be worse than no viewer: the two would be quoted against each other in a code
+ * review and one of them would be wrong.
+ *
+ * Three questions arrive here, and they are one question with different
+ * bindings:
+ *
+ * - `?from=&to=` — a directed question, from the search box's flow grammar.
+ *   Both ends pinned, shortest path wins.
+ * - `?symbols=a,b,c` — explore's own question, verbatim. Longest chain among
+ *   the named symbols wins, at most one unnamed bridge.
+ * - `?hop=s<id>&hop=d<id>…` — the trail, read as a flow. Nothing is searched:
+ *   the hops are the ones the reader walked, and the work is finding the edge
+ *   that already connects each consecutive pair.
+ *
+ * **Nothing here is cached.** Every other multi-symbol endpoint memoises on the
+ * index version, and this one deliberately does not: a flow card carries source
+ * read from disk, and the drift verdict on it changes without the index
+ * changing. A cached "no drift" is exactly the failure `/api/source` exists to
+ * prevent. The search itself costs tens of milliseconds; the windows are seven
+ * lines each.
+ */
+import type CodeGraph from '../../index';
+import type { Edge } from '../../types';
+import { type HighlightResult } from '../highlight';
+import { type WireEdge, type WireList, type WireNodeRef } from './wire';
+/** Lines shown either side of the call site on a card (design spec §3.5). */
+export declare const SOURCE_WINDOW = 3;
+/** Distinct paths returned. The header's flow picker is a short list or nothing. */
+export declare const MAX_FLOWS = 4;
+export interface WireFlowEdge extends WireEdge {
+    /** The link's label: "calls", "via callback · registered at file:line". */
+    label: string;
+    /** This hop reads callee → caller — the reader stepped UP into it. */
+    upward: boolean;
+    /** `metadata.confidence` below {@link UNCERTAIN_BELOW}: dashed `2 3`. */
+    uncertain: boolean;
+    /** A synthesized dynamic-dispatch bridge: dashed `5 3`. */
+    synthesized: boolean;
+}
+export interface WireFlowSource {
+    file: string;
+    language: string;
+    from: number;
+    to: number;
+    /** Absent when `drift` — a mis-sliced window is worse than an empty card. */
+    lines?: string[];
+    highlight?: HighlightResult;
+    drift: boolean;
+    /** Why there are no lines, when there are none. */
+    reason?: string;
+}
+/**
+ * The call site this card is opened at — the identifier the strip draws as a
+ * link, and the line the source window is centred on.
+ *
+ * It is not always a call to the NEXT card. Reading a trail backwards steps
+ * from a callee up to its caller, and the line that connects them then lives in
+ * the caller's body and names the symbol on the PREVIOUS card. Either way the
+ * rule is the same: a card opens at the line that ties it to its neighbour.
+ */
+export interface WireFlowCallRef {
+    line: number;
+    /** 0-based column the edge recorded, or null when it carries none. */
+    col: number | null;
+    /** The identifier as the graph names it — what the token must match. */
+    name: string;
+    /** The symbol at the other end of the edge. */
+    targetId: string;
+    /** The link points back at the previous card, not on to the next one. */
+    backwards: boolean;
+}
+export interface WireFlowHop {
+    node: WireNodeRef;
+    /** The edge from the PREVIOUS hop into this one; null on the first. */
+    edge: WireFlowEdge | null;
+    /** Where this card is opened, and what it links to. Null when it is neither. */
+    callRef: WireFlowCallRef | null;
+    /** The window this card shows, centred on `callRef` or the definition. */
+    source: WireFlowSource | null;
+}
+/** One plausible runtime target of a keyed dispatch — a clickable cap row. */
+export interface WireBoundaryCandidate {
+    node: WireNodeRef;
+    /** How to name it: usually the qualified name, or `Class.handlerMethod`. */
+    display: string;
+    /** The question already named this symbol — "you were right, here's the wiring". */
+    named: boolean;
+}
+/** A dynamic-dispatch site: the form, the key when it is visible, the targets. */
+export interface WireBoundarySite {
+    /** Stable form id, e.g. `computed-call`. */
+    form: string;
+    /** What to call it on screen: "computed member call", "getattr dispatch". */
+    label: string;
+    /** The source line of the site, trimmed. */
+    snippet: string;
+    line: number;
+    /** The statically visible key (`handlers['save']` → `save`), or null. */
+    key: string | null;
+    /** The key is a TYPE name, so the target is `<Type>Handler` by convention. */
+    keyIsType: boolean;
+    /** Further sites of the same form and key in this body. */
+    moreSites: number;
+    candidates: WireBoundaryCandidate[];
+    /** Why there is no shortlist, when a key was visible but too generic. */
+    candidateNote: string | null;
+}
+/** A call out of the stopping symbol, and how sure the resolver was. */
+export interface WireFlowContinuation {
+    node: WireNodeRef;
+    line: number | null;
+    confidence: number | null;
+}
+/**
+ * Where the graph stops (design spec §3.5).
+ *
+ * Attached to a flow that does not reach everything the question named. It is
+ * the same verdict `codegraph_explore` announces in prose — both render
+ * `findDynamicBoundaries` — so the strip's end cap and the MCP answer can never
+ * disagree about where a path ends or what could continue it.
+ */
+export interface WireFlowBoundary {
+    /** The last symbol the static path reached. The cap hangs off this card. */
+    node: WireNodeRef;
+    /** Dispatch sites in that symbol's body. Empty when none was detected. */
+    sites: WireBoundarySite[];
+    /** Name-only matches under 0.6 the search did NOT follow. */
+    uncertain: WireList<WireFlowContinuation>;
+    /** Calls the resolver was sure of that this path does not need. */
+    further: WireList<WireFlowContinuation>;
+    /** Symbols the question named that this path never reaches. */
+    missed: WireNodeRef[];
+}
+export interface WireFlow {
+    /** Stable within a payload: the hop ids joined. Used as the picker's value. */
+    id: string;
+    /** "execute → rowToFileRecord", for the header's flow picker. */
+    label: string;
+    hops: WireFlowHop[];
+    /**
+     * The end cap, when this path stops short of the question. Null on a flow
+     * that reaches everything it was asked about — a connected answer has no
+     * boundary to announce, and saying otherwise would be noise.
+     */
+    boundary: WireFlowBoundary | null;
+    /**
+     * This strip is not an answer to the question, it is where the answer ran
+     * out: one card at the dispatch site rather than a path.
+     */
+    partial: boolean;
+}
+/** An endpoint that named more than one definition, and which one was taken. */
+export interface WireFlowAmbiguity {
+    token: string;
+    chosen: WireNodeRef | null;
+    others: WireNodeRef[];
+}
+export interface WireFlowPayload {
+    query: {
+        kind: 'directed' | 'symbols' | 'trail';
+        from: string | null;
+        to: string | null;
+        /** The tokens the search actually used. */
+        symbols: string[];
+    };
+    flows: WireFlow[];
+    ambiguous: WireFlowAmbiguity[];
+    /** Tokens that named nothing in this index. */
+    unresolved: string[];
+    /** Why there is no flow, when there is none. Null when there is one. */
+    reason: string | null;
+    index: {
+        lastIndexedAt: number | null;
+        edges: number;
+        files: number;
+    };
+    timing: {
+        elapsedMs: number;
+    };
+}
+export type FlowQuery = {
+    kind: 'directed';
+    from: string;
+    to: string;
+} | {
+    kind: 'symbols';
+    text: string;
+} | {
+    kind: 'trail';
+    hops: Array<{
+        id: string;
+        dir: 'start' | 'down' | 'up';
+    }>;
+};
+/**
+ * Read the question out of the query string.
+ *
+ * A trail hop arrives as its own `hop` parameter rather than in one joined
+ * list, for the same reason `/api/nodes` repeats `id`: a node id can be a file
+ * path and a file path can contain a comma. The one-character direction prefix
+ * mirrors `ui/src/lib/trail-codec.ts`, which owns the format.
+ */
+export declare function parseFlowQuery(query: URLSearchParams): FlowQuery;
+/**
+ * The sentence under a link.
+ *
+ * A synthesized hop must never read as a plain `calls`: it is a bridge the
+ * resolver inferred, and the wiring site is the evidence for it. Design spec
+ * §3.5 fixes the phrasing — "via callback · registered at file:line".
+ */
+export declare function flowEdgeLabel(edge: Edge, upward: boolean): string;
+export declare function buildFlow(cg: CodeGraph, projectRoot: string, query: URLSearchParams): Promise<WireFlowPayload>;
+//# sourceMappingURL=flow.d.ts.map

package/dist/ui-server/api/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../../src/ui-server/api/flow.ts"],"names":[],"mappings":"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"}