@abdulmunimjemal/codescope 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -93,6 +93,20 @@ interface Neighborhood {
     /** Names referenced in the graph that have no definition in the index. */
     unresolved: string[];
 }
+/** A symbol in a blast-radius result, with its hop distance from the root. */
+type ImpactRow = SymbolRow & {
+    distance: number;
+};
+/** A token-budgeted task-context map: seed matches + ranked neighbours + edges. */
+interface ContextBundle {
+    query: string;
+    seeds: SymbolRow[];
+    related: SymbolRow[];
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+}
 interface IndexStats {
     files: number;
     symbols: number;
@@ -149,15 +163,50 @@ declare class GraphStore {
     getSymbol(name: string, opts?: {
         limit?: number;
     }): SymbolRow[];
-    /** Symbols that call a given name (both bare `foo()` and `x.foo()`). */
+    /**
+     * Distinct callers of a name (both bare `foo()` and `x.foo()`). Multiple call
+     * sites from the same caller in the same file collapse to one row — fewer
+     * tokens and a more useful "who depends on this" answer.
+     */
     findCallers(name: string, opts?: {
         limit?: number;
     }): RefRow[];
+    /** The definitions that a symbol calls, resolved kind-aware to project symbols. */
+    findCallees(name: string, opts?: {
+        limit?: number;
+    }): SymbolRow[];
+    /** How many call sites reference this name (popularity / centrality signal). */
+    callerCount(name: string): number;
+    /**
+     * The blast radius of changing a symbol: its transitive callers, breadth-first,
+     * annotated with hop distance and ordered nearest-first. Answers "what could
+     * break if I change this?" without reading the codebase.
+     */
+    impact(name: string, opts?: {
+        depth?: number;
+        limit?: number;
+    }): ImpactRow[];
+    /**
+     * A token-budgeted relevance map for a task: the symbols matching `query` plus
+     * their immediate call neighbourhood, ranked by call-site centrality, capped at
+     * `maxSymbols`. This is the slice of the codebase an agent needs to start a
+     * change — delivered as graph facts, not file dumps.
+     */
+    context(query: string, opts?: {
+        maxSymbols?: number;
+    }): ContextBundle;
     /** All references (calls + imports) to a name. */
     findReferences(name: string, opts?: {
         kind?: "call" | "method" | "import";
         limit?: number;
     }): RefRow[];
+    /**
+     * Files whose imports reference a module basename (e.g. `store` for
+     * `src/store.ts`). Matches `import … from "./store"`, `"../src/store.js"`,
+     * etc. Used by affected-test analysis to follow import edges, which — unlike
+     * call edges — reliably reach test files (tests import the module under test).
+     */
+    findImporters(moduleBasename: string): string[];
     /** The symbols defined in a file, in source order. */
     fileOutline(path: string): SymbolRow[];
     /** Distinct (callee, callKind) pairs invoked from inside symbols named `from`. */
@@ -256,11 +305,15 @@ declare function parseSource(langId: string, source: string): Promise<ParseResul
  * "member access" node — so definitions, calls, and imports are all described
  * declaratively here and interpreted by a single generic walker.
  */
-type NameStrategy = "field" | "c_declarator";
+type NameStrategy = "field" | "c_declarator" | "first_typed";
 interface DefRule {
     kind: SymbolKind;
-    /** How to read the definition's name (default: the `name` field). */
+    /** How to read the definition's name (default: `field` on `name`). */
     name?: NameStrategy;
+    /** For the `field` strategy: which field holds the name (default `name`). */
+    nameField?: string;
+    /** For the `first_typed` strategy: pick the first named child of these types. */
+    nameTypes?: string[];
 }
 interface CallRule {
     /** AST node type for this kind of call. */
@@ -318,20 +371,72 @@ declare function createServer(store: GraphStore): McpServer;
 /** Connect a codescope server to stdio (the transport coding agents speak). */
 declare function runStdioServer(store: GraphStore): Promise<void>;
 
+/** Whether a repo-relative path looks like a test file. */
+declare function isTestFile(path: string): boolean;
+interface AffectedResult {
+    changed: string[];
+    /** Every file that defines a symbol transitively affected by the changes. */
+    impactedFiles: string[];
+    /** The impacted files that look like tests — the suite worth re-running. */
+    tests: string[];
+}
+declare function affected(store: GraphStore, changedPaths: string[], opts?: {
+    depth?: number;
+}): AffectedResult;
+
+/** Agents whose config is plain JSON with an `mcpServers` map (auto-wirable). */
+type AgentId = "claude" | "cursor";
+declare const SUPPORTED_AGENTS: readonly AgentId[];
+interface ServerEntry {
+    command: string;
+    args: string[];
+}
+/** The MCP server entry agents need to launch codescope over stdio. */
+declare function serverEntry(serveTarget?: string): ServerEntry;
+/** The config file codescope writes for a given agent. */
+declare function configPath(agent: AgentId, root: string, global?: boolean): string;
+interface InstallOutcome {
+    agent: AgentId;
+    path: string;
+    action: "added" | "updated";
+}
+/**
+ * Idempotently wire codescope into an agent's MCP config. Preserves any other
+ * servers already configured and overwrites only the `codescope` entry.
+ */
+declare function installInto(agent: AgentId, root: string, opts?: {
+    global?: boolean;
+    serveTarget?: string;
+}): InstallOutcome;
+/** Wire codescope into one or more agents. */
+declare function install(root: string, opts?: {
+    agents?: AgentId[];
+    global?: boolean;
+    serveTarget?: string;
+}): InstallOutcome[];
+/** Copy-paste config for agents whose config isn't plain JSON (e.g. Codex, TOML). */
+declare function codexSnippet(serveTarget?: string): string;
+
 declare function formatSymbols(rows: SymbolRow[]): string;
 declare function formatRefs(rows: RefRow[]): string;
 declare function formatNeighborhood(n: Neighborhood): string;
+declare function formatImpact(rows: ImpactRow[]): string;
+declare function formatContext(b: ContextBundle): string;
+declare function formatAffected(r: AffectedResult): string;
 declare function formatStats(s: IndexStats): string;
 
+declare const format_formatAffected: typeof formatAffected;
+declare const format_formatContext: typeof formatContext;
+declare const format_formatImpact: typeof formatImpact;
 declare const format_formatNeighborhood: typeof formatNeighborhood;
 declare const format_formatRefs: typeof formatRefs;
 declare const format_formatStats: typeof formatStats;
 declare const format_formatSymbols: typeof formatSymbols;
 declare namespace format {
-  export { format_formatNeighborhood as formatNeighborhood, format_formatRefs as formatRefs, format_formatStats as formatStats, format_formatSymbols as formatSymbols };
+  export { format_formatAffected as formatAffected, format_formatContext as formatContext, format_formatImpact as formatImpact, format_formatNeighborhood as formatNeighborhood, format_formatRefs as formatRefs, format_formatStats as formatStats, format_formatSymbols as formatSymbols };
 }
 
 /** The codescope version. Kept in sync with package.json at release time. */
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.3.0";
 
-export { type FileIndexOutcome, type FileMeta, GraphStore, type IndexOptions, type IndexRunResult, type IndexStats, Indexer, LANGUAGES, type LanguageConfig, type Neighborhood, type ParseResult, type ParsedRef, type ParsedSymbol, type RefKind, type RefRow, SUPPORTED_EXTENSIONS, type SymbolKind, type SymbolRow, VERSION, type WatchEvents, type WatchHandle, type WatchOptions, createServer, format, languageForPath, parseSource, runStdioServer, watch };
+export { type AffectedResult, type AgentId, type ContextBundle, type FileIndexOutcome, type FileMeta, GraphStore, type ImpactRow, type IndexOptions, type IndexRunResult, type IndexStats, Indexer, type InstallOutcome, LANGUAGES, type LanguageConfig, type Neighborhood, type ParseResult, type ParsedRef, type ParsedSymbol, type RefKind, type RefRow, SUPPORTED_AGENTS, SUPPORTED_EXTENSIONS, type SymbolKind, type SymbolRow, VERSION, type WatchEvents, type WatchHandle, type WatchOptions, affected, codexSnippet, configPath, createServer, format, install, installInto, isTestFile, languageForPath, parseSource, runStdioServer, serverEntry, watch };