dbgraph 0.1.0

package/dist/mcp/transport.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * MCP Transport Layer
+ *
+ * JSON-RPC over stdin/stdout for direct mode (MCP stdio transport).
+ * JSON-RPC over Unix sockets / named pipes for daemon mode.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketTransport = exports.StdioTransport = exports.ErrorCodes = void 0;
+exports.getDaemonSocketPath = getDaemonSocketPath;
+exports.getDaemonPidPath = getDaemonPidPath;
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+var ErrorCodes;
+(function (ErrorCodes) {
+    ErrorCodes[ErrorCodes["ParseError"] = -32700] = "ParseError";
+    ErrorCodes[ErrorCodes["InvalidRequest"] = -32600] = "InvalidRequest";
+    ErrorCodes[ErrorCodes["MethodNotFound"] = -32601] = "MethodNotFound";
+    ErrorCodes[ErrorCodes["InvalidParams"] = -32602] = "InvalidParams";
+    ErrorCodes[ErrorCodes["InternalError"] = -32603] = "InternalError";
+})(ErrorCodes || (exports.ErrorCodes = ErrorCodes = {}));
+// =============================================================================
+// Stdio Transport (direct MCP mode)
+// =============================================================================
+class StdioTransport {
+    handler = null;
+    buffer = '';
+    stopped = false;
+    start(handler) {
+        this.handler = handler;
+        process.stdin.on('data', this.onData);
+        process.stdin.on('end', this.onEnd);
+        process.stdin.setEncoding('utf-8');
+    }
+    onData = (chunk) => {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() ?? '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const message = JSON.parse(trimmed);
+                this.handler?.(message);
+            }
+            catch {
+                this.sendError(0, ErrorCodes.ParseError, 'Failed to parse JSON');
+            }
+        }
+    };
+    onEnd = () => {
+        this.stopped = true;
+    };
+    sendResult(id, result) {
+        this.write({ jsonrpc: '2.0', id, result });
+    }
+    sendError(id, code, message, data) {
+        this.write({ jsonrpc: '2.0', id, error: { code, message, data } });
+    }
+    sendNotification(method, params) {
+        this.write({ jsonrpc: '2.0', method, params });
+    }
+    stop() {
+        this.stopped = true;
+        process.stdin.removeListener('data', this.onData);
+        process.stdin.removeListener('end', this.onEnd);
+    }
+    write(msg) {
+        if (this.stopped)
+            return;
+        const raw = JSON.stringify(msg) + '\n';
+        process.stdout.write(raw);
+    }
+}
+exports.StdioTransport = StdioTransport;
+// =============================================================================
+// Socket Transport (daemon mode)
+// =============================================================================
+class SocketTransport {
+    socket;
+    handler = null;
+    buffer = '';
+    stopped = false;
+    constructor(socket) {
+        this.socket = socket;
+    }
+    start(handler) {
+        this.handler = handler;
+        this.socket.on('data', this.onData);
+        this.socket.on('close', this.onClose);
+        this.socket.setEncoding('utf-8');
+    }
+    onData = (chunk) => {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() ?? '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const message = JSON.parse(trimmed);
+                this.handler?.(message);
+            }
+            catch {
+                this.sendError(0, ErrorCodes.ParseError, 'Failed to parse JSON');
+            }
+        }
+    };
+    onClose = () => {
+        this.stopped = true;
+    };
+    sendResult(id, result) {
+        if (!this.stopped)
+            this.socket.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
+    }
+    sendError(id, code, message, data) {
+        if (!this.stopped)
+            this.socket.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message, data } }) + '\n');
+    }
+    sendNotification(method, params) {
+        if (!this.stopped)
+            this.socket.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
+    }
+    stop() {
+        this.stopped = true;
+        this.socket.removeListener('data', this.onData);
+        this.socket.removeListener('close', this.onClose);
+        if (!this.socket.destroyed)
+            this.socket.destroy();
+    }
+}
+exports.SocketTransport = SocketTransport;
+// =============================================================================
+// Daemon path utilities
+// =============================================================================
+function getDaemonSocketPath(projectRoot) {
+    const dir = path.join(projectRoot, '.dbgraph');
+    // Use a hash to avoid path-length issues on Windows
+    const hash = Buffer.from(projectRoot).toString('base64').replace(/[/+=]/g, '_');
+    return os.platform() === 'win32'
+        ? path.join(dir, `dbgraph-${hash}.pipe`)
+        : path.join(dir, `dbgraph-${hash}.sock`);
+}
+function getDaemonPidPath(projectRoot) {
+    return path.join(projectRoot, '.dbgraph', 'daemon.pid');
+}
+//# sourceMappingURL=transport.js.map

