cgraphx 1.1.0

package/dist/markdown/mcp-tools.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * MCP tool definitions and dispatch for the markdown knowledge base.
+ *
+ * 5 tools (spec §9.3):
+ *   - codegraph_docs_list_concepts
+ *   - codegraph_docs_list_domains
+ *   - codegraph_docs_list_tags
+ *   - codegraph_docs_find
+ *   - codegraph_docs_refs
+ *
+ * The main `tools.ts` imports `MARKDOWN_TOOL_DEFINITIONS` to register them
+ * and `isMarkdownTool` / `handleMarkdownTool` to dispatch. Handlers run
+ * independently of the codegraph ToolHandler — no shared state, no
+ * worktree-staleness banner (docs aren't file-watched), no tree-sitter.
+ *
+ * Error policy (spec §9.4): every expected miss returns a SUCCESS-shaped
+ * text result (NOT MCP isError), so a transient empty index or a typo in a
+ * docId never teaches the agent session-long codegraph abandonment.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MARKDOWN_TOOL_SHORT_NAMES = exports.MARKDOWN_TOOL_DEFINITIONS = void 0;
+exports.isMarkdownTool = isMarkdownTool;
+exports.handleMarkdownTool = handleMarkdownTool;
+const node_path_1 = __importDefault(require("node:path"));
+const directory_1 = require("../directory");
+const errors_1 = require("./errors");
+const query_1 = require("./query");
+const schema_bootstrap_1 = require("./schema-bootstrap");
+const constants_1 = require("./constants");
+exports.MARKDOWN_TOOL_DEFINITIONS = [
+    {
+        name: 'codegraph_docs_list_concepts',
+        description: 'List all business concepts in the project\'s markdown knowledge base. ' +
+            'Returns each concept with its document count and the domains it belongs to. ' +
+            'Use this FIRST when starting a new task to see what concepts already exist, ' +
+            'then use codegraph_docs_find to fetch documents for a concept you want to ' +
+            'reuse. Requires running `codegraph docs index` first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: {
+                    type: 'string',
+                    description: 'Absolute path to the project root (or any directory inside it). codegraph walks up to the nearest .codegraph/. Omit to use the current session\'s default project (whichever .codegraph/ is at or above the server\'s cwd).',
+                },
+            },
+        },
+    },
+    {
+        name: 'codegraph_docs_list_domains',
+        description: 'List all business domains in the markdown knowledge base, each with its document count.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: { type: 'string', description: 'Optional. Absolute path to the project (or any directory inside it); omit to use the session default.' },
+            },
+        },
+    },
+    {
+        name: 'codegraph_docs_list_tags',
+        description: 'List all tags in the markdown knowledge base, each with its document count.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: { type: 'string', description: 'Optional. Absolute path to the project (or any directory inside it); omit to use the session default.' },
+            },
+        },
+    },
+    {
+        name: 'codegraph_docs_find',
+        description: 'Find documents in the markdown knowledge base by filtering on concept, domain, tag, status, document type, or keyword. ' +
+            'Returns document descriptors including title, summary, file path, and associated concepts/domains/tags. ' +
+            'Multiple filters are intersected (AND). Use the returned file path with the Read tool to view the full document when the summary is insufficient.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: { type: 'string', description: 'Optional. Absolute path to the project (or any directory inside it); omit to use the session default.' },
+                concept: { type: 'string', description: 'Filter by exact concept name (case-sensitive)' },
+                domain: { type: 'string', description: 'Filter by domain name' },
+                tag: { type: 'string', description: 'Filter by tag name' },
+                status: { type: 'string', enum: constants_1.DOCUMENT_STATUSES, description: 'Filter by status (draft/active/superseded/deprecated)' },
+                documentType: { type: 'string', enum: constants_1.DOCUMENT_TYPES, description: 'Filter by document_type (decision/architecture/guide/...)' },
+                q: { type: 'string', description: 'Substring match against title or summary (case-insensitive)' },
+                limit: { type: 'integer', default: 20, description: 'Max results (1-100; default 20)' },
+            },
+        },
+    },
+    {
+        name: 'codegraph_docs_refs',
+        description: 'Get the reference relationships of a document: which documents this one cites (outgoing) and which documents cite it (incoming). ' +
+            'Useful for tracing how a decision propagates. Accepts a document ID (64-hex) or a project-relative path.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: { type: 'string', description: 'Optional. Absolute path to the project (or any directory inside it); omit to use the session default.' },
+                docId: {
+                    type: 'string',
+                    description: 'Document ID (64-hex) or project-relative path',
+                },
+            },
+            required: ['docId'],
+        },
+    },
+];
+const MARKDOWN_TOOL_NAMES = new Set(exports.MARKDOWN_TOOL_DEFINITIONS.map(t => t.name));
+function isMarkdownTool(name) {
+    return MARKDOWN_TOOL_NAMES.has(name);
+}
+/**
+ * Dispatch a markdown tool call.
+ *
+ * Returns a ToolResult (success-shaped text content for all expected
+ * outcomes, including empty index / unknown docId). Throws only for
+ * genuinely unexpected failures; the caller wraps them.
+ */
+async function handleMarkdownTool(name, args) {
+    // projectPath is OPTIONAL — mirrors codegraph's main tool policy. When
+    // omitted we walk up from cwd for the nearest .codegraph/. Multi-project
+    // sessions (agent querying a sub-project of a monorepo, or a second repo
+    // in the same session) pass projectPath explicitly. Each project's
+    // markdown_* tables live in its own .codegraph/codegraph.db, so there is
+    // zero cross-project bleed regardless of how the path is resolved.
+    const projectPathRaw = typeof args.projectPath === 'string' ? args.projectPath : '';
+    let projectRoot;
+    if (projectPathRaw) {
+        projectRoot = node_path_1.default.resolve(projectPathRaw);
+    }
+    else {
+        const resolved = (0, directory_1.findNearestCodeGraphRoot)(process.cwd());
+        if (!resolved) {
+            return textResult('No `projectPath` provided, and no .codegraph/ index was found at or above ' +
+                'the current working directory. Pass `projectPath` (absolute path to a ' +
+                'codegraph-initialized project, or any directory inside it) to specify ' +
+                'which project\'s markdown knowledge base to query.');
+        }
+        projectRoot = resolved;
+    }
+    // Open + ensure schema
+    let connection;
+    try {
+        connection = (0, schema_bootstrap_1.openMarkdownDb)(projectRoot);
+    }
+    catch (err) {
+        if (err instanceof errors_1.ProjectNotInitializedError) {
+            return textResult(`Codegraph is not initialized at ${projectRoot}. ` +
+                'Run `codegraph init` first to create the .codegraph/ index.');
+        }
+        throw err;
+    }
+    try {
+        const query = new query_1.MarkdownQuery(connection.getDb());
+        switch (name) {
+            case 'codegraph_docs_list_concepts': {
+                const concepts = query.listConcepts();
+                if (concepts.length === 0) {
+                    return textResult('Markdown knowledge base is empty. ' +
+                        'Run `codegraph docs index` after adding documents to docs/knowledge/.');
+                }
+                return textResult([
+                    `Found ${concepts.length} concept(s):`,
+                    '',
+                    ...concepts.map(c => `- ${c.name} (${c.documentCount} doc${c.documentCount === 1 ? '' : 's'}; ` +
+                        `domains: ${c.domains.join(', ') || 'none'})`),
+                ].join('\n'));
+            }
+            case 'codegraph_docs_list_domains': {
+                const domains = query.listDomains();
+                if (domains.length === 0) {
+                    return textResult(emptyIndexMessage());
+                }
+                return textResult([
+                    `Found ${domains.length} domain(s):`,
+                    '',
+                    ...domains.map(d => `- ${d.name} (${d.documentCount} doc${d.documentCount === 1 ? '' : 's'})`),
+                ].join('\n'));
+            }
+            case 'codegraph_docs_list_tags': {
+                const tags = query.listTags();
+                if (tags.length === 0)
+                    return textResult(emptyIndexMessage());
+                return textResult([
+                    `Found ${tags.length} tag(s):`,
+                    '',
+                    ...tags.map(t => `- ${t.name} (${t.documentCount} doc${t.documentCount === 1 ? '' : 's'})`),
+                ].join('\n'));
+            }
+            case 'codegraph_docs_find': {
+                const filter = {
+                    concept: typeof args.concept === 'string' ? args.concept : undefined,
+                    domain: typeof args.domain === 'string' ? args.domain : undefined,
+                    tag: typeof args.tag === 'string' ? args.tag : undefined,
+                    status: typeof args.status === 'string' ? args.status : undefined,
+                    documentType: typeof args.documentType === 'string' ? args.documentType : undefined,
+                    q: typeof args.q === 'string' ? args.q : undefined,
+                    limit: typeof args.limit === 'number' ? args.limit : undefined,
+                };
+                const docs = query.find(filter);
+                if (docs.length === 0) {
+                    return textResult('No matching documents for the given filters. ' +
+                        'Try `codegraph_docs_list_concepts` to see available concepts.');
+                }
+                return textResult(formatFindForAgent(docs));
+            }
+            case 'codegraph_docs_refs': {
+                const docRef = typeof args.docId === 'string' ? args.docId : '';
+                if (!docRef) {
+                    return textResult('`docId` is required. Pass a 64-hex document ID or a project-relative path. ' +
+                        'Use `codegraph_docs_find` to list valid documents.');
+                }
+                const normalized = normalizeDocRef(docRef, projectRoot);
+                try {
+                    const view = query.getReferences(normalized);
+                    return textResult(formatReferencesForAgent(view));
+                }
+                catch (err) {
+                    if (err instanceof errors_1.DocumentNotFoundError) {
+                        return textResult(`Document not found: ${docRef}. ` +
+                            'Use `codegraph_docs_find` to list valid documents.');
+                    }
+                    throw err;
+                }
+            }
+            default:
+                return textResult(`Unknown markdown tool: ${name}`);
+        }
+    }
+    finally {
+        connection.close();
+    }
+}
+// ----- helpers -----------------------------------------------------------
+function textResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function emptyIndexMessage() {
+    return ('Markdown knowledge base is empty. ' +
+        'Run `codegraph docs index` after adding documents to docs/knowledge/.');
+}
+function normalizeDocRef(input, projectRoot) {
+    if (/^[a-f0-9]{64}$/.test(input))
+        return input;
+    const normalized = input.split('\\').join('/');
+    if (node_path_1.default.isAbsolute(input)) {
+        const rel = node_path_1.default.relative(projectRoot, input).split(node_path_1.default.sep).join('/');
+        return rel || normalized;
+    }
+    return normalized;
+}
+function formatFindForAgent(docs) {
+    const out = [`Found ${docs.length} document(s):`, ''];
+    for (const d of docs) {
+        out.push(`## ${d.title}`);
+        out.push(`- path: ${d.path}`);
+        out.push(`- type: ${d.documentType}`);
+        out.push(`- status: ${d.status}`);
+        out.push(`- updated: ${d.updatedAt ?? 'unknown'}`);
+        if (d.concepts.length > 0)
+            out.push(`- concepts: ${d.concepts.join(', ')}`);
+        if (d.domains.length > 0)
+            out.push(`- domains: ${d.domains.join(', ')}`);
+        if (d.tags.length > 0)
+            out.push(`- tags: ${d.tags.join(', ')}`);
+        if (d.summary) {
+            out.push('', '**Summary:**', d.summary);
+        }
+        out.push('');
+    }
+    out.push('Tip: use the `path` field to Read the full document when a summary is insufficient.');
+    return out.join('\n');
+}
+function formatReferencesForAgent(view) {
+    const out = [
+        `# ${view.documentTitle}`,
+        `path: ${view.documentPath}`,
+        '',
+        `## Outgoing references (${view.outgoing.length})`,
+    ];
+    if (view.outgoing.length === 0) {
+        out.push('(none)');
+    }
+    else {
+        for (const t of view.outgoing)
+            out.push(`- → ${t.title}  [${t.path}]`);
+    }
+    out.push('', `## Incoming references (${view.incoming.length})`);
+    if (view.incoming.length === 0) {
+        out.push('(none)');
+    }
+    else {
+        for (const t of view.incoming)
+            out.push(`- ← ${t.title}  [${t.path}]`);
+    }
+    return out.join('\n');
+}
+/** Short names (without `codegraph_` prefix) for DEFAULT_MCP_TOOLS membership. */
+exports.MARKDOWN_TOOL_SHORT_NAMES = new Set(exports.MARKDOWN_TOOL_DEFINITIONS.map(t => t.name.replace(/^codegraph_/, '')));
+//# sourceMappingURL=mcp-tools.js.map

