trace-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,656 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import Database from 'better-sqlite3';
+import { Result } from 'neverthrow';
+import { z } from 'zod';
+
+type TraceMcpError = {
+    code: 'PARSE_ERROR';
+    file: string;
+    partial: boolean;
+    message: string;
+} | {
+    code: 'NOT_FOUND';
+    id: string;
+    candidates?: string[];
+} | {
+    code: 'RESOLUTION_FAILED';
+    path: string;
+    message: string;
+} | {
+    code: 'TIMEOUT';
+    operation: string;
+    ms: number;
+} | {
+    code: 'SECURITY_VIOLATION';
+    detail: string;
+} | {
+    code: 'PLUGIN_ERROR';
+    plugin: string;
+    message: string;
+} | {
+    code: 'DB_ERROR';
+    message: string;
+} | {
+    code: 'CONFIG_ERROR';
+    message: string;
+} | {
+    code: 'VALIDATION_ERROR';
+    message: string;
+    details?: unknown;
+};
+type TraceMcpResult<T> = Result<T, TraceMcpError>;
+
+interface NodeTypeDeclaration {
+    name: string;
+}
+interface EdgeTypeDeclaration {
+    name: string;
+    category: string;
+    directed?: boolean;
+    description?: string;
+}
+interface RawSymbol {
+    symbolId: string;
+    name: string;
+    kind: SymbolKind;
+    fqn?: string;
+    parentSymbolId?: string;
+    signature?: string;
+    byteStart: number;
+    byteEnd: number;
+    lineStart?: number;
+    lineEnd?: number;
+    metadata?: Record<string, unknown>;
+}
+type SymbolKind = 'class' | 'method' | 'function' | 'constant' | 'property' | 'interface' | 'trait' | 'enum' | 'type' | 'variable' | 'enum_case' | 'namespace' | 'decorator';
+interface RawEdge {
+    sourceSymbolId?: string;
+    sourceNodeType?: string;
+    sourceRefId?: number;
+    targetSymbolId?: string;
+    targetNodeType?: string;
+    targetRefId?: number;
+    edgeType: string;
+    resolved?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface RawRoute {
+    method: string;
+    uri: string;
+    name?: string;
+    controllerSymbolId?: string;
+    handler?: string;
+    middleware?: string[];
+    fileId?: number;
+    line?: number;
+    metadata?: Record<string, unknown>;
+}
+interface RawComponent {
+    name: string;
+    kind: 'page' | 'component' | 'layout' | 'context' | 'provider' | 'hook';
+    props?: Record<string, unknown>;
+    emits?: string[];
+    slots?: string[];
+    composables?: string[];
+    framework: string;
+}
+interface RawMigration {
+    tableName: string;
+    operation: 'create' | 'alter' | 'drop';
+    columns?: Record<string, unknown>[];
+    indices?: Record<string, unknown>[];
+    timestamp?: string;
+}
+interface RawOrmModel {
+    name: string;
+    orm: 'mongoose' | 'sequelize' | 'sqlalchemy' | 'django' | 'prisma' | 'typeorm' | 'drizzle';
+    collectionOrTable?: string;
+    fields?: Record<string, unknown>[];
+    options?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+interface RawOrmAssociation {
+    sourceModelName: string;
+    targetModelName: string;
+    kind: string;
+    options?: Record<string, unknown>;
+    line?: number;
+}
+interface RawRnScreen {
+    name: string;
+    componentPath?: string;
+    navigatorType?: 'stack' | 'tab' | 'drawer' | 'native-stack';
+    options?: Record<string, unknown>;
+    deepLink?: string;
+    metadata?: Record<string, unknown>;
+}
+interface FileParseResult {
+    language?: string;
+    frameworkRole?: string;
+    status: 'ok' | 'partial' | 'error';
+    symbols: RawSymbol[];
+    edges?: RawEdge[];
+    routes?: RawRoute[];
+    components?: RawComponent[];
+    migrations?: RawMigration[];
+    ormModels?: RawOrmModel[];
+    ormAssociations?: RawOrmAssociation[];
+    rnScreens?: RawRnScreen[];
+    warnings?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface PluginManifest {
+    name: string;
+    version: string;
+    priority: number;
+    dependencies?: string[];
+}
+interface ProjectContext {
+    rootPath: string;
+    composerJson?: Record<string, unknown>;
+    packageJson?: Record<string, unknown>;
+    pyprojectToml?: Record<string, unknown>;
+    requirementsTxt?: string[];
+    configFiles: string[];
+}
+interface LanguagePlugin {
+    manifest: PluginManifest;
+    supportedExtensions: string[];
+    extractSymbols(filePath: string, content: Buffer): TraceMcpResult<FileParseResult>;
+}
+interface FrameworkPlugin {
+    manifest: PluginManifest;
+    detect(ctx: ProjectContext): boolean;
+    registerSchema(): {
+        nodeTypes?: NodeTypeDeclaration[];
+        edgeTypes?: EdgeTypeDeclaration[];
+    };
+    extractNodes?(filePath: string, content: Buffer, language: string): TraceMcpResult<FileParseResult>;
+    resolveEdges?(ctx: ResolveContext): TraceMcpResult<RawEdge[]>;
+    configure?(config: Record<string, unknown>): void;
+}
+interface ResolveContext {
+    rootPath: string;
+    getAllFiles(): {
+        id: number;
+        path: string;
+        language: string | null;
+    }[];
+    getSymbolsByFile(fileId: number): {
+        id: number;
+        symbolId: string;
+        name: string;
+        kind: string;
+        fqn: string | null;
+        lineStart?: number | null;
+        lineEnd?: number | null;
+        metadata?: Record<string, unknown> | null;
+    }[];
+    getSymbolByFqn(fqn: string): {
+        id: number;
+        symbolId: string;
+    } | undefined;
+    getNodeId(nodeType: string, refId: number): number | undefined;
+    createNodeIfNeeded(nodeType: string, refId: number): number;
+    /** Read file content — uses Pass 1 cache when available, falls back to disk. */
+    readFile(relPath: string): string | undefined;
+}
+
+declare class Store {
+    readonly db: Database.Database;
+    constructor(db: Database.Database);
+    insertFile(path: string, language: string | null, contentHash: string | null, byteLength: number | null, workspace?: string | null): number;
+    getFile(path: string): FileRow | undefined;
+    getFileById(id: number): FileRow | undefined;
+    getAllFiles(): FileRow[];
+    updateFileWorkspace(fileId: number, workspace: string): void;
+    getFilesByWorkspace(workspace: string): FileRow[];
+    updateFileHash(fileId: number, hash: string, byteLength: number): void;
+    updateFileStatus(fileId: number, status: string, frameworkRole?: string): void;
+    deleteFile(fileId: number): void;
+    /** Delete routes, components, migrations, ORM models, and RN screens for a file (and their nodes). */
+    deleteEntitiesByFile(fileId: number): void;
+    insertSymbol(fileId: number, sym: RawSymbol): number;
+    insertSymbols(fileId: number, symbols: RawSymbol[]): number[];
+    deleteSymbolsByFile(fileId: number): void;
+    getSymbolsByFile(fileId: number): SymbolRow[];
+    getSymbolBySymbolId(symbolId: string): SymbolRow | undefined;
+    getSymbolByFqn(fqn: string): SymbolRow | undefined;
+    createNode(nodeType: string, refId: number): number;
+    getNodeId(nodeType: string, refId: number): number | undefined;
+    insertEdge(sourceNodeId: number, targetNodeId: number, edgeTypeName: string, resolved?: boolean, metadata?: Record<string, unknown>, isCrossWs?: boolean): TraceMcpResult<number>;
+    deleteEdgesForFileNodes(fileId: number): void;
+    traverseEdges(startNodeId: number, direction: 'outgoing' | 'incoming', depth: number): EdgeRow[];
+    insertRoute(route: RawRoute, fileId: number): number;
+    insertComponent(comp: RawComponent, fileId: number): number;
+    getComponentByFileId(fileId: number): ComponentRow | undefined;
+    getComponentByName(name: string): ComponentRow | undefined;
+    getAllComponents(): ComponentRow[];
+    /** Ensure an edge type exists in the database, inserting if missing. */
+    ensureEdgeType(name: string, category: string, description: string): void;
+    /** Get the edge type name by its id */
+    getEdgeTypeName(edgeTypeId: number): string | undefined;
+    /** Reverse-lookup: find which symbol/file a node refers to */
+    getNodeRef(nodeId: number): {
+        nodeType: string;
+        refId: number;
+    } | undefined;
+    insertMigration(mig: RawMigration, fileId: number): number;
+    getRouteByUriAndMethod(uri: string, method: string): RouteRow | undefined;
+    getAllRoutes(): RouteRow[];
+    findRouteByPattern(uri: string, method: string): RouteRow | undefined;
+    getMigrationsByTable(tableName: string): MigrationRow[];
+    getAllMigrations(): MigrationRow[];
+    getEdgesByType(edgeTypeName: string): EdgeRow[];
+    getOutgoingEdges(nodeId: number): (EdgeRow & {
+        edge_type_name: string;
+    })[];
+    getIncomingEdges(nodeId: number): (EdgeRow & {
+        edge_type_name: string;
+    })[];
+    insertOrmModel(model: RawOrmModel, fileId: number): number;
+    getOrmModelByName(name: string): OrmModelRow | undefined;
+    getOrmModelsByOrm(orm: string): OrmModelRow[];
+    getAllOrmModels(): OrmModelRow[];
+    insertOrmAssociation(sourceModelId: number, targetModelId: number | null, targetModelName: string, kind: string, options?: Record<string, unknown>, fileId?: number, line?: number): number;
+    getAllOrmAssociations(): OrmAssociationRow[];
+    getOrmAssociationsByModel(modelId: number): OrmAssociationRow[];
+    insertRnScreen(screen: RawRnScreen, fileId: number): number;
+    getRnScreenByName(name: string): RnScreenRow | undefined;
+    getAllRnScreens(): RnScreenRow[];
+    getSymbolById(id: number): SymbolRow | undefined;
+    getNodeByNodeId(nodeId: number): {
+        node_type: string;
+        ref_id: number;
+    } | undefined;
+    findImplementors(name: string): SymbolWithFilePath[];
+    getExportedSymbols(filePattern?: string): SymbolWithFilePath[];
+    getEdgeTypes(): EdgeTypeRow[];
+    /**
+     * Get all symbols that have heritage metadata (extends/implements).
+     * Used by the TypeScript heritage resolver in the pipeline.
+     */
+    getSymbolsWithHeritage(): (SymbolRow & {
+        file_path: string;
+    })[];
+    /**
+     * Find a symbol by name and optional kind.
+     * Returns the first match (prefers exact name match over substring).
+     */
+    getSymbolByName(name: string, kind?: string): SymbolRow | undefined;
+    /** Resolve multiple node IDs in one query. Returns Map<refId, nodeId>. */
+    getNodeIdsBatch(nodeType: string, refIds: number[]): Map<number, number>;
+    /** Resolve multiple node refs in one query. Returns Map<nodeId, {nodeType, refId}>. */
+    getNodeRefsBatch(nodeIds: number[]): Map<number, {
+        nodeType: string;
+        refId: number;
+    }>;
+    /** Batch-fetch symbols by internal IDs. Returns Map<id, SymbolRow>. */
+    getSymbolsByIds(ids: number[]): Map<number, SymbolRow>;
+    /** Batch-fetch files by internal IDs. Returns Map<id, FileRow>. */
+    getFilesByIds(ids: number[]): Map<number, FileRow>;
+    /**
+     * Fetch all edges where any of the given node IDs appear as source or target.
+     * Returns edges annotated with edge_type_name and the pivot node id (the one from the input set).
+     */
+    getEdgesForNodesBatch(nodeIds: number[]): Array<EdgeRow & {
+        edge_type_name: string;
+        pivot_node_id: number;
+    }>;
+    /** Find a class/interface symbol by name with optional framework_role filter. Single query with JOIN. */
+    findSymbolByRole(name: string, frameworkRole?: string): SymbolRow | undefined;
+    insertEnvVar(fileId: number, entry: {
+        key: string;
+        valueType: string;
+        valueFormat: string | null;
+        comment: string | null;
+        quoted: boolean;
+        line: number;
+    }): number;
+    deleteEnvVarsByFile(fileId: number): void;
+    getEnvVarsByFile(fileId: number): EnvVarRow[];
+    getAllEnvVars(): (EnvVarRow & {
+        file_path: string;
+    })[];
+    searchEnvVars(pattern: string): (EnvVarRow & {
+        file_path: string;
+    })[];
+    updateSymbolSummary(symbolId: number, summary: string): void;
+    getUnsummarizedSymbols(kinds: string[], limit: number): {
+        id: number;
+        name: string;
+        fqn: string | null;
+        kind: string;
+        signature: string | null;
+        file_path: string;
+        byte_start: number;
+        byte_end: number;
+    }[];
+    getStats(): IndexStats;
+}
+interface FileRow {
+    id: number;
+    path: string;
+    language: string | null;
+    framework_role: string | null;
+    status: string;
+    content_hash: string | null;
+    byte_length: number | null;
+    indexed_at: string;
+    metadata: string | null;
+    workspace: string | null;
+}
+interface SymbolRow {
+    id: number;
+    file_id: number;
+    symbol_id: string;
+    name: string;
+    kind: string;
+    fqn: string | null;
+    parent_id: number | null;
+    signature: string | null;
+    summary: string | null;
+    byte_start: number;
+    byte_end: number;
+    line_start: number | null;
+    line_end: number | null;
+    metadata: string | null;
+}
+interface EdgeRow {
+    id: number;
+    source_node_id: number;
+    target_node_id: number;
+    edge_type_id: number;
+    resolved: number;
+    metadata: string | null;
+    is_cross_ws: number;
+}
+interface RouteRow {
+    id: number;
+    method: string;
+    uri: string;
+    name: string | null;
+    handler: string | null;
+    controller_symbol_id: string | null;
+    middleware: string | null;
+    metadata: string | null;
+    file_id: number | null;
+    line: number | null;
+}
+interface MigrationRow {
+    id: number;
+    file_id: number;
+    table_name: string;
+    operation: string;
+    columns: string | null;
+    indices: string | null;
+    timestamp: string | null;
+}
+interface ComponentRow {
+    id: number;
+    file_id: number;
+    name: string;
+    kind: string;
+    props: string | null;
+    emits: string | null;
+    slots: string | null;
+    composables: string | null;
+    framework: string;
+}
+interface OrmModelRow {
+    id: number;
+    file_id: number;
+    name: string;
+    orm: string;
+    collection_or_table: string | null;
+    fields: string | null;
+    options: string | null;
+    metadata: string | null;
+}
+interface OrmAssociationRow {
+    id: number;
+    source_model_id: number;
+    target_model_id: number | null;
+    target_model_name: string | null;
+    kind: string;
+    options: string | null;
+    file_id: number | null;
+    line: number | null;
+}
+interface RnScreenRow {
+    id: number;
+    file_id: number;
+    name: string;
+    component_path: string | null;
+    navigator_type: string | null;
+    options: string | null;
+    deep_link: string | null;
+    metadata: string | null;
+}
+interface EnvVarRow {
+    id: number;
+    file_id: number;
+    key: string;
+    value_type: string;
+    value_format: string | null;
+    comment: string | null;
+    quoted: number;
+    line: number | null;
+}
+interface SymbolWithFilePath extends SymbolRow {
+    file_path: string;
+}
+interface EdgeTypeRow {
+    name: string;
+    category: string;
+    description: string;
+}
+interface IndexStats {
+    totalFiles: number;
+    totalSymbols: number;
+    totalEdges: number;
+    totalNodes: number;
+    totalRoutes: number;
+    totalComponents: number;
+    totalMigrations: number;
+    partialFiles: number;
+    errorFiles: number;
+}
+
+declare class PluginRegistry {
+    private languagePlugins;
+    private frameworkPlugins;
+    registerLanguagePlugin(plugin: LanguagePlugin): void;
+    registerFrameworkPlugin(plugin: FrameworkPlugin): void;
+    getLanguagePlugins(): LanguagePlugin[];
+    getActiveFrameworkPlugins(ctx: ProjectContext): TraceMcpResult<FrameworkPlugin[]>;
+    getAllFrameworkPlugins(): FrameworkPlugin[];
+    getLanguagePluginForFile(filePath: string): LanguagePlugin | undefined;
+    private sortByPriority;
+    private topologicalSort;
+}
+
+declare const TraceMcpConfigSchema: z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+    include: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    db: z.ZodDefault<z.ZodObject<{
+        path: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+    }, {
+        path?: string | undefined;
+    }>>;
+    frameworks: z.ZodOptional<z.ZodObject<{
+        laravel: z.ZodOptional<z.ZodObject<{
+            artisan: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+                timeout: z.ZodDefault<z.ZodNumber>;
+            }, "strip", z.ZodTypeAny, {
+                enabled: boolean;
+                timeout: number;
+            }, {
+                enabled?: boolean | undefined;
+                timeout?: number | undefined;
+            }>>;
+            graceful_degradation: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            graceful_degradation: boolean;
+            artisan?: {
+                enabled: boolean;
+                timeout: number;
+            } | undefined;
+        }, {
+            artisan?: {
+                enabled?: boolean | undefined;
+                timeout?: number | undefined;
+            } | undefined;
+            graceful_degradation?: boolean | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        laravel?: {
+            graceful_degradation: boolean;
+            artisan?: {
+                enabled: boolean;
+                timeout: number;
+            } | undefined;
+        } | undefined;
+    }, {
+        laravel?: {
+            artisan?: {
+                enabled?: boolean | undefined;
+                timeout?: number | undefined;
+            } | undefined;
+            graceful_degradation?: boolean | undefined;
+        } | undefined;
+    }>>;
+    ai: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        provider: z.ZodDefault<z.ZodEnum<["ollama", "openai"]>>;
+        base_url: z.ZodOptional<z.ZodString>;
+        api_key: z.ZodOptional<z.ZodString>;
+        inference_model: z.ZodOptional<z.ZodString>;
+        fast_model: z.ZodOptional<z.ZodString>;
+        embedding_model: z.ZodOptional<z.ZodString>;
+        embedding_dimensions: z.ZodOptional<z.ZodNumber>;
+        summarize_on_index: z.ZodDefault<z.ZodBoolean>;
+        summarize_batch_size: z.ZodDefault<z.ZodNumber>;
+        summarize_kinds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        reranker_model: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        provider: "ollama" | "openai";
+        summarize_on_index: boolean;
+        summarize_batch_size: number;
+        summarize_kinds: string[];
+        base_url?: string | undefined;
+        api_key?: string | undefined;
+        inference_model?: string | undefined;
+        fast_model?: string | undefined;
+        embedding_model?: string | undefined;
+        embedding_dimensions?: number | undefined;
+        reranker_model?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        provider?: "ollama" | "openai" | undefined;
+        base_url?: string | undefined;
+        api_key?: string | undefined;
+        inference_model?: string | undefined;
+        fast_model?: string | undefined;
+        embedding_model?: string | undefined;
+        embedding_dimensions?: number | undefined;
+        summarize_on_index?: boolean | undefined;
+        summarize_batch_size?: number | undefined;
+        summarize_kinds?: string[] | undefined;
+        reranker_model?: string | undefined;
+    }>>;
+    plugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    security: z.ZodOptional<z.ZodObject<{
+        secret_patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        max_file_size_bytes: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        secret_patterns?: string[] | undefined;
+        max_file_size_bytes?: number | undefined;
+    }, {
+        secret_patterns?: string[] | undefined;
+        max_file_size_bytes?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    root: string;
+    include: string[];
+    exclude: string[];
+    db: {
+        path: string;
+    };
+    plugins: string[];
+    frameworks?: {
+        laravel?: {
+            graceful_degradation: boolean;
+            artisan?: {
+                enabled: boolean;
+                timeout: number;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+    ai?: {
+        enabled: boolean;
+        provider: "ollama" | "openai";
+        summarize_on_index: boolean;
+        summarize_batch_size: number;
+        summarize_kinds: string[];
+        base_url?: string | undefined;
+        api_key?: string | undefined;
+        inference_model?: string | undefined;
+        fast_model?: string | undefined;
+        embedding_model?: string | undefined;
+        embedding_dimensions?: number | undefined;
+        reranker_model?: string | undefined;
+    } | undefined;
+    security?: {
+        secret_patterns?: string[] | undefined;
+        max_file_size_bytes?: number | undefined;
+    } | undefined;
+}, {
+    root?: string | undefined;
+    include?: string[] | undefined;
+    exclude?: string[] | undefined;
+    db?: {
+        path?: string | undefined;
+    } | undefined;
+    frameworks?: {
+        laravel?: {
+            artisan?: {
+                enabled?: boolean | undefined;
+                timeout?: number | undefined;
+            } | undefined;
+            graceful_degradation?: boolean | undefined;
+        } | undefined;
+    } | undefined;
+    ai?: {
+        enabled?: boolean | undefined;
+        provider?: "ollama" | "openai" | undefined;
+        base_url?: string | undefined;
+        api_key?: string | undefined;
+        inference_model?: string | undefined;
+        fast_model?: string | undefined;
+        embedding_model?: string | undefined;
+        embedding_dimensions?: number | undefined;
+        summarize_on_index?: boolean | undefined;
+        summarize_batch_size?: number | undefined;
+        summarize_kinds?: string[] | undefined;
+        reranker_model?: string | undefined;
+    } | undefined;
+    plugins?: string[] | undefined;
+    security?: {
+        secret_patterns?: string[] | undefined;
+        max_file_size_bytes?: number | undefined;
+    } | undefined;
+}>;
+type TraceMcpConfig = z.infer<typeof TraceMcpConfigSchema>;
+declare function loadConfig(searchFrom?: string): Promise<TraceMcpResult<TraceMcpConfig>>;
+
+declare function createServer(store: Store, registry: PluginRegistry, config: TraceMcpConfig, rootPath?: string): McpServer;
+
+declare function initializeDatabase(dbPath: string): Database.Database;
+
+export { type FrameworkPlugin, type LanguagePlugin, type PluginManifest, PluginRegistry, Store, type TraceMcpConfig, type TraceMcpError, type TraceMcpResult, createServer, initializeDatabase, loadConfig };