codegraph-java 0.1.0

package/dist/graph/named-symbol-flow.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The call path among a bag of named symbols — the one path finder.
+ *
+ * `codegraph_explore` leads its answer with a "Flow" section: the longest call
+ * chain among the symbols an agent named, riding synthesized dynamic-dispatch
+ * edges so a controller reaches its implementation through the interface. The
+ * viewer's Flow strip (`/api/flow`, design spec §3.5) draws the same thing as
+ * cards. They must never disagree, so the search lives here once and both
+ * callers ride it: same token parsing, same overload disambiguation, same
+ * bridge budget, same edges.
+ *
+ * What differs between the two callers is expressed as OPTIONS, not as a second
+ * implementation:
+ *
+ * - **`mode: 'named'`** is exactly what explore does. Every resolved symbol is
+ *   both a possible start and a possible end, at most ONE unnamed symbol may
+ *   bridge two named ones ({@link DEFAULT_MAX_BRIDGE}), and the LONGEST chain
+ *   wins. The bridge cap is what stops the search wandering a god-function's
+ *   fan-out: the agent's own naming is the evidence that a hop is on-topic.
+ * - **`mode: 'directed'`** is "how does X reach Y", which the agent has no way
+ *   to ask and the viewer's search box does. Both ends are pinned, so the
+ *   evidence the bridge cap was standing in for is already there and the search
+ *   bridges freely — a two-token query under the named rules could never return
+ *   more than three cards. The SHORTEST path wins, because with both ends fixed
+ *   a longer route is a detour rather than a fuller answer.
+ *
+ * Overloads are handled differently for the same reason. A bare ambiguous name
+ * in `named` mode is filtered by CO-NAMING (keep `list` only where the agent
+ * also named its class); in `directed` mode every candidate for both endpoints
+ * is tried and the pair that actually connects is the answer — which is a
+ * better disambiguator than co-naming and the only one available when the
+ * whole query is two words.
+ */
+import type CodeGraph from '../index';
+import type { Node, Edge } from '../types';
+/**
+ * Rust path roots that have no file-system equivalent — `crate` is the
+ * current crate, `super` is the parent module, `self` is the current
+ * module. Used by `matchesSymbol` to strip these before file-path
+ * matching so `crate::configurator::stage_apply::run` resolves the
+ * same as `configurator::stage_apply::run`.
+ */
+export declare const RUST_PATH_PREFIXES: Set<string>;
+/**
+ * Last `::` / `.` / `/`-separated segment of a qualified symbol. An Erlang
+ * arity tail (`mod::fn/3`, `fn/3`) is stripped first — the useful last segment
+ * is the function name, never the digits (#1610).
+ */
+export declare function lastQualifierPart(symbol: string): string;
+/**
+ * Check if a node matches a symbol query.
+ *
+ * Accepts simple names (`run`) and three flavors of qualifier:
+ *   - dotted     `Session.request`         (TS/JS/Python)
+ *   - colon-pair `stage_apply::run`        (Rust, C++, Ruby)
+ *   - slash      `configurator/stage_apply` (path-ish)
+ *
+ * Multi-level qualifiers compose: `crate::configurator::stage_apply::run`
+ * works. Rust path prefixes (`crate`, `super`, `self`) are stripped so
+ * the canonical `crate::module::symbol` form resolves.
+ *
+ * Resolution order, last part must always equal `node.name`:
+ *   1. Suffix-match against `qualifiedName` (handles class-scoped methods
+ *      where the extractor builds the qualified name from the AST stack)
+ *   2. File-path containment (handles file-derived modules in Rust/
+ *      Python — `stage_apply::run` matches a `run` in `stage_apply.rs`)
+ */
+export declare function matchesSymbol(node: Node, symbol: string): boolean;
+/**
+ * Find ALL symbols matching a name. Used by callers/callees/impact to aggregate
+ * results across all matching symbols (e.g., multiple classes with an `execute` method).
+ */
+export declare function findAllSymbols(cg: CodeGraph, symbol: string): {
+    nodes: Node[];
+    note: string;
+};
+/** Node kinds that can sit on a call chain. */
+export declare const FLOW_CALLABLE_KINDS: ReadonlySet<string>;
+/**
+ * Edge kinds a flow may ride. `navigates` is a screen transition (Expo Router
+ * `router.push('/x')` → the route node) — a hop in the user's flow exactly as
+ * a call is a hop in the program's.
+ */
+export declare const FLOW_EDGE_KINDS: ReadonlySet<string>;
+/** Chain length ceiling, in NODES. Explore's Flow section has always used 7. */
+export declare const DEFAULT_MAX_HOPS = 7;
+/**
+ * Longer ceiling for a directed question.
+ *
+ * "How does X reach Y" is asked about two symbols that a reader believes are
+ * connected, and a real call path between a CLI entry point and a storage
+ * primitive runs deeper than seven frames. Explore's ceiling stays where it is:
+ * there, a longer chain is a bigger guess, because nothing pins the far end.
+ */
+export declare const DIRECTED_MAX_HOPS = 12;
+/** At most one consecutive UNNAMED hop may bridge two named symbols. */
+export declare const DEFAULT_MAX_BRIDGE = 1;
+export interface FlowStep {
+    node: Node;
+    /** The edge INTO this node from the previous step; null on the first. */
+    edge: Edge | null;
+}
+export interface FlowChain {
+    steps: FlowStep[];
+    /** For each node on the chain, the line where it calls the NEXT one. */
+    callSites: Map<string, number>;
+}
+export interface NamedSymbolFlowOptions {
+    /** `named` = explore's rules; `directed` = a pinned from → to question. */
+    mode?: 'named' | 'directed';
+    /** Required in `directed` mode: the token the path must start at. */
+    from?: string;
+    /** Required in `directed` mode: the token the path must end at. */
+    to?: string;
+    maxHops?: number;
+    /** Consecutive unnamed hops allowed. `Infinity` in directed mode. */
+    maxBridge?: number;
+    /** Distinct chains to return. Explore only ever looks at the first. */
+    maxChains?: number;
+}
+export interface NamedSymbolFlow {
+    /** The query's symbol tokens, in the order they were written. */
+    tokens: string[];
+    /** Every CALLABLE the tokens resolved to, by node id. */
+    named: Map<string, Node>;
+    /** Non-callable endpoints of synthesized edges (RTK thunks and friends). */
+    dynNamed: Map<string, Node>;
+    /** token → the node ids it resolved to. */
+    tokenNodes: Map<string, string[]>;
+    /** token → its whole same-name callable family, before the container filter. */
+    tokenFamily: Map<string, Node[]>;
+    /** Ids whose token was a (near-)unique callable name — at most 3 defs. */
+    uniqueNamedNodeIds: Set<string>;
+    /** Ids resolved from a shape-precise token (camelCase, dotted, PascalCase…). */
+    preciseNamedIds: Set<string>;
+    /** Chains found, best first. Empty when nothing connects. */
+    chains: FlowChain[];
+}
+/** The symbol-shaped tokens of a query, deduped and capped. */
+export declare function flowTokens(query: string): string[];
+/**
+ * Resolve a query's tokens to nodes, with the overload rules described in the
+ * module header. No graph traversal happens here.
+ */
+export declare function resolveNamedTokens(cg: CodeGraph, query: string, opts?: NamedSymbolFlowOptions): NamedSymbolFlow;
+/**
+ * The call path among a query's named symbols. See the module header for what
+ * the two modes mean and why they differ.
+ */
+export declare function resolveNamedSymbolFlow(cg: CodeGraph, query: string, opts?: NamedSymbolFlowOptions): NamedSymbolFlow;
+/** The token spelling {@link flowTokens} would have produced for one word. */
+export declare function normalizeToken(token: string): string;
+//# sourceMappingURL=named-symbol-flow.d.ts.map

package/dist/graph/named-symbol-flow.d.ts.map

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