@nithin554/code-crawler 0.1.55 → 0.1.58

package/dist/graph/insights.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Higher-level analyses built on top of the primitive queries.
+ *
+ * These power the "agent-facing" tools: what the index could not resolve, what
+ * breaks if a symbol changes, a one-shot explanation of a symbol, call cycles,
+ * and graph export in diagram formats.
+ */
+import { type DecoratorInfo, type SymbolRef, type WiringEdge } from "./queries.js";
+import type { EdgeKind, NodeKind } from "./schema.js";
+import type { GraphStore } from "./store.js";
+export interface UnresolvedCall {
+    caller: SymbolRef;
+    /** Placeholder node id the call edge points at (`__unknown__:<label>`). */
+    targetId: string;
+    /** Callee as written in source, e.g. `System.out.println`. */
+    targetLabel: string;
+    /** Why the resolver gave up. */
+    reason: string;
+    line?: number;
+    edgeKind: EdgeKind;
+}
+export interface ReasonCount {
+    reason: string;
+    count: number;
+}
+export interface UnresolvedReport {
+    /** Total unresolved call edges matching the filters, ignoring `limit`. */
+    total: number;
+    /** Unresolved edges grouped by resolver reason, most frequent first. */
+    byReason: ReasonCount[];
+    calls: UnresolvedCall[];
+    /** True when `calls` hit the scan limit before `total` did. */
+    scanTruncated: boolean;
+    /** `kind` filter that was applied to the caller node kind. */
+    callerKind?: NodeKind;
+    /** `reason` filter that was applied (substring, case-insensitive). */
+    reasonFilter?: string;
+}
+export interface UnresolvedQueryOptions {
+    /** Substring match against the resolver reason, case-insensitive. */
+    reason?: string;
+    /** Restrict to unresolved calls made by callers of this node kind. */
+    kind?: NodeKind;
+    /** Cap on rows scanned (default 2000). */
+    limit?: number;
+}
+/**
+ * Every call the resolver could not bind to a node, with the reason it failed.
+ *
+ * Unresolved calls are the honest boundary of a static index: they show where
+ * analysis stops (dynamic dispatch, untyped receivers, missing dependencies)
+ * and they are the highest-signal input for improving the parsers.
+ */
+export declare function findUnresolved(store: GraphStore, opts?: UnresolvedQueryOptions): UnresolvedReport;
+export interface NodeUnresolvedInfo {
+    /** Calls this node makes that could not be resolved. */
+    outgoing: UnresolvedCall[];
+    /** Unresolved calls elsewhere in the graph that point at this node. */
+    incoming: {
+        caller: SymbolRef;
+        line?: number;
+    }[];
+}
+/**
+ * Unresolved call detail for a single node, used to annotate `get_node`.
+ * Returns `undefined` when the node has no unresolved edges in either
+ * direction so callers can omit the block entirely.
+ */
+export declare function unresolvedForNode(store: GraphStore, nodeId: string): NodeUnresolvedInfo | undefined;
+export interface ImpactCaller {
+    caller: SymbolRef;
+    depth: number;
+    callSiteLine?: number;
+    edgeKind: EdgeKind;
+}
+export interface ImpactImplementation {
+    type: SymbolRef;
+    /** Override of the analyzed method, when the symbol is a member. */
+    method?: SymbolRef;
+    depth: number;
+    via: "EXTENDS" | "IMPLEMENTS";
+}
+export interface ImpactSummary {
+    totalCallers: number;
+    directCallers: number;
+    entryPoints: number;
+    routes: number;
+    implementations: number;
+    affectedFiles: number;
+    /**
+     * Heuristic blast radius: `high` when a framework entry point reaches the
+     * symbol, `medium` when at least one caller exists, else `low`.
+     */
+    risk: "low" | "medium" | "high";
+}
+export interface ImpactAnalysis {
+    symbol: SymbolRef;
+    summary: ImpactSummary;
+    callers: ImpactCaller[];
+    entryPoints: {
+        symbol: SymbolRef;
+        entryPointKind: string;
+        detail?: string;
+        viaDepth?: number;
+    }[];
+    routes: WiringEdge[];
+    implementations: ImpactImplementation[];
+    affectedFiles: string[];
+}
+export interface ImpactOptions {
+    maxDepth?: number;
+    includeDynamic?: boolean;
+    limit?: number;
+}
+/**
+ * "What breaks if I change this?" — reverse callers, framework entry points,
+ * routes and implementations in a single response.
+ *
+ * A type aggregates the callers of its contained methods, since call edges bind
+ * to methods and a class is usually changed through its members.
+ */
+export declare function impactAnalysis(store: GraphStore, symbol: string, opts?: ImpactOptions): ImpactAnalysis | null;
+export interface ExplainedMember {
+    symbol: SymbolRef;
+    line?: number;
+    decorators: DecoratorInfo[];
+}
+export interface SymbolExplanation {
+    symbol: SymbolRef;
+    line?: number;
+    isEntryPoint?: boolean;
+    decorators: DecoratorInfo[];
+    members: ExplainedMember[];
+    callers: ImpactCaller[];
+    callees: ImpactCaller[];
+    implementations: ImpactImplementation[];
+    routes: WiringEdge[];
+    injections: WiringEdge[];
+    reflections: WiringEdge[];
+    summary: {
+        members: number;
+        callers: number;
+        callees: number;
+        implementations: number;
+        wiringEdges: number;
+    };
+}
+export interface ExplainOptions {
+    maxDepth?: number;
+    includeDynamic?: boolean;
+    limit?: number;
+}
+/**
+ * One-shot digest of a symbol: what it is, what it is annotated with, what it
+ * contains, who calls it, what it calls, and how frameworks reach it.
+ *
+ * Intended to replace a chain of five tool calls with one round trip.
+ */
+export declare function explainSymbol(store: GraphStore, symbol: string, opts?: ExplainOptions): SymbolExplanation | null;
+export interface CallCycle {
+    size: number;
+    members: SymbolRef[];
+    /** Shortest closed walk through the cycle, starting at the first member. */
+    sample: string[];
+}
+export interface CycleReport {
+    /** Number of multi-node cycles reported (after `minSize`). */
+    cycleCount: number;
+    cycles: CallCycle[];
+    /** Symbols that call themselves directly (size-1 cycles). */
+    selfRecursive: SymbolRef[];
+    edgeKinds: EdgeKind[];
+    scannedNodes: number;
+    scannedEdges: number;
+    /** True when the edge scan hit `maxNodes` and results may be incomplete. */
+    scanTruncated: boolean;
+}
+export interface CycleOptions {
+    edgeKinds?: EdgeKind[];
+    includeDynamic?: boolean;
+    /** Minimum cycle size to report. Default 2 (direct recursion is separate). */
+    minSize?: number;
+    /** Cap on edges scanned, guarding against very large graphs. */
+    maxEdges?: number;
+    limit?: number;
+}
+/**
+ * Find strongly connected components in the call graph with an iterative
+ * Tarjan. A component larger than one node means the members are mutually
+ * reachable, i.e. a call cycle; a self-edge is direct recursion.
+ *
+ * Iterative rather than recursive so deep call chains cannot blow the stack.
+ */
+export declare function findCycles(store: GraphStore, opts?: CycleOptions): CycleReport;
+export type ExportFormat = "mermaid" | "dot";
+export interface GraphExport {
+    format: ExportFormat;
+    diagram: string;
+    nodeCount: number;
+    edgeCount: number;
+    truncated: boolean;
+    /** Symbol the export was centered on, when one was given. */
+    center?: SymbolRef;
+}
+export interface ExportOptions {
+    symbol?: string;
+    radius?: number;
+    edgeKinds?: EdgeKind[];
+    format?: ExportFormat;
+    direction?: "LR" | "TB" | "RL" | "BT";
+    limit?: number;
+}
+/**
+ * Render a neighborhood (or the whole graph) as Mermaid or Graphviz DOT so an
+ * agent can show the user a diagram instead of a list of edges.
+ */
+export declare function exportGraph(store: GraphStore, opts?: ExportOptions): GraphExport | null;