package/dist/mcp/transport.js.map

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

package/dist/search/query-parser.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Query Parser
+ *
+ * Parses search queries for structured field filters. Users can narrow
+ * results by prefixing terms with field selectors:
+ *
+ *   kind:table     — filter by node kind (table, column, index, …)
+ *   source:prod    — filter by database source alias
+ *   name:orders    — filter by object name
+ *
+ * Examples:
+ *   "kind:table name:orders"         → text=""        kinds=["table"]    nameFilters=["orders"]
+ *   "orders kind:column"             → text="orders"  kinds=["column"]   nameFilters=[]
+ *   "source:prod kind:table user"    → text="user"    kinds=["table"]    sources=["prod"]
+ *   "kind:table kind:index name:pk"  → text=""        kinds=["table","index"] nameFilters=["pk"]
+ */
+export interface ParsedQuery {
+    /** The remaining query text after all field filters have been extracted */
+    text: string;
+    /** Values from `kind:` filters (e.g., ["table", "column"]) */
+    kinds: string[];
+    /** Values from `source:` filters (e.g., ["prod", "analytics"]) */
+    sources: string[];
+    /** Values from `name:` filters (e.g., ["orders", "users"]) */
+    nameFilters: string[];
+}
+/**
+ * Parse a search query and extract structured field filters.
+ *
+ * The parser scans tokens from left to right:
+ *  1. Tokens matching `kind:<value>` are collected in `kinds`.
+ *  2. Tokens matching `source:<value>` are collected in `sources`.
+ *  3. Tokens matching `name:<value>` are collected in `nameFilters`.
+ *  4. All remaining tokens (non-field-filter) are joined and returned as `text`.
+ *
+ * Filters are case-insensitive for the field prefix but preserve the
+ * value casing for downstream matching.
+ *
+ * @param input - Raw search query string (e.g., `kind:table name:orders`)
+ * @returns A ParsedQuery with extracted filters and remaining text.
+ */
+export declare function parseQuery(input: string): ParsedQuery;
+/**
+ * Apply a parsed query to build a concise search string and derived options.
+ *
+ * @returns A search string (suitable for QueryBuilder.searchNodes) and an
+ *          optional set of SearchOptions overrides.
+ */
+export interface AppliedQuery {
+    searchText: string;
+    filterKinds?: string[];
+    filterSource?: string;
+    filterName?: string;
+}
+/**
+ * Convert a ParsedQuery into inputs for QueryBuilder.searchNodes.
+ *
+ * The `source:` filter maps directly to SearchOptions.source.
+ * The `kind:` filter maps to SearchOptions.kinds.
+ * The `name:` filter, if present, produces additional LIKE clauses.
+ *
+ * @param parsed - The parsed query from parseQuery()
+ * @returns An AppliedQuery with the text and filter overrides.
+ */
+export declare function applyParsedQuery(parsed: ParsedQuery): AppliedQuery;
+//# sourceMappingURL=query-parser.d.ts.map

package/dist/search/query-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-parser.d.ts","sourceRoot":"","sources":["../../src/search/query-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IAEb,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAgCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAgDrD;AAMD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAmBlE"}

