cgraphx 1.1.0

package/dist/markdown/frontmatter-parser.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * Minimal YAML frontmatter parser.
+ *
+ * Supports the limited subset of YAML the markdown knowledge base requires:
+ *   - `key: value`                 (scalar)
+ *   - `key:` followed by a list of `  - item` lines
+ *
+ * Rejects (throws) on anything more complex — nested objects, anchors/aliases,
+ * flow collections, block scalars, tab indentation, full-width colons. This is
+ * deliberate: the frontmatter convention is intentionally simple, and a parser
+ * that silently accepts surprising shapes is worse than one that errors.
+ *
+ * Does NOT depend on the `yaml` npm package. No new runtime deps for the
+ * subsystem.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrontmatterSyntaxError = void 0;
+exports.extractFrontmatterBlock = extractFrontmatterBlock;
+exports.parseFrontmatter = parseFrontmatter;
+exports.parseFrontmatterBlock = parseFrontmatterBlock;
+exports.readScalar = readScalar;
+exports.readList = readList;
+exports.hasNonEmpty = hasNonEmpty;
+class FrontmatterSyntaxError extends Error {
+    line;
+    constructor(message, line) {
+        super(`Line ${line}: ${message}`);
+        this.line = line;
+        this.name = 'FrontmatterSyntaxError';
+    }
+}
+exports.FrontmatterSyntaxError = FrontmatterSyntaxError;
+/**
+ * Extract the YAML frontmatter block delimited by leading `---` lines.
+ *
+ * Returns `null` when no frontmatter is present. Throws `FrontmatterSyntaxError`
+ * when an opening `---` is found but no matching close is.
+ *
+ * @param source full file source (CRLF normalized to LF)
+ * @returns the body between the fences (excluding the fences themselves)
+ */
+function extractFrontmatterBlock(source) {
+    const lines = source.split('\n');
+    // Optional BOM at the very start
+    if (lines[0]?.startsWith('')) {
+        lines[0] = lines[0].slice(1);
+    }
+    // Skip leading blank lines (allow whitespace before the fence)
+    let i = 0;
+    while (i < lines.length && lines[i].trim() === '') {
+        i++;
+    }
+    if (i >= lines.length || lines[i].trim() !== '---') {
+        return null;
+    }
+    const startIdx = i + 1;
+    // Find the close fence. Spec: a line whose trimmed content is exactly `---` or `...`.
+    let endIdx = -1;
+    for (let j = startIdx; j < lines.length; j++) {
+        const t = lines[j].trim();
+        if (t === '---' || t === '...') {
+            endIdx = j;
+            break;
+        }
+    }
+    if (endIdx === -1) {
+        throw new FrontmatterSyntaxError('frontmatter opened with --- but never closed', startIdx);
+    }
+    return lines.slice(startIdx, endIdx).join('\n');
+}
+/**
+ * Parse the YAML-subset frontmatter into a Map.
+ *
+ * @throws FrontmatterSyntaxError on any unsupported syntax
+ */
+function parseFrontmatter(source) {
+    const block = extractFrontmatterBlock(source);
+    if (block === null) {
+        return { values: new Map() };
+    }
+    return parseFrontmatterBlock(block);
+}
+function parseFrontmatterBlock(block) {
+    const values = new Map();
+    const lines = block.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        const raw = lines[i];
+        // Skip blank lines and comments
+        if (raw.trim() === '' || raw.trim().startsWith('#')) {
+            i++;
+            continue;
+        }
+        const lineNo = i + 1;
+        if (raw.startsWith('\t')) {
+            throw new FrontmatterSyntaxError('tab indentation is not allowed; use spaces', lineNo);
+        }
+        // Top-level key:value (no leading indentation)
+        if (/^\s/.test(raw)) {
+            throw new FrontmatterSyntaxError('unexpected indented line (expected a top-level key)', lineNo);
+        }
+        const colonIdx = raw.indexOf(':');
+        if (colonIdx === -1) {
+            throw new FrontmatterSyntaxError(`expected "key: value" but no colon found in: ${raw}`, lineNo);
+        }
+        const key = raw.slice(0, colonIdx).trim();
+        const restRaw = raw.slice(colonIdx + 1);
+        // Reject full-width colon anywhere in the line — common CJK typo
+        // (U+FF1A, not the ASCII ':' that delimits key from value)
+        if (raw.includes('：')) {
+            throw new FrontmatterSyntaxError('full-width colon (：) is not allowed; use half-width ":"', lineNo);
+        }
+        if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(key)) {
+            throw new FrontmatterSyntaxError(`invalid key "${key}"; expected alphanumeric/underscore/dash`, lineNo);
+        }
+        const rest = restRaw.trim();
+        if (rest === '') {
+            // Could be `key:` with inline null OR `key:\n  - item` list. Peek next lines.
+            const listItems = [];
+            let j = i + 1;
+            while (j < lines.length) {
+                const nl = lines[j];
+                if (nl.trim() === '') {
+                    j++;
+                    continue;
+                }
+                // List item: starts with whitespace then `-`
+                if (/^\s+-\s+/.test(nl) || /^\s+-$/.test(nl)) {
+                    if (nl.includes('\t')) {
+                        throw new FrontmatterSyntaxError('tab indentation is not allowed in list items', j + 1);
+                    }
+                    const item = nl.replace(/^\s+-\s*/, '').trim();
+                    listItems.push(stripQuotes(item, j + 1));
+                    j++;
+                }
+                else {
+                    break;
+                }
+            }
+            if (listItems.length > 0) {
+                values.set(key, listItems);
+                i = j;
+            }
+            else {
+                // Empty value — treat as empty string
+                values.set(key, '');
+                i++;
+            }
+        }
+        else {
+            // Inline scalar
+            values.set(key, stripQuotes(rest, lineNo));
+            i++;
+        }
+    }
+    return { values };
+}
+/** Remove surrounding matching quotes (single or double). Throws on mismatched. */
+function stripQuotes(value, line) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' || first === "'") && first === last) {
+            return value.slice(1, -1);
+        }
+        if ((first === '"' || first === "'") && first !== last) {
+            throw new FrontmatterSyntaxError(`mismatched quote in value: ${value}`, line);
+        }
+    }
+    return value;
+}
+/** Convenience: read a scalar value (default ''). */
+function readScalar(parsed, key) {
+    const v = parsed.values.get(key);
+    if (v === undefined)
+        return '';
+    return Array.isArray(v) ? v[0] ?? '' : v;
+}
+/** Convenience: read a list value (default []). Throws if the key holds a scalar. */
+function readList(parsed, key) {
+    const v = parsed.values.get(key);
+    if (v === undefined)
+        return [];
+    if (typeof v === 'string') {
+        throw new FrontmatterSyntaxError(`key "${key}" should be a list, got scalar "${v}"`, 0);
+    }
+    return v;
+}
+/** Convenience: presence + non-empty check. */
+function hasNonEmpty(parsed, key) {
+    const v = parsed.values.get(key);
+    if (v === undefined)
+        return false;
+    if (typeof v === 'string')
+        return v.trim() !== '';
+    return v.length > 0;
+}
+//# sourceMappingURL=frontmatter-parser.js.map

