@coldsmirk/inkstone-sql 0.13.0

package/README.md

@@ -0,0 +1,68 @@
+# @coldsmirk/inkstone-sql
+
+Schema-aware SQL editing intelligence for Monaco: lexical statement reading under per-dialect noise profiles, catalog-driven completion / hover / signature help, unified-placeholder awareness, `sql-formatter` integration, and a drop-in React `<SqlEditor>`.
+
+Part of [inkstone](https://github.com/coldsmirk/inkstone). Extracted from dragoman's SQL console; built for the [**polyglot**](https://github.com/coldsmirk/polyglot) unified-placeholder surface — the SQL its scanner rebinds (`?` positional / `:name` named, `??` and `::` escapes) across `postgres` / `mysql` / `oracle` / `sqlserver` / `dm` (KingbaseES rides `postgres`, OceanBase's MySQL mode rides `mysql`).
+
+## Entries
+
+- **`@coldsmirk/inkstone-sql`** — the framework-free core. Zero editor dependencies; runs anywhere.
+- **`@coldsmirk/inkstone-sql/monaco`** — `registerSqlLanguage(monaco, modelPath, hooks)`: the Monaco providers (completion, hover, signature help, formatting) over an assist read per-request through a hook. Peer: `monaco-editor`.
+- **`@coldsmirk/inkstone-sql/react`** — `<SqlEditor>`: a controlled SQL editor built on `@coldsmirk/inkstone-react`'s `<MonacoEditor>`, with a run key (Ctrl/Cmd-Enter handing over the live caret), a runnable-statement gutter mark, caret tracking, and an insert/format handle for schema trees and toolbars. Peers: `monaco-editor`, `react`.
+
+## The shape
+
+```ts
+import { createSqlAssist, readStatement, runnableStatement, statementMarkers } from "@coldsmirk/inkstone-sql";
+
+// The catalog is YOURS to fetch — and it MUST be a cache-backed read (a query cache, a memo
+// your schema-refresh invalidates), never a fresh fetch: completion reads it on every
+// keystroke, columns once per referenced table, and the package deliberately holds no cache of
+// its own.
+const assist = createSqlAssist("postgres", {
+  tables: () => cachedTables(),          // CatalogTable[]
+  columns: (schema, table) => cachedColumns(schema, table),  // CatalogColumn[]
+  functions: () => cachedFunctions()     // CatalogFunction[]
+});
+
+// What one run should send: the selection where there is one, else the caret's statement.
+const runnable = runnableStatement(text, from, to, "postgres");
+
+if (runnable.kind === "one") {
+  // Markers are read off the BLANKED form — `select '?'` binds nothing — and under the kind's
+  // own binding rules: `markers.refusal` mirrors the engine scanner's own faults (mixed forms,
+  // `??` on mysql/dm, a hand-written `$1` beside a minted marker), so the editor can say so
+  // before the round trip does.
+  const markers = statementMarkers(runnable.blanked, "postgres");
+}
+```
+
+Everything the intelligence answers goes through one lexical reader taken under the connection kind's own noise profile, so completion, hover, signature help and the parameter grid can never disagree about what is prose and what is SQL.
+
+## The mirror invariant
+
+`noise.ts` (which runs of a statement are strings / comments / quoted names, per kind) and the marker grammar mirror [**polyglot's engine scanner**](https://github.com/coldsmirk/polyglot) (`internal/scan`) flag for flag. The scanner decides what actually binds; a reader that diverged would prompt for a parameter the engine refuses, or send a statement short of one it binds. **A scanner change requires a matching release of this package**, and the per-kind cases in `reader.test.ts` are the invariant's guard.
+
+## Structured refusals
+
+Every refusal and every status is a **code**, never a sentence: a parameter that cannot bind comes back as `{ ok: false, form, key, refusal }` with `refusal` one of `"empty" | "not-a-boolean" | "not-a-number" | "not-finite" | "unsafe-integer"`; a statement the engine's scanner would fault carries `StatementMarkers.refusal` (`"mixed-forms" | "question-escape-unsupported" | "native-marker-collision"`); a multi-statement selection reads as `{ kind: "several" }`; a join suggestion's rationale is `JoinReason` (`"named-foreign-key" | "shared-key"`). The consuming app owns the wording and the language for all of them. The one deliberate exception is reference prose: hover cards and the curated function summaries read as English documentation, the way a vendor's manual does.
+
+## Install
+
+```bash
+pnpm add @coldsmirk/inkstone-sql monaco-editor
+```
+
+Every peer is optional, because the root entry needs none of them: `/monaco` needs `monaco-editor`, and `/react` additionally needs `react` (>= 19) and `@coldsmirk/inkstone-react`. Never import `monaco-editor` statically — take the module from `onMount` / `ensureMonacoHost()`; type-only imports erase and are fine.
+
+## Styling the gutter mark
+
+`<SqlEditor highlight={span}>` marks the runnable statement with a line decoration classed `inkstone-sql-runnable` (override via `highlightClassName`). The host owns the stylesheet:
+
+```css
+.inkstone-sql-runnable {
+  width: 3px !important;
+  margin-left: 3px;
+  background: var(--your-accent);
+}
+```

package/dist/assist-gLTZKSD3.d.ts

@@ -0,0 +1,401 @@
+//#region src/catalog.d.ts
+/**
+ * The vocabulary the whole package speaks: which database dialect a surface is editing for, and
+ * the catalog shapes every assist reads. The host owns how these are fetched (an HTTP endpoint, an
+ * IPC command, a fixture) — the package only ever *reads* them through {@link SqlCatalog}.
+ */
+/**
+ * One supported database dialect. A kind is added when a kind-specific *behavior* exists, not per
+ * brand name: KingbaseES connects and completes as `postgres`, an OceanBase MySQL deployment as
+ * `mysql`, and 达梦 (`dm`) carries Oracle's idiom wherever it documents Oracle compatibility.
+ */
+type SqlKind = "postgres" | "mysql" | "oracle" | "sqlserver" | "dm";
+/**
+ * One table or view as the catalog reports it. Names carry the vendor's own casing — that casing
+ * is information, and everything downstream preserves it.
+ */
+interface CatalogTable {
+  /**
+   * Empty where the kind reports no schema (or the object sits in the session's own).
+   */
+  schema: string;
+  name: string;
+  /**
+   * The wire's own vocabulary — `"table"` or `"view"` today, and append-only by contract, so
+   * the type stays open: a kind added on the wire must not fail to parse here. Everything
+   * downstream treats an unknown kind as a table.
+   */
+  kind: "table" | "view" | (string & {});
+  /**
+   * The object's own catalog comment; empty when none is declared.
+   */
+  comment: string;
+}
+/**
+ * One column as the catalog reports it. The key flags overlap by construction (a primary key is
+ * also unique and indexed); surfaces choose how much of that to show.
+ */
+interface CatalogColumn {
+  name: string;
+  dataType: string;
+  nullable: boolean;
+  primaryKey: boolean;
+  foreignKey: boolean;
+  unique: boolean;
+  indexed: boolean;
+  /**
+   * The column's own catalog comment; empty when none is declared.
+   */
+  comment: string;
+}
+/**
+ * One function as the catalog reports it — the estate's own routines and, where the kind's
+ * catalog describes them, the vendor's built-ins.
+ */
+interface CatalogFunction {
+  /**
+   * The owner or package a call must qualify with; empty where the kind reports none.
+   */
+  schema: string;
+  name: string;
+  /**
+   * The call as the kind spells it — what signature help parses.
+   */
+  signature: string;
+  /**
+   * The return type; empty where the kind's catalog does not report one.
+   */
+  returns: string;
+  /**
+   * The function's own description; empty when none is declared.
+   */
+  comment: string;
+  builtin: boolean;
+}
+//#endregion
+//#region src/reader.d.ts
+/**
+ * One table the statement names: `schema.table alias` with any part optional. A three-part T-SQL
+ * name keeps its last two — the catalog speaks schema and table.
+ */
+interface TableRef {
+  schema: string;
+  table: string;
+  alias: string;
+  /**
+   * The alias exactly as the statement wrote it — delimiters and all — or `""` where the ref
+   * declares none. Generated SQL must qualify by this text, never by re-spelling `alias`:
+   * unquoting is lossy (`"u"` and `u` both read `u`, and only one of them is what an Oracle
+   * statement means), so the operator's own text is the one spelling guaranteed to re-parse as
+   * the correlation they declared.
+   */
+  aliasWritten: string;
+  /**
+   * The clause word that introduced it, which is what tells an `insert` target from a `join`.
+   */
+  anchor: string;
+  /**
+   * Character offsets of the name itself, alias excluded — the reader orders refs by them.
+   */
+  from: number;
+  to: number;
+}
+type StatementContext = {
+  kind: "none";
+} | {
+  kind: "member";
+  parts: string[];
+} | {
+  kind: "table";
+} | {
+  kind: "insertColumns";
+  into: TableRef;
+} | {
+  kind: "joinCondition";
+  joined: TableRef;
+  earlier: TableRef[];
+} | {
+  kind: "expression";
+};
+interface StatementRead {
+  context: StatementContext;
+  /**
+   * Every table the statement names — the expression context needs them all, and an alias only
+   * resolves against this list.
+   */
+  refs: TableRef[];
+  /**
+   * The partial word at the caret. Monaco filters on it; the engine reads it only to decide the
+   * case its own vocabulary answers in.
+   */
+  typed: string;
+  /**
+   * The token standing immediately before the partial word, `""` at the start of a statement —
+   * what says whether a select-list item can begin here at all.
+   */
+  previous: string;
+  /**
+   * The caret sits directly on a `*`, which the column-list expansion stands in for. A `*` with
+   * whitespace between it and the caret is not one: the expansion would then trail the star
+   * instead of replacing it, and `select * id, name` does not run.
+   */
+  onStar: boolean;
+  /**
+   * The clause the caret is writing in — the nearest clause head to its left, `""` at the start
+   * of a statement. `and` / `or` do not head a clause, so `on a = b and |` still reads `on`.
+   */
+  clause: string;
+}
+/**
+ * What the caret is asking for, and everything the answer needs. `null` means the caret sits
+ * inside a string or a comment, where the bench has nothing to say.
+ */
+declare function readStatement(text: string, cursor: number, kind: SqlKind): StatementRead | null;
+/**
+ * What one run sends. The endpoint takes exactly one statement, so this is where
+ * a scratchpad of them narrows to the one the operator meant.
+ */
+type Runnable = {
+  kind: "one";
+  /**
+   * The statement itself, without the whitespace around it or the `;` that ended it.
+   */
+  text: string;
+  /**
+   * The same span with everything the engine's own scanner skips whole — literals, comments and
+   * quoted names — overwritten by spaces, character for character, so offsets still line up with
+   * `text`. Anything reading the statement's syntax rather than its content must read this: in
+   * `select '?'` the `?` is prose, and a marker scan of the raw text would ask the operator for
+   * a value the engine then refuses as an extra argument.
+   */
+  blanked: string;
+  from: number;
+  to: number;
+  /**
+   * The document holds no other statement, so nothing needs marking — the operator can only
+   * have meant this one.
+   */
+  alone: boolean;
+} | {
+  /**
+   * A selection covering more than one statement. One run cannot send it, and sending its
+   * first would run something other than what was selected.
+   */
+  kind: "several";
+} | {
+  kind: "none";
+};
+/**
+ * The statement a run should send: the selection where there is one, otherwise the statement the
+ * caret sits in. `from` and `to` are the selection's own offsets, equal where nothing is selected
+ * — a caret is a selection of nothing.
+ */
+declare function runnableStatement(text: string, from: number, to: number, kind: SqlKind): Runnable;
+interface IdentifierRead {
+  /**
+   * The dotted name's parts, unquoted, ending with the part the offset landed on — hovering `id`
+   * in `u.id` reads `["u", "id"]`, hovering `u` reads `["u"]`.
+   */
+  parts: string[];
+  from: number;
+  to: number;
+  refs: TableRef[];
+}
+/**
+ * The name at `offset`, with the qualifiers standing to its left. `null` where the offset is not
+ * on a name at all — punctuation, whitespace, a string, a comment.
+ */
+declare function readIdentifier(text: string, offset: number, kind: SqlKind): IdentifierRead | null;
+interface CallRead {
+  name: string;
+  /**
+   * Which argument the caret sits in, counted by the commas at this call's own paren depth.
+   */
+  argument: number;
+}
+/**
+ * The innermost call whose parens are still open at the caret, named by whatever word opened them
+ * — `in (` reports `in`, and whether that is a function is the dialect's to say, not this file's.
+ * `null` where the caret is in no parens, or in ones punctuation opened.
+ */
+declare function readCall(text: string, cursor: number, kind: SqlKind): CallRead | null;
+//#endregion
+//#region src/schema.d.ts
+/**
+ * The catalog as the bench reads it: the very RPCs the schema tree makes, so an
+ * already-expanded table answers straight from the page's query cache.
+ *
+ * **All three functions must be cache-backed reads** — a query cache, a memo the host's
+ * schema-refresh action invalidates — never fresh fetches. Completion reads them on every
+ * keystroke, `columns` once per table the statement references, and the package deliberately
+ * holds no cache of its own ({@link SqlSchema}): wired to raw fetches, every character typed is
+ * an N+1 burst of catalog calls.
+ */
+interface SqlCatalog {
+  tables: () => Promise<CatalogTable[]>;
+  columns: (schema: string, table: string) => Promise<CatalogColumn[]>;
+  functions: () => Promise<CatalogFunction[]>;
+}
+/**
+ * A table's qualified name as it *reads* — the rail's filter and the hover card's heading, which
+ * are documentation and not statement. Text on its way into the editor goes through
+ * `spelling.ts` instead, which delimits it where the kind demands it. Kinds whose catalog reports
+ * no schema (or whose objects sit in the session's own) get the bare name.
+ */
+declare function qualifiedName(table: CatalogTable): string;
+/**
+ * One table the statement reads, resolved to the catalog's own spelling and loaded.
+ */
+interface SqlSource {
+  table: CatalogTable;
+  /**
+   * How the statement refers to it: its alias where it declared one, else the name it wrote —
+   * the identity completion and hover match a qualifier against, always unquoted.
+   */
+  as: string;
+  /**
+   * The alias exactly as the statement wrote it, delimiters and all — `""` where the ref has
+   * none. Generated SQL qualifies by `spellQualifier`, which uses this or falls back to the
+   * catalog name in the kind's spelling: re-spelling the unquoted `as` would be lossy, since
+   * `"u"` and `u` both read `u` and only one of them is what an Oracle statement means.
+   */
+  aliasWritten: string;
+  columns: CatalogColumn[];
+}
+/**
+ * The catalog behind one selected system, in the shape the reader's questions take.
+ *
+ * It holds no cache of its own — deliberately. The host's catalog queries are the bench's one
+ * cache: they dedupe an in-flight read, they never go stale on their own, and the host's
+ * schema-refresh action invalidates them. A memo here would be a second cache the refresh cannot reach,
+ * and completion would keep answering from a schema the tree has already reloaded.
+ */
+interface SqlSchema {
+  tables: () => Promise<CatalogTable[]>;
+  columns: (table: CatalogTable) => Promise<CatalogColumn[]>;
+  /**
+   * Every function this data source could be asked to call — the estate's own routines, and the
+   * kind's built-ins where its catalog describes them. Refused the same way the rest is: a kind
+   * that cannot answer leaves the curated vocabulary to speak alone.
+   */
+  functions: () => Promise<CatalogFunction[]>;
+  /**
+   * The catalog's own entry for a name the statement wrote — Oracle's catalog says `ORDERS`
+   * however the statement spelled it, and every later read must use the catalog's spelling.
+   */
+  find: (ref: {
+    schema: string;
+    table: string;
+  }) => Promise<CatalogTable | null>;
+  /**
+   * The table one bare name stands for where the statement stands: an alias it declared, a table
+   * it already reads, or — failing both — a table of that name in the catalog. Completion and
+   * hover both ask, and a name must never mean two things between them.
+   */
+  resolve: (name: string, refs: TableRef[]) => Promise<CatalogTable | null>;
+  /**
+   * Every ref the statement names, resolved and loaded. Refs the catalog does not know (a CTE, a
+   * subquery's alias, a typo) simply drop out, as does any table whose columns refuse to load —
+   * the answer is thinner, never absent.
+   */
+  sources: (refs: TableRef[]) => Promise<SqlSource[]>;
+}
+declare function createSqlSchema(catalog: SqlCatalog): SqlSchema;
+//#endregion
+//#region src/assist.d.ts
+/**
+ * One suggestion. `label` is what the pane shows and what the editor filters the operator's
+ * typing against; `insertText` is what lands in the statement, which differs whenever the
+ * position needs more than the name (a qualified column, an expanded list, a whole join
+ * condition).
+ */
+interface SqlCompletionCandidate {
+  label: string;
+  /**
+   * Drives the pane's icon. `snippet` is the synthetic kind: a candidate that is an edit rather
+   * than a name — the `*` expansion, the insert skeleton, a join condition.
+   */
+  kind: "keyword" | "function" | "schema" | "table" | "view" | "column" | "snippet";
+  insertText: string;
+  /**
+   * `insertText` is a snippet (`$0` marks the caret) rather than plain text.
+   */
+  snippet?: boolean;
+  /**
+   * Characters immediately before the caret that this insert replaces, beyond the partial word
+   * the editor already replaces on its own. Only the `*` expansion uses it — it stands in for a
+   * `*` the operator has already typed, which is punctuation and so outside the editor's word
+   * range.
+   */
+  replace?: number;
+  detail?: string;
+  documentation?: string;
+  /**
+   * Rank band. Lower bands sort first; within one band the engine's own array order decides, so
+   * a column list keeps the catalog's ordinal order instead of falling to the alphabet.
+   */
+  sortGroup: number;
+}
+/**
+ * What hovering a span of the statement says about it. Offsets are into the text handed to
+ * `hover`, so the editor can turn them into its own range without re-reading the SQL.
+ */
+interface SqlHoverCard {
+  from: number;
+  to: number;
+  /**
+   * Markdown blocks, rendered in order.
+   */
+  markdown: string[];
+}
+/**
+ * One call's signature while the caret sits inside its parens.
+ */
+interface SqlSignatureHelp {
+  /**
+   * The whole call as it is written, e.g. `coalesce(value, fallback, …)`.
+   */
+  label: string;
+  /**
+   * Each parameter's `[start, end)` within `label` — offsets rather than substrings, so a
+   * signature that repeats a parameter name still marks the right one.
+   */
+  parameters: Array<[number, number]>;
+  /**
+   * The parameter the caret is in, already clamped onto a variadic tail.
+   */
+  active: number;
+  documentation?: string;
+}
+/**
+ * The editor's assist for one connection's schema and dialect: everything the surface can ask
+ * that needs to know either. One instance per selected connection — the catalog memo behind it
+ * lives exactly as long.
+ */
+interface SqlAssist {
+  complete: (text: string, offset: number) => Promise<SqlCompletionCandidate[]>;
+  hover: (text: string, offset: number) => Promise<SqlHoverCard | null>;
+  /**
+   * The vocabulary a signature comes from includes the estate's own routines, which only the
+   * catalog knows — so this waits on I/O like the rest, and answers from a memo after the first.
+   */
+  signature: (text: string, offset: number) => Promise<SqlSignatureHelp | null>;
+  /**
+   * The whole statement text, reformatted — or `null` when the dialect cannot parse it, which
+   * leaves the operator's text untouched.
+   */
+  format: (text: string) => Promise<string | null>;
+}
+/**
+ * Everything the SQL editor can ask about one connection's schema, over one shared catalog:
+ * completion, hover and signature help all read the same statement through `reader.ts` — under
+ * this kind's own lexical profile — and the same schema through `schema.ts`, so they can never
+ * disagree about what the operator is looking at, and the catalog is asked for nothing beyond
+ * what a schema tree already fetches.
+ *
+ * One instance per selected connection. The host memoizes it; another vendor's schema is another
+ * object, and nothing is held here that could outlive it.
+ */
+declare function createSqlAssist(kind: SqlKind, catalog: SqlCatalog): SqlAssist;
+//#endregion
+export { CatalogTable as C, CatalogFunction as S, readCall as _, createSqlAssist as a, runnableStatement as b, SqlSource as c, CallRead as d, IdentifierRead as f, TableRef as g, StatementRead as h, SqlSignatureHelp as i, createSqlSchema as l, StatementContext as m, SqlCompletionCandidate as n, SqlCatalog as o, Runnable as p, SqlHoverCard as r, SqlSchema as s, SqlAssist as t, qualifiedName as u, readIdentifier as v, SqlKind as w, CatalogColumn as x, readStatement as y };