package/dist/markdown/mcp-tools.js.map

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

package/dist/markdown/query.d.ts

@@ -0,0 +1,108 @@
+/**
+ * MarkdownQuery — read-side operations for the markdown subsystem.
+ *
+ * Five query entry points, matching the 5 MCP tools:
+ *   - listConcepts / listDomains / listTags
+ *   - find (multi-dimensional filter)
+ *   - getReferences (bidirectional)
+ *
+ * Plus one internal helper (`getDocumentDetail`) used by the CLI `show`
+ * command. All methods reuse the shared DB handle; callers own the
+ * connection lifecycle.
+ */
+import type { SqliteDatabase } from '../db';
+import type { ConceptSummary, DedupResponse, DocumentDescriptor, DocumentDetail, DomainSummary, FindFilter, ReferenceView, SeenNameAddResult, SeenNameCheckResult, SeenNameClearResult, SeenNameListResponse, TagSummary } from './types';
+export declare class MarkdownQuery {
+    private readonly db;
+    constructor(db: SqliteDatabase);
+    /**
+     * List all concepts with document count and domains.
+     *
+     * Sort modes:
+     *   - 'doc-count' (default): document count DESC, then name ASC
+     *   - 'name': name ASC
+     *
+     * Limit: when provided, cap results to the top N (after sort).
+     *
+     * Backward compatible: omitting both opts reproduces the legacy behavior
+     * (doc_count DESC, no limit).
+     *
+     * Note on LIMIT: SQLite's prepared-statement `?` cannot bind to LIMIT, so
+     * we interpolate the integer into the SQL string. The `Number.isInteger`
+     * guard is the SQL-injection boundary — it rejects strings, NaN, and
+     * non-integer numbers, so only JS numbers that are non-negative integers
+     * reach the SQL. Never interpolate a raw user value.
+     */
+    listConcepts(opts?: {
+        sort?: 'doc-count' | 'name';
+        limit?: number;
+    }): ConceptSummary[];
+    listDomains(): DomainSummary[];
+    listTags(): TagSummary[];
+    find(filter: FindFilter): DocumentDescriptor[];
+    getReferences(docIdOrPath: string): ReferenceView;
+    /** Internal — used by `cgraphx docs show` CLI command. */
+    getDocumentDetail(docIdOrPath: string): DocumentDetail | null;
+    /**
+     * Persist entry-point names as "already explored" (idempotent).
+     *
+     * Each name is normalized; an empty normalized form is dropped silently
+     * (consistent with checkConceptDedup's warnings but the Layer 1 contract
+     * here is fire-and-forget — callers are the agent itself, not a UI surfacing
+     * warnings). The original spelling is preserved in `original_name` so
+     * `listSeenNames` can show it.
+     *
+     * Idempotency is enforced by the UNIQUE constraint on `normalized_name` +
+     * `INSERT OR IGNORE`. The per-row `changes()` value distinguishes a real
+     * insert (1) from a skipped duplicate (0).
+     */
+    addSeenNames(names: string[]): SeenNameAddResult;
+    /**
+     * Check whether candidate names have been seen.
+     *
+     * Single IN-clause query loads all matching normalized names; the rest is
+     * a Set lookup in TS. Empty normalized forms are reported with `is_seen: false`
+     * (we never persist them, so they can never be "seen").
+     */
+    checkSeenNames(names: string[]): SeenNameCheckResult;
+    /**
+     * List all seen entry names (newest first). Used for debugging / inspection.
+     */
+    listSeenNames(): SeenNameListResponse;
+    /**
+     * Delete every seen-name row for this project. Returns the count removed.
+     */
+    clearSeenNames(): SeenNameClearResult;
+    /**
+     * Check candidate names against the indexed vocabulary.
+     *
+     * Two match modes, exact first:
+     *   - exact: normalize(candidate) === normalize(concept.name)
+     *   - alias: normalize(candidate) === normalize(document.aliases[i])
+     *     (matched_concept is then the document's primary concept name,
+     *      resolved through markdown_document_concepts)
+     *
+     * All concepts + all document aliases are pulled in two batch queries
+     * (no per-candidate SQL, no SQLite JSON1 — aliases are JSON.parse'd in TS).
+     */
+    checkConceptDedup(names: string[]): DedupResponse;
+    /** Resolve a document by ID or by project-relative path. */
+    private resolveDocument;
+    /** Domains of any document that contains this concept, deduped. */
+    private domainsForConcept;
+    /** Document IDs linked to a given vocab name (concept/domain/tag). */
+    private docIdsForVocab;
+    private sortByRelevance;
+    private sortByRecency;
+    private hydrateDescriptor;
+    private hydrateDetail;
+    private vocabNamesForDoc;
+    private computeScore;
+}
+/**
+ * Resolve a user-supplied "doc id or path" to a document ID without
+ * instantiating a query object. Used by the CLI to surface a friendly
+ * "not found" without leaking exceptions.
+ */
+export declare function isLikelyDocumentId(s: string): boolean;
+//# sourceMappingURL=query.d.ts.map

package/dist/markdown/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/markdown/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAQ5C,OAAO,KAAK,EACV,cAAc,EAEd,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,UAAU,EAEV,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EACX,MAAM,SAAS,CAAC;AASjB,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,cAAc;IAI/C;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,EAAE;IAwCtF,WAAW,IAAI,aAAa,EAAE;IAY9B,QAAQ,IAAI,UAAU,EAAE;IAcxB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,kBAAkB,EAAE;IA+E9C,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa;IAiCjD,0DAA0D;IAC1D,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAQ7D;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,iBAAiB;IA+BhD;;;;;;OAMG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,mBAAmB;IAyBpD;;OAEG;IACH,aAAa,IAAI,oBAAoB;IAmBrC;;OAEG;IACH,cAAc,IAAI,mBAAmB;IASrC;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,aAAa;IAmIjD,4DAA4D;IAC5D,OAAO,CAAC,eAAe;IAevB,mEAAmE;IACnE,OAAO,CAAC,iBAAiB;IAezB,sEAAsE;IACtE,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,iBAAiB;IAoBzB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,YAAY;CAMrB;AAWD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAErD"}