@saluzi/codegraph 0.1.0 → 0.2.0

package/dist/installer/targets/types.d.ts

@@ -1,122 +0,0 @@
-/**
- * Agent target abstraction for the installer.
- *
- * Each MCP-capable agent (Claude Code, Cursor, Codex CLI, opencode, ...)
- * implements this interface so the installer orchestrator can write the
- * right MCP-server config + instructions file + permissions for that
- * agent without baking client-specific paths into core code. Adding a
- * new agent = one new file in `targets/` + one entry in `registry.ts`.
- *
- * Closes the Claude-locked installer issue (upstream #137). The
- * runtime MCP server is already agent-agnostic; this brings the
- * installer to the same surface.
- */
-export type Location = 'global' | 'local'
-/**
- * Stable string id used in the `--target` CLI flag and the registry
- * lookup. New targets add a value here when they're added to the
- * registry. Keep these short and lowercase.
- */
-export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'hermes'
-/**
- * Result of `target.detect(location)`.
- *
- * `installed` is a best-effort heuristic that the agent's CLI / app /
- * config dir is present on this system — used to default the
- * multiselect prompt to "what's actually here." False positives are
- * acceptable (we still write); false negatives just mean the user
- * has to opt in manually.
- *
- * `alreadyConfigured` reports whether codegraph has already been
- * wired into this target at this location — drives the
- * "Updated"-vs-"Added" log line and lets `--check` exit 0/1.
- */
-export interface DetectionResult {
-  installed: boolean
-  alreadyConfigured: boolean
-  /** Path inspected; surfaced in diagnostic / dry-run output. */
-  configPath?: string
-}
-/**
- * What `target.install(location)` actually changed on disk. The
- * orchestrator renders one log line per file using `action`.
- *
- * `unchanged` means we touched the file but its contents were already
- * what we'd write — used for byte-identical idempotent re-runs.
- */
-export interface WriteResult {
-  files: Array<{
-    path: string
-    action:
-      | 'created'
-      | 'updated'
-      | 'unchanged'
-      | 'removed'
-      | 'not-found'
-      | 'kept'
-  }>
-  /**
-   * Optional one-line notes the orchestrator surfaces verbatim — e.g.
-   * "Restart Cursor to apply." Keep these short; multi-line goes in
-   * the README.
-   */
-  notes?: string[]
-}
-export interface InstallOptions {
-  /**
-   * Whether to write the agent's permissions / auto-allow surface
-   * (Claude `settings.json`, others where applicable). When the
-   * target has no permissions concept this option is a no-op.
-   */
-  autoAllow: boolean
-}
-export interface AgentTarget {
-  /** Stable id; matches the `TargetId` union. */
-  readonly id: TargetId
-  /** Human-readable name shown in clack prompts and log lines. */
-  readonly displayName: string
-  /** Optional URL for "where do I learn more about this agent." */
-  readonly docsUrl?: string
-  /**
-   * Whether this target supports the given install location.
-   *
-   * Some agents (Codex CLI as of 2026-05) have no project-local
-   * config concept — only a single `~/.codex/` dir. Returning false
-   * for an unsupported (target, location) pair lets the orchestrator
-   * skip cleanly with a clear message.
-   */
-  supportsLocation(loc: Location): boolean
-  detect(loc: Location): DetectionResult
-  install(loc: Location, opts: InstallOptions): WriteResult
-  /**
-   * Inverse of install. Removes only what install would have written;
-   * preserves sibling MCP servers, sibling permissions, and unrelated
-   * markdown sections. Must be safe to call when nothing was ever
-   * installed (returns `not-found` actions).
-   */
-  uninstall(loc: Location): WriteResult
-  /**
-   * Print the MCP-server snippet a user would paste manually for this
-   * target. Used by `codegraph install --print-config <id>` and by
-   * the README. Must NOT touch the filesystem.
-   */
-  printConfig(loc: Location): string
-  /** Filesystem paths this target would write to at this location. */
-  describePaths(loc: Location): string[]
-  /**
-   * Optional. Write any project-local surfaces this target needs in
-   * order to work fully when its MCP config is configured globally.
-   * Called by `codegraph init` to bootstrap new projects without
-   * forcing the user to re-run `codegraph install` per project.
-   *
-   * Most targets need nothing here — their global config is complete.
-   * Cursor is the notable exception: its rules system
-   * (`.cursor/rules/*.mdc`) is project-scoped only, and is what makes
-   * Cursor's agent prefer codegraph over its built-in grep.
-   *
-   * Must be idempotent. Targets that have nothing project-local omit
-   * the method entirely.
-   */
-  wireProjectSurfaces?(): WriteResult
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/mcp/index.d.ts

@@ -1,98 +0,0 @@
-/**
- * CodeGraph MCP Server
- *
- * Model Context Protocol server that exposes CodeGraph functionality
- * as tools for AI assistants like Claude.
- *
- * @module mcp
- *
- * @example
- * ```typescript
- * import { MCPServer } from 'codegraph';
- *
- * const server = new MCPServer('/path/to/project');
- * await server.start();
- * ```
- */
-/**
- * MCP Server for CodeGraph
- *
- * Implements the Model Context Protocol to expose CodeGraph
- * functionality as tools that can be called by AI assistants.
- */
-export declare class MCPServer {
-  private transport
-  private cg
-  private toolHandler
-  private projectPath
-  private initPromise
-  private clientSupportsRoots
-  private rootsAttempted
-  private originalPpid
-  private hostPpid
-  private ppidWatchdog
-  private stopped
-  constructor(projectPath?: string)
-  /**
-   * Start the MCP server
-   *
-   * Note: CodeGraph initialization is deferred until the initialize request
-   * is received, which includes the rootUri from the client.
-   */
-  start(): Promise<void>
-  /**
-   * Try to initialize CodeGraph for the default project.
-   *
-   * Walks up parent directories to find the nearest .codegraph/ folder,
-   * similar to how git finds .git/ directories.
-   *
-   * If initialization fails, the error is recorded but the server continues
-   * to work — cross-project queries and retries on subsequent tool calls
-   * are still possible.
-   */
-  private tryInitializeDefault
-  /**
-   * Retry initialization of the default project if it previously failed.
-   * Called lazily on tool calls that need the default project.
-   * Re-walks parent directories each time so it picks up projects
-   * initialized after the MCP server started.
-   *
-   * Awaits any in-flight background init (kicked off by handleInitialize) so
-   * we never open the SQLite file twice concurrently.
-   */
-  private retryInitIfNeeded
-  /**
-   * Resolve the project root via the MCP `roots/list` request and initialize
-   * from the first root the client reports. Falls back to the process cwd if
-   * the client returns no usable root or doesn't answer in time. See issue #196.
-   */
-  private initFromRoots
-  /**
-   * Start file watching on the active CodeGraph instance.
-   * Logs sync activity to stderr for diagnostics.
-   */
-  private startWatching
-  /**
-   * Stop the server
-   */
-  stop(): void
-  /**
-   * Handle incoming JSON-RPC messages
-   */
-  private handleMessage
-  /**
-   * Handle initialize request
-   */
-  private handleInitialize
-  /**
-   * Handle tools/list request
-   */
-  private handleToolsList
-  /**
-   * Handle tools/call request
-   */
-  private handleToolsCall
-}
-export { StdioTransport } from './transport'
-export { tools, ToolHandler } from './tools'
-//# sourceMappingURL=index.d.ts.map

package/dist/mcp/server-instructions.d.ts

@@ -1,20 +0,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.
- */
-export declare const SERVER_INSTRUCTIONS =
-  '# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file\nin the workspace. Reads are sub-millisecond; the index lags writes by\nabout a second through the file watcher. Consult it BEFORE writing or\nediting code, not during.\n\n## Answer directly \u2014 don\'t delegate exploration\n\nFor "how does X work", architecture, trace, or where-is-X questions,\nanswer DIRECTLY using 2-3 codegraph calls: `codegraph_context` first,\nthen ONE `codegraph_explore` for the source of the symbols it surfaces.\nCodegraph IS the pre-built search index \u2014 so delegating the lookup to a\nseparate file-reading sub-task/agent, or running your own grep + read\nloop, repeats work codegraph already did and costs more for the same\nanswer. Reach for raw Read/Grep only to confirm a specific detail\ncodegraph didn\'t cover. A direct codegraph answer is typically a handful\nof calls; a grep/read exploration is dozens.\n\n## Tool selection by intent\n\n- **"What is the symbol named X?"** \u2192 `codegraph_search`\n- **"What\'s the deal with this task / feature / area?"** \u2192 `codegraph_context` (PRIMARY \u2014 composes search + node + callers + callees in one call)\n- **"What calls this?"** \u2192 `codegraph_callers`\n- **"What does this call?"** \u2192 `codegraph_callees`\n- **"What would changing this break?"** \u2192 `codegraph_impact`\n- **"Show me this symbol\'s source / signature / docstring."** \u2192 `codegraph_node`\n- **"Show me several related symbols\' source / survey an area."** \u2192 `codegraph_explore` (ONE capped call; prefer over many codegraph_node/Read)\n- **"What\'s in directory X?"** \u2192 `codegraph_files`\n- **"Is the index ready / what\'s its size?"** \u2192 `codegraph_status`\n\n## Common chains\n\n- **Onboarding**: `codegraph_context` first. If still unclear, `codegraph_explore` for breadth, then `codegraph_node` on specific symbols.\n- **Refactor planning**: `codegraph_search` \u2192 `codegraph_callers` \u2192 `codegraph_impact`. The blast-radius answer comes from impact, not from walking callers manually.\n- **Debugging a regression**: `codegraph_callers` of the suspected symbol; widen with `codegraph_impact` if an unexpected call appears.\n\n## Anti-patterns\n\n- **Don\'t grep first** when looking up a symbol by name \u2014 `codegraph_search` is faster and returns kind + location + signature.\n- **Don\'t chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one round-trip.\n- **Don\'t loop `codegraph_node` over many symbols** \u2014 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.\n- **Don\'t query the index immediately after editing a file** \u2014 the watcher needs ~500ms to debounce + sync. Wait for the next turn.\n\n## Limitations\n\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that\'s still the TypeScript compiler / test suite / linter\'s job. Codegraph supplements those with structural context they don\'t have.\n'
-//# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/tools.d.ts

@@ -1,269 +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 within length bounds.
-   *
-   * The `maxLength` cap protects against MCP clients that ship huge
-   * payloads (10MB+ query strings either by accident or maliciously).
-   * Without this, a single oversized input can pin the FTS5 index or
-   * exhaust memory before any real work runs.
-   */
-  private validateString
-  /**
-   * Validate an optional path-like string input. Returns the value if
-   * valid (or undefined), or a ToolResult with the error.
-   */
-  private validateOptionalPath
-  /**
-   * 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/transport.d.ts

@@ -1,117 +0,0 @@
-/**
- * MCP Stdio Transport
- *
- * Handles JSON-RPC 2.0 communication over stdin/stdout for MCP protocol.
- */
-/**
- * JSON-RPC 2.0 Request
- */
-export interface JsonRpcRequest {
-  jsonrpc: '2.0'
-  id: string | number
-  method: string
-  params?: unknown
-}
-/**
- * JSON-RPC 2.0 Response
- */
-export interface JsonRpcResponse {
-  jsonrpc: '2.0'
-  id: string | number | null
-  result?: unknown
-  error?: JsonRpcError
-}
-/**
- * JSON-RPC 2.0 Error
- */
-export interface JsonRpcError {
-  code: number
-  message: string
-  data?: unknown
-}
-/**
- * JSON-RPC 2.0 Notification (no id, no response expected)
- */
-export interface JsonRpcNotification {
-  jsonrpc: '2.0'
-  method: string
-  params?: unknown
-}
-export declare const ErrorCodes: {
-  readonly ParseError: -32700
-  readonly InvalidRequest: -32600
-  readonly MethodNotFound: -32601
-  readonly InvalidParams: -32602
-  readonly InternalError: -32603
-}
-export type MessageHandler = (
-  message: JsonRpcRequest | JsonRpcNotification,
-) => Promise<void>
-/**
- * Stdio Transport for MCP
- *
- * Reads JSON-RPC messages from stdin and writes responses to stdout.
- */
-export declare class StdioTransport {
-  private rl
-  private messageHandler
-  private pending
-  private nextRequestId
-  /**
-   * Start listening for messages on stdin
-   */
-  start(handler: MessageHandler): void
-  /**
-   * Stop listening
-   */
-  stop(): void
-  /**
-   * Send a server-initiated request to the client and await its response.
-   *
-   * MCP is bidirectional: the server can ask the client questions too. We use
-   * this for `roots/list` — the spec-blessed way to learn the workspace root
-   * when the client didn't pass one in `initialize` (see issue #196). Rejects
-   * on timeout so callers can fall back rather than hang forever.
-   */
-  request(
-    method: string,
-    params?: unknown,
-    timeoutMs?: number,
-  ): Promise<unknown>
-  /**
-   * Send a response
-   */
-  send(response: JsonRpcResponse): void
-  /**
-   * Send a notification (no id)
-   */
-  notify(method: string, params?: unknown): void
-  /**
-   * Send a success response
-   */
-  sendResult(id: string | number, result: unknown): void
-  /**
-   * Send an error response
-   */
-  sendError(
-    id: string | number | null,
-    code: number,
-    message: string,
-    data?: unknown,
-  ): void
-  /**
-   * Handle an incoming line of JSON
-   */
-  private handleLine
-  /**
-   * Resolve (or reject) the pending server-initiated request matching this
-   * response's id. Unknown ids are ignored — the client may echo something we
-   * never sent, or a request may have already timed out.
-   */
-  private handleResponse
-  /**
-   * Check if message is a valid JSON-RPC 2.0 message
-   */
-  private isValidMessage
-}
-//# sourceMappingURL=transport.d.ts.map

package/dist/resolution/frameworks/cargo-workspace.d.ts

@@ -1,20 +0,0 @@
-/**
- * Cargo Workspace Resolver Helper
- *
- * Parses a project's root Cargo.toml and member crate manifests to
- * build a crate-name -> member-directory map. Used by the Rust
- * resolver to resolve `use crate_name::...` references that point
- * into workspace member crates.
- */
-import { ResolutionContext } from '../types'
-/**
- * Build a map from crate-name aliases to workspace member directory paths.
- * Example: "mytool-core" and "mytool_core" -> "crates/mytool-core"
- *
- * Supports glob members (e.g. `members = ["crates/*"]`) via picomatch
- * when the context exposes `listDirectories`.
- */
-export declare function getCargoWorkspaceCrateMap(
-  context: ResolutionContext,
-): Map<string, string>
-//# sourceMappingURL=cargo-workspace.d.ts.map