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

package/lib/assert.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Exhaustiveness guard for a closed union, owned by this package rather than borrowed from the host.
+ *
+ * The equivalent helper used to live in `@deepseek-ai/dsh-llm`; the 0.2.1 runtime moved it to
+ * `@deepseek-ai/dsh-util-values` and stopped re-exporting it from the old location, which turns a
+ * static `import { assertNever } from '@deepseek-ai/dsh-llm'` into a load-time failure — the whole
+ * consumer plugin vanishes from the host instead of failing at one unreachable branch. Carrying the
+ * three lines here keeps every dbgraph package loadable across host versions instead of pinning one.
+ * @module dsh-plugin-dbgraph-service/assert
+ */
+/**
+ * Assert at compile time that `value` is unreachable, and throw if it ever is reached at runtime.
+ * @param value - the value typed `never` by an exhaustive switch or if-chain.
+ * @param context - optional name of the union being switched on, for the error message.
+ * @returns never — the call always throws.
+ */
+export declare function assertNever(value: never, context?: string): never;
+//# sourceMappingURL=assert.d.ts.map

package/lib/assert.js

@@ -0,0 +1,21 @@
+/**
+ * Exhaustiveness guard for a closed union, owned by this package rather than borrowed from the host.
+ *
+ * The equivalent helper used to live in `@deepseek-ai/dsh-llm`; the 0.2.1 runtime moved it to
+ * `@deepseek-ai/dsh-util-values` and stopped re-exporting it from the old location, which turns a
+ * static `import { assertNever } from '@deepseek-ai/dsh-llm'` into a load-time failure — the whole
+ * consumer plugin vanishes from the host instead of failing at one unreachable branch. Carrying the
+ * three lines here keeps every dbgraph package loadable across host versions instead of pinning one.
+ * @module dsh-plugin-dbgraph-service/assert
+ */
+/**
+ * Assert at compile time that `value` is unreachable, and throw if it ever is reached at runtime.
+ * @param value - the value typed `never` by an exhaustive switch or if-chain.
+ * @param context - optional name of the union being switched on, for the error message.
+ * @returns never — the call always throws.
+ */
+export function assertNever(value, context) {
+    const rendered = JSON.stringify(value) ?? String(value);
+    throw new Error(`unreachable variant${context === undefined ? '' : ` in ${context}`}: ${rendered}`);
+}
+//# sourceMappingURL=assert.js.map

package/lib/brand.d.ts

@@ -0,0 +1,36 @@
+/**
+ * dbgraph's owned branded ids. {@link ConnectionId} names one configured database connection; it is
+ * the key everything else is scoped by (index directory, credential reference, status entry).
+ * @module dsh-plugin-dbgraph-service/brand
+ */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/**
+ * Opaque identity of one configured connection. Chosen by the user (`prod`, `test-qingpei`), used
+ * verbatim as a directory name under the index root, so the registry validates it against a
+ * restricted alphabet before minting one.
+ */
+export type ConnectionId = Branded<'ConnectionId'>;
+/**
+ * Brand a string as a {@link ConnectionId}. No validation — the caller that reads user configuration
+ * is what rejects an unusable id (see `isValidConnectionId`).
+ * @param id - the connection's stable identifier.
+ * @returns the same string, branded.
+ */
+export declare function ConnectionId(id: string): ConnectionId;
+/**
+ * Whether a raw string may become a {@link ConnectionId}. Restricted to what is safe as both a
+ * directory name and a POSIX-environment-variable fragment, because the credential reference is
+ * derived from it: lowercase letters, digits, `-` and `_`, starting with a letter or digit.
+ * @param id - candidate identifier.
+ * @returns true when the id is usable as a connection identity.
+ */
+export declare function isValidConnectionId(id: string): boolean;
+/**
+ * The credential reference a connection's password lives under. The host's credential seam carries
+ * POSIX environment-variable names, so this is the derivation every caller must share: consume it
+ * through {@link credentialRefName} rather than rebuilding the string.
+ * @param id - the connection identity.
+ * @returns the environment-variable-style reference name, e.g. `DBGRAPH_PROD_PASSWORD`.
+ */
+export declare function credentialRefName(id: ConnectionId): string;
+//# sourceMappingURL=brand.d.ts.map

package/lib/brand.js

