@selvakumaresra/specship 0.1.1 → 0.1.3

package/dist/mcp/tools.d.ts

@@ -1,404 +0,0 @@
-/**
- * MCP Tool Definitions
- *
- * Defines the tools exposed by the SpecShip MCP server.
- */
-import type SpecShip from '../index';
-import type { PendingFile } from '../sync';
-/**
- * Calculate the recommended number of specship_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 `specship_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;
-    /**
-     * Hard-drop test/spec/icon/i18n files from the relevant-file set unless
-     * the query itself mentions tests. Today they're only deprioritized in
-     * the sort, which on tiny repos still lets one slip into the top N (e.g.
-     * cobra's `command_test.go` displaced `args.go` and contributed ~10KB of
-     * pure noise to "How does cobra parse commands?"). Off by default; on
-     * for the very-tiny tier where one slip dominates the budget.
-     */
-    excludeLowValueFiles: boolean;
-}
-export declare function getExploreOutputBudget(fileCount: number): ExploreOutputBudget;
-/**
- * Per-file staleness banner emitted at the top of a tool response when the
- * file watcher has pending events for files referenced by the response.
- * The agent uses this to fall back to Read for those specific files
- * without waiting for the debounced sync (issue #403).
- */
-export declare function formatStaleBanner(stale: PendingFile[]): string;
-/**
- * Compact footer listing pending files that are NOT referenced in this
- * response. Gives the agent a complete project-wide freshness picture
- * without bloating the main banner.
- */
-export declare function formatStaleFooter(stale: PendingFile[]): string;
-/**
- * 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;
-}
-export declare const tools: ToolDefinition[];
-/**
- * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
- * proxy answers `tools/list` with before any project is open. Mirrors
- * `ToolHandler.getTools()` in the no-SpecShip case (the dynamic per-repo budget
- * note in a description only adds once `cg` is loaded; the schemas are static).
- */
-export declare function getStaticTools(): ToolDefinition[];
-/**
- * Tool handler that executes tools against a SpecShip 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;
-    private worktreeMismatchCache;
-    private catchUpGate;
-    constructor(cg: SpecShip | null);
-    /**
-     * Update the default SpecShip instance (e.g. after lazy initialization)
-     */
-    setDefaultSpecShip(cg: SpecShip): void;
-    /**
-     * Engine-only: register the catch-up sync promise so the next `execute()`
-     * call awaits it before serving. The handler swallows rejections (the
-     * engine logs them) so a sync failure never propagates as a tool error;
-     * we still want to serve a best-effort result over the same potentially-
-     * stale data, which is what would have happened without the gate.
-     */
-    setCatchUpGate(p: Promise<void> | null): 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 SpecShip instance is available
-     */
-    hasDefaultSpecShip(): boolean;
-    /**
-     * Optional allowlist of exposed tools, parsed from the SPECSHIP_MCP_TOOLS
-     * env var (comma-separated short names, e.g. "trace,search,node,context").
-     * Unset/empty → every tool is exposed. Lets an operator (or an A/B harness)
-     * trim the tool surface without rebuilding the client config; the ablated
-     * tool is then truly absent from ListTools rather than merely denied on call.
-     * Matching is on the short form, so "node" and "specship_node" both work.
-     */
-    private toolAllowlist;
-    /** Whether a tool name passes the SPECSHIP_MCP_TOOLS allowlist (if any). */
-    private isToolAllowed;
-    /**
-     * Get tool definitions with dynamic descriptions based on project size.
-     * The specship_explore tool description includes a budget recommendation
-     * scaled to the number of indexed files. Honors the SPECSHIP_MCP_TOOLS
-     * allowlist so a trimmed surface is reflected in ListTools.
-     */
-    getTools(): ToolDefinition[];
-    /**
-     * Get SpecShip instance for a project
-     *
-     * If projectPath is provided, opens that project's SpecShip (cached).
-     * Otherwise returns the default SpecShip instance.
-     *
-     * Walks up parent directories to find the nearest .specship/ folder,
-     * similar to how git finds .git/ directories.
-     */
-    private getSpecShip;
-    /**
-     * 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;
-    /**
-     * Cached git worktree/index mismatch for a tool call's effective project.
-     *
-     * The "effective project" is what the request targets: an explicit
-     * `projectPath` arg, else the directory the server resolved its default
-     * project from (`defaultProjectHint`), else cwd. Memoized per start path —
-     * see `worktreeMismatchCache`. Best-effort: if the project can't be resolved
-     * (e.g. nothing initialized yet), it reports "no mismatch" so a tool is never
-     * broken by this check.
-     */
-    private worktreeMismatchFor;
-    /**
-     * Prefix a successful read-tool result with a compact worktree-mismatch
-     * notice when the resolved index belongs to a different git working tree than
-     * the caller's (issue #155). Without this, an agent in a nested worktree
-     * silently trusts main-branch results. No-op on error results and when there
-     * is no mismatch. `specship_status` is excluded — it embeds its own verbose
-     * warning — so it stays out of this path.
-     */
-    private withWorktreeNotice;
-    /**
-     * Annotate a successful read-tool result with per-file staleness — the
-     * non-blocking answer to issue #403. The file watcher tracks every event
-     * it sees per path; here we intersect "files referenced in this response"
-     * against that pending set and prepend a compact banner so the agent can
-     * fall back to Read for those *specific* files without waiting for the
-     * debounced sync to fire. Other pending files in the project (not
-     * referenced by this response) get a small footer so the agent has a
-     * complete picture without bloating the banner.
-     *
-     * Cost when nothing is pending — the common case — is one boolean check.
-     * No I/O, no parsing of markdown beyond a per-pending-file substring scan.
-     */
-    private withStalenessNotice;
-    /**
-     * Execute a tool by name
-     */
-    execute(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
-    /**
-     * Handle specship_search
-     */
-    private handleSearch;
-    /**
-     * Handle specship_callers
-     */
-    private handleCallers;
-    /**
-     * Handle specship_callees
-     */
-    private handleCallees;
-    /**
-     * Handle specship_impact
-     */
-    private handleImpact;
-    /**
-     * Describe a synthesized (dynamic-dispatch) edge for human output: how the
-     * callback was wired up — the bridge static parsing can't see. Returns null
-     * for ordinary static edges. Used by trace + the node trail so a synthesized
-     * hop reads as "registered via onUpdate at App.tsx:3148", not a bare arrow.
-     */
-    private synthEdgeNote;
-    /**
-     * Flow-from-named-symbols: an agent's specship_explore query is a bag of
-     * symbol names that usually spans the flow it's investigating (e.g.
-     * "PmsProductController getList PmsProductService list PmsProductServiceImpl").
-     * Surface the longest call chain AMONG those named symbols — scoped to what the
-     * agent explicitly named, so (unlike a fuzzy relevance set) there's no
-     * wrong-feature wandering. Rides synthesized edges, so controller→service-
-     * interface→impl shows up. Returns '' if no chain of >=3 nodes exists.
-     *
-     * Ambiguous tokens (Java `list` → dozens of nodes) are disambiguated by
-     * CO-NAMING: the agent names the class too, so we keep only `list` candidates
-     * whose qualifiedName contains another named token (`PmsProductServiceImpl::list`),
-     * dropping unrelated `OmsOrderService::list`.
-     */
-    private buildFlowFromNamedSymbols;
-    /**
-     * Compact "blast radius" for the entry symbols of an explore result: who
-     * depends on each (callers) and which test files cover it — LOCATIONS ONLY,
-     * no source, so the agent knows what to update / re-verify before editing
-     * without reaching for a separate impact call. Always-on, but skips symbols
-     * that have no dependents (nothing to warn about), and returns '' when none
-     * qualify so a leaf-only exploration stays clean.
-     */
-    private buildBlastRadiusSection;
-    /**
-     * Graph-connectivity relevance via Random-Walk-with-Restart (personalized
-     * PageRank) from the query's matched SEED nodes over the call/reference graph.
-     *
-     * This is the ranking signal text search (FTS/bm25) CANNOT provide, and it's
-     * specship's home turf: relevance by STRUCTURE, not words. A file whose
-     * symbols are call-connected to the matched cluster accrues walk mass and
-     * ranks high; a lone TEXT match — e.g. `LensSwitcher.swift` matched the word
-     * "switch" from `switchOrganization`, but calls none of `setUser`/`fetchUser`
-     * — gets only its own restart probability and ranks ~0. Immune to the
-     * tokenization trap that fools term matching, deterministic, no embeddings.
-     *
-     * Undirected adjacency (reachability both ways), restart α=0.25 to the seeds,
-     * power iteration to convergence. Bounded to the already-relevant subgraph, so
-     * it's a few hundred nodes × ~25 iterations — negligible cost.
-     */
-    private computeGraphRelevance;
-    /**
-     * Handle specship_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 specship_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 specship_node
-     */
-    private handleNode;
-    /** Render one symbol: details + (optional) body/outline + its caller/callee trail. */
-    private renderNodeSection;
-    /**
-     * Build the "trail" for a symbol: its direct callees (what it calls) and
-     * callers (what calls it), each with file:line — so specship_node doubles as
-     * the structural Grep→Read→expand primitive: a spot PLUS where to go next.
-     * Capped to stay cheap. Walk the graph by calling specship_node on a trail
-     * entry; no Read needed for covered hops. Empty edges on a non-leaf often mean
-     * dynamic dispatch the static graph couldn't resolve — that absence is itself
-     * a signal (read that one hop) rather than a dead end.
-     */
-    private formatTrail;
-    /**
-     * Handle specship_status
-     */
-    private handleStatus;
-    /**
-     * Handle specship_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;
-    /**
-     * Find ALL definitions matching a name, ranked, so specship_node can return
-     * every overload instead of guessing one (the wrong guess → a Read). Keepers
-     * rank before generated stubs (.pb.go etc.); stable within a group preserves
-     * FTS order. Returns [] when nothing matches; a qualified lookup that finds no
-     * exact match returns [] rather than a misleading fuzzy file hit (#173); a
-     * bare name with no exact match falls back to the single top fuzzy result.
-     */
-    private findSymbolMatches;
-    /**
-     * 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 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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"}