package/dist/markdown/frontmatter-parser.js.map

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

package/dist/markdown/indexer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * MarkdownIndexer — cover-the-table full rebuild.
+ *
+ * Flow (spec §6.1):
+ *   1. Open shared codegraph DB; ensure markdown schema.
+ *   2. Scan <projectRoot>/docs/knowledge/ recursively (skip symlinks + dot-dirs).
+ *   3. Extract each .md/.mdx via `extractFromFile`.
+ *   4. In ONE transaction: wipeAll → insert documents/vocabularies/edges →
+ *      resolve document_references → rebuild FTS5.
+ *   5. Return IndexReport.
+ *
+ * Failure handling: any throw inside the transaction triggers ROLLBACK;
+ * the prior index is preserved untouched. The function itself only throws
+ * for unrecoverable problems (DB not initialized, scan dir absolutely
+ * unreadable).
+ *
+ * Not integrated: .gitignore filtering (YAGNI — docs/knowledge/ is a curated
+ * knowledge dir, not a vendor payload). Can be added later if needed.
+ */
+import type { IndexReport } from './types';
+export interface IndexOptions {
+    onProgress?: (msg: string) => void;
+}
+/**
+ * Index the markdown knowledge base under <projectRoot>/docs/knowledge/.
+ *
+ * Re-uses the shared `.cgraphx/cgraphx.db` (must already exist via
+ * `cgraphx init`). The markdown schema is auto-applied on first call.
+ *
+ * Errors thrown: only for unrecoverable problems. User-data problems
+ * (bad frontmatter, missing fields) are returned via `report.skipBreakdown`.
+ */
+export declare function indexMarkdownKnowledgeBase(projectRoot: string, options?: IndexOptions): Promise<IndexReport>;
+//# sourceMappingURL=indexer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../../src/markdown/indexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,OAAO,KAAK,EACV,WAAW,EAIZ,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAaD;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAuKtB"}