package/dist/search/query-parser.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Query Parser
+ *
+ * Parses search queries for structured field filters. Users can narrow
+ * results by prefixing terms with field selectors:
+ *
+ *   kind:table     — filter by node kind (table, column, index, …)
+ *   source:prod    — filter by database source alias
+ *   name:orders    — filter by object name
+ *
+ * Examples:
+ *   "kind:table name:orders"         → text=""        kinds=["table"]    nameFilters=["orders"]
+ *   "orders kind:column"             → text="orders"  kinds=["column"]   nameFilters=[]
+ *   "source:prod kind:table user"    → text="user"    kinds=["table"]    sources=["prod"]
+ *   "kind:table kind:index name:pk"  → text=""        kinds=["table","index"] nameFilters=["pk"]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseQuery = parseQuery;
+exports.applyParsedQuery = applyParsedQuery;
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Known database object kinds that are valid for `kind:` filters.
+ * Derived from the NODE_KINDS union in types.ts.
+ */
+const VALID_KINDS = new Set([
+    'server',
+    'database',
+    'schema',
+    'table',
+    'view',
+    'column',
+    'index',
+    'trigger',
+    'stored_procedure',
+    'function',
+    'sequence',
+    'constraint',
+    'foreign_key',
+    'module',
+    'namespace',
+]);
+// =============================================================================
+// parseQuery
+// =============================================================================
+/**
+ * Parse a search query and extract structured field filters.
+ *
+ * The parser scans tokens from left to right:
+ *  1. Tokens matching `kind:<value>` are collected in `kinds`.
+ *  2. Tokens matching `source:<value>` are collected in `sources`.
+ *  3. Tokens matching `name:<value>` are collected in `nameFilters`.
+ *  4. All remaining tokens (non-field-filter) are joined and returned as `text`.
+ *
+ * Filters are case-insensitive for the field prefix but preserve the
+ * value casing for downstream matching.
+ *
+ * @param input - Raw search query string (e.g., `kind:table name:orders`)
+ * @returns A ParsedQuery with extracted filters and remaining text.
+ */
+function parseQuery(input) {
+    const result = {
+        text: '',
+        kinds: [],
+        sources: [],
+        nameFilters: [],
+    };
+    if (!input || input.trim().length === 0) {
+        return result;
+    }
+    // Normalize whitespace and split into tokens.
+    // Preserve quoted phrases as single tokens: `"order items"` stays together.
+    const tokens = tokenize(input);
+    const remainingTokens = [];
+    for (const token of tokens) {
+        // Try to match `field:value` patterns. Value can be quoted or unquoted.
+        const kindMatch = token.match(/^kind:(.+)$/i);
+        const sourceMatch = token.match(/^source:(.+)$/i);
+        const nameMatch = token.match(/^name:(.+)$/i);
+        if (kindMatch) {
+            const value = kindMatch[1].replace(/^["']|["']$/g, '').toLowerCase();
+            if (VALID_KINDS.has(value) && !result.kinds.includes(value)) {
+                result.kinds.push(value);
+            }
+            // Silently drop invalid kind values (don't add to remaining text)
+        }
+        else if (sourceMatch) {
+            const value = sourceMatch[1].replace(/^["']|["']$/g, '');
+            if (value.length > 0 && !result.sources.includes(value)) {
+                result.sources.push(value);
+            }
+        }
+        else if (nameMatch) {
+            const value = nameMatch[1].replace(/^["']|["']$/g, '');
+            if (value.length > 0 && !result.nameFilters.includes(value)) {
+                result.nameFilters.push(value);
+            }
+        }
+        else {
+            remainingTokens.push(token);
+        }
+    }
+    result.text = remainingTokens.join(' ').trim();
+    return result;
+}
+/**
+ * Convert a ParsedQuery into inputs for QueryBuilder.searchNodes.
+ *
+ * The `source:` filter maps directly to SearchOptions.source.
+ * The `kind:` filter maps to SearchOptions.kinds.
+ * The `name:` filter, if present, produces additional LIKE clauses.
+ *
+ * @param parsed - The parsed query from parseQuery()
+ * @returns An AppliedQuery with the text and filter overrides.
+ */
+function applyParsedQuery(parsed) {
+    const result = {
+        searchText: parsed.text,
+    };
+    if (parsed.kinds.length > 0) {
+        result.filterKinds = parsed.kinds;
+    }
+    if (parsed.sources.length > 0) {
+        // Use the first source filter; multiple sources would need OR logic
+        result.filterSource = parsed.sources[0];
+    }
+    if (parsed.nameFilters.length > 0) {
+        result.filterName = parsed.nameFilters.join(' ');
+    }
+    return result;
+}
+// =============================================================================
+// Tokenizer
+// =============================================================================
+/**
+ * Split input into tokens, respecting double-quoted and single-quoted phrases.
+ *
+ * "order items" → ["order items"]
+ * kind:table name:"order items" → ["kind:table", "name:order items"]
+ */
+function tokenize(input) {
+    const tokens = [];
+    const trimmed = input.trim();
+    if (trimmed.length === 0)
+        return tokens;
+    const re = /(?:[^\s"']+|"[^"]*"|'[^']*')+/g;
+    let match;
+    while ((match = re.exec(trimmed)) !== null) {
+        let token = match[0];
+        // Strip surrounding quotes from the entire token if it's quoted
+        if ((token.startsWith('"') && token.endsWith('"')) ||
+            (token.startsWith("'") && token.endsWith("'"))) {
+            token = token.slice(1, -1);
+        }
+        if (token.length > 0) {
+            tokens.push(token);
+        }
+    }
+    return tokens;
+}
+//# sourceMappingURL=query-parser.js.map

package/dist/search/query-parser.js.map

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

package/dist/search/query-utils.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Query Utilities
+ *
+ * Scoring and relevance helpers for search results. These functions provide
+ * small numeric boosts that can be composed with FTS5 scores to improve
+ * result ranking for database schema objects.
+ */
+import { SearchResult } from '../types';
+/**
+ * Boost score for certain node kinds.
+ *
+ * Tables and views get the highest boost (0.15), columns are next (0.12),
+ * indexes and constraints get a moderate boost (0.08), and utility objects
+ * like triggers / functions / sequences get a smaller boost (0.05–0.06).
+ * Schema and database container nodes get a minimal boost (0.03–0.04).
+ *
+ * @param kind - The node kind string (e.g., "table", "column", "index").
+ * @returns A bonus value in [0.02, 0.15] to add to the base score.
+ */
+export declare function kindBonus(kind: string): number;
+/**
+ * Boost score when the query matches part of the node's source path.
+ *
+ * The filePath field (stored as `source` in graph terminology) is a URI
+ * like `db://@prod/public` or `db://host:5432/dbname/schema`. When a
+ * query token matches part of this path, it indicates the user is
+ * narrowing their search to a specific database or schema.
+ *
+ * Matching logic:
+ *  - Exact match of any path segment → 0.10 boost.
+ *  - Prefix match of any path segment → 0.05 boost.
+ *  - Substring match anywhere in path → 0.02 boost.
+ *  - No match → 0.
+ *
+ * @param filePath - The node's source path (Node.filePath).
+ * @param query    - The raw search query text.
+ * @returns A bonus value in [0, 0.10].
+ */
+export declare function scorePathRelevance(filePath: string, query: string): number;
+/**
+ * Boost exact name matches over prefix or substring matches.
+ *
+ * When a query token matches a node's name with different degrees of
+ * specificity, this function returns a higher bonus for closer matches:
+ *
+ *  - Exact match (case-insensitive)         → 0.20
+ *  - Exact match of one token (multi-word)  → 0.15
+ *  - Prefix match (name starts with query)  → 0.10
+ *  - Substring match                        → 0.05
+ *  - No match                               → 0
+ *
+ * @param name  - The node's name (Node.name).
+ * @param query - The raw search query text.
+ * @returns A bonus value in [0, 0.20].
+ */
+export declare function nameMatchBonus(name: string, query: string): number;
+/**
+ * Compute an augmented score for a single search result by composing the
+ * base relevance score with the kind, path, and name bonuses.
+ *
+ * This is useful when re-ranking results after retrieving them from
+ * QueryBuilder.searchNodes.
+ *
+ * @param result   - A SearchResult from QueryBuilder.
+ * @param query    - The original query text (for name/path relevance).
+ * @returns A new score with all applicable bonuses added.
+ */
+export declare function computeAugmentedScore(result: SearchResult, query: string): number;
+/**
+ * Re-rank an array of SearchResults by their augmented score in
+ * descending order. Mutates the input array in place.
+ *
+ * @param results - Search results to re-rank.
+ * @param query   - The original query text.
+ * @returns The same array (sorted in place) for chaining.
+ */
+export declare function rerankResults(results: SearchResult[], query: string): SearchResult[];
+//# sourceMappingURL=query-utils.d.ts.map

package/dist/search/query-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-utils.d.ts","sourceRoot":"","sources":["../../src/search/query-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAmCxC;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAuC1E;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAiClE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOjF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAMpF"}