@@ -0,0 +1,35 @@
+/**
+ * dbgraph's owned branded ids. {@link ConnectionId} names one configured database connection; it is
+ * the key everything else is scoped by (index directory, credential reference, status entry).
+ * @module dsh-plugin-dbgraph-service/brand
+ */
+/**
+ * Brand a string as a {@link ConnectionId}. No validation — the caller that reads user configuration
+ * is what rejects an unusable id (see `isValidConnectionId`).
+ * @param id - the connection's stable identifier.
+ * @returns the same string, branded.
+ */
+export function ConnectionId(id) {
+    return id;
+}
+/**
+ * Whether a raw string may become a {@link ConnectionId}. Restricted to what is safe as both a
+ * directory name and a POSIX-environment-variable fragment, because the credential reference is
+ * derived from it: lowercase letters, digits, `-` and `_`, starting with a letter or digit.
+ * @param id - candidate identifier.
+ * @returns true when the id is usable as a connection identity.
+ */
+export function isValidConnectionId(id) {
+    return /^[a-z0-9][a-z0-9_-]{0,63}$/.test(id);
+}
+/**
+ * The credential reference a connection's password lives under. The host's credential seam carries
+ * POSIX environment-variable names, so this is the derivation every caller must share: consume it
+ * through {@link credentialRefName} rather than rebuilding the string.
+ * @param id - the connection identity.
+ * @returns the environment-variable-style reference name, e.g. `DBGRAPH_PROD_PASSWORD`.
+ */
+export function credentialRefName(id) {
+    return `DBGRAPH_${id.toUpperCase().replace(/-/g, '_')}_PASSWORD`;
+}
+//# sourceMappingURL=brand.js.map