package/dist/markdown/indexer.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * MarkdownIndexer — cover-the-table full rebuild.
+ *
+ * Flow (spec §6.1):
+ *   1. Open shared codegraph DB; ensure markdown schema.
+ *   2. Scan <projectRoot>/docs/knowledge/ recursively (skip symlinks + dot-dirs).
+ *   3. Extract each .md/.mdx via `extractFromFile`.
+ *   4. In ONE transaction: wipeAll → insert documents/vocabularies/edges →
+ *      resolve document_references → rebuild FTS5.
+ *   5. Return IndexReport.
+ *
+ * Failure handling: any throw inside the transaction triggers ROLLBACK;
+ * the prior index is preserved untouched. The function itself only throws
+ * for unrecoverable problems (DB not initialized, scan dir absolutely
+ * unreadable).
+ *
+ * Not integrated: .gitignore filtering (YAGNI — docs/knowledge/ is a curated
+ * knowledge dir, not a vendor payload). Can be added later if needed.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexMarkdownKnowledgeBase = indexMarkdownKnowledgeBase;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const constants_1 = require("./constants");
+const extractor_1 = require("./extractor");
+const store_1 = require("./store");
+const schema_bootstrap_1 = require("./schema-bootstrap");
+const EMPTY_SKIP_BREAKDOWN = {
+    no_frontmatter: 0,
+    frontmatter_unclosed: 0,
+    frontmatter_parse_error: 0,
+    field_type_error: 0,
+    missing_required_field: 0,
+    invalid_enum_value: 0,
+    read_error: 0,
+    dangling_reference: 0,
+};
+/**
+ * Index the markdown knowledge base under <projectRoot>/docs/knowledge/.
+ *
+ * Re-uses the shared `.cgraphx/cgraphx.db` (must already exist via
+ * `cgraphx init`). The markdown schema is auto-applied on first call.
+ *
+ * Errors thrown: only for unrecoverable problems. User-data problems
+ * (bad frontmatter, missing fields) are returned via `report.skipBreakdown`.
+ */
+async function indexMarkdownKnowledgeBase(projectRoot, options = {}) {
+    const startedAt = Date.now();
+    const runId = node_crypto_1.default
+        .createHash('sha256')
+        .update(`${projectRoot}:${startedAt}`)
+        .digest('hex')
+        .slice(0, 16);
+    const knowledgeDir = node_path_1.default.join(projectRoot, constants_1.KNOWLEDGE_DIR);
+    if (!node_fs_1.default.existsSync(knowledgeDir)) {
+        return {
+            runId,
+            startedAt,
+            finishedAt: Date.now(),
+            durationMs: 0,
+            scannedFiles: 0,
+            indexedDocuments: 0,
+            skippedFiles: 0,
+            skipBreakdown: { ...EMPTY_SKIP_BREAKDOWN },
+            conceptsCreated: 0,
+            domainsCreated: 0,
+            tagsCreated: 0,
+            referencesCreated: 0,
+            danglingReferences: 0,
+            conflictPaths: [],
+            error: `${constants_1.KNOWLEDGE_DIR}/ not found at ${knowledgeDir}`,
+        };
+    }
+    // Phase 1: scan
+    const filePaths = collectMarkdownFiles(knowledgeDir);
+    options.onProgress?.(`Found ${filePaths.length} file(s) under ${constants_1.KNOWLEDGE_DIR}/`);
+    // Phase 2: extract
+    const parsedFiles = [];
+    const skipLog = [];
+    for (const absPath of filePaths) {
+        const result = (0, extractor_1.extractFromFile)(absPath, projectRoot);
+        if (result.ok) {
+            parsedFiles.push(result.parsed);
+        }
+        else {
+            skipLog.push(result.skip);
+        }
+    }
+    options.onProgress?.(`Extracted ${parsedFiles.length} valid document(s); ${skipLog.length} skipped`);
+    // Phase 3: transactional rebuild
+    const connection = (0, schema_bootstrap_1.openMarkdownDb)(projectRoot);
+    const store = new store_1.MarkdownStore(connection.getDb());
+    let report;
+    try {
+        report = store.transaction(() => {
+            // Wipe (cover-the-table)
+            store.wipeAll();
+            // Insert documents
+            for (const file of parsedFiles) {
+                store.upsertDocument(file.document);
+            }
+            // Insert vocabulary (deduped via UNIQUE + ON CONFLICT DO NOTHING)
+            const conceptSet = new Set();
+            const domainSet = new Set();
+            const tagSet = new Set();
+            for (const file of parsedFiles) {
+                for (const c of file.concepts)
+                    conceptSet.add(c);
+                for (const d of file.domains)
+                    domainSet.add(d);
+                for (const t of file.tags)
+                    tagSet.add(t);
+            }
+            for (const name of conceptSet)
+                store.upsertVocab('markdown_concepts', name);
+            for (const name of domainSet)
+                store.upsertVocab('markdown_domains', name);
+            for (const name of tagSet)
+                store.upsertVocab('markdown_tags', name);
+            // Link edges
+            for (const file of parsedFiles) {
+                const docId = file.document.id;
+                for (const c of file.concepts) {
+                    store.linkDocumentConcept(docId, (0, store_1.vocabIdFromName)(c));
+                }
+                for (const d of file.domains) {
+                    store.linkDocumentDomain(docId, (0, store_1.vocabIdFromName)(d));
+                }
+                for (const t of file.tags) {
+                    store.linkDocumentTag(docId, (0, store_1.vocabIdFromName)(t));
+                }
+            }
+            // Resolve references (two-phase: documents all inserted above)
+            let referencesCreated = 0;
+            const dangling = [];
+            for (const file of parsedFiles) {
+                const sourceId = file.document.id;
+                const sourceDir = node_path_1.default.dirname(file.document.path);
+                for (const rawRef of file.relatedDocumentsRaw) {
+                    // Support BOTH conventions: many authors write `related_documents`
+                    // as project-root-relative (`docs/knowledge/x.md`), others write
+                    // them as source-document-relative (`./x.md`, `../y.md`). Try
+                    // source-relative first (markdown-link convention), then
+                    // root-relative (project-overview convention).
+                    const fromSource = resolveRefPath(rawRef, sourceDir, projectRoot);
+                    const fromRoot = resolveRefPath(rawRef, '', projectRoot);
+                    const targetFromSource = store.getDocumentByPath(fromSource);
+                    const target = targetFromSource ?? store.getDocumentByPath(fromRoot);
+                    if (target) {
+                        store.linkDocumentReference(sourceId, target.id, rawRef);
+                        referencesCreated++;
+                    }
+                    else {
+                        dangling.push({
+                            path: file.document.path,
+                            reason: 'dangling_reference',
+                            detail: `unresolved ref "${rawRef}" (tried ${fromSource}, ${fromRoot})`,
+                        });
+                    }
+                }
+            }
+            // Rebuild keyword index: with LIKE-based search (see schema.sql note),
+            // there's no separate FTS table to refresh — title/summary_text live in
+            // markdown_documents, which the upsert loop above already populated.
+            // Write skip log
+            for (const entry of skipLog) {
+                store.insertSkipLog(runId, entry);
+            }
+            for (const entry of dangling) {
+                store.insertSkipLog(runId, entry);
+            }
+            // Compose report
+            const skipBreakdown = { ...EMPTY_SKIP_BREAKDOWN };
+            for (const entry of skipLog) {
+                skipBreakdown[entry.reason]++;
+            }
+            skipBreakdown.dangling_reference = dangling.length;
+            return {
+                runId,
+                startedAt,
+                finishedAt: Date.now(),
+                durationMs: Date.now() - startedAt,
+                scannedFiles: filePaths.length,
+                indexedDocuments: parsedFiles.length,
+                skippedFiles: skipLog.length,
+                skipBreakdown,
+                conceptsCreated: conceptSet.size,
+                domainsCreated: domainSet.size,
+                tagsCreated: tagSet.size,
+                referencesCreated,
+                danglingReferences: dangling.length,
+                conflictPaths: [],
+            };
+        });
+    }
+    finally {
+        connection.close();
+    }
+    options.onProgress?.(`Done: ${report.indexedDocuments} docs, ${report.conceptsCreated} concepts, ${report.durationMs}ms`);
+    return report;
+}
+/**
+ * Walk a directory and collect markdown files.
+ *
+ * - Skip dot-directories (e.g. `.git/`, `.drafts/`).
+ * - Skip symlinks (prevents cycles + security).
+ * - Accept only .md / .mdx extensions (case-sensitive — README.MD is rejected).
+ */
+function collectMarkdownFiles(rootDir) {
+    const results = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const fullPath = node_path_1.default.join(dir, entry.name);
+            // Symlinks: lstat via Dirent.isSymbolicLink() catches them
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                if (constants_1.ACCEPTED_EXTENSIONS.some(ext => entry.name.endsWith(ext))) {
+                    results.push(fullPath);
+                }
+            }
+        }
+    }
+    walk(rootDir);
+    results.sort(); // deterministic order across runs
+    return results;
+}
+/**
+ * Resolve a `related_documents` reference to a project-relative path.
+ *
+ * Reference is relative to the SOURCE document's directory (not the project
+ * root). Output is normalized to POSIX for `markdown_documents.path` lookup.
+ */
+function resolveRefPath(rawRef, sourceDocDir, projectRoot) {
+    const absolute = node_path_1.default.resolve(projectRoot, sourceDocDir, rawRef);
+    const rel = node_path_1.default.relative(projectRoot, absolute);
+    return rel.split(node_path_1.default.sep).join('/');
+}
+//# sourceMappingURL=indexer.js.map

package/dist/markdown/indexer.js.map

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

package/dist/markdown/mcp-tools.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+import type { ToolDefinition, ToolResult } from '../mcp/tools';
+export declare const MARKDOWN_TOOL_DEFINITIONS: ToolDefinition[];
+export declare function isMarkdownTool(name: string): boolean;
+/**
+ * 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.
+ */
+export declare function handleMarkdownTool(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+/** Short names (without `codegraph_` prefix) for DEFAULT_MCP_TOOLS membership. */
+export declare const MARKDOWN_TOOL_SHORT_NAMES: ReadonlySet<string>;
+//# sourceMappingURL=mcp-tools.d.ts.map

package/dist/markdown/mcp-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools.d.ts","sourceRoot":"","sources":["../../src/markdown/mcp-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO/D,eAAO,MAAM,yBAAyB,EAAE,cAAc,EA8ErD,CAAC;AAMF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC,CAyIrB;AAqFD,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAEzD,CAAC"}