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

package/lib/schema.d.ts

@@ -0,0 +1,782 @@
+/**
+ * The two dbgraph tools' model-facing schemas: the parameter spec the model fills in, and the
+ * canonical output union each tool returns.
+ *
+ * The output is a closed `oneOf` keyed on `operation`, not one loose object with every field
+ * optional, so a Code Mode program that switches on `operation` gets exactly the fields that
+ * operation produces and nothing it must test for. The build-side tool gets its own union, also
+ * discriminated, because a background run has no report to report yet: "0 objects indexed" and
+ * "not indexed yet" are different answers and must stay distinguishable.
+ * @module dsh-plugin-dbgraph-tool/schema
+ */
+import type { InferArgs, InferValue } from '@deepseek-ai/dsh-tools';
+/**
+ * Operations the primary `dbgraph` tool accepts, one per `ctx.dbgraph` seam method.
+ *
+ * `index` is deliberately absent: building an index runs through the dedicated `dbgraph_index`
+ * tool, which carries its own (much larger) timeout budget instead of this tool's query-sized one.
+ * `connections` is the only operation that takes no `connection` argument — it is how the model
+ * learns which connection ids exist.
+ */
+export declare const DBGRAPH_OPERATIONS: readonly ["connections", "schema", "objects", "columns", "find", "sql", "impact", "refs"];
+/** One query-side operation name. */
+export type DbgraphToolOperation = (typeof DBGRAPH_OPERATIONS)[number];
+/** Modes the index tool accepts; `full` runs L1 then L2. */
+export declare const DBGRAPH_INDEX_MODES: readonly ["l1", "l2", "full"];
+/** Which writer an index run may use. `js` is the parity reference and the fallback. */
+export declare const DBGRAPH_INDEX_WRITERS: readonly ["auto", "js", "rust"];
+/** The canonical value every `dbgraph` call returns, discriminated by `operation`. */
+export declare const DBGRAPH_OUTPUT_SCHEMA: {
+    readonly oneOf: readonly [{
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "connections";
+            };
+        } & {
+            readonly connections: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly id: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly engine: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly label: {
+                            readonly type: "string";
+                        };
+                        readonly host: {
+                            readonly type: "string";
+                        };
+                        readonly database: {
+                            readonly type: "string";
+                        };
+                        readonly credential_configured: {
+                            readonly type: "boolean";
+                            readonly required: true;
+                        };
+                        readonly index: {
+                            readonly required: true;
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly l1_indexed_at: {
+                                    readonly type: "integer";
+                                };
+                                readonly l2_indexed_at: {
+                                    readonly type: "integer";
+                                };
+                                readonly objects: {
+                                    readonly type: "integer";
+                                    readonly required: true;
+                                };
+                                readonly columns: {
+                                    readonly type: "integer";
+                                    readonly required: true;
+                                };
+                                readonly stale: {
+                                    readonly type: "boolean";
+                                    readonly required: true;
+                                };
+                                readonly writer: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "schema";
+            };
+        } & {
+            readonly connection: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly engine: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly database: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly objects: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly object: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly comment: {
+                            readonly type: "string";
+                        };
+                        readonly column_count: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly row_estimate: {
+                            readonly type: "integer";
+                        };
+                    };
+                };
+            };
+            readonly truncated: {
+                readonly type: "boolean";
+                readonly required: true;
+            };
+            readonly comment_coverage: {
+                readonly type: "number";
+                readonly required: true;
+            };
+            readonly index: {
+                readonly required: true;
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly l1_indexed_at: {
+                        readonly type: "integer";
+                    };
+                    readonly l2_indexed_at: {
+                        readonly type: "integer";
+                    };
+                    readonly objects: {
+                        readonly type: "integer";
+                        readonly required: true;
+                    };
+                    readonly columns: {
+                        readonly type: "integer";
+                        readonly required: true;
+                    };
+                    readonly stale: {
+                        readonly type: "boolean";
+                        readonly required: true;
+                    };
+                    readonly writer: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "objects";
+            };
+        } & {
+            readonly connection: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly objects: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly object: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly comment: {
+                            readonly type: "string";
+                        };
+                        readonly column_count: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly row_estimate: {
+                            readonly type: "integer";
+                        };
+                    };
+                };
+            };
+            readonly truncated: {
+                readonly type: "boolean";
+                readonly required: true;
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "columns";
+            };
+        } & {
+            readonly connection: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly object: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly comment: {
+                readonly type: "string";
+            };
+            readonly columns: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly name: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly type: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly nullable: {
+                            readonly type: "boolean";
+                            readonly required: true;
+                        };
+                        readonly default_value: {
+                            readonly type: "string";
+                        };
+                        readonly comment: {
+                            readonly type: "string";
+                        };
+                        readonly is_primary_key: {
+                            readonly type: "boolean";
+                            readonly required: true;
+                        };
+                        readonly is_unique: {
+                            readonly type: "boolean";
+                            readonly required: true;
+                        };
+                        readonly enum_values: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+            readonly truncated: {
+                readonly type: "boolean";
+                readonly required: true;
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "find";
+            };
+        } & {
+            readonly connection: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly status: {
+                readonly type: "string";
+                readonly required: true;
+                readonly enum: readonly ["resolved", "ambiguous", "missing_predicate", "not_found"];
+            };
+            readonly reason: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly confidence: {
+                readonly type: "number";
+                readonly required: true;
+            };
+            readonly resolved: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly object: {
+                        readonly type: "string";
+                        readonly required: true;
+                    };
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly required: true;
+                    };
+                    readonly comment: {
+                        readonly type: "string";
+                    };
+                    readonly score: {
+                        readonly type: "number";
+                        readonly required: true;
+                    };
+                    readonly columns: {
+                        readonly type: "array";
+                        readonly required: true;
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly column: {
+                                    readonly type: "string";
+                                    readonly required: true;
+                                };
+                                readonly comment: {
+                                    readonly type: "string";
+                                };
+                                readonly matched_by: {
+                                    readonly type: "string";
+                                    readonly required: true;
+                                    readonly enum: readonly ["name", "name-part", "comment", "synonym", "fuzzy"];
+                                };
+                                readonly term: {
+                                    readonly type: "string";
+                                };
+                                readonly score: {
+                                    readonly type: "number";
+                                    readonly required: true;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+            readonly candidates: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly object: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly comment: {
+                            readonly type: "string";
+                        };
+                        readonly score: {
+                            readonly type: "number";
+                            readonly required: true;
+                        };
+                        readonly columns: {
+                            readonly type: "array";
+                            readonly required: true;
+                            readonly items: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly properties: {
+                                    readonly column: {
+                                        readonly type: "string";
+                                        readonly required: true;
+                                    };
+                                    readonly comment: {
+                                        readonly type: "string";
+                                    };
+                                    readonly matched_by: {
+                                        readonly type: "string";
+                                        readonly required: true;
+                                        readonly enum: readonly ["name", "name-part", "comment", "synonym", "fuzzy"];
+                                    };
+                                    readonly term: {
+                                        readonly type: "string";
+                                    };
+                                    readonly score: {
+                                        readonly type: "number";
+                                        readonly required: true;
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+            readonly sql: {
+                readonly type: "string";
+            };
+            readonly rows: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "json";
+                };
+            };
+            readonly row_count: {
+                readonly type: "integer";
+            };
+            readonly truncated: {
+                readonly type: "boolean";
+            };
+            readonly redacted: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly elapsed_ms: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "sql";
+            };
+        } & {
+            readonly connection: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly columns: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly rows: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "json";
+                };
+            };
+            readonly row_count: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly truncated: {
+                readonly type: "boolean";
+                readonly required: true;
+            };
+            readonly redacted: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly affected_rows: {
+                readonly type: "integer";
+            };
+            readonly elapsed_ms: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly warnings: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "impact";
+            };
+        } & {
+            readonly connection: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly object: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly entries: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly object: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly column: {
+                            readonly type: "string";
+                        };
+                        readonly ref_column: {
+                            readonly type: "string";
+                        };
+                        readonly name: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+            readonly truncated: {
+                readonly type: "boolean";
+                readonly required: true;
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "refs";
+            };
+        } & {
+            readonly connection: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly object: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly entries: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly object: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly column: {
+                            readonly type: "string";
+                        };
+                        readonly ref_column: {
+                            readonly type: "string";
+                        };
+                        readonly name: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+            readonly truncated: {
+                readonly type: "boolean";
+                readonly required: true;
+            };
+        };
+    }];
+};
+/** The parameters the model fills in for `dbgraph`. Which ones apply depends on `operation`. */
+export declare const DBGRAPH_PARAMETERS: {
+    readonly operation: {
+        readonly type: "string";
+        readonly required: true;
+        readonly enum: readonly ["connections", "schema", "objects", "columns", "find", "sql", "impact", "refs"];
+        readonly description: "connections (list configured connections with their index state), schema (one connection's structural overview), objects (find tables by word, ranked), columns (one table's columns), find (resolve words to a table and columns, then execute ONE parameterized read — the fast path), sql (execute one statement verbatim), impact (what a table's change reaches), refs (what references a table). To build or refresh an index, call the dbgraph_index tool instead.";
+    };
+    readonly connection: {
+        readonly type: "string";
+        readonly description: "Connection id, as listed by operation \"connections\". Required by every operation except \"connections\".";
+    };
+    readonly query: {
+        readonly type: "string";
+        readonly description: "Search text for objects (a table name or comment word), or the statement for sql.";
+    };
+    readonly object: {
+        readonly type: "string";
+        readonly description: "Table or view name for columns, impact, and refs. For find, names the table outright and skips object resolution.";
+    };
+    readonly entity: {
+        readonly type: "string";
+        readonly description: "What the user is talking about for find, e.g. 用户 or 订单. Matched against table names, comments, and Chinese aliases.";
+    };
+    readonly fields: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "string";
+        };
+        readonly description: "Columns the caller wants for find, e.g. [\"密码\"]. Omit for every column.";
+    };
+    readonly where: {
+        readonly type: "json";
+        readonly description: "Filter for find: a JSON object mapping a column name to a value, e.g. {\"id\": 7}. A column that does not exist fails with the available column list.";
+    };
+    readonly limit: {
+        readonly type: "number";
+        readonly description: "Largest number of rows or objects to return.";
+    };
+};
+/**
+ * The parameters the dedicated `dbgraph_index` tool takes. It needs no `operation` — building an
+ * index is the only thing it does — and none of the query-side fields, which an index run has no
+ * use for.
+ */
+export declare const DBGRAPH_INDEX_PARAMETERS: {
+    readonly connection: {
+        readonly type: "string";
+        readonly description: "Connection id to index. Omitted indexes every configured connection.";
+    };
+    readonly mode: {
+        readonly type: "string";
+        readonly enum: readonly ["l1", "l2", "full"];
+        readonly description: "How deep to build: l1 (structure only, fast), full (L1 then L2 enrichment, the default), l2 (accepted as an alias of full: every non-l1 run re-reads L1 first).";
+    };
+    readonly writer: {
+        readonly type: "string";
+        readonly enum: readonly ["auto", "js", "rust"];
+        readonly description: "Which writer to prefer: auto (native when available, JS otherwise), js, or rust.";
+    };
+};
+/** The canonical value every `dbgraph_index` call returns, discriminated by `status`. */
+export declare const DBGRAPH_INDEX_OUTPUT_SCHEMA: {
+    readonly oneOf: readonly [{
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly status: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "started";
+            };
+        } & {
+            readonly job_id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly connection: {
+                readonly type: "string";
+            };
+            readonly mode: {
+                readonly type: "string";
+                readonly required: true;
+                readonly enum: readonly ["l1", "l2", "full"];
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly status: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "completed";
+            };
+        } & {
+            readonly reports: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly connection: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly level: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly enum: readonly ["l1", "l2"];
+                        };
+                        readonly objects: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly columns: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly edges: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly terms: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly writer: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly enum: readonly ["js", "rust"];
+                        };
+                        readonly elapsed_ms: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly warnings: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    }];
+};
+/** The canonical value, inferred from {@link DBGRAPH_OUTPUT_SCHEMA} so the two cannot drift. */
+export type DbgraphToolValue = InferValue<typeof DBGRAPH_OUTPUT_SCHEMA>;
+/** The validated arguments, inferred from {@link DBGRAPH_PARAMETERS}. */
+export type DbgraphToolArgs = InferArgs<typeof DBGRAPH_PARAMETERS>;
+/** The canonical value, inferred from {@link DBGRAPH_INDEX_OUTPUT_SCHEMA}. */
+export type DbgraphIndexToolValue = InferValue<typeof DBGRAPH_INDEX_OUTPUT_SCHEMA>;
+/** The validated arguments, inferred from {@link DBGRAPH_INDEX_PARAMETERS}. */
+export type DbgraphIndexToolArgs = InferArgs<typeof DBGRAPH_INDEX_PARAMETERS>;
+/** The canonical value for one operation. */
+export type DbgraphValueFor<O extends DbgraphToolOperation> = Extract<DbgraphToolValue, {
+    operation: O;
+}>;
+//# sourceMappingURL=schema.d.ts.map