package/lib/index.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Service Definition for the database-graph capability seam (`ctx.dbgraph`).
+ *
+ * Three registries, each with a different arity rule, because they answer different questions:
+ *
+ * - **dialects** — one per {@link Engine}. A second dialect for the same engine is a configuration
+ *   error, not a preference, so registration rejects it (`DBGRAPH_CONFLICT`).
+ * - **the store** — exactly one. Connections are data (rows in `connections.json`), not plugins, so
+ *   nothing needs per-connection routing; a second store would only be ambiguous.
+ * - **connections** — zero or more, read from configuration on demand. Several connections being
+ *   live at once is the normal case, which is the one place this seam deliberately differs from
+ *   `ctx.codegraph`'s "exactly one claimant per root".
+ *
+ * The seam itself does no network I/O and no SQLite: dialects reach servers, the store reads the
+ * index, and {@link Dbgraph.find} is the only method that composes both — resolve offline, then
+ * execute once.
+ * @module dsh-plugin-dbgraph-service
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+import type { ColumnsRequest, ColumnsResult, ConnectionSummary, DatabaseDialect, DbgraphService, DbgraphStore, Engine, FindRequest, FindResult, ImpactRequest, ImpactResult, IndexReport, IndexRequest, ObjectsRequest, ObjectsResult, RefsRequest, RefsResult, SchemaRequest, SchemaResult, SqlRequest, SqlResult, StoredConnection } from './types.ts';
+export { assertNever } from './assert.ts';
+export { ConnectionId, credentialRefName, isValidConnectionId } from './brand.ts';
+export type { ConnectionId as ConnectionIdType } from './brand.ts';
+export { CONNECTIONS_FILE_NAME, DEFAULT_ENUM_SAMPLE_LIMIT, DEFAULT_INDEX_STALE_HOURS, DEFAULT_STATUS_DIGEST_OBJECTS, INDEX_FILE_NAME, INDEX_ROOT_DIRNAME, INDEX_META_KEYS, INDEX_SCHEMA_DDL, INDEX_SCHEMA_VERSION, STATUS_FILE_NAME, } from './schema.ts';
+export type { ConnectionsFile, StatusConnectionEntry, StatusDigestEntry, StatusFile, StoredConnection, } from './schema.ts';
+export { SENSITIVE_CJK_WORDS, SENSITIVE_COLUMN_PATTERNS, SENSITIVE_COLUMN_TOKENS, ZH_ALIASES, isSensitiveColumn, } from './zh-aliases.ts';
+export { searchDocument, searchMatchQuery, tokenizeForSearch } from './tokenize.ts';
+export { ENGINES, OBJECT_KINDS, EDGE_KINDS } from './types.ts';
+export type { AliasGroup, ColumnView, ColumnsRequest, ColumnsResult, ConnectionConfig, ConnectionSummary, DatabaseDialect, DbgraphService, DbgraphStore, DialectInput, DialectProbe, EdgeKind, Engine, ExecuteLimits, FindCandidate, FindRequest, FindResult, FindStatus, ImpactRequest, ImpactResult, IndexLevel, IndexReport, IndexRequest, IndexState, IndexWriterKind, MatchedColumn, MatchSource, ObjectKind, ObjectView, ObjectsRequest, ObjectsResult, PredicatePlan, RawCatalog, RawColumn, RawEdge, RawObject, RefsRequest, RefsResult, RelationView, Resolution, Row, SchemaRequest, SchemaResult, SensitiveMode, SqlRequest, SqlResult, WriteOptions, } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        dbgraph: Dbgraph;
+    }
+}
+/**
+ * Structured database-graph failure. Extends {@link HarnessError} with a stable `code` that callers
+ * route on instead of parsing `message`:
+ *
+ * `DBGRAPH_INVALID_PROVIDER`, `DBGRAPH_INVALID_REQUEST`, `DBGRAPH_CONFLICT`, `DBGRAPH_NO_STORE`,
+ * `DBGRAPH_NO_DIALECT`, `DBGRAPH_DRIVER_MISSING`, `DBGRAPH_UNKNOWN_CONNECTION`, `DBGRAPH_UNKNOWN_OBJECT`,
+ * `DBGRAPH_UNAVAILABLE`, `DBGRAPH_MALFORMED_INDEX`, `DBGRAPH_QUERY_FAILED`, `DBGRAPH_WRITE_FAILED`,
+ * `DBGRAPH_READ_ONLY`, `DBGRAPH_ABORTED`.
+ *
+ * Three of those are worth telling apart at a call site: `UNAVAILABLE` means the thing is not there
+ * (no index file, no server), `MALFORMED_INDEX` means it is there and this build cannot read it, and
+ * `READ_ONLY` means the request was refused rather than failing.
+ */
+export declare class DbgraphError extends HarnessError {
+}
+/** Default rows returned by a `find` or `sql` call when the caller names no limit. */
+export declare const DEFAULT_MAX_ROWS = 50;
+/** Hard ceiling on rows any one call returns, whatever the caller asks for. */
+export declare const HARD_MAX_ROWS = 500;
+/** Default per-statement timeout, in milliseconds. */
+export declare const DEFAULT_QUERY_TIMEOUT_MS = 10000;
+/** Plugin configuration: only the bounds a deployment may retune. */
+export interface Config {
+    /** Hours after which an L2 snapshot counts as stale. */
+    indexStaleHours?: number;
+    /** Statement timeout in milliseconds. */
+    queryTimeoutMs?: number;
+    /** Rows returned when a caller names no limit. */
+    defaultMaxRows?: number;
+    /** Distinct-value sample size requested from a dialect. */
+    enumSampleLimit?: number;
+    /**
+     * Whether `sql` may run a statement that is not a read (default `false`).
+     *
+     * Deliberately separate from a connection's `sensitiveColumns`: masking decides what a result
+     * *shows*, and it must never decide whether a statement is allowed to *write*. Turning masking off
+     * for one connection is a routine thing to do; opening every connection to DML is not.
+     */
+    allowWrites?: boolean;
+}
+/**
+ * `ctx.dbgraph`. Holds the dialect registry and the single store reservation; every read goes
+ * through whatever is registered at call time, so a store that unloads mid-session stops serving
+ * without leaving a stale route behind.
+ */
+export declare class Dbgraph extends Service implements DbgraphService {
+    private readonly dialects;
+    private store;
+    private readonly config;
+    /**
+     * @param ctx - Cordis context.
+     * @param config - deployment bounds.
+     */
+    constructor(ctx: Context, config?: Config);
+    /** Hours after which an L2 snapshot is reported stale. */
+    get indexStaleHours(): number;
+    /** Rows a call returns when the caller names no limit. */
+    get defaultMaxRows(): number;
+    /** Statement timeout in milliseconds. */
+    get queryTimeoutMs(): number;
+    /** Distinct-value sample size requested from a dialect. */
+    get enumSampleLimit(): number;
+    /**
+     * Whether `sql` may run a non-read statement. Off unless the deployment says otherwise.
+     * @returns the configured value; `false` when unset.
+     */
+    get allowWrites(): boolean;
+    /**
+     * The index root the registered store reads and writes, when one is mounted.
+     *
+     * The prompt digest and the `backgroundIndex` decision read the sidecar synchronously from this
+     * path. Deriving it here from the store — rather than each caller deriving its own from the
+     * environment — is what keeps the digest and the index describing the same directory.
+     * @returns the absolute root, or `undefined` when no store is registered.
+     */
+    get storeRoot(): string | undefined;
+    /**
+     * Register one engine's dialect.
+     * @param dialect - the dialect to serve.
+     * @returns the disposer that unregisters it.
+     */
+    registerDialect(dialect: DatabaseDialect): () => void;
+    /**
+     * Register the offline index store.
+     * @param store - the store to serve every read and write.
+     * @returns the disposer that unregisters it.
+     */
+    registerStore(store: DbgraphStore): () => void;
+    /**
+     * Every configured connection with its index state.
+     * @returns one entry per connection, secrets omitted.
+     */
+    listConnections(): Promise<readonly ConnectionSummary[]>;
+    /**
+     * Structural overview of one connection, from the index.
+     * @param request - the connection to describe.
+     * @param signal - aborts the read.
+     * @returns the overview.
+     */
+    schema(request: SchemaRequest, signal?: AbortSignal): Promise<SchemaResult>;
+    /**
+     * Ranked object listing for one connection, from the index.
+     * @param request - the listing request.
+     * @param signal - aborts the read.
+     * @returns the listing.
+     */
+    objects(request: ObjectsRequest, signal?: AbortSignal): Promise<ObjectsResult>;
+    /**
+     * One object's columns, from the index.
+     * @param request - the columns request.
+     * @param signal - aborts the read.
+     * @returns the column list.
+     */
+    columns(request: ColumnsRequest, signal?: AbortSignal): Promise<ColumnsResult>;
+    /**
+     * Resolve words to an object and columns offline, then execute one parameterized read.
+     *
+     * This is the method the plugin exists for: zero round-trips learning the schema, exactly one
+     * round-trip fetching the answer.
+     * @param request - what the user asked about.
+     * @param signal - aborts both the resolution and the execution.
+     * @returns the rows, or why there are none.
+     */
+    find(request: FindRequest, signal?: AbortSignal): Promise<FindResult>;
+    /**
+     * Execute one statement against the server, with no semantic resolution.
+     * @param request - the statement and its limits.
+     * @param signal - aborts the execution.
+     * @returns the result set.
+     */
+    sql(request: SqlRequest, signal?: AbortSignal): Promise<SqlResult>;
+    /**
+     * Objects a change to one object reaches, from the index.
+     * @param request - the object to trace.
+     * @param signal - aborts the read.
+     * @returns the affected objects.
+     */
+    impact(request: ImpactRequest, signal?: AbortSignal): Promise<ImpactResult>;
+    /**
+     * Objects referencing one object, from the index.
+     * @param request - the object to trace.
+     * @param signal - aborts the read.
+     * @returns the referencing objects.
+     */
+    refs(request: RefsRequest, signal?: AbortSignal): Promise<RefsResult>;
+    /**
+     * Build or refresh an index. With no `connection`, every configured connection is indexed and the
+     * first report is returned; use {@link indexMany} when the caller needs all of them.
+     * @param request - which connection and how deep.
+     * @param signal - aborts the run.
+     * @returns the first connection's report.
+     */
+    index(request: IndexRequest, signal?: AbortSignal): Promise<IndexReport>;
+    /**
+     * Index every target connection in one call.
+     * @param request - which connections and how deep.
+     * @param signal - aborts the run.
+     * @returns one report per connection, in configuration order.
+     */
+    indexMany(request: IndexRequest, signal?: AbortSignal): Promise<IndexReport[]>;
+    /**
+     * Resolve one connection's password through the host credential seam.
+     * @param connection - the connection to resolve for.
+     * @returns the plaintext password, or undefined when the seam is absent or the ref is unconfigured.
+     */
+    passwordOf(connection: StoredConnection): Promise<string | undefined>;
+    /**
+     * The configured connections, as the store's configuration file lists them.
+     * @returns the connection list in configuration order.
+     */
+    readConnections(): Promise<readonly StoredConnection[]>;
+    private indexOne;
+    private dialectInputFor;
+    private dialectInput;
+    private indexStateOf;
+    private describeCredential;
+    /**
+     * The host's credential seam, when this composition has one. Looked up per call rather than
+     * captured, so a profile that mounts it later starts working without a restart.
+     * @returns the seam, or undefined.
+     */
+    private credentialSeam;
+    private requireStore;
+    private requireDialect;
+    private requireConnection;
+}
+/**
+ * Quote an identifier the way an engine expects.
+ * @param engine - which dialect's quoting rules to apply.
+ * @param name - the identifier.
+ * @returns the quoted identifier.
+ */
+export declare function quoteIdentifier(engine: Engine, name: string): string;
+/**
+ * Render a fully qualified object name.
+ * @param engine - which dialect's quoting rules to apply.
+ * @param object - name, possibly schema-qualified.
+ * @returns the quoted, dotted name.
+ */
+export declare function qualifiedName(engine: Engine, object: string): string;
+/**
+ * Render a statement with its bound values substituted, for display only.
+ *
+ * The result is never executed: it exists so a model reading the answer can see what condition was
+ * applied without guessing. Every value is rendered as a quoted literal.
+ * @param sql - the statement with `?` placeholders.
+ * @param values - the bound values, in placeholder order.
+ * @returns the statement with literals substituted.
+ */
+export declare function renderStatement(sql: string, values: readonly unknown[]): string;
+/**
+ * Clamp a caller's row limit into the configured ceiling.
+ * @param requested - the caller's value, when one was named.
+ * @param fallback - the configured default.
+ * @returns a limit between 1 and {@link HARD_MAX_ROWS}.
+ */
+export declare function clampLimit(requested: number | undefined, fallback: number): number;
+/** Re-exported so a dialect package can name the branded id without importing `brand.ts`. */
+export type { Branded } from '@deepseek-ai/dsh-brand';
+export default Dbgraph;
+//# sourceMappingURL=index.d.ts.map