cgraphx 1.1.0

package/dist/markdown/schema-bootstrap.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Markdown subsystem schema bootstrap.
+ *
+ * Owns the lifecycle of the markdown tables inside the shared codegraph 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 codegraph's main 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/markdown/schema.sql` (production,
+ * copied by `npm run copy-assets`) and `src/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 codegraph 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/markdown/schema-bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-bootstrap.js","sourceRoot":"","sources":["../../src/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/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: code-impact-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, 'code-impact-init migration: entry name dedup table');

package/dist/markdown/store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * MarkdownStore — low-level persistence for the markdown subsystem.
+ *
+ * Each method is a thin wrapper around a prepared statement. The indexer
+ * (`indexer.ts`) drives these inside a single transaction for atomic
+ * full-table replacement; the query layer (`query.ts`) reads via its own
+ * prepared statements on the same DB handle.
+ *
+ * No code in `src/markdown/` reads or writes the main cgraphx tables
+ * (`nodes`, `edges`, `files`, …). This store touches `markdown_*` only.
+ */
+import type { SqliteDatabase } from '../db';
+import type { MarkdownDocumentRecord, SkipLogEntry } from './types';
+/**
+ * Stable ID for a document — sha256 of its project-relative path.
+ *
+ * The path is the natural identity: renaming a file is treated as a delete
+ * + insert, which is consistent with the cover-the-table rebuild semantics.
+ */
+export declare function documentIdFromPath(projectRelativePath: string): string;
+/**
+ * Stable ID for a concept / domain / tag — sha256 of its (case-sensitive)
+ * name. `Order` and `order` are two distinct concepts (PRD §6.7).
+ */
+export declare function vocabIdFromName(name: string): string;
+export declare class MarkdownStore {
+    private readonly db;
+    constructor(db: SqliteDatabase);
+    upsertDocument(doc: MarkdownDocumentRecord): void;
+    getDocumentById(id: string): MarkdownDocumentRow | undefined;
+    getDocumentByPath(projectRelativePath: string): MarkdownDocumentRow | undefined;
+    listAllDocumentPaths(): string[];
+    /** Upsert a concept/domain/tag name and return its id. */
+    upsertVocab(table: 'markdown_concepts' | 'markdown_domains' | 'markdown_tags', name: string): string;
+    linkDocumentConcept(documentId: string, conceptId: string): void;
+    linkDocumentDomain(documentId: string, domainId: string): void;
+    linkDocumentTag(documentId: string, tagId: string): void;
+    linkDocumentReference(sourceDocumentId: string, targetDocumentId: string, refPath: string): void;
+    private linkEdge;
+    /**
+     * Find document IDs whose title or summary_text contains the keyword.
+     * Case-insensitive, substring match. Returns IDs only; the caller hydrates.
+     */
+    findDocumentIdsByKeyword(keyword: string): string[];
+    insertSkipLog(runId: string, entry: SkipLogEntry): void;
+    /**
+     * Wipe all markdown_* tables. Used at the start of a full rebuild.
+     *
+     * Foreign-key cascades handle edge tables. The schema_versions row is
+     * preserved.
+     */
+    wipeAll(): void;
+    /**
+     * Run a function inside BEGIN/COMMIT, rolling back on throw.
+     *
+     * Mirrors `SqliteDatabase.transaction()` so callers don't have to import
+     * the low-level type to do this.
+     */
+    transaction<T>(fn: () => T): T;
+}
+/** Raw row shape from `markdown_documents`. Used by query layer for decoding. */
+export interface MarkdownDocumentRow {
+    id: string;
+    path: string;
+    title: string;
+    document_type: string;
+    status: string;
+    source_type: string;
+    summary_text: string;
+    owners: string;
+    aliases: string;
+    related_code: string;
+    created: string | null;
+    updated: string | null;
+    indexed_at: number;
+}
+//# sourceMappingURL=store.d.ts.map

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

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

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * MarkdownStore — low-level persistence for the markdown subsystem.
+ *
+ * Each method is a thin wrapper around a prepared statement. The indexer
+ * (`indexer.ts`) drives these inside a single transaction for atomic
+ * full-table replacement; the query layer (`query.ts`) reads via its own
+ * prepared statements on the same DB handle.
+ *
+ * No code in `src/markdown/` reads or writes the main cgraphx tables
+ * (`nodes`, `edges`, `files`, …). This store touches `markdown_*` only.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarkdownStore = void 0;
+exports.documentIdFromPath = documentIdFromPath;
+exports.vocabIdFromName = vocabIdFromName;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/**
+ * Stable ID for a document — sha256 of its project-relative path.
+ *
+ * The path is the natural identity: renaming a file is treated as a delete
+ * + insert, which is consistent with the cover-the-table rebuild semantics.
+ */
+function documentIdFromPath(projectRelativePath) {
+    return node_crypto_1.default
+        .createHash('sha256')
+        .update(projectRelativePath)
+        .digest('hex');
+}
+/**
+ * Stable ID for a concept / domain / tag — sha256 of its (case-sensitive)
+ * name. `Order` and `order` are two distinct concepts (PRD §6.7).
+ */
+function vocabIdFromName(name) {
+    return node_crypto_1.default.createHash('sha256').update(name).digest('hex');
+}
+/** JSON-stringify an array defensively (always returns '[]' for null/undefined). */
+function jsonString(arr) {
+    return JSON.stringify(arr ?? []);
+}
+class MarkdownStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ----- documents ---------------------------------------------------------
+    upsertDocument(doc) {
+        const id = documentIdFromPath(doc.path);
+        this.db
+            .prepare(`INSERT INTO markdown_documents (
+           id, path, title, document_type, status, source_type,
+           summary_text, owners, aliases, related_code, created, updated,
+           indexed_at
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           path = excluded.path,
+           title = excluded.title,
+           document_type = excluded.document_type,
+           status = excluded.status,
+           source_type = excluded.source_type,
+           summary_text = excluded.summary_text,
+           owners = excluded.owners,
+           aliases = excluded.aliases,
+           related_code = excluded.related_code,
+           created = excluded.created,
+           updated = excluded.updated,
+           indexed_at = excluded.indexed_at`)
+            .run(id, doc.path, doc.title, doc.documentType, doc.status, doc.sourceType, doc.summaryText, jsonString(doc.owners), jsonString(doc.aliases), jsonString(doc.relatedCode), doc.created, doc.updated, Date.now());
+    }
+    getDocumentById(id) {
+        return this.db
+            .prepare('SELECT * FROM markdown_documents WHERE id = ?')
+            .get(id);
+    }
+    getDocumentByPath(projectRelativePath) {
+        return this.db
+            .prepare('SELECT * FROM markdown_documents WHERE path = ?')
+            .get(projectRelativePath);
+    }
+    listAllDocumentPaths() {
+        const rows = this.db
+            .prepare('SELECT path FROM markdown_documents')
+            .all();
+        return rows.map(r => r.path);
+    }
+    // ----- vocabulary --------------------------------------------------------
+    /** Upsert a concept/domain/tag name and return its id. */
+    upsertVocab(table, name) {
+        const id = vocabIdFromName(name);
+        this.db
+            .prepare(`INSERT INTO ${table} (id, name, created_at) VALUES (?, ?, ?)
+         ON CONFLICT(id) DO NOTHING`)
+            .run(id, name, Date.now());
+        return id;
+    }
+    // ----- edges -------------------------------------------------------------
+    linkDocumentConcept(documentId, conceptId) {
+        this.linkEdge('markdown_document_concepts', 'concept_id', documentId, conceptId);
+    }
+    linkDocumentDomain(documentId, domainId) {
+        this.linkEdge('markdown_document_domains', 'domain_id', documentId, domainId);
+    }
+    linkDocumentTag(documentId, tagId) {
+        this.linkEdge('markdown_document_tags', 'tag_id', documentId, tagId);
+    }
+    linkDocumentReference(sourceDocumentId, targetDocumentId, refPath) {
+        this.db
+            .prepare(`INSERT INTO markdown_document_references
+           (source_document_id, target_document_id, ref_path)
+         VALUES (?, ?, ?)
+         ON CONFLICT(source_document_id, target_document_id) DO NOTHING`)
+            .run(sourceDocumentId, targetDocumentId, refPath);
+    }
+    linkEdge(table, targetColumn, documentId, targetId) {
+        this.db
+            .prepare(`INSERT INTO ${table} (document_id, ${targetColumn}) VALUES (?, ?)
+         ON CONFLICT DO NOTHING`)
+            .run(documentId, targetId);
+    }
+    // ----- keyword search (LIKE-based, see schema.sql note) -----------------
+    /**
+     * Find document IDs whose title or summary_text contains the keyword.
+     * Case-insensitive, substring match. Returns IDs only; the caller hydrates.
+     */
+    findDocumentIdsByKeyword(keyword) {
+        const like = `%${keyword.replace(/[%_]/g, m => '\\' + m)}%`;
+        const rows = this.db
+            .prepare(`SELECT id FROM markdown_documents
+         WHERE title LIKE ? ESCAPE '\\' OR summary_text LIKE ? ESCAPE '\\'`)
+            .all(like, like);
+        return rows.map(r => r.id);
+    }
+    // ----- skip log ----------------------------------------------------------
+    insertSkipLog(runId, entry) {
+        this.db
+            .prepare(`INSERT INTO markdown_skip_log (run_id, path, reason, detail)
+         VALUES (?, ?, ?, ?)`)
+            .run(runId, entry.path, entry.reason, entry.detail ?? null);
+    }
+    // ----- bulk wipe (for cover-the-table rebuild) ---------------------------
+    /**
+     * Wipe all markdown_* tables. Used at the start of a full rebuild.
+     *
+     * Foreign-key cascades handle edge tables. The schema_versions row is
+     * preserved.
+     */
+    wipeAll() {
+        this.db.exec(`
+      DELETE FROM markdown_documents;
+      DELETE FROM markdown_concepts;
+      DELETE FROM markdown_domains;
+      DELETE FROM markdown_tags;
+      DELETE FROM markdown_document_references;
+      DELETE FROM markdown_skip_log;
+    `);
+        // Edge tables (document_concepts/domains/tags) cascade-delete with
+        // markdown_documents, but the FK enforcement depends on PRAGMA state at
+        // the moment of delete; clear them defensively too.
+        this.db.exec(`
+      DELETE FROM markdown_document_concepts;
+      DELETE FROM markdown_document_domains;
+      DELETE FROM markdown_document_tags;
+    `);
+    }
+    // ----- transaction helpers ----------------------------------------------
+    /**
+     * Run a function inside BEGIN/COMMIT, rolling back on throw.
+     *
+     * Mirrors `SqliteDatabase.transaction()` so callers don't have to import
+     * the low-level type to do this.
+     */
+    transaction(fn) {
+        this.db.exec('BEGIN');
+        try {
+            const result = fn();
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (err) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // ROLLBACK failure is rare and secondary to the original error
+            }
+            throw err;
+        }
+    }
+}
+exports.MarkdownStore = MarkdownStore;
+//# sourceMappingURL=store.js.map

package/dist/markdown/store.js.map

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

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

@@ -0,0 +1,22 @@
+/**
+ * Extract the `## Summary` (or `## 摘要`) section from a markdown document.
+ *
+ * Spec §4 — strict, line-oriented scan. No markdown parser dependency.
+ *
+ * Rules:
+ *   - Recognized headings: `## Summary` / `## 摘要` exactly (case-sensitive,
+ *     exactly two `#`, exactly one space after `##`).
+ *   - Section body extends from the line after the heading until the next
+ *     `^#{1,2} ` heading (same or higher level) or end of file.
+ *   - Body is trimmed; runs of blank lines collapse to one.
+ *   - Multiple matching headings: only the first is read.
+ *   - Returns empty string when no matching heading is found.
+ */
+/**
+ * Extract the summary body from a markdown source.
+ *
+ * @param source full file source, with or without frontmatter
+ * @returns trimmed summary body (empty string if absent)
+ */
+export declare function extractSummary(source: string): string;
+//# sourceMappingURL=summary-extractor.d.ts.map

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

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

package/dist/markdown/summary-extractor.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Extract the `## Summary` (or `## 摘要`) section from a markdown document.
+ *
+ * Spec §4 — strict, line-oriented scan. No markdown parser dependency.
+ *
+ * Rules:
+ *   - Recognized headings: `## Summary` / `## 摘要` exactly (case-sensitive,
+ *     exactly two `#`, exactly one space after `##`).
+ *   - Section body extends from the line after the heading until the next
+ *     `^#{1,2} ` heading (same or higher level) or end of file.
+ *   - Body is trimmed; runs of blank lines collapse to one.
+ *   - Multiple matching headings: only the first is read.
+ *   - Returns empty string when no matching heading is found.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSummary = extractSummary;
+const constants_1 = require("./constants");
+const HEADING_LEVEL_1_OR_2 = /^#{1,2}\s+\S/;
+/** Match `## Summary` / `## 摘要` exactly. */
+function isSummaryHeading(line) {
+    // Must start with exactly two `#` followed by exactly one space
+    if (!line.startsWith('## '))
+        return false;
+    const rest = line.slice(3); // after `## `
+    // Reject anything with extra trailing content on the same line
+    // Acceptable: rest is exactly `Summary` or `摘要`
+    return constants_1.SUMMARY_HEADINGS.includes(rest);
+}
+/**
+ * Extract the summary body from a markdown source.
+ *
+ * @param source full file source, with or without frontmatter
+ * @returns trimmed summary body (empty string if absent)
+ */
+function extractSummary(source) {
+    // Normalize CRLF → LF so line splitting is consistent cross-platform
+    const normalized = source.replace(/\r\n/g, '\n');
+    const lines = normalized.split('\n');
+    // Find the first Summary heading
+    let headingIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (isSummaryHeading(line)) {
+            headingIdx = i;
+            break;
+        }
+    }
+    if (headingIdx === -1)
+        return '';
+    // Collect body until next level-1 or level-2 heading, or EOF
+    const body = [];
+    for (let j = headingIdx + 1; j < lines.length; j++) {
+        const line = lines[j];
+        if (HEADING_LEVEL_1_OR_2.test(line))
+            break;
+        body.push(line);
+    }
+    // Trim + collapse runs of blank lines
+    const collapsed = body
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n') // 3+ newlines → 2 (one blank line)
+        .trim();
+    return collapsed;
+}
+//# sourceMappingURL=summary-extractor.js.map

package/dist/markdown/summary-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary-extractor.js","sourceRoot":"","sources":["../../src/markdown/summary-extractor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;AAsBH,wCA8BC;AAlDD,2CAA+C;AAE/C,MAAM,oBAAoB,GAAG,cAAc,CAAC;AAE5C,4CAA4C;AAC5C,SAAS,gBAAgB,CAAC,IAAY;IACpC,gEAAgE;IAChE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc;IAC1C,+DAA+D;IAC/D,gDAAgD;IAChD,OAAQ,4BAAsC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAChE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,MAAc;IAC3C,qEAAqE;IACrE,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAErC,iCAAiC;IACjC,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACvB,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,UAAU,GAAG,CAAC,CAAC;YACf,MAAM;QACR,CAAC;IACH,CAAC;IACD,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjC,6DAA6D;IAC7D,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,UAAU,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACvB,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,MAAM;QAC3C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAED,sCAAsC;IACtC,MAAM,SAAS,GAAG,IAAI;SACnB,IAAI,CAAC,IAAI,CAAC;SACV,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,mCAAmC;SAC9D,IAAI,EAAE,CAAC;IACV,OAAO,SAAS,CAAC;AACnB,CAAC"}