cgraphx 1.4.1 → 2.0.0

package/dist/core/markdown/query.js

@@ -0,0 +1,367 @@
+"use strict";
+/**
+ * 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.
+ *
+ * 私有管线(候选收集 / 求交排序 / hydrate / 引用计数)已拆至同目录
+ * query-helpers.ts;Layer 2 概念去重实现体拆至 query-dedup.ts —— 本文件
+ * 只保留公共 API 与薄委托,公共方法行为逐字节不变(测试即契约)。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarkdownQuery = void 0;
+exports.isLikelyDocumentId = isLikelyDocumentId;
+const constants_1 = require("./constants");
+const dedup_1 = require("./dedup");
+const errors_1 = require("./errors");
+const query_helpers_1 = require("./query-helpers");
+const query_dedup_1 = require("./query-dedup");
+/** Default cap on `find` results. */
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+class MarkdownQuery {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ----- vocabulary listing ----------------------------------------------
+    /**
+     * 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) {
+        const sort = opts?.sort ?? 'doc-count';
+        if (sort !== 'doc-count' && sort !== 'name') {
+            throw new TypeError(`listConcepts: invalid sort '${sort}', expected 'doc-count' or 'name'`);
+        }
+        const orderBy = sort === 'name' ? 'c.name ASC' : 'doc_count DESC, c.name ASC';
+        let limitClause = '';
+        if (opts?.limit !== undefined && opts?.limit !== null) {
+            // Number.isInteger 严格校验:必须是非负整数(number 类型 + 整数 + >= 0)。
+            // 这样 listConcepts({ limit: "5; DROP" as any }) 会因 typeof === 'string'
+            // 被 Number.isInteger 拒绝(同样拒绝 NaN / 5.5)。
+            if (!Number.isInteger(opts.limit) || opts.limit < 0) {
+                throw new TypeError(`listConcepts: invalid limit '${opts.limit}', expected non-negative integer`);
+            }
+            limitClause = `LIMIT ${opts.limit}`;
+        }
+        const rows = this.db
+            .prepare(`SELECT c.id, c.name,
+           (SELECT count(*) FROM markdown_document_concepts dc WHERE dc.concept_id = c.id) AS doc_count
+         FROM markdown_concepts c
+         ORDER BY ${orderBy}
+         ${limitClause}`)
+            .all();
+        return rows.map(r => ({
+            id: r.id,
+            name: r.name,
+            documentCount: r.doc_count,
+            domains: this.domainsForConcept(r.id),
+        }));
+    }
+    listDomains() {
+        const rows = this.db
+            .prepare(`SELECT d.id, d.name,
+           (SELECT count(*) FROM markdown_document_domains dd WHERE dd.domain_id = d.id) AS doc_count
+         FROM markdown_domains d
+         ORDER BY doc_count DESC, d.name ASC`)
+            .all();
+        return rows.map(r => ({ id: r.id, name: r.name, documentCount: r.doc_count }));
+    }
+    listTags() {
+        const rows = this.db
+            .prepare(`SELECT t.id, t.name,
+           (SELECT count(*) FROM markdown_document_tags dt WHERE dt.tag_id = t.id) AS doc_count
+         FROM markdown_tags t
+         ORDER BY doc_count DESC, t.name ASC`)
+            .all();
+        return rows.map(r => ({ id: r.id, name: r.name, documentCount: r.doc_count }));
+    }
+    // ----- multi-dimensional find ------------------------------------------
+    /**
+     * Multi-dimensional find (CLI 面,行为与输出逐字节锁定)。
+     *
+     * 管线与 findPaged 共用:Phase 1 候选收集(collectCandidateSets)→
+     * Phase 2 求交 + 排序(orderCandidates,不切片)→ 本方法 slice(0, limit)
+     * 后 hydrate。默认 limit 20、上限 100;无过滤维度返回全量(按 limit);
+     * 非法枚举值返回 []。
+     */
+    find(filter) {
+        const limit = Math.min(Math.max(filter.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+        const candidateSets = (0, query_helpers_1.collectCandidateSets)(this.db, filter);
+        if (candidateSets === null)
+            return []; // 非法枚举 → 空结果
+        // 与重构前一致:有 q 按相关度,无 q 按时间倒序
+        const orderedIds = (0, query_helpers_1.orderCandidates)(this.db, candidateSets, {
+            q: filter.q,
+            sort: filter.q ? 'relevance' : 'recency',
+        });
+        return orderedIds
+            .slice(0, limit)
+            .map(id => (0, query_helpers_1.hydrateDescriptor)(this.db, id, filter.q));
+    }
+    /**
+     * 分页版 find(web 列表页使用,spec §3.3:不静默截断、呈现匹配总数)。
+     *
+     * - total = 分页前匹配总数;items = 同一有序列表的 [offset, offset+limit) 切片;
+     * - limit 缺省 20、钳制 [1,100](沿用 DEFAULT_LIMIT/MAX_LIMIT);
+     * - offset 缺省 0,必须是非负整数,否则抛 TypeError(沿用 listConcepts 的
+     *   Number.isInteger 注入边界模式);
+     * - sort 缺省 = 有 q 按相关度、无 q 按时间倒序;'title' = title ASC,
+     *   并列 updated DESC;显式 'relevance' 但无 q 时降级为 recency;
+     * - 当页条目额外填充 referencesCount / owners / aliases(find() 不填)。
+     */
+    findPaged(filter, opts) {
+        const offset = opts?.offset ?? 0;
+        // Number.isInteger 是注入边界:拒绝字符串 / NaN / 非整数 / 负数,
+        // 与 listConcepts 的 LIMIT 守卫同一模式。
+        if (!Number.isInteger(offset) || offset < 0) {
+            throw new TypeError(`findPaged: invalid offset '${offset}', expected non-negative integer`);
+        }
+        const limit = Math.min(Math.max(opts?.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+        const candidateSets = (0, query_helpers_1.collectCandidateSets)(this.db, filter);
+        if (candidateSets === null)
+            return { total: 0, items: [] }; // 非法枚举 → 空结果
+        const sort = opts?.sort ?? (filter.q ? 'relevance' : 'recency');
+        const orderedIds = (0, query_helpers_1.orderCandidates)(this.db, candidateSets, { q: filter.q, sort });
+        const pageIds = orderedIds.slice(offset, offset + limit);
+        // 当页引用计数:一条 IN 聚合查询(出向 + 入向),非 N+1
+        const refCounts = (0, query_helpers_1.referenceCountsForDocs)(this.db, pageIds);
+        const items = pageIds.map(id => {
+            const doc = this.db
+                .prepare('SELECT * FROM markdown_documents WHERE id = ?')
+                .get(id);
+            return {
+                ...(0, query_helpers_1.hydrateDescriptorFromRow)(this.db, doc, filter.q),
+                referencesCount: refCounts.get(id) ?? 0,
+                // owners/aliases 从同行 JSON 列解析(沿用 hydrateDetail 的
+                // parseJsonArray 模式,零额外查询)
+                owners: (0, query_helpers_1.parseJsonArray)(doc.owners),
+                aliases: (0, query_helpers_1.parseJsonArray)(doc.aliases),
+            };
+        });
+        return { total: orderedIds.length, items };
+    }
+    /**
+     * 知识库统计条(web 总览页头部)。
+     *
+     * byType / byStatus 的 Record 由枚举常量全键初始化为 0,再用
+     * GROUP BY 结果覆写 —— 未出现的类型/状态保证键在、计数 0。
+     */
+    getStats() {
+        const countOf = (table) => this.db.prepare(`SELECT count(*) AS c FROM ${table}`).get().c;
+        const latest = this.db
+            .prepare('SELECT max(indexed_at) AS m FROM markdown_documents')
+            .get();
+        const byType = Object.fromEntries(constants_1.DOCUMENT_TYPES.map(t => [t, 0]));
+        const typeRows = this.db
+            .prepare('SELECT document_type AS t, count(*) AS c FROM markdown_documents GROUP BY document_type')
+            .all();
+        for (const r of typeRows) {
+            if (constants_1.DOCUMENT_TYPES.includes(r.t)) {
+                byType[r.t] = r.c;
+            }
+        }
+        const byStatus = Object.fromEntries(constants_1.DOCUMENT_STATUSES.map(s => [s, 0]));
+        const statusRows = this.db
+            .prepare('SELECT status AS s, count(*) AS c FROM markdown_documents GROUP BY status')
+            .all();
+        for (const r of statusRows) {
+            if (constants_1.DOCUMENT_STATUSES.includes(r.s)) {
+                byStatus[r.s] = r.c;
+            }
+        }
+        return {
+            documentCount: countOf('markdown_documents'),
+            conceptCount: countOf('markdown_concepts'),
+            domainCount: countOf('markdown_domains'),
+            tagCount: countOf('markdown_tags'),
+            latestIndexedAt: latest.m ?? null,
+            byType,
+            byStatus,
+        };
+    }
+    // ----- references ------------------------------------------------------
+    getReferences(docIdOrPath) {
+        const doc = (0, query_helpers_1.resolveDocument)(this.db, docIdOrPath);
+        if (!doc)
+            throw new errors_1.DocumentNotFoundError(docIdOrPath);
+        const outgoing = this.db
+            .prepare(`SELECT d.id, d.title, d.path
+         FROM markdown_document_references r
+         JOIN markdown_documents d ON d.id = r.target_document_id
+         WHERE r.source_document_id = ?
+         ORDER BY d.title ASC`)
+            .all(doc.id);
+        const incoming = this.db
+            .prepare(`SELECT d.id, d.title, d.path
+         FROM markdown_document_references r
+         JOIN markdown_documents d ON d.id = r.source_document_id
+         WHERE r.target_document_id = ?
+         ORDER BY d.title ASC`)
+            .all(doc.id);
+        return {
+            documentId: doc.id,
+            documentTitle: doc.title,
+            documentPath: doc.path,
+            outgoing,
+            incoming,
+        };
+    }
+    /** Internal — used by `cgraphx docs show` CLI command. */
+    getDocumentDetail(docIdOrPath) {
+        const doc = (0, query_helpers_1.resolveDocument)(this.db, docIdOrPath);
+        if (!doc)
+            return null;
+        return (0, query_helpers_1.hydrateDetail)(this.db, doc);
+    }
+    // ----- seen-names (Layer 1 entry name dedup) --------------------------
+    /**
+     * 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) {
+        const insert = this.db.prepare(`INSERT OR IGNORE INTO markdown_explored_entry_names
+         (normalized_name, original_name, added_at) VALUES (?, ?, ?)`);
+        const now = Date.now();
+        const added = [];
+        const skipped = [];
+        for (const name of names) {
+            const normalized = (0, dedup_1.normalizeName)(name);
+            if (normalized.length === 0)
+                continue; // empty normalized → skip
+            const res = insert.run(normalized, name, now);
+            if (res.changes > 0) {
+                added.push(normalized);
+            }
+            else {
+                skipped.push(normalized);
+            }
+        }
+        const totalRow = this.db
+            .prepare('SELECT count(*) AS c FROM markdown_explored_entry_names')
+            .get();
+        return {
+            added,
+            skipped_already_present: skipped,
+            total_seen: totalRow.c,
+        };
+    }
+    /**
+     * 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) {
+        const candidates = names.map(name => ({ name, normalized: (0, dedup_1.normalizeName)(name) }));
+        const nonEmpty = candidates.filter(c => c.normalized.length > 0);
+        const seenSet = new Set();
+        if (nonEmpty.length > 0) {
+            const placeholders = nonEmpty.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT normalized_name FROM markdown_explored_entry_names
+           WHERE normalized_name IN (${placeholders})`)
+                .all(...nonEmpty.map(c => c.normalized));
+            for (const r of rows)
+                seenSet.add(r.normalized_name);
+        }
+        return {
+            results: candidates.map(c => ({
+                name: c.name,
+                normalized: c.normalized,
+                is_seen: seenSet.has(c.normalized),
+            })),
+        };
+    }
+    /**
+     * List all seen entry names (newest first). Used for debugging / inspection.
+     */
+    listSeenNames() {
+        const rows = this.db
+            .prepare(`SELECT normalized_name, original_name, added_at
+         FROM markdown_explored_entry_names
+         ORDER BY added_at DESC, id DESC`)
+            .all();
+        return {
+            names: rows.map(r => ({
+                original: r.original_name,
+                normalized: r.normalized_name,
+                added_at: r.added_at,
+            })),
+            total: rows.length,
+        };
+    }
+    /**
+     * Delete every seen-name row for this project. Returns the count removed.
+     */
+    clearSeenNames() {
+        const res = this.db
+            .prepare('DELETE FROM markdown_explored_entry_names')
+            .run();
+        return { removed: res.changes };
+    }
+    // ----- concept dedup (Layer 2) ----------------------------------------
+    /**
+     * Check candidate names against the indexed vocabulary.
+     * 实现体见 query-dedup.ts 的 runConceptDedupCheck(整体搬出,行为不变)。
+     */
+    checkConceptDedup(names) {
+        return (0, query_dedup_1.runConceptDedupCheck)(this.db, names);
+    }
+    // ----- helpers ---------------------------------------------------------
+    /** Domains of any document that contains this concept, deduped. */
+    domainsForConcept(conceptId) {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT d.name
+         FROM markdown_document_domains dd
+         JOIN markdown_domains d ON d.id = dd.domain_id
+         WHERE dd.document_id IN (
+           SELECT document_id FROM markdown_document_concepts WHERE concept_id = ?
+         )
+         ORDER BY d.name ASC`)
+            .all(conceptId);
+        return rows.map(r => r.name);
+    }
+}
+exports.MarkdownQuery = MarkdownQuery;
+/**
+ * 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.
+ */
+function isLikelyDocumentId(s) {
+    return /^[a-f0-9]{64}$/.test(s);
+}
+//# sourceMappingURL=query.js.map

package/dist/core/markdown/query.js.map

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

package/dist/core/markdown/schema-bootstrap.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Markdown subsystem schema bootstrap.
+ *
+ * Owns the lifecycle of the markdown tables inside the shared cgraphx DB:
+ *   1. Read `schema.sql` shipped alongside the compiled JS.
+ *   2. Apply it (idempotent — every statement uses IF NOT EXISTS).
+ *   3. Track applied version in `markdown_schema_versions`.
+ *
+ * The shared `.cgraphx/cgraphx.db` file is reused (no separate DB file),
+ * but tables are strictly isolated by the `markdown_` prefix and never read
+ * or written by the (now-removed) code-graph layer.
+ */
+import { DatabaseConnection, type SqliteDatabase } from '../db';
+/** Read the current markdown schema version recorded in the DB, or 0 if none. */
+export declare function getCurrentMarkdownSchemaVersion(db: SqliteDatabase): number;
+/**
+ * Apply the markdown schema to a DB handle.
+ *
+ * Idempotent: safe to call on every docs command. The SQL is composed entirely
+ * of `CREATE ... IF NOT EXISTS` + a single version-row `INSERT OR IGNORE`.
+ *
+ * @throws SchemaMismatchError if a recorded version is *newer* than what this
+ *   build of the subsystem supports (would happen when a newer cgraphx wrote
+ *   the schema and an older one tried to read it).
+ */
+export declare function ensureMarkdownSchema(db: SqliteDatabase): void;
+/**
+ * Open the shared cgraphx DB for markdown-subsystem use and ensure the
+ * markdown schema is applied.
+ *
+ * Re-uses `DatabaseConnection.open` so WAL/foreign_keys/busy_timeout settings
+ * from the main DB layer apply. The returned connection is the caller's
+ * responsibility — close it when done with `connection.close()`.
+ *
+ * @throws ProjectNotInitializedError if `<projectRoot>/.cgraphx/cgraphx.db`
+ *   does not exist (i.e. `cgraphx init` was never run).
+ */
+export declare function openMarkdownDb(projectRoot: string): DatabaseConnection;
+export declare const MARKDOWN_SCHEMA_VERSION = 2;
+//# sourceMappingURL=schema-bootstrap.d.ts.map

package/dist/core/markdown/schema-bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-bootstrap.d.ts","sourceRoot":"","sources":["../../../src/core/markdown/schema-bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EACL,kBAAkB,EAElB,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAgBf,iFAAiF;AACjF,wBAAgB,+BAA+B,CAAC,EAAE,EAAE,cAAc,GAAG,MAAM,CAO1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,CAS7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAWtE;AAED,eAAO,MAAM,uBAAuB,IAAkC,CAAC"}

package/dist/core/markdown/schema-bootstrap.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Markdown subsystem schema bootstrap.
+ *
+ * Owns the lifecycle of the markdown tables inside the shared cgraphx DB:
+ *   1. Read `schema.sql` shipped alongside the compiled JS.
+ *   2. Apply it (idempotent — every statement uses IF NOT EXISTS).
+ *   3. Track applied version in `markdown_schema_versions`.
+ *
+ * The shared `.cgraphx/cgraphx.db` file is reused (no separate DB file),
+ * but tables are strictly isolated by the `markdown_` prefix and never read
+ * or written by the (now-removed) code-graph layer.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MARKDOWN_SCHEMA_VERSION = void 0;
+exports.getCurrentMarkdownSchemaVersion = getCurrentMarkdownSchemaVersion;
+exports.ensureMarkdownSchema = ensureMarkdownSchema;
+exports.openMarkdownDb = openMarkdownDb;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const db_1 = require("../db");
+const errors_1 = require("./errors");
+const CURRENT_MARKDOWN_SCHEMA_VERSION = 2;
+/**
+ * Locate `schema.sql` next to the compiled module.
+ *
+ * Resolves correctly both under `dist/core/markdown/schema.sql` (production,
+ * copied by `npm run copy-assets`) and `src/core/markdown/schema.sql` (when
+ * run under tsx/vitest without a build).
+ */
+function resolveSchemaPath() {
+    return node_path_1.default.join(__dirname, 'schema.sql');
+}
+/** Read the current markdown schema version recorded in the DB, or 0 if none. */
+function getCurrentMarkdownSchemaVersion(db) {
+    const row = db
+        .prepare('SELECT version FROM markdown_schema_versions ORDER BY version DESC LIMIT 1')
+        .get();
+    return row?.version ?? 0;
+}
+/**
+ * Apply the markdown schema to a DB handle.
+ *
+ * Idempotent: safe to call on every docs command. The SQL is composed entirely
+ * of `CREATE ... IF NOT EXISTS` + a single version-row `INSERT OR IGNORE`.
+ *
+ * @throws SchemaMismatchError if a recorded version is *newer* than what this
+ *   build of the subsystem supports (would happen when a newer cgraphx wrote
+ *   the schema and an older one tried to read it).
+ */
+function ensureMarkdownSchema(db) {
+    const schemaPath = resolveSchemaPath();
+    const sql = node_fs_1.default.readFileSync(schemaPath, 'utf-8');
+    db.exec(sql);
+    const current = getCurrentMarkdownSchemaVersion(db);
+    if (current > CURRENT_MARKDOWN_SCHEMA_VERSION) {
+        throw new errors_1.SchemaMismatchError(CURRENT_MARKDOWN_SCHEMA_VERSION, current);
+    }
+}
+/**
+ * Open the shared cgraphx DB for markdown-subsystem use and ensure the
+ * markdown schema is applied.
+ *
+ * Re-uses `DatabaseConnection.open` so WAL/foreign_keys/busy_timeout settings
+ * from the main DB layer apply. The returned connection is the caller's
+ * responsibility — close it when done with `connection.close()`.
+ *
+ * @throws ProjectNotInitializedError if `<projectRoot>/.cgraphx/cgraphx.db`
+ *   does not exist (i.e. `cgraphx init` was never run).
+ */
+function openMarkdownDb(projectRoot) {
+    const resolved = node_path_1.default.resolve(projectRoot);
+    const dbPath = (0, db_1.getDatabasePath)(resolved);
+    if (!node_fs_1.default.existsSync(dbPath)) {
+        throw new errors_1.ProjectNotInitializedError(resolved);
+    }
+    const connection = db_1.DatabaseConnection.open(dbPath);
+    ensureMarkdownSchema(connection.getDb());
+    return connection;
+}
+exports.MARKDOWN_SCHEMA_VERSION = CURRENT_MARKDOWN_SCHEMA_VERSION;
+//# sourceMappingURL=schema-bootstrap.js.map

package/dist/core/markdown/schema-bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-bootstrap.js","sourceRoot":"","sources":["../../../src/core/markdown/schema-bootstrap.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;;;;AA0BH,0EAOC;AAYD,oDASC;AAaD,wCAWC;AA5ED,sDAAyB;AACzB,0DAA6B;AAE7B,8BAIe;AACf,qCAA2E;AAE3E,MAAM,+BAA+B,GAAG,CAAC,CAAC;AAE1C;;;;;;GAMG;AACH,SAAS,iBAAiB;IACxB,OAAO,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAC5C,CAAC;AAED,iFAAiF;AACjF,SAAgB,+BAA+B,CAAC,EAAkB;IAChE,MAAM,GAAG,GAAG,EAAE;SACX,OAAO,CACN,4EAA4E,CAC7E;SACA,GAAG,EAAqC,CAAC;IAC5C,OAAO,GAAG,EAAE,OAAO,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,oBAAoB,CAAC,EAAkB;IACrD,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAAC;IACvC,MAAM,GAAG,GAAG,iBAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACjD,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEb,MAAM,OAAO,GAAG,+BAA+B,CAAC,EAAE,CAAC,CAAC;IACpD,IAAI,OAAO,GAAG,+BAA+B,EAAE,CAAC;QAC9C,MAAM,IAAI,4BAAmB,CAAC,+BAA+B,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,cAAc,CAAC,WAAmB;IAChD,MAAM,QAAQ,GAAG,mBAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAA,oBAAe,EAAC,QAAQ,CAAC,CAAC;IAEzC,IAAI,CAAC,iBAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,mCAA0B,CAAC,QAAQ,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,UAAU,GAAG,uBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnD,oBAAoB,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;IACzC,OAAO,UAAU,CAAC;AACpB,CAAC;AAEY,QAAA,uBAAuB,GAAG,+BAA+B,CAAC"}

package/dist/core/markdown/schema.sql

@@ -0,0 +1,124 @@
+-- ============================================================
+-- Markdown Knowledge Base Schema
+-- Independent of cgraphx main schema. Managed via markdown_schema_versions.
+-- Idempotent: all CREATE statements use IF NOT EXISTS.
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS markdown_schema_versions (
+    version INTEGER PRIMARY KEY,
+    applied_at INTEGER NOT NULL,
+    description TEXT
+);
+
+CREATE TABLE IF NOT EXISTS markdown_documents (
+    id TEXT PRIMARY KEY,
+    path TEXT NOT NULL UNIQUE,
+    title TEXT NOT NULL,
+    document_type TEXT NOT NULL,
+    status TEXT NOT NULL,
+    source_type TEXT NOT NULL,
+    summary_text TEXT NOT NULL DEFAULT '',
+    owners TEXT NOT NULL DEFAULT '[]',
+    aliases TEXT NOT NULL DEFAULT '[]',
+    related_code TEXT NOT NULL DEFAULT '[]',
+    created TEXT,
+    updated TEXT,
+    indexed_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS markdown_concepts (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS markdown_domains (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS markdown_tags (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS markdown_document_concepts (
+    document_id TEXT NOT NULL,
+    concept_id TEXT NOT NULL,
+    PRIMARY KEY (document_id, concept_id),
+    FOREIGN KEY (document_id) REFERENCES markdown_documents(id) ON DELETE CASCADE,
+    FOREIGN KEY (concept_id) REFERENCES markdown_concepts(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS markdown_document_domains (
+    document_id TEXT NOT NULL,
+    domain_id TEXT NOT NULL,
+    PRIMARY KEY (document_id, domain_id),
+    FOREIGN KEY (document_id) REFERENCES markdown_documents(id) ON DELETE CASCADE,
+    FOREIGN KEY (domain_id) REFERENCES markdown_domains(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS markdown_document_tags (
+    document_id TEXT NOT NULL,
+    tag_id TEXT NOT NULL,
+    PRIMARY KEY (document_id, tag_id),
+    FOREIGN KEY (document_id) REFERENCES markdown_documents(id) ON DELETE CASCADE,
+    FOREIGN KEY (tag_id) REFERENCES markdown_tags(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS markdown_document_references (
+    source_document_id TEXT NOT NULL,
+    target_document_id TEXT NOT NULL,
+    ref_path TEXT NOT NULL,
+    PRIMARY KEY (source_document_id, target_document_id),
+    FOREIGN KEY (source_document_id) REFERENCES markdown_documents(id) ON DELETE CASCADE,
+    FOREIGN KEY (target_document_id) REFERENCES markdown_documents(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS markdown_skip_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id TEXT NOT NULL,
+    path TEXT NOT NULL,
+    reason TEXT NOT NULL,
+    detail TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_documents_path ON markdown_documents(path);
+CREATE INDEX IF NOT EXISTS idx_documents_status_type ON markdown_documents(status, document_type);
+CREATE INDEX IF NOT EXISTS idx_doc_concepts_cid ON markdown_document_concepts(concept_id);
+CREATE INDEX IF NOT EXISTS idx_doc_domains_did ON markdown_document_domains(domain_id);
+CREATE INDEX IF NOT EXISTS idx_doc_tags_tid ON markdown_document_tags(tag_id);
+CREATE INDEX IF NOT EXISTS idx_doc_refs_target ON markdown_document_references(target_document_id);
+CREATE INDEX IF NOT EXISTS idx_skip_log_run ON markdown_skip_log(run_id);
+
+-- Note: keyword search (q parameter in `find`) uses LIKE on title + summary_text
+-- instead of FTS5. Rationale: SQLite's default FTS5 tokenizer (unicode61)
+-- treats CJK characters as separators, so Chinese queries ("退订", "订单") match
+-- nothing. trigram would need >=3-char queries. For the expected scale (tens to
+-- a few hundred documents) LIKE on indexed text columns is well within the
+-- <100ms budget (spec §7.4) and supports any Unicode substring.
+
+INSERT OR IGNORE INTO markdown_schema_versions (version, applied_at, description)
+VALUES (1, strftime('%s', 'now') * 1000, 'Initial markdown knowledge base schema');
+
+-- ============================================================
+-- v2: knowledge-init migration — entry point name dedup
+-- Persisted Layer 1 dedup state, replaces the original
+-- code-impact-graph HTTP /api/exploration/seen-names endpoint.
+-- Isolated by project_path (one .cgraphx/cgraphx.db per project).
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS markdown_explored_entry_names (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    normalized_name TEXT NOT NULL,
+    original_name TEXT NOT NULL,
+    added_at INTEGER NOT NULL,
+    UNIQUE (normalized_name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_entry_names_norm ON markdown_explored_entry_names(normalized_name);
+
+INSERT OR IGNORE INTO markdown_schema_versions (version, applied_at, description)
+VALUES (2, strftime('%s', 'now') * 1000, 'knowledge-init migration: entry name dedup table');

package/dist/core/markdown/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/core/markdown/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,KAAK,EACV,sBAAsB,EACtB,YAAY,EACb,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,mBAAmB,EAAE,MAAM,GAAG,MAAM,CAKtE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAOD,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,cAAc;IAI/C,cAAc,CAAC,GAAG,EAAE,sBAAsB,GAAG,IAAI;IAwCjD,eAAe,CAAC,EAAE,EAAE,MAAM,GAGV,mBAAmB,GAAG,SAAS;IAG/C,iBAAiB,CAAC,mBAAmB,EAAE,MAAM,GAGZ,mBAAmB,GAAG,SAAS;IAGhE,oBAAoB,IAAI,MAAM,EAAE;IAShC,0DAA0D;IAC1D,WAAW,CACT,KAAK,EAAE,mBAAmB,GAAG,kBAAkB,GAAG,eAAe,EACjE,IAAI,EAAE,MAAM,GACX,MAAM;IAaT,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIhE,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI9D,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIxD,qBAAqB,CACnB,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM,GACd,IAAI;IAWP,OAAO,CAAC,QAAQ;IAgBhB;;;OAGG;IACH,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAanD,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IAWvD;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAqBf;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;CAe/B;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/core/markdown/store.js.map

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

package/dist/core/markdown/summary-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary-extractor.d.ts","sourceRoot":"","sources":["../../../src/core/markdown/summary-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgBH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA8BrD"}