dsh-plugin-dbgraph-store 0.0.0-stage → 0.1.0

package/lib/aliases.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Alias-table matching, shared by the writer (which expands a column's name and comment into sibling
+ * words) and the resolver (which expands a user's word back into the columns it could mean).
+ *
+ * The table itself lives in `dsh-plugin-dbgraph-service` (`ZH_ALIASES`) and crosses into the native
+ * writer as JSON, so this module only ever *applies* a caller-supplied table — it never owns a copy of
+ * the vocabulary.
+ * @module dsh-plugin-dbgraph-store/aliases
+ */
+import type { AliasGroup } from 'dsh-plugin-dbgraph-service';
+/**
+ * The alias groups whose vocabulary appears in a text.
+ * @param parts - name and comment, in any order; undefined and empty entries are ignored.
+ * @param aliases - the alias table.
+ * @returns matched groups, in table order; empty when the text names nothing from the table.
+ */
+export declare function aliasGroupsIn(parts: readonly (string | undefined)[], aliases: readonly AliasGroup[]): readonly AliasGroup[];
+/**
+ * The tokens a group contributes once it matched: every sibling word plus the canonical meaning.
+ * Tokens — not raw words — because the index stores the tokenizer's output, and a word the tokenizer
+ * would split (`real_name`) has to be looked up by its parts.
+ * @param group - the matched alias group.
+ * @returns deduplicated tokens, in first-seen order.
+ */
+export declare function aliasGroupTokens(group: AliasGroup): readonly string[];
+/**
+ * Whether a user's word is one of a group's words (exact, case-insensitive, separator-insensitive).
+ * The resolver uses this to decide which groups a free-text entity mentions.
+ * @param word - the user's word.
+ * @param group - the candidate group.
+ * @returns true when the word names the group.
+ */
+export declare function wordNamesGroup(word: string, group: AliasGroup): boolean;
+//# sourceMappingURL=aliases.d.ts.map

package/lib/aliases.js

@@ -0,0 +1,92 @@
+/**
+ * Alias-table matching, shared by the writer (which expands a column's name and comment into sibling
+ * words) and the resolver (which expands a user's word back into the columns it could mean).
+ *
+ * The table itself lives in `dsh-plugin-dbgraph-service` (`ZH_ALIASES`) and crosses into the native
+ * writer as JSON, so this module only ever *applies* a caller-supplied table — it never owns a copy of
+ * the vocabulary.
+ * @module dsh-plugin-dbgraph-store/aliases
+ */
+import { tokenizeForSearch } from 'dsh-plugin-dbgraph-service';
+import { hasCjk, isAsciiToken, normalizeIdentifier } from "./normalize.js";
+/**
+ * Whether one alias word occurs in a text.
+ *
+ * Three shapes, because one rule cannot fit all three:
+ * - a single ASCII token matches an exact token (`user` in `sys_user`), never a substring — otherwise
+ *   `order` would match `border_id`;
+ * - a CJK word matches as a substring (`用户` in `系统用户`) because Chinese has no separators;
+ * - a multi-token ASCII word (`real_name`) matches its folded form, which keeps `real_name` and
+ *   `realname` interchangeable.
+ * @param word - one word from an alias group.
+ * @param text - the name or comment being tested.
+ * @param tokens - `tokenizeForSearch(text)`, already computed by the caller.
+ * @param folded - `normalizeIdentifier(text)`, already computed by the caller.
+ * @returns true when the word is present.
+ */
+function wordOccursIn(word, text, tokens, folded) {
+    const normalizedWord = word.normalize('NFKC').toLowerCase().trim();
+    if (normalizedWord === '')
+        return false;
+    const wordTokens = tokenizeForSearch(normalizedWord);
+    if (wordTokens.length === 0)
+        return false;
+    if (hasCjk(normalizedWord))
+        return normalizedWord !== '' && text.toLowerCase().includes(normalizedWord);
+    if (wordTokens.length === 1 && isAsciiToken(wordTokens[0]))
+        return tokens.has(wordTokens[0]);
+    return folded.includes(normalizeIdentifier(normalizedWord));
+}
+/**
+ * The alias groups whose vocabulary appears in a text.
+ * @param parts - name and comment, in any order; undefined and empty entries are ignored.
+ * @param aliases - the alias table.
+ * @returns matched groups, in table order; empty when the text names nothing from the table.
+ */
+export function aliasGroupsIn(parts, aliases) {
+    const text = parts.filter((part) => part !== undefined && part !== '').join(' ');
+    if (text === '')
+        return [];
+    const tokens = new Set(tokenizeForSearch(text));
+    const folded = normalizeIdentifier(text);
+    const matched = [];
+    for (const group of aliases) {
+        if (group.words.some(word => wordOccursIn(word, text, tokens, folded)))
+            matched.push(group);
+    }
+    return matched;
+}
+/**
+ * The tokens a group contributes once it matched: every sibling word plus the canonical meaning.
+ * Tokens — not raw words — because the index stores the tokenizer's output, and a word the tokenizer
+ * would split (`real_name`) has to be looked up by its parts.
+ * @param group - the matched alias group.
+ * @returns deduplicated tokens, in first-seen order.
+ */
+export function aliasGroupTokens(group) {
+    const seen = new Set();
+    const tokens = [];
+    for (const word of [...group.words, group.meaning]) {
+        for (const token of tokenizeForSearch(word)) {
+            if (seen.has(token))
+                continue;
+            seen.add(token);
+            tokens.push(token);
+        }
+    }
+    return tokens;
+}
+/**
+ * Whether a user's word is one of a group's words (exact, case-insensitive, separator-insensitive).
+ * The resolver uses this to decide which groups a free-text entity mentions.
+ * @param word - the user's word.
+ * @param group - the candidate group.
+ * @returns true when the word names the group.
+ */
+export function wordNamesGroup(word, group) {
+    const folded = normalizeIdentifier(word);
+    if (folded === '')
+        return false;
+    return group.words.some(candidate => normalizeIdentifier(candidate) === folded);
+}
+//# sourceMappingURL=aliases.js.map

package/lib/connections.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `connections.json` — the configured connection list.
+ *
+ * Deliberately boring, for a security reason: this file never holds a password, only the name of the
+ * credential-seam entry that does (`credentialRef`). It is the one place a connection id arrives from
+ * outside the process, and that id becomes a directory name, so **every** entry is validated against
+ * `isValidConnectionId` before it may be used. A malformed file fails loudly rather than yielding a
+ * list that a later path join would silently turn into a path traversal.
+ *
+ * The file is written atomically (staging file + rename) and with `0600`, because it lists hosts,
+ * users, and database names even though it holds no secret.
+ * @module dsh-plugin-dbgraph-store/connections
+ */
+import type { StoredConnection } from 'dsh-plugin-dbgraph-service';
+/** Format version this build writes and the only one it understands. */
+export declare const CONNECTIONS_FORMAT_VERSION = 1;
+/**
+ * Read the connection list.
+ *
+ * A missing file is an empty list, not an error: a fresh installation has no connections yet, and
+ * every read path must keep working while the user is still configuring their first one.
+ * @param root - index root.
+ * @returns the configured connections, in file order.
+ */
+export declare function readConnections(root: string): readonly StoredConnection[];
+/**
+ * Replace the connection list atomically.
+ *
+ * Round-tripping through the file (read → modify → write) is the supported way to add or remove one
+ * connection; preserving order is the caller's business, not this function's.
+ * @param connections - the full list to persist.
+ * @param root - index root.
+ */
+export declare function writeConnections(connections: readonly StoredConnection[], root: string): void;
+/**
+ * The configured connection with this id, when there is one.
+ * @param id - connection identity.
+ * @param root - index root.
+ * @returns the entry, or undefined.
+ */
+export declare function findConnection(id: string, root: string): StoredConnection | undefined;
+//# sourceMappingURL=connections.d.ts.map

package/lib/connections.js

@@ -0,0 +1,172 @@
+/**
+ * `connections.json` — the configured connection list.
+ *
+ * Deliberately boring, for a security reason: this file never holds a password, only the name of the
+ * credential-seam entry that does (`credentialRef`). It is the one place a connection id arrives from
+ * outside the process, and that id becomes a directory name, so **every** entry is validated against
+ * `isValidConnectionId` before it may be used. A malformed file fails loudly rather than yielding a
+ * list that a later path join would silently turn into a path traversal.
+ *
+ * The file is written atomically (staging file + rename) and with `0600`, because it lists hosts,
+ * users, and database names even though it holds no secret.
+ * @module dsh-plugin-dbgraph-store/connections
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DbgraphError, isValidConnectionId } from 'dsh-plugin-dbgraph-service';
+import { connectionsPath } from "./paths.js";
+/** Format version this build writes and the only one it understands. */
+export const CONNECTIONS_FORMAT_VERSION = 1;
+/**
+ * One thrown value's message.
+ * @param error - the thrown value.
+ * @returns a non-empty message.
+ */
+function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    return JSON.stringify(error) ?? 'unknown error';
+}
+/**
+ * Read one entry out of a parsed document, validating everything that could later become a path or a
+ * credential reference.
+ * @param value - one entry of the parsed `connections` array.
+ * @param position - its index, for the error message.
+ * @returns the validated entry.
+ */
+function parseConnection(value, position) {
+    if (typeof value !== 'object' || value === null) {
+        throw new DbgraphError(`connections.json entry ${position} is not an object`, 'DBGRAPH_MALFORMED_INDEX');
+    }
+    const record = value;
+    const id = record.id;
+    if (typeof id !== 'string' || !isValidConnectionId(id)) {
+        throw new DbgraphError(`connections.json entry ${position} has an unusable id: ${JSON.stringify(id)}`, 'DBGRAPH_MALFORMED_INDEX');
+    }
+    const engine = record.engine;
+    if (typeof engine !== 'string' || engine.trim() === '') {
+        throw new DbgraphError(`connections.json entry "${id}" has no engine`, 'DBGRAPH_MALFORMED_INDEX');
+    }
+    const patterns = record.sensitivePatterns;
+    const sensitivePatterns = Array.isArray(patterns)
+        ? patterns.filter((pattern) => typeof pattern === 'string')
+        : undefined;
+    return {
+        id,
+        engine,
+        ...(typeof record.label === 'string' ? { label: record.label } : {}),
+        ...(typeof record.host === 'string' ? { host: record.host } : {}),
+        ...(typeof record.port === 'number' ? { port: record.port } : {}),
+        ...(typeof record.database === 'string' ? { database: record.database } : {}),
+        ...(typeof record.user === 'string' ? { user: record.user } : {}),
+        ...(typeof record.credentialRef === 'string' ? { credentialRef: record.credentialRef } : {}),
+        ...(typeof record.sensitiveColumns === 'string' ? { sensitiveColumns: record.sensitiveColumns } : {}),
+        ...(sensitivePatterns === undefined ? {} : { sensitivePatterns }),
+        ...(typeof record.addedAt === 'number' ? { addedAt: record.addedAt } : {}),
+    };
+}
+/**
+ * Read the connection list.
+ *
+ * A missing file is an empty list, not an error: a fresh installation has no connections yet, and
+ * every read path must keep working while the user is still configuring their first one.
+ * @param root - index root.
+ * @returns the configured connections, in file order.
+ */
+export function readConnections(root) {
+    const path = connectionsPath(root);
+    if (!existsSync(path))
+        return [];
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new DbgraphError(`connections.json is unreadable: ${messageOf(error)}`, 'DBGRAPH_MALFORMED_INDEX', {
+            cause: error,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new DbgraphError(`connections.json is not valid JSON: ${messageOf(error)}`, 'DBGRAPH_MALFORMED_INDEX', {
+            cause: error,
+        });
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new DbgraphError('connections.json is not an object', 'DBGRAPH_MALFORMED_INDEX');
+    }
+    const document = parsed;
+    if (document.version !== CONNECTIONS_FORMAT_VERSION) {
+        throw new DbgraphError(`connections.json is version ${JSON.stringify(document.version)}; this build writes and reads`
+            + ` version ${CONNECTIONS_FORMAT_VERSION}`, 'DBGRAPH_MALFORMED_INDEX');
+    }
+    if (!Array.isArray(document.connections)) {
+        throw new DbgraphError('connections.json has no connections array', 'DBGRAPH_MALFORMED_INDEX');
+    }
+    const seen = new Set();
+    const connections = [];
+    for (let index = 0; index < document.connections.length; index += 1) {
+        const entry = parseConnection(document.connections[index], index);
+        if (seen.has(entry.id)) {
+            throw new DbgraphError(`connections.json lists "${entry.id}" twice`, 'DBGRAPH_MALFORMED_INDEX');
+        }
+        seen.add(entry.id);
+        connections.push(entry);
+    }
+    return connections;
+}
+/**
+ * Replace the connection list atomically.
+ *
+ * Round-tripping through the file (read → modify → write) is the supported way to add or remove one
+ * connection; preserving order is the caller's business, not this function's.
+ * @param connections - the full list to persist.
+ * @param root - index root.
+ */
+export function writeConnections(connections, root) {
+    const seen = new Set();
+    const document = {
+        version: CONNECTIONS_FORMAT_VERSION,
+        connections: connections.map((connection, index) => {
+            if (!isValidConnectionId(connection.id)) {
+                throw new DbgraphError(`connection entry ${index} has an unusable id: "${connection.id}"`, 'DBGRAPH_MALFORMED_INDEX');
+            }
+            if (connection.engine.trim() === '') {
+                throw new DbgraphError(`connection "${connection.id}" has no engine`, 'DBGRAPH_MALFORMED_INDEX');
+            }
+            if (seen.has(connection.id)) {
+                throw new DbgraphError(`connection "${connection.id}" is listed twice`, 'DBGRAPH_MALFORMED_INDEX');
+            }
+            seen.add(connection.id);
+            return { ...connection };
+        }),
+    };
+    const target = connectionsPath(root);
+    mkdirSync(dirname(target), { recursive: true });
+    const staging = `${target}.tmp`;
+    writeFileSync(staging, `${JSON.stringify(document, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    try {
+        renameSync(staging, target);
+    }
+    catch (error) {
+        rmSync(staging, { force: true });
+        throw new DbgraphError(`writing connections.json failed: ${messageOf(error)}`, 'DBGRAPH_WRITE_FAILED', {
+            cause: error,
+        });
+    }
+}
+/**
+ * The configured connection with this id, when there is one.
+ * @param id - connection identity.
+ * @param root - index root.
+ * @returns the entry, or undefined.
+ */
+export function findConnection(id, root) {
+    return readConnections(root).find(connection => connection.id === id);
+}
+//# sourceMappingURL=connections.js.map

package/lib/database.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Opening an index file, verifying its format version, and keeping a bounded number of connections
+ * warm.
+ *
+ * Databases open READ-ONLY. A writer replaces the file wholesale (a per-run staging file → rename) while this
+ * reader may be serving a query, so the store never takes a write lock and never repairs a file it does
+ * not own. The pool therefore keys a cached handle on the path's *on-disk identity* (`dev:ino`): after
+ * a rename the path names a new inode, the cached handle is stale, and the next read reopens instead of
+ * serving the previous index forever.
+ * @module dsh-plugin-dbgraph-store/database
+ */
+import { DatabaseSync } from 'node:sqlite';
+/** An open index and the `meta` rows read from it. */
+export interface OpenedIndex {
+    /** The live, read-only connection. */
+    readonly db: DatabaseSync;
+    /** Every `meta` key/value the file carries. */
+    readonly meta: ReadonlyMap<string, string>;
+}
+/**
+ * Open one index read-only and refuse a file this build does not understand.
+ * @param path - absolute path of the index file.
+ * @returns the live connection and its meta rows.
+ */
+export declare function openIndex(path: string): OpenedIndex;
+/**
+ * A bounded LRU pool of read-only index connections.
+ *
+ * A stat per acquire is deliberate: it is the cheapest way to notice that a writer replaced the file,
+ * and the alternative — trusting a handle until the process restarts — is exactly the bug an
+ * atomically-replaced index would otherwise create.
+ */
+export declare class IndexPool {
+    private readonly entries;
+    private readonly maxOpen;
+    private clock;
+    private disposed;
+    /**
+     * @param maxOpen - how many index files to keep open at once (default 4).
+     */
+    constructor(maxOpen?: number);
+    /**
+     * Acquire the live connection for one index, reopening when the file on disk was replaced.
+     * @param path - absolute path of the index file.
+     * @returns the open index.
+     */
+    acquire(path: string): OpenedIndex;
+    /**
+     * Close every pooled connection. Idempotent.
+     */
+    close(): void;
+    /**
+     * The `dev:ino` identity of a file, as a cache key for "is this still the same file".
+     * @param path - absolute path.
+     * @returns the identity string.
+     */
+    private identityOf;
+    private closeEntry;
+    private evictIfNeeded;
+}
+//# sourceMappingURL=database.d.ts.map

package/lib/database.js

@@ -0,0 +1,176 @@
+/**
+ * Opening an index file, verifying its format version, and keeping a bounded number of connections
+ * warm.
+ *
+ * Databases open READ-ONLY. A writer replaces the file wholesale (a per-run staging file → rename) while this
+ * reader may be serving a query, so the store never takes a write lock and never repairs a file it does
+ * not own. The pool therefore keys a cached handle on the path's *on-disk identity* (`dev:ino`): after
+ * a rename the path names a new inode, the cached handle is stale, and the next read reopens instead of
+ * serving the previous index forever.
+ * @module dsh-plugin-dbgraph-store/database
+ */
+import { existsSync, statSync } from 'node:fs';
+import { DatabaseSync } from 'node:sqlite';
+import { DbgraphError, INDEX_META_KEYS, INDEX_SCHEMA_VERSION, } from 'dsh-plugin-dbgraph-service';
+/**
+ * One thrown value's message.
+ * @param error - the thrown value.
+ * @returns a non-empty message.
+ */
+function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    return JSON.stringify(error) ?? 'unknown error';
+}
+/**
+ * Read `meta` into a map.
+ * @param db - an open index.
+ * @returns every key/value pair.
+ */
+function readMeta(db) {
+    const rows = db.prepare('SELECT key, value FROM meta').all();
+    const meta = new Map();
+    for (const row of rows) {
+        const key = row.key;
+        const value = row.value;
+        if (typeof key === 'string' && typeof value === 'string')
+            meta.set(key, value);
+    }
+    return meta;
+}
+/**
+ * Open one index read-only and refuse a file this build does not understand.
+ * @param path - absolute path of the index file.
+ * @returns the live connection and its meta rows.
+ */
+export function openIndex(path) {
+    if (!existsSync(path)) {
+        throw new DbgraphError(`no database-graph index exists at ${path}`, 'DBGRAPH_UNAVAILABLE');
+    }
+    let db;
+    try {
+        db = new DatabaseSync(path, { readOnly: true });
+        const meta = readMeta(db);
+        const version = meta.get(INDEX_META_KEYS.schemaVersion);
+        if (version === undefined) {
+            throw new DbgraphError(`the index at ${path} records no schema version`, 'DBGRAPH_MALFORMED_INDEX');
+        }
+        if (Number(version) !== INDEX_SCHEMA_VERSION) {
+            throw new DbgraphError(`the index at ${path} uses schema version ${version}; this build understands ${INDEX_SCHEMA_VERSION}`, 'DBGRAPH_MALFORMED_INDEX');
+        }
+        return { db, meta };
+    }
+    catch (error) {
+        try {
+            db?.close();
+        }
+        catch {
+            // Closing a handle that failed to open is best-effort; the original error is the signal.
+        }
+        if (error instanceof DbgraphError)
+            throw error;
+        throw new DbgraphError(`the index at ${path} is not readable: ${messageOf(error)}`, 'DBGRAPH_MALFORMED_INDEX', { cause: error });
+    }
+}
+/**
+ * A bounded LRU pool of read-only index connections.
+ *
+ * A stat per acquire is deliberate: it is the cheapest way to notice that a writer replaced the file,
+ * and the alternative — trusting a handle until the process restarts — is exactly the bug an
+ * atomically-replaced index would otherwise create.
+ */
+export class IndexPool {
+    entries = new Map();
+    maxOpen;
+    clock = 0;
+    disposed = false;
+    /**
+     * @param maxOpen - how many index files to keep open at once (default 4).
+     */
+    constructor(maxOpen = 4) {
+        if (!Number.isInteger(maxOpen) || maxOpen < 1) {
+            throw new Error('dbgraph-store: maxOpenIndexes must be a positive integer');
+        }
+        this.maxOpen = maxOpen;
+    }
+    /**
+     * Acquire the live connection for one index, reopening when the file on disk was replaced.
+     * @param path - absolute path of the index file.
+     * @returns the open index.
+     */
+    acquire(path) {
+        if (this.disposed)
+            throw new DbgraphError('the dbgraph store is disposed', 'DBGRAPH_UNAVAILABLE');
+        const identity = this.identityOf(path);
+        const cached = this.entries.get(path);
+        if (cached !== undefined && cached.identity !== identity) {
+            this.closeEntry(cached);
+            this.entries.delete(path);
+        }
+        const existing = this.entries.get(path);
+        if (existing !== undefined) {
+            existing.lastUsed = ++this.clock;
+            return existing.opened;
+        }
+        const opened = openIndex(path);
+        // Re-stat after opening: a rename between the first stat and the open would otherwise record the
+        // previous file's identity against the new handle, and the next acquire would trust a stale map.
+        const openedIdentity = this.identityOf(path);
+        const entry = { opened, identity: openedIdentity, lastUsed: ++this.clock };
+        this.entries.set(path, entry);
+        this.evictIfNeeded();
+        return opened;
+    }
+    /**
+     * Close every pooled connection. Idempotent.
+     */
+    close() {
+        this.disposed = true;
+        for (const entry of this.entries.values())
+            this.closeEntry(entry);
+        this.entries.clear();
+    }
+    /**
+     * The `dev:ino` identity of a file, as a cache key for "is this still the same file".
+     * @param path - absolute path.
+     * @returns the identity string.
+     */
+    identityOf(path) {
+        try {
+            const stats = statSync(path);
+            return `${stats.dev}:${stats.ino}`;
+        }
+        catch (error) {
+            throw new DbgraphError(`no database-graph index exists at ${path}: ${messageOf(error)}`, 'DBGRAPH_UNAVAILABLE', { cause: error });
+        }
+    }
+    closeEntry(entry) {
+        try {
+            entry.opened.db.close();
+        }
+        catch (error) {
+            // A handle that already died needs no second close, but a failure here can leak a descriptor:
+            // one line is enough to notice it.
+            console.error('[dbgraph-store] closing a cached index handle failed:', messageOf(error));
+        }
+    }
+    evictIfNeeded() {
+        if (this.entries.size <= this.maxOpen)
+            return;
+        let oldestPath;
+        let oldest;
+        for (const [path, entry] of this.entries) {
+            if (oldest === undefined || entry.lastUsed < oldest.lastUsed) {
+                oldest = entry;
+                oldestPath = path;
+            }
+        }
+        if (oldest !== undefined && oldestPath !== undefined) {
+            this.closeEntry(oldest);
+            this.entries.delete(oldestPath);
+        }
+    }
+}
+//# sourceMappingURL=database.js.map