@tablecraft-app/plugin-api 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tranphucbol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @tablecraft-app/plugin-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The contract between [TableCraft](https://github.com/tranphucbol/table-craft) and its datasource
+plugins: the types a plugin implements, the manifest schema, the shared SQL helpers and the
+contract test suite every built-in plugin passes.
+
+| Entry                                | Holds                                                                                                     |
+| :----------------------------------- | :-------------------------------------------------------------------------------------------------------- |
+| `@tablecraft-app/plugin-api`         | `DatasourcePlugin`, `Session`, `SqlLanguage`, the manifest schema, `PluginError`, `API_VERSION`, and more |
+| `@tablecraft-app/plugin-api/sql`     | The statement splitter, classifier, literal helpers, completer and formatter plugins build `language` on  |
+| `@tablecraft-app/plugin-api/testing` | `runPluginContract(plugin, fixture)`, the contract suite, for Vitest                                      |
+
+## A plugin
+
+A plugin is a folder with a `table-craft-plugin.json` manifest and an ES module whose default
+export implements `DatasourcePlugin`. Put it in `plugins/<id>/` in the TableCraft profile folder.
+Set the manifest's `apiVersion` to the version of this package you built against; bundle this
+package and your driver into the module, since TableCraft loads the plugin from its folder alone.
+
+```ts
+import type { DatasourcePlugin } from "@tablecraft-app/plugin-api";
+
+const plugin: DatasourcePlugin = {
+  id: "example",
+  capabilities: ["sql"],
+  // connectionSchema, language and connect
+};
+
+export default plugin;
+```
+
+Test it with the contract suite in a Vitest file: `runPluginContract(plugin, fixture)` connects
+with `fixture.config` to a database seeded with the suite's `type_probe` table, and checks every
+capability the manifest declares. `ContractFixture` documents each field.
+
+## Compatibility
+
+This package follows semver, and its version is the plugin API version:
+
+- TableCraft with plugin API `1.z` loads a plugin built for `1.y` when `y` is `z` or lower.
+- A minor version only adds: new exports, new optional fields and methods, new capabilities.
+- Breaking changes wait for the next major. Before removal, a member is marked `@deprecated` with
+  its replacement for at least one major.
+
+## License
+
+MIT

package/dist/catalog.d.ts

@@ -0,0 +1,112 @@
+/**
+ * A database or schema: the unit the explorer lists, introspects and caches (decision 022).
+ * `path` names it from the server down, such as `["table_craft", "public"]` on PostgreSQL.
+ */
+export interface Namespace {
+    readonly path: readonly string[];
+    readonly name: string;
+    readonly kind: "database" | "schema";
+    /** The database's own catalog, such as `pg_catalog`; hidden unless the user asks. */
+    readonly system: boolean;
+    /** Where unqualified names resolve for this connection. */
+    readonly current: boolean;
+}
+export interface ColumnMeta {
+    readonly name: string;
+    /** 1-based, in table order. */
+    readonly position: number;
+    /** The type as the database spells it, such as `numeric(12,2)`. */
+    readonly type: string;
+    readonly nullable: boolean;
+    /** The default expression as the database prints it; null when there is none. */
+    readonly default: string | null;
+    readonly comment: string | null;
+    readonly autoIncrement: boolean;
+}
+export interface Key {
+    readonly name: string;
+    readonly columns: readonly string[];
+}
+export interface ForeignKey {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly target: {
+        readonly path: readonly string[];
+        readonly relation: string;
+        readonly columns: readonly string[];
+    };
+    /** The referential action as SQL spells it, such as `CASCADE` or `NO ACTION`. */
+    readonly onDelete: string;
+    readonly onUpdate: string;
+}
+export interface Index {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+    readonly primary: boolean;
+}
+export type RelationKind = "table" | "view" | "materializedView";
+export interface Relation {
+    readonly name: string;
+    readonly kind: RelationKind;
+    readonly comment: string | null;
+    /** Ordered by position. */
+    readonly columns: readonly ColumnMeta[];
+    readonly primaryKey: Key | null;
+    readonly uniqueKeys: readonly Key[];
+    readonly foreignKeys: readonly ForeignKey[];
+    readonly indexes: readonly Index[];
+}
+export declare const ROUTINE_PARAMETER_MODES: readonly ["in", "out", "inout", "variadic"];
+export type RoutineParameterMode = (typeof ROUTINE_PARAMETER_MODES)[number];
+export interface RoutineParameter {
+    /** Null when the database records none, as PostgreSQL allows. */
+    readonly name: string | null;
+    /** As the database prints it, `numeric` or `decimal(12,2)`. */
+    readonly type: string;
+    readonly mode: RoutineParameterMode;
+    readonly hasDefault: boolean;
+}
+/** Name, kind and signature are unique in a namespace; PostgreSQL overloads are separate routines. */
+export interface Routine {
+    readonly name: string;
+    readonly kind: "function" | "procedure";
+    /** The argument list as the database prints it, without parentheses. */
+    readonly signature: string;
+    /** In declaration order; a function's result and `RETURNS TABLE` columns are not parameters. */
+    readonly parameters: readonly RoutineParameter[];
+    /** A function's result as the database prints it; null for a procedure. */
+    readonly returns: string | null;
+}
+export interface Sequence {
+    readonly name: string;
+}
+/** Everything one `describe` returns; every list but `columns` is sorted by name. */
+export interface NamespaceCatalog {
+    readonly path: readonly string[];
+    readonly relations: readonly Relation[];
+    readonly routines: readonly Routine[];
+    readonly sequences: readonly Sequence[];
+}
+/** Present on a session exactly when the plugin declares `schemaTree`. */
+export interface Introspector {
+    /** Every namespace the connection can see, system ones included and marked. */
+    namespaces(): Promise<readonly Namespace[]>;
+    /**
+     * Rejects with a `PluginError` coded `introspectionFailed` when the namespace does not exist
+     * or the user cannot read it.
+     */
+    describe(path: readonly string[]): Promise<NamespaceCatalog>;
+    /** `name` inside `path`, quoted the way this database quotes identifiers. */
+    qualifiedName(path: readonly string[], name: string): string;
+    /**
+     * Present exactly when the plugin declares `ddl` (decision 029). The statements that create
+     * relation `name` in `path`, read from the database on every call: each ends in `;` and a blank
+     * line separates them. Rejects with `DefinitionNotFoundError` when there is no such relation.
+     */
+    definition?(path: readonly string[], name: string): Promise<string>;
+}
+/** Sorts by `name`, the order every catalog list but columns is returned in. */
+export declare function byName<T extends {
+    readonly name: string;
+}>(items: Iterable<T>): T[];

package/dist/catalog.js

@@ -0,0 +1,5 @@
+export const ROUTINE_PARAMETER_MODES = ["in", "out", "inout", "variadic"];
+/** Sorts by `name`, the order every catalog list but columns is returned in. */
+export function byName(items) {
+    return [...items].sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+}

package/dist/completion.d.ts

@@ -0,0 +1,109 @@
+import type { ForeignKey, Namespace, Relation } from "./catalog.js";
+/** What a completion item names; the console draws each with the Database pane's glyph for it. */
+export declare const COMPLETION_KINDS: readonly ["namespace", "table", "view", "column", "alias", "cte", "join", "function", "keyword"];
+export type CompletionKind = (typeof COMPLETION_KINDS)[number];
+export interface CompletionItem {
+    /** What the popup shows and the editor filters on. */
+    readonly label: string;
+    readonly kind: CompletionKind;
+    /** A column's type, a relation's namespace or a join's foreign key; null when there is nothing to add. */
+    readonly detail: string | null;
+    /** The text accepting the item inserts over the result's `from`…`to`, quoted where the dialect needs it. */
+    readonly apply: string;
+    /** Orders items the typed prefix matches equally well; higher comes first, within -99…99. */
+    readonly boost: number;
+    /** Longer text the popup shows beside the selected item, such as a function's signatures and summary. */
+    readonly info: string | null;
+    /** Where the caret lands, as an offset into `apply`; null for its end. */
+    readonly caret: number | null;
+}
+export interface FunctionParameter {
+    readonly name: string;
+    readonly optional?: boolean;
+    /** Repeats: the call may pass it any number of times. */
+    readonly variadic?: boolean;
+}
+/** One way to call a function: its parameters in order and what it returns. */
+export interface FunctionSignature {
+    readonly parameters: readonly FunctionParameter[];
+    readonly returns: string;
+}
+/** The function call around the caret (decision 098). */
+export interface SignatureHelp {
+    readonly name: string;
+    readonly summary: string;
+    readonly signatures: readonly FunctionSignature[];
+    /** The zero-based argument the caret is in: the top-level commas before it inside the call. */
+    readonly argument: number;
+    /** The call's name to the end of its arguments, or to the caret while it is still open. */
+    readonly from: number;
+    readonly to: number;
+}
+/** What completion knows about the server it completes for; null fields when the catalog could not open. */
+export interface CompletionServer {
+    /** The version string the session reports, such as `8.4.3` or `5.7.25-TiDB-v4.0.14`. */
+    readonly version: string | null;
+}
+/** The table a clause body is written against, such as the table editor's WHERE bar (plan 009 decision 9). */
+export interface CompletionScope {
+    readonly path: readonly string[];
+    readonly relation: string;
+}
+export interface CompletionRequest {
+    readonly text: string;
+    /** The caret, in UTF-16 offsets into `text` (decision 023). */
+    readonly offset: number;
+    /** When present, `text` is a clause body with `relation` in scope, not a whole script. */
+    readonly scope?: CompletionScope;
+}
+export interface CompletionResult {
+    /** The span accepting an item replaces: the word typed before the caret. */
+    readonly from: number;
+    readonly to: number;
+    readonly items: readonly CompletionItem[];
+    /**
+     * A regular expression source the editor may keep filtering these items with while the typed word
+     * still matches it, without asking again; null to ask again on every keystroke.
+     */
+    readonly validFor: string | null;
+}
+export interface ResolveRequest {
+    readonly text: string;
+    readonly offset: number;
+}
+/** Where the name at the caret was declared (plan 009 decision 10). */
+export type Declaration = {
+    readonly kind: "alias" | "cte";
+    readonly from: number;
+    readonly to: number;
+} | {
+    readonly kind: "relation";
+    readonly path: readonly string[];
+    readonly relation: string;
+} | {
+    readonly kind: "column";
+    readonly path: readonly string[];
+    readonly relation: string;
+    readonly column: string;
+};
+/** A foreign key in `path`.`relation` that targets the relation asked about. */
+export interface IncomingForeignKey {
+    readonly path: readonly string[];
+    readonly relation: string;
+    readonly foreignKey: ForeignKey;
+}
+/**
+ * What completion may read about the datasource (decision 028): the engine's catalog cache. It
+ * never touches a console's session, and answers with what it has once a describe runs too long.
+ */
+export interface CompletionCatalog {
+    /** Where unqualified names resolve; null when the datasource reports no current namespace. */
+    readonly current: readonly string[] | null;
+    /** The server behind the cache, so a plugin offers only the functions it has (decision 097). */
+    readonly server: CompletionServer;
+    namespaces(): Promise<readonly Namespace[]>;
+    /** Every relation in `path`, described on demand; empty when the describe fails or runs too long. */
+    relations(path: readonly string[]): Promise<readonly Relation[]>;
+    /** Foreign keys targeting `path`.`relation` in every namespace described so far. */
+    referencing(path: readonly string[], relation: string): Promise<readonly IncomingForeignKey[]>;
+}

package/dist/completion.js

@@ -0,0 +1,12 @@
+/** What a completion item names; the console draws each with the Database pane's glyph for it. */
+export const COMPLETION_KINDS = [
+    "namespace",
+    "table",
+    "view",
+    "column",
+    "alias",
+    "cte",
+    "join",
+    "function",
+    "keyword",
+];

package/dist/errors.d.ts

@@ -0,0 +1,67 @@
+/** Failures the host tells apart; anything else a plugin throws is reported as `statementFailed`. */
+export declare const PLUGIN_ERROR_CODES: readonly ["cancelled", "connectionFailed", "statementFailed", "introspectionFailed", "definitionNotFound", "explainUnsupported", "connectionLost", "sessionBusy", "conflict"];
+export type PluginErrorCode = (typeof PLUGIN_ERROR_CODES)[number];
+/**
+ * Where the database located a failure, relative to the statement text the plugin received:
+ * `offset` is 0-based in UTF-16 code units (a JavaScript string index); `line` and `column` count
+ * from 1, the column in UTF-16 code units too.
+ */
+export type ErrorPosition = {
+    readonly offset: number;
+} | {
+    readonly line: number;
+    readonly column: number;
+};
+export interface PluginErrorOptions extends ErrorOptions {
+    /** Leave it out when the database did not say; the host then underlines nothing. */
+    readonly position?: ErrorPosition;
+}
+/** What a plugin throws when the host should react to the kind of failure, not just show it. */
+export declare class PluginError extends Error {
+    readonly code: PluginErrorCode;
+    readonly name = "PluginError";
+    readonly position: ErrorPosition | undefined;
+    constructor(code: PluginErrorCode, message: string, options?: PluginErrorOptions);
+}
+/**
+ * Structural, because every bundled plugin carries its own copy of this module, so `instanceof`
+ * fails for an error thrown by a plugin and caught by the host.
+ */
+export declare function isPluginError(error: unknown): error is PluginError;
+/**
+ * The position a plugin attached to a `PluginError`, checked by shape, since the error comes from
+ * another bundle; anything malformed reads as no position.
+ */
+export declare function errorPositionOf(error: unknown): ErrorPosition | undefined;
+/** `position` as a 0-based offset into `text`, clamped to the text. */
+export declare function offsetOfPosition(text: string, position: ErrorPosition): number;
+/**
+ * A `connectionFailed` the SSL settings caused: a certificate file that cannot be read or used, or
+ * a server certificate that failed verification. The host then points at those settings instead
+ * of the host, port, user and password (decision 072).
+ */
+export declare class TlsSettingsError extends PluginError {
+    readonly tlsSettings = true;
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Structural for the same reason as `isPluginError`. */
+export declare function isTlsSettingsError(error: unknown): error is TlsSettingsError;
+/**
+ * A guarded `Keyspace.apply` found `target` changed since it was read (decision 115): `detail`
+ * says what differs, such as `field name is now "Bo"`. Nothing was written.
+ */
+export declare class ConflictError extends PluginError {
+    readonly target: string;
+    readonly detail: string;
+    constructor(target: string, detail: string, options?: ErrorOptions);
+}
+/**
+ * `Introspector.definition` asked for a relation the database does not have, usually one dropped
+ * or renamed since the catalog was read (decision 029). Coded `definitionNotFound`, so the host
+ * recognises it with `isPluginError` across plugin bundles.
+ */
+export declare class DefinitionNotFoundError extends PluginError {
+    readonly path: readonly string[];
+    readonly relation: string;
+    constructor(path: readonly string[], relation: string, options?: ErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,124 @@
+/** Failures the host tells apart; anything else a plugin throws is reported as `statementFailed`. */
+export const PLUGIN_ERROR_CODES = [
+    "cancelled",
+    "connectionFailed",
+    "statementFailed",
+    "introspectionFailed",
+    "definitionNotFound",
+    /** `Session.explain` refused the statement; the message says why and what to explain instead. */
+    "explainUnsupported",
+    /**
+     * The connection was gone before the statement was sent, so the host may reconnect and run it
+     * again; `Session.ping` rejects with it too.
+     */
+    "connectionLost",
+    /**
+     * The session is still busy with an earlier statement or result and refused this one unsent
+     * (decision 058). The host waits for every close first, so this is a bug it logs and heals by
+     * reconnecting; never a message for the user.
+     */
+    "sessionBusy",
+    /**
+     * A guarded write found what it was to change already changed by someone else, and wrote
+     * nothing (decision 115); the host offers to reload or to overwrite.
+     */
+    "conflict",
+];
+/** What a plugin throws when the host should react to the kind of failure, not just show it. */
+export class PluginError extends Error {
+    code;
+    name = "PluginError";
+    position;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.position = options?.position;
+    }
+}
+/**
+ * Structural, because every bundled plugin carries its own copy of this module, so `instanceof`
+ * fails for an error thrown by a plugin and caught by the host.
+ */
+export function isPluginError(error) {
+    if (!(error instanceof Error) || error.name !== "PluginError")
+        return false;
+    const code = error.code;
+    return PLUGIN_ERROR_CODES.some((known) => known === code);
+}
+function isWholeAtLeast(value, least) {
+    return typeof value === "number" && Number.isInteger(value) && value >= least;
+}
+/**
+ * The position a plugin attached to a `PluginError`, checked by shape, since the error comes from
+ * another bundle; anything malformed reads as no position.
+ */
+export function errorPositionOf(error) {
+    if (!isPluginError(error))
+        return undefined;
+    const position = error.position;
+    if (typeof position !== "object" || position === null)
+        return undefined;
+    const { offset, line, column } = position;
+    if (isWholeAtLeast(offset, 0))
+        return { offset };
+    if (isWholeAtLeast(line, 1) && isWholeAtLeast(column, 1))
+        return { line, column };
+    return undefined;
+}
+/** `position` as a 0-based offset into `text`, clamped to the text. */
+export function offsetOfPosition(text, position) {
+    if ("offset" in position)
+        return Math.min(position.offset, text.length);
+    let start = 0;
+    for (let line = 1; line < position.line; line += 1) {
+        const end = text.indexOf("\n", start);
+        if (end === -1)
+            return text.length;
+        start = end + 1;
+    }
+    const lineEnd = text.indexOf("\n", start);
+    const limit = lineEnd === -1 ? text.length : lineEnd;
+    return Math.min(start + position.column - 1, limit);
+}
+/**
+ * A `connectionFailed` the SSL settings caused: a certificate file that cannot be read or used, or
+ * a server certificate that failed verification. The host then points at those settings instead
+ * of the host, port, user and password (decision 072).
+ */
+export class TlsSettingsError extends PluginError {
+    tlsSettings = true;
+    constructor(message, options) {
+        super("connectionFailed", message, options);
+    }
+}
+/** Structural for the same reason as `isPluginError`. */
+export function isTlsSettingsError(error) {
+    return isPluginError(error) && error.tlsSettings === true;
+}
+/**
+ * A guarded `Keyspace.apply` found `target` changed since it was read (decision 115): `detail`
+ * says what differs, such as `field name is now "Bo"`. Nothing was written.
+ */
+export class ConflictError extends PluginError {
+    target;
+    detail;
+    constructor(target, detail, options) {
+        super("conflict", `${target} changed since it was read: ${detail}. Reload it, or overwrite the change.`, options);
+        this.target = target;
+        this.detail = detail;
+    }
+}
+/**
+ * `Introspector.definition` asked for a relation the database does not have, usually one dropped
+ * or renamed since the catalog was read (decision 029). Coded `definitionNotFound`, so the host
+ * recognises it with `isPluginError` across plugin bundles.
+ */
+export class DefinitionNotFoundError extends PluginError {
+    path;
+    relation;
+    constructor(path, relation, options) {
+        super("definitionNotFound", `There is no relation ${relation} in ${path.join(".")}; synchronize the data source to see what it holds now.`, options);
+        this.path = path;
+        this.relation = relation;
+    }
+}

package/dist/explain.d.ts

@@ -0,0 +1,58 @@
+import type { ServerMessage } from "./plugin.js";
+/** A name and its value as the database printed it, such as `Filter` and `(total > 10)`. */
+export interface PlanProperty {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * One step of a plan (decision 031), normalised from whatever the dialect prints. Numbers are plain
+ * JavaScript numbers, not wire values: they are estimates and timings, never data. Null where the
+ * dialect reports nothing, so a view leaves the cell empty.
+ */
+export interface PlanNode {
+    /** What the step does, such as `Seq Scan` or `Nested loop inner join`. */
+    readonly operation: string;
+    /** The relation it reads, such as `orders o`; null when it reads none or the dialect does not say. */
+    readonly target: string | null;
+    /** One line more about the step, such as the index it uses; null when there is none. */
+    readonly detail: string | null;
+    readonly estimatedRows: number | null;
+    /** The planner's total cost, in the dialect's own units. */
+    readonly estimatedCost: number | null;
+    readonly actualRows: number | null;
+    /** Milliseconds until the step returned its last row, per loop. */
+    readonly actualTimeMs: number | null;
+    readonly loops: number | null;
+    /** Everything else the dialect reports about the step, in its order. */
+    readonly properties: readonly PlanProperty[];
+    readonly children: readonly PlanNode[];
+}
+/** What `Session.explain` answers. */
+export interface ExplainedPlan {
+    /** The EXPLAIN statement the plugin sent, which is what history records. */
+    readonly statement: string;
+    /** Whether the statement ran (Explain Analyse) rather than only being planned. */
+    readonly analyzed: boolean;
+    readonly roots: readonly PlanNode[];
+    /** Facts about the whole plan, such as `Planning Time` and `Execution Time`. */
+    readonly summary: readonly PlanProperty[];
+    /** The plan as the database printed it. */
+    readonly raw: string;
+    /** What the server said while explaining, as `ExecuteResult.messages`; present exactly when the plugin declares `serverMessages`. */
+    readonly messages?: readonly ServerMessage[];
+}
+export interface ExplainOptions {
+    /** Run the statement and report what it did (Explain Analyse), not only how it would run. */
+    readonly analyze: boolean;
+}
+/**
+ * Whether a statement can be explained, decided without a database. `writes` says the statement
+ * changes something, so analysing it, which runs it, needs the user's consent first.
+ */
+export type Explainability = {
+    readonly ok: true;
+    readonly writes: boolean;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};

package/dist/explain.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { byName, type ColumnMeta, type ForeignKey, type Index, type Introspector, type Key, type Namespace, type NamespaceCatalog, type Relation, type RelationKind, ROUTINE_PARAMETER_MODES, type Routine, type RoutineParameter, type RoutineParameterMode, type Sequence, } from "./catalog.js";
+export { COMPLETION_KINDS, type CompletionCatalog, type CompletionItem, type CompletionKind, type CompletionRequest, type CompletionResult, type CompletionScope, type CompletionServer, type Declaration, type FunctionParameter, type FunctionSignature, type IncomingForeignKey, type ResolveRequest, type SignatureHelp, } from "./completion.js";
+export { INSPECTION_IDS, type InspectionId, type InspectionRequest, type Problem, PROBLEM_SEVERITIES, type ProblemSeverity, type QuickFix, type TextEdit, } from "./inspection.js";
+export { ConflictError, DefinitionNotFoundError, type ErrorPosition, errorPositionOf, isPluginError, isTlsSettingsError, offsetOfPosition, PLUGIN_ERROR_CODES, PluginError, type PluginErrorCode, type PluginErrorOptions, TlsSettingsError, } from "./errors.js";
+export { type ExplainedPlan, type Explainability, type ExplainOptions, type PlanNode, type PlanProperty, } from "./explain.js";
+export { KEY_TYPES, type KeyApplied, type KeyApplyOptions, type KeyBytes, type KeyChange, type KeyContents, type KeyDatabase, type KeyDetails, type KeyExpiry, type KeyInfo, type KeyName, type KeyReadRequest, type KeyScan, type KeyScanRequest, type Keyspace, type KeyType, } from "./keyspace.js";
+export { OBJECT_KINDS, type CatalogObject, type CheckDesign, type ColumnDesign, type DdlContext, type DdlScript, type ForeignKeyDesign, type IndexDesign, type ObjectChange, type ObjectChangeKind, type ObjectEditor, type ObjectFeatures, type ObjectKind, type TableDesign, } from "./objects.js";
+export { CONNECTION_FIELD_GROUPS, CONNECTION_FIELD_KINDS, CONNECTION_URL_FORMS, CONNECTION_URL_PARTS, connectionFieldSchema, connectionUrlSchema, MANIFEST_FILE, networkSpecSchema, pluginManifestSchema, TLS_FIELD_ROLES, tlsSpecSchema, type ConnectionField, type ConnectionFieldGroup, type ConnectionFieldKind, type ConnectionUrl, type ConnectionUrlForm, type ConnectionUrlPart, type NetworkSpec, type PluginManifest, type TlsFieldRole, type TlsSpec, } from "./manifest.js";
+export { ConnectionUrlError, formatConnectionUrl, parseConnectionUrl, type ConnectionForm, type ConnectionUrlSpec, type ConnectionValue, type ParsedConnectionUrl, } from "./url.js";
+export { type BoundStatement, CAPABILITIES, type Capability, type Column, type ColumnOrigin, type CommandLanguage, type CommandReply, type ConnectOptions, type DatasourcePlugin, type ExecuteOptions, type ExecuteResult, type FormatOptions, FORMAT_STYLES, type FormatStyle, GENERATED_STATEMENTS, type GeneratedStatement, IMPORT_KINDS, type ImportKind, type InferredColumn, type InsertRow, type InsertTarget, KEYWORD_CASES, type NamespaceSwitch, NODE_ALL_PRIMARIES, NODE_AUTO, NODE_ROLES, type NodeRole, type ServerInfo, type ServerInfoSection, type ServerNode, type SlowCommand, switchableTo, type NewColumn, type KeywordCase, PARAMETER_STYLES, type ParameterStyle, type ParameterValue, type RoutineArgument, type RoutineCall, type Row, type SavepointStatements, type SelectSource, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, type ServerMessage, type ServerMessageLevel, type SqlParameter, type Session, type SqlLanguage, STATEMENT_KINDS, type StatementClass, type StatementKind, type StatementSpan, type StatementStream, type StreamedStatement, type TlsInfo, TRANSACTION_MODES, type TransactionMode, type Transactions, } from "./plugin.js";
+export { SERVER_SESSION_STATES, type ServerSession, type ServerSessionState, type SessionListing, type SessionMonitor, type SessionTarget, } from "./sessions.js";
+export { TLS_CHAIN_CODES, TLS_HOST_CODE, homeExpanded, tlsFailureMessage, tlsFileMessage, tlsKeyIsEncrypted, tlsKeyMessage, type TlsVerification, } from "./tls.js";
+export { BYTES_PREVIEW_LENGTH, toBytesValue, toWireInteger, toWireValue, type WireValueOptions, type BigIntValue, type BytesValue, type DateValue, type JsonValue, type TypeClass, type WireValue, } from "./values.js";
+export { API_VERSION, incompatibility, type Incompatibility, isCompatible, parseVersion } from "./version.js";
+/** Plugins build `connectionSchema` with the zod the contract was compiled against, not their own pick. */
+export { z } from "zod";

package/dist/index.js

@@ -0,0 +1,16 @@
+export { byName, ROUTINE_PARAMETER_MODES, } from "./catalog.js";
+export { COMPLETION_KINDS, } from "./completion.js";
+export { INSPECTION_IDS, PROBLEM_SEVERITIES, } from "./inspection.js";
+export { ConflictError, DefinitionNotFoundError, errorPositionOf, isPluginError, isTlsSettingsError, offsetOfPosition, PLUGIN_ERROR_CODES, PluginError, TlsSettingsError, } from "./errors.js";
+export {} from "./explain.js";
+export { KEY_TYPES, } from "./keyspace.js";
+export { OBJECT_KINDS, } from "./objects.js";
+export { CONNECTION_FIELD_GROUPS, CONNECTION_FIELD_KINDS, CONNECTION_URL_FORMS, CONNECTION_URL_PARTS, connectionFieldSchema, connectionUrlSchema, MANIFEST_FILE, networkSpecSchema, pluginManifestSchema, TLS_FIELD_ROLES, tlsSpecSchema, } from "./manifest.js";
+export { ConnectionUrlError, formatConnectionUrl, parseConnectionUrl, } from "./url.js";
+export { CAPABILITIES, FORMAT_STYLES, GENERATED_STATEMENTS, IMPORT_KINDS, KEYWORD_CASES, NODE_ALL_PRIMARIES, NODE_AUTO, NODE_ROLES, switchableTo, PARAMETER_STYLES, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, STATEMENT_KINDS, TRANSACTION_MODES, } from "./plugin.js";
+export { SERVER_SESSION_STATES, } from "./sessions.js";
+export { TLS_CHAIN_CODES, TLS_HOST_CODE, homeExpanded, tlsFailureMessage, tlsFileMessage, tlsKeyIsEncrypted, tlsKeyMessage, } from "./tls.js";
+export { BYTES_PREVIEW_LENGTH, toBytesValue, toWireInteger, toWireValue, } from "./values.js";
+export { API_VERSION, incompatibility, isCompatible, parseVersion } from "./version.js";
+/** Plugins build `connectionSchema` with the zod the contract was compiled against, not their own pick. */
+export { z } from "zod";

package/dist/inspection.d.ts

@@ -0,0 +1,38 @@
+/** How loudly the console marks a problem (plan 108): red wavy, amber wavy, or muted dotted. */
+export declare const PROBLEM_SEVERITIES: readonly ["error", "warning", "weak"];
+export type ProblemSeverity = (typeof PROBLEM_SEVERITIES)[number];
+/**
+ * The inspections `sqlInspector` runs. The ids are DataGrip's, so a `-- noinspection <Id>` comment
+ * written there silences the same check here.
+ */
+export declare const INSPECTION_IDS: readonly ["SqlSyntax", "SqlResolve", "SqlAmbiguousColumn", "SqlReservedWordAsName", "SqlInsertValues", "SqlWithoutWhere", "SqlNullComparison", "SqlConstantCondition", "SqlUnusedCte", "SqlDuplicateAlias", "SqlRedundantOrderingDirection", "SqlRedundantAlias", "SqlRedundantElseNull"];
+export type InspectionId = (typeof INSPECTION_IDS)[number];
+/** One replacement in the inspected text; offsets are UTF-16 indexes into `InspectionRequest.text`. */
+export interface TextEdit {
+    readonly from: number;
+    readonly to: number;
+    readonly insert: string;
+}
+/** A fix the user can apply from Alt+Enter: its edits apply together, as one undo step. */
+export interface QuickFix {
+    readonly title: string;
+    readonly edits: readonly TextEdit[];
+    /** Where the caret goes after the edits, as an offset into the edited text; absent leaves it. */
+    readonly caret?: number;
+}
+/** A problem found while typing, before anything runs. */
+export interface Problem {
+    readonly from: number;
+    readonly to: number;
+    readonly severity: ProblemSeverity;
+    /** An `INSPECTION_IDS` entry, or a plugin's own id for a check it adds. */
+    readonly inspection: string;
+    readonly message: string;
+    readonly fixes: readonly QuickFix[];
+}
+export interface InspectionRequest {
+    /** The whole console text; problems cover every statement in it. */
+    readonly text: string;
+    /** Inspections the user turned off; the plugin skips them. */
+    readonly disabled?: readonly string[];
+}