@colbymchenry/codegraph 0.8.0 → 0.9.1

package/dist/mcp/server-instructions.js

@@ -1,71 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SERVER_INSTRUCTIONS = void 0;
-/**
- * Server-level instructions emitted in the MCP `initialize` response.
- *
- * MCP clients (Claude Code, Cursor, opencode, LangChain, OpenAI Agent
- * SDK, …) surface this text in the agent's system prompt automatically,
- * giving the agent a high-level playbook for the codegraph toolset
- * before it sees individual tool descriptions.
- *
- * Goals when editing this:
- *   - Tool selection by intent (which tool for which question)
- *   - Common chains (refactor planning = X then Y)
- *   - Anti-patterns (don't grep when codegraph_search is faster)
- *
- * Keep it tight. The agent reads this every session — long instructions
- * burn tokens. Reference only tools that exist on `main`; gate any
- * conditional tools behind feature checks if/when they ship.
- */
-exports.SERVER_INSTRUCTIONS = `# Codegraph — code intelligence over an indexed knowledge graph
-
-Codegraph is a SQLite knowledge graph of every symbol, edge, and file
-in the workspace. Reads are sub-millisecond; the index lags writes by
-about a second through the file watcher. Consult it BEFORE writing or
-editing code, not during.
-
-## Answer directly — don't delegate exploration
-
-For "how does X work", architecture, trace, or where-is-X questions,
-answer DIRECTLY using 2-3 codegraph calls: \`codegraph_context\` first,
-then ONE \`codegraph_explore\` for the source of the symbols it surfaces.
-Codegraph IS the pre-built search index — so delegating the lookup to a
-separate file-reading sub-task/agent, or running your own grep + read
-loop, repeats work codegraph already did and costs more for the same
-answer. Reach for raw Read/Grep only to confirm a specific detail
-codegraph didn't cover. A direct codegraph answer is typically a handful
-of calls; a grep/read exploration is dozens.
-
-## Tool selection by intent
-
-- **"What is the symbol named X?"** → \`codegraph_search\`
-- **"What's the deal with this task / feature / area?"** → \`codegraph_context\` (PRIMARY — composes search + node + callers + callees in one call)
-- **"What calls this?"** → \`codegraph_callers\`
-- **"What does this call?"** → \`codegraph_callees\`
-- **"What would changing this break?"** → \`codegraph_impact\`
-- **"Show me this symbol's source / signature / docstring."** → \`codegraph_node\`
-- **"Show me several related symbols' source / survey an area."** → \`codegraph_explore\` (ONE capped call; prefer over many codegraph_node/Read)
-- **"What's in directory X?"** → \`codegraph_files\`
-- **"Is the index ready / what's its size?"** → \`codegraph_status\`
-
-## Common chains
-
-- **Onboarding**: \`codegraph_context\` first. If still unclear, \`codegraph_explore\` for breadth, then \`codegraph_node\` on specific symbols.
-- **Refactor planning**: \`codegraph_search\` → \`codegraph_callers\` → \`codegraph_impact\`. The blast-radius answer comes from impact, not from walking callers manually.
-- **Debugging a regression**: \`codegraph_callers\` of the suspected symbol; widen with \`codegraph_impact\` if an unexpected call appears.
-
-## Anti-patterns
-
-- **Don't grep first** when looking up a symbol by name — \`codegraph_search\` is faster and returns kind + location + signature.
-- **Don't chain \`codegraph_search\` + \`codegraph_node\`** when you just want context — \`codegraph_context\` is one round-trip.
-- **Don't loop \`codegraph_node\` over many symbols** — one \`codegraph_explore\` call returns them all grouped by file, while each separate call re-reads the whole context and costs far more. Use \`codegraph_node\` for a single symbol.
-- **Don't query the index immediately after editing a file** — the watcher needs ~500ms to debounce + sync. Wait for the next turn.
-
-## Limitations
-
-- Index lags file writes by ~1 second.
-- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.
-- No live correctness validation — that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.
-`;
-//# sourceMappingURL=server-instructions.js.map

package/dist/mcp/server-instructions.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDlC,CAAC"}

package/dist/mcp/tools.d.ts

@@ -1,257 +0,0 @@
-/**
- * MCP Tool Definitions
- *
- * Defines the tools exposed by the CodeGraph MCP server.
- */
-import CodeGraph from '../index';
-/**
- * Calculate the recommended number of codegraph_explore calls based on project size.
- * Larger codebases need more exploration calls to cover their surface area,
- * but smaller ones should use fewer to avoid unnecessary overhead.
- */
-export declare function getExploreBudget(fileCount: number): number;
-/**
- * Adaptive output budget for `codegraph_explore`, scaled to project size.
- *
- * Smaller codebases get a tighter total cap, fewer default files, smaller
- * per-file cap, and tighter clustering — so a focused query on a 100-file
- * project doesn't dump a whole file's worth of source into the agent's
- * context. Larger codebases keep the generous defaults because the
- * agent's native discovery cost (grep + find + many Reads) genuinely
- * dwarfs a fat explore call at that scale.
- *
- * Meta-text (relationships map, "additional relevant files" list,
- * completeness signal, budget note) is gated off for tiny projects
- * where one rich call is the whole story and the extra prose is just
- * overhead.
- *
- * Tier breakpoints mirror `getExploreBudget` so a project sits in the
- * same tier across both knobs.
- */
-export interface ExploreOutputBudget {
-    /** Hard cap on total output characters. */
-    maxOutputChars: number;
-    /** Default `maxFiles` when the caller didn't specify one. */
-    defaultMaxFiles: number;
-    /** Cap on contiguous source returned per file (across all its clusters). */
-    maxCharsPerFile: number;
-    /** Cluster gap threshold in lines — tighter clustering on small projects. */
-    gapThreshold: number;
-    /** Max symbols listed in the per-file header (`#### path — sym(kind), ...`). */
-    maxSymbolsInFileHeader: number;
-    /** Max edges shown per relationship kind in the Relationships section. */
-    maxEdgesPerRelationshipKind: number;
-    /** Include the "Relationships" section. */
-    includeRelationships: boolean;
-    /** Include the "Additional relevant files (not shown)" trailing list. */
-    includeAdditionalFiles: boolean;
-    /** Include the "Complete source code is included above…" reminder. */
-    includeCompletenessSignal: boolean;
-    /** Include the explore-budget reminder at the end. */
-    includeBudgetNote: boolean;
-}
-export declare function getExploreOutputBudget(fileCount: number): ExploreOutputBudget;
-/**
- * MCP Tool definition
- */
-export interface ToolDefinition {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: 'object';
-        properties: Record<string, PropertySchema>;
-        required?: string[];
-    };
-}
-interface PropertySchema {
-    type: string;
-    description: string;
-    enum?: string[];
-    default?: unknown;
-}
-/**
- * Tool execution result
- */
-export interface ToolResult {
-    content: Array<{
-        type: 'text';
-        text: string;
-    }>;
-    isError?: boolean;
-}
-/**
- * All CodeGraph MCP tools
- *
- * Designed for minimal context usage - use codegraph_context as the primary tool,
- * and only use other tools for targeted follow-up queries.
- *
- * All tools support cross-project queries via the optional `projectPath` parameter.
- */
-export declare const tools: ToolDefinition[];
-/**
- * Tool handler that executes tools against a CodeGraph instance
- *
- * Supports cross-project queries via the projectPath parameter.
- * Other projects are opened on-demand and cached for performance.
- */
-export declare class ToolHandler {
-    private cg;
-    private projectCache;
-    private defaultProjectHint;
-    constructor(cg: CodeGraph | null);
-    /**
-     * Update the default CodeGraph instance (e.g. after lazy initialization)
-     */
-    setDefaultCodeGraph(cg: CodeGraph): void;
-    /**
-     * Record the directory the server tried to resolve the default project from.
-     * Used only to make the "no default project" error actionable.
-     */
-    setDefaultProjectHint(searchedPath: string): void;
-    /**
-     * Whether a default CodeGraph instance is available
-     */
-    hasDefaultCodeGraph(): boolean;
-    /**
-     * Get tool definitions with dynamic descriptions based on project size.
-     * The codegraph_explore tool description includes a budget recommendation
-     * scaled to the number of indexed files.
-     */
-    getTools(): ToolDefinition[];
-    /**
-     * Get CodeGraph instance for a project
-     *
-     * If projectPath is provided, opens that project's CodeGraph (cached).
-     * Otherwise returns the default CodeGraph instance.
-     *
-     * Walks up parent directories to find the nearest .codegraph/ folder,
-     * similar to how git finds .git/ directories.
-     */
-    private getCodeGraph;
-    /**
-     * Close all cached project connections
-     */
-    closeAll(): void;
-    /**
-     * Validate that a value is a non-empty string
-     */
-    private validateString;
-    /**
-     * Execute a tool by name
-     */
-    execute(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
-    /**
-     * Handle codegraph_search
-     */
-    private handleSearch;
-    /**
-     * Handle codegraph_context
-     */
-    private handleContext;
-    /**
-     * Heuristic to detect if a query looks like a feature request
-     */
-    private looksLikeFeatureRequest;
-    /**
-     * Handle codegraph_callers
-     */
-    private handleCallers;
-    /**
-     * Handle codegraph_callees
-     */
-    private handleCallees;
-    /**
-     * Handle codegraph_impact
-     */
-    private handleImpact;
-    /**
-     * Handle codegraph_explore — deep exploration in a single call
-     *
-     * Strategy: find relevant symbols via graph traversal, group by file,
-     * then read contiguous file sections covering all symbols per file.
-     * This replaces multiple codegraph_node + Read calls.
-     *
-     * Output size is adaptive to project file count via
-     * `getExploreOutputBudget` — see #185 for why a fixed 35k cap was a
-     * tax on small projects while earning its keep on large ones.
-     */
-    private handleExplore;
-    /**
-     * Handle codegraph_node
-     */
-    private handleNode;
-    /**
-     * Handle codegraph_status
-     */
-    private handleStatus;
-    /**
-     * Handle codegraph_files - get project file structure from the index
-     */
-    private handleFiles;
-    /**
-     * Convert glob pattern to regex
-     */
-    private globToRegex;
-    /**
-     * Format files as a flat list
-     */
-    private formatFilesFlat;
-    /**
-     * Format files grouped by language
-     */
-    private formatFilesGrouped;
-    /**
-     * Format files as a tree structure
-     */
-    private formatFilesTree;
-    /**
-     * Find a symbol by name, handling disambiguation when multiple matches exist.
-     * Returns the best match and a note about alternatives if any.
-     */
-    /**
-     * 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`)
-     */
-    private matchesSymbol;
-    private findSymbol;
-    /**
-     * 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).
-     */
-    private findAllSymbols;
-    /**
-     * Truncate output if it exceeds the maximum length
-     */
-    private truncateOutput;
-    private formatSearchResults;
-    private formatNodeList;
-    private formatImpact;
-    /**
-     * Build a compact structural outline of a container symbol from its
-     * indexed children (methods, fields, properties, …) — name, kind,
-     * line number, and signature — so the agent gets the shape of a class
-     * without the full source of every method. Returns '' when the container
-     * has no indexed children, so the caller can fall back to full source.
-     */
-    private buildContainerOutline;
-    private formatNodeDetails;
-    private formatTaskContext;
-    private textResult;
-    private errorResult;
-}
-export {};
-//# sourceMappingURL=tools.d.ts.map

package/dist/mcp/tools.d.ts.map

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