@tablecraft-app/plugin-api 1.2.0 → 1.4.0

package/dist/completion.d.ts

@@ -22,6 +22,8 @@ export interface FunctionParameter {
     readonly optional?: boolean;
     /** Repeats: the call may pass it any number of times. */
     readonly variadic?: boolean;
+    /** The keyword written before it instead of a comma, such as `FROM` in `EXTRACT(unit FROM date)`; `|` separates alternatives. */
+    readonly lead?: string;
 }
 /** One way to call a function: its parameters in order and what it returns. */
 export interface FunctionSignature {
@@ -33,7 +35,10 @@ 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. */
+    /**
+     * The zero-based parameter the caret is in: the top-level commas before it inside the call, or,
+     * when the signature has keyword-led parameters (`lead`), the one the separators walk to.
+     */
     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;

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { COMPLETION_KINDS, type CompletionCatalog, type CompletionItem, type Com
 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 { 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 KeySource, 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";

package/dist/keyspace.d.ts

@@ -15,6 +15,18 @@ export interface KeyBytes {
 }
 /** A key's name: bytes, since a key may be any binary string. */
 export type KeyName = KeyBytes;
+/**
+ * The one key a command's reply was read from (decision 119), so the host can open the key or
+ * edit the reply as the key. `whole` is true when the reply holds the entire key, such as
+ * `HGETALL` or `LRANGE k 0 -1`; its columns are then the ones `Keyspace.read` gives that type,
+ * without positions a key tab adds (a zset's `#`), and a string's is one `value` column.
+ */
+export interface KeySource {
+    readonly database: number;
+    readonly key: KeyName;
+    readonly type: KeyType;
+    readonly whole: boolean;
+}
 /** One logical database of the keyspace: Redis' `db0`–`db15`, or the one database of a cluster. */
 export interface KeyDatabase {
     readonly index: number;

package/dist/plugin.d.ts

@@ -3,7 +3,7 @@ import type { Introspector, Namespace, Relation, Routine } from "./catalog.js";
 import type { CompletionCatalog, CompletionRequest, CompletionResult, Declaration, ResolveRequest, SignatureHelp } from "./completion.js";
 import type { ExplainedPlan, Explainability, ExplainOptions } from "./explain.js";
 import type { InspectionRequest, Problem } from "./inspection.js";
-import type { Keyspace } from "./keyspace.js";
+import type { KeySource, Keyspace } from "./keyspace.js";
 import type { ObjectEditor } from "./objects.js";
 import type { SessionMonitor } from "./sessions.js";
 import type { TypeClass, WireValue } from "./values.js";
@@ -58,16 +58,27 @@ export interface ExecuteResult {
     readonly messages?: readonly ServerMessage[];
     /**
      * A command's one-value answer, such as a status, a number or a string (decision 112): the
-     * console shows it in Output and opens no result. Only a `commands` plugin sets it, and then
+     * console shows it in Output and opens no result unless it is `read`. Only a `commands` plugin sets it, and then
      * `columns` and `rows` are empty.
      */
     readonly reply?: CommandReply;
+    /**
+     * The one key the command read, when it read exactly one (decision 119); absent for writes,
+     * keyless and multi-key commands. Only a `keyValue` plugin sets it.
+     */
+    readonly source?: KeySource;
 }
 /** A scalar reply to a command (decision 112). */
 export interface CommandReply {
     readonly value: WireValue;
     /** The reply as the server's own client prints it: `"Ann"`, `(integer) 5`, `(nil)`, `OK`. */
     readonly text: string;
+    /**
+     * The reply is a value read, such as a bulk string from `GET` or `HGET` or the nil of a missing
+     * one (decision 119): the console opens it as a one-row `value` result besides Output. Absent
+     * for statuses, numbers and errors, which stay in Output.
+     */
+    readonly read?: boolean;
 }
 /** How serious a `ServerMessage` is, from the server's own word for it. */
 export declare const SERVER_MESSAGE_LEVELS: readonly ["error", "warning", "notice", "info"];

package/dist/sql/complete.js

@@ -1,4 +1,4 @@
-import { functionItem, functionName, isAvailable } from "./functions.js";
+import { functionItem, functionName, functionPackage, isAvailable, leadMatches, memberItem, } from "./functions.js";
 import { callAt } from "./signature.js";
 import { parseSimpleSelect, SELECT_READ_ONLY_REASONS } from "./select.js";
 import { scopeAt } from "./scope.js";
@@ -76,6 +76,50 @@ const QUOTES = new Set(['"', "`", "["]);
 /** Below every other namespace: `USE mysql` is legitimate but rarely meant. */
 const SYSTEM_NAMESPACE_BOOST = -20;
 const CURRENT_DETAIL = "current";
+const COMMA = ",";
+const MEMBER_SEPARATOR = ".";
+/**
+ * Walks `separators` through `signature`: a comma moves to the next parameter without a lead, a
+ * word to the next one it leads. A word nothing leads is an argument's own (`YEAR`, `DECIMAL`).
+ * Past the last parameter a comma keeps counting, as the hint's variadic rule expects; a variadic
+ * parameter keyword-led ones follow (`CHAR(code... USING charset)`) takes every comma.
+ */
+function argumentAt(signature, separators) {
+    const { parameters } = signature;
+    let at = 0;
+    let entered = false;
+    let led = 0;
+    for (const separator of separators) {
+        if (separator === COMMA) {
+            const next = parameters.findIndex((parameter, index) => index > at && parameter.lead === undefined);
+            if (next >= 0)
+                at = next;
+            else if (!(parameters[at]?.variadic === true && at < parameters.length - 1))
+                at += 1;
+            entered = true;
+            continue;
+        }
+        const next = parameters.findIndex((parameter, index) => (index > at || (index === at && !entered)) &&
+            parameter.lead !== undefined &&
+            leadMatches(parameter.lead, separator));
+        if (next < 0)
+            continue;
+        at = next;
+        entered = true;
+        led += 1;
+    }
+    return { argument: at, led };
+}
+/** The argument the caret is in, by the overload whose leads the call follows most; the first on a tie. */
+function argumentOf(spec, call) {
+    let best = null;
+    for (const signature of spec.signatures) {
+        const found = argumentAt(signature, call.separators ?? []);
+        if (best === null || found.led > best.led)
+            best = found;
+    }
+    return best?.argument ?? call.argument;
+}
 function relationKind(relation) {
     return relation.kind === "table" ? "table" : "view";
 }
@@ -93,6 +137,13 @@ export function sqlCompleter(options) {
     function specNamed(name, server) {
         return specs.get(name.toUpperCase())?.find((spec) => isAvailable(spec, server));
     }
+    /** The members of the package `qualifier` names, as offered after its dot. */
+    function memberItems(qualifier, server) {
+        const name = qualifier.map((part) => part.name.toUpperCase()).join(MEMBER_SEPARATOR);
+        return availableFunctions(server, true)
+            .filter((spec) => typeof spec !== "string" && functionPackage(spec) === name)
+            .map((spec) => memberItem(spec, BOOST.function));
+    }
     function quoted(name) {
         return options.plainIdentifier.test(name) && !reserved.has(name.toUpperCase())
             ? name
@@ -115,10 +166,13 @@ export function sqlCompleter(options) {
             .filter((keyword) => !except.has(keyword.toUpperCase()))
             .map((keyword) => item("keyword", keyword, keyword, null));
     }
-    function availableFunctions(server) {
+    /** Plain functions, or with `members` the package members only: a bare name never offers `pkg.member`. */
+    function availableFunctions(server, members = false) {
         const offered = new Set();
         return options.functions.filter((spec) => {
             const name = functionName(spec).toUpperCase();
+            if ((functionPackage(spec) !== null) !== members)
+                return false;
             if (offered.has(name) || (typeof spec !== "string" && !isAvailable(spec, server)))
                 return false;
             offered.add(name);
@@ -131,21 +185,22 @@ export function sqlCompleter(options) {
         if (last === undefined)
             return [];
         const relational = clause === "relation" || clause === "join";
+        const members = relational ? [] : memberItems(qualifier, lookup.server);
         if (qualifier.length === 1 && !relational) {
             const source = sourceNamed(query, last);
             if (source !== undefined)
-                return columnItems(await lookup.columnsOf(source, query));
+                return [...columnItems(await lookup.columnsOf(source, query)), ...members];
             const cte = cteNamed(query, last);
             if (cte !== undefined)
-                return columnItems(await lookup.cteColumns(cte, 1));
+                return [...columnItems(await lookup.cteColumns(cte, 1)), ...members];
         }
         const namespace = await lookup.namespace(qualifier);
         if (namespace !== undefined)
-            return relationItems(await lookup.relations(namespace.path), null);
+            return [...members, ...relationItems(await lookup.relations(namespace.path), null)];
         if (relational)
             return [];
         const found = await lookup.relation(qualifier.slice(0, -1), last);
-        return found === null ? [] : columnItems(found.relation.columns);
+        return found === null ? members : [...columnItems(found.relation.columns), ...members];
     }
     async function relationContextItems(scope, lookup) {
         const current = lookup.current;
@@ -463,7 +518,11 @@ export function sqlCompleter(options) {
     function signatureAt(request, catalog) {
         const { text, offset, shift } = wrap(request);
         const server = serverOf(catalog);
-        const call = callAt(text, offset, options.dialect, reserved, (name) => specNamed(name, server) !== undefined);
+        const callable = (name) => {
+            const spec = specNamed(name, server);
+            return spec !== undefined && spec.bare !== true;
+        };
+        const call = callAt(text, offset, options.dialect, reserved, callable);
         const spec = call === null ? undefined : specNamed(call.name, server);
         if (call === null || spec === undefined)
             return Promise.resolve(null);
@@ -471,7 +530,7 @@ export function sqlCompleter(options) {
             name: spec.name.toLowerCase(),
             summary: spec.summary,
             signatures: spec.signatures,
-            argument: call.argument,
+            argument: argumentOf(spec, call),
             from: call.from - shift,
             to: call.to - shift,
         });

package/dist/sql/functions.d.ts

@@ -21,26 +21,42 @@ export interface FunctionSpec {
     readonly summary: string;
     readonly category: FunctionCategory;
     readonly available?: ServerRange;
+    /** Written without parentheses, such as Oracle's `SYSDATE`; the call is the name alone and has no hint. */
+    readonly bare?: true;
 }
-/** `[name, signatures, summary, available?]`, a signature written `"date, format -> string"`. */
+/**
+ * `[name, signatures, summary, available?]`, a signature written `"date, format -> string"`, a
+ * keyword-led parameter `"unit FROM date -> integer"`, a bare function `"= date"` and a procedure
+ * `"str ->"`. A name `PKG.MEMBER` is offered after `pkg.`.
+ */
 export type FunctionEntry = readonly [
     name: string,
     signatures: string | readonly string[],
     summary: string,
     available?: ServerRange
 ];
-/** Reads `"str, len? -> string"`: `?` marks an optional parameter, `...` one that repeats. */
+/** Whether `lead` is `word` or offers it among its `|` alternatives. */
+export declare function leadMatches(lead: string, word: string): boolean;
+/**
+ * Reads `"str, len? -> string"`: `?` marks an optional parameter, `...` one that repeats, an
+ * upper-case word between names the keyword before the next (`"unit FROM date -> integer"`).
+ * `"= date"` is a bare function's and `"str ->"` a procedure's, which returns nothing.
+ */
 export declare function parseSignature(written: string): FunctionSignature;
 /** Specs for one category, from compact entries a plugin's data file lists. */
 export declare function functionSpecs(category: FunctionCategory, entries: readonly FunctionEntry[]): FunctionSpec[];
 /** Whether `spec` exists on `server`; an unknown server has every function any flavour has. */
 export declare function isAvailable(spec: FunctionSpec, server: ServerIdentity | null): boolean;
-/** `(date, format) → string`, the popup's detail for one signature. */
+/** `(date, format) → string`, the popup's detail for one signature; a lead replaces the comma, a procedure has no `→`. */
 export declare function signatureLabel(signature: FunctionSignature): string;
 /** Every signature on its own line, then the summary. */
 export declare function functionInfo(spec: FunctionSpec): string;
-/** A spec as an item: `name()` with the caret between the parentheses when it takes arguments. */
+/** A spec as an item: `name()` with the caret between the parentheses when it takes arguments, the name alone when bare. */
 export declare function functionItem(spec: FunctionSpec | string, boost: number): CompletionItem;
+/** The package a spec named `PKG.MEMBER` belongs to, upper case; null for a plain function. */
+export declare function functionPackage(spec: FunctionSpec | string): string | null;
+/** A package member as offered after `pkg.`: the member's name alone, the info naming it in full. */
+export declare function memberItem(spec: FunctionSpec, boost: number): CompletionItem;
 /** The name a function entry is offered under, either form. */
 export declare function functionName(spec: FunctionSpec | string): string;
 /** Aggregate and scalar functions every built-in dialect has; a plugin adds its own. Written in our own words. */

package/dist/sql/functions.js

@@ -20,7 +20,13 @@ const SHOWN_ARROW = "→";
 const OPTIONAL_MARK = "?";
 const VARIADIC_MARK = "...";
 const COMPARATOR = /^(>=|<=|>|<|=)?(\d+(?:\.\d+)*)$/;
-function parameter(written) {
+const BARE_MARK = "=";
+const LEAD_WORD = /^[A-Z][A-Z_]*$/;
+const LEAD_CHOICE = "|";
+const PARAMETER_SEPARATOR = ",";
+const COMMA_SHOWN = ", ";
+const MEMBER_SEPARATOR = ".";
+function parameter(written, lead) {
     let name = written.trim();
     const variadic = name.endsWith(VARIADIC_MARK);
     if (variadic)
@@ -28,28 +34,85 @@ function parameter(written) {
     const optional = name.endsWith(OPTIONAL_MARK);
     if (optional)
         name = name.slice(0, -OPTIONAL_MARK.length).trim();
-    return { name, ...(optional ? { optional } : {}), ...(variadic ? { variadic } : {}) };
+    return {
+        name,
+        ...(optional ? { optional } : {}),
+        ...(variadic ? { variadic } : {}),
+        ...(lead === null ? {} : { lead }),
+    };
 }
-/** Reads `"str, len? -> string"`: `?` marks an optional parameter, `...` one that repeats. */
+function isLeadWord(word) {
+    return word.split(LEAD_CHOICE).every((choice) => LEAD_WORD.test(choice));
+}
+/** Whether `lead` is `word` or offers it among its `|` alternatives. */
+export function leadMatches(lead, word) {
+    return lead.split(LEAD_CHOICE).includes(word);
+}
+/**
+ * One comma-separated part: an upper-case word between names leads the next, as one before the
+ * first parameter does; one standing alone is a keyword choice. After a comma the keyword is the
+ * argument's own (`date, INTERVAL expr unit`), since the comma already separates it.
+ */
+function leadParameters(part, index) {
+    const words = part.trim().split(/\s+/);
+    const parameters = [];
+    let lead = null;
+    let name = [];
+    const flush = () => {
+        if (name.length > 0)
+            parameters.push(parameter(name.join(" "), lead));
+        name = [];
+        lead = null;
+    };
+    words.forEach((word, at) => {
+        const next = words[at + 1];
+        const afterComma = at === 0 && index > 0;
+        if (!afterComma && isLeadWord(word) && next !== undefined && !isLeadWord(next)) {
+            flush();
+            lead = word;
+        }
+        else
+            name.push(word);
+    });
+    flush();
+    return parameters;
+}
+function isBareSignature(written) {
+    return written.trim().startsWith(BARE_MARK);
+}
+/**
+ * Reads `"str, len? -> string"`: `?` marks an optional parameter, `...` one that repeats, an
+ * upper-case word between names the keyword before the next (`"unit FROM date -> integer"`).
+ * `"= date"` is a bare function's and `"str ->"` a procedure's, which returns nothing.
+ */
 export function parseSignature(written) {
+    if (isBareSignature(written))
+        return { parameters: [], returns: written.trim().slice(BARE_MARK.length).trim() };
     const arrow = written.lastIndexOf(RETURNS_ARROW);
     if (arrow < 0)
         throw new Error(`Signature "${written}" has no "${RETURNS_ARROW} type"; add what it returns.`);
     const list = written.slice(0, arrow).trim();
     return {
-        parameters: list === "" ? [] : list.split(",").map(parameter),
+        parameters: list === "" ? [] : list.split(PARAMETER_SEPARATOR).flatMap(leadParameters),
         returns: written.slice(arrow + RETURNS_ARROW.length).trim(),
     };
 }
 /** Specs for one category, from compact entries a plugin's data file lists. */
 export function functionSpecs(category, entries) {
-    return entries.map(([name, signatures, summary, available]) => ({
-        name,
-        signatures: (typeof signatures === "string" ? [signatures] : signatures).map(parseSignature),
-        summary,
-        category,
-        ...(available === undefined ? {} : { available }),
-    }));
+    return entries.map(([name, signatures, summary, available]) => {
+        const written = typeof signatures === "string" ? [signatures] : signatures;
+        const bare = written.filter(isBareSignature).length;
+        if (bare > 0 && bare < written.length)
+            throw new Error(`${name} mixes "${BARE_MARK} type" with called signatures; write the bare form as "-> type".`);
+        return {
+            name,
+            signatures: written.map(parseSignature),
+            summary,
+            category,
+            ...(available === undefined ? {} : { available }),
+            ...(bare > 0 ? { bare: true } : {}),
+        };
+    });
 }
 function compareVersions(left, right) {
     for (let at = 0; at < Math.max(left.length, right.length); at += 1) {
@@ -91,37 +154,65 @@ export function isAvailable(spec, server) {
         .filter((comparator) => comparator !== "")
         .every((comparator) => satisfies(server.version, comparator));
 }
-function shownParameter(parameter) {
+function shownParameter(parameter, index) {
     const name = parameter.variadic === true ? `${parameter.name}${VARIADIC_MARK}` : parameter.name;
-    return parameter.optional === true ? `[${name}]` : name;
+    const led = parameter.lead === undefined ? name : `${parameter.lead} ${name}`;
+    const separator = index === 0 ? "" : parameter.lead === undefined ? COMMA_SHOWN : " ";
+    return separator + (parameter.optional === true ? `[${led}]` : led);
 }
-/** `(date, format) → string`, the popup's detail for one signature. */
+function returnsLabel(returns) {
+    return returns === "" ? "" : `${SHOWN_ARROW} ${returns}`;
+}
+/** `(date, format) → string`, the popup's detail for one signature; a lead replaces the comma, a procedure has no `→`. */
 export function signatureLabel(signature) {
-    return `(${signature.parameters.map(shownParameter).join(", ")}) ${SHOWN_ARROW} ${signature.returns}`;
+    const list = `(${signature.parameters.map(shownParameter).join("")})`;
+    const returns = returnsLabel(signature.returns);
+    return returns === "" ? list : `${list} ${returns}`;
+}
+function shownSignature(spec, signature) {
+    return spec.bare === true ? returnsLabel(signature.returns) : signatureLabel(signature);
 }
 /** Every signature on its own line, then the summary. */
 export function functionInfo(spec) {
     const label = spec.name.toLowerCase();
-    const lines = spec.signatures.map((signature) => `${label}${signatureLabel(signature)}`);
+    const gap = spec.bare === true ? " " : "";
+    const lines = spec.signatures.map((signature) => `${label}${gap}${shownSignature(spec, signature)}`);
     return `${lines.join("\n")}\n\n${spec.summary}`;
 }
-/** A spec as an item: `name()` with the caret between the parentheses when it takes arguments. */
-export function functionItem(spec, boost) {
-    if (typeof spec === "string")
-        return { label: spec, kind: "function", detail: null, apply: spec, boost, info: null, caret: null };
-    const label = spec.name.toLowerCase();
+/**
+ * A spec as an item: `name()` with the caret between the parentheses when it takes arguments, or
+ * the name alone for a bare one. `label` is what the popup offers, the member alone after `pkg.`.
+ */
+function specItem(spec, label, boost) {
     const first = spec.signatures[0];
     const takesArguments = spec.signatures.some((signature) => signature.parameters.length > 0);
+    const bare = spec.bare === true;
     return {
         label,
         kind: "function",
-        detail: first === undefined ? null : signatureLabel(first),
-        apply: `${label}()`,
+        detail: first === undefined ? null : shownSignature(spec, first),
+        apply: bare ? label : `${label}()`,
         boost,
         info: functionInfo(spec),
-        caret: takesArguments ? label.length + 1 : null,
+        caret: takesArguments && !bare ? label.length + 1 : null,
     };
 }
+/** A spec as an item: `name()` with the caret between the parentheses when it takes arguments, the name alone when bare. */
+export function functionItem(spec, boost) {
+    if (typeof spec === "string")
+        return { label: spec, kind: "function", detail: null, apply: spec, boost, info: null, caret: null };
+    return specItem(spec, spec.name.toLowerCase(), boost);
+}
+/** The package a spec named `PKG.MEMBER` belongs to, upper case; null for a plain function. */
+export function functionPackage(spec) {
+    const name = functionName(spec);
+    const dot = name.lastIndexOf(MEMBER_SEPARATOR);
+    return dot < 0 ? null : name.slice(0, dot).toUpperCase();
+}
+/** A package member as offered after `pkg.`: the member's name alone, the info naming it in full. */
+export function memberItem(spec, boost) {
+    return specItem(spec, spec.name.slice(spec.name.lastIndexOf(MEMBER_SEPARATOR) + 1).toLowerCase(), boost);
+}
 /** The name a function entry is offered under, either form. */
 export function functionName(spec) {
     return typeof spec === "string" ? spec : spec.name;

package/dist/sql/signature.d.ts

@@ -3,13 +3,21 @@ import type { SqlDialectOptions } from "./tokens.js";
 export interface CallAt {
     /** As written. */
     readonly name: string;
+    /** The top-level commas before the caret. */
     readonly argument: number;
+    /**
+     * The call's top-level `,` and words before the caret, in order, words upper case: what moves a
+     * keyword-led parameter list such as `EXTRACT(YEAR FROM d)` along. Always set by `callAt`;
+     * optional so a value built against the older shape still type-checks (decision 106).
+     */
+    readonly separators?: readonly string[];
     readonly from: number;
     readonly to: number;
 }
 /**
  * Finds the innermost call around `offset` whose name `known` accepts, counting its top-level
- * commas; strings, comments and quoted names are tokens of their own, so their commas never count.
+ * commas and listing its separators; strings, comments and quoted names are tokens of their own,
+ * so their commas never count. `pkg.member (` asks `known` for `PKG.MEMBER`.
  * Grouping parentheses are looked through; a subquery, a non-function name before `(` or a caret
  * in a string or comment ends the search with null. `reserved` holds the dialect's keywords: a
  * function spelled like one (`VALUES`, `LEFT`) is a call only where an operand fits, not after a

package/dist/sql/signature.js

@@ -1,4 +1,8 @@
 import { statementTokens } from "./scope.js";
+const COMMA = ",";
+const MEMBER_SEPARATOR = ".";
+/** Calls a procedure by name, so it may come before a package member as it never may before a function. */
+const CALL_WORD = "CALL";
 /** Words a relation or routine name follows, so `TABLE upper (` defines rather than calls. */
 const NAME_INTRODUCERS = new Set([
     "CALL",
@@ -25,7 +29,8 @@ function upperWord(text, token) {
 }
 /**
  * Finds the innermost call around `offset` whose name `known` accepts, counting its top-level
- * commas; strings, comments and quoted names are tokens of their own, so their commas never count.
+ * commas and listing its separators; strings, comments and quoted names are tokens of their own,
+ * so their commas never count. `pkg.member (` asks `known` for `PKG.MEMBER`.
  * Grouping parentheses are looked through; a subquery, a non-function name before `(` or a caret
  * in a string or comment ends the search with null. `reserved` holds the dialect's keywords: a
  * function spelled like one (`VALUES`, `LEFT`) is a call only where an operand fits, not after a
@@ -35,23 +40,42 @@ export function callAt(text, offset, dialect, reserved, known) {
     const { tokens, literal } = statementTokens(text, offset, dialect);
     if (literal)
         return null;
-    function callable(at) {
+    /** `pkg.member` ending at `at`, when the package's spec knows the member. */
+    function member(at) {
         const name = tokens[at];
+        const owner = tokens[at - 2];
         const word = upperWord(text, name);
-        if (name === undefined || word === null || !known(word))
+        const ownerWord = upperWord(text, owner);
+        if (name === undefined || owner === undefined || word === null || ownerWord === null)
+            return null;
+        if (!known(`${ownerWord}${MEMBER_SEPARATOR}${word}`))
             return null;
+        const previous = upperWord(text, tokens[at - 3]);
+        if (previous !== null && previous !== CALL_WORD && NAME_INTRODUCERS.has(previous))
+            return null;
+        return {
+            written: `${text.slice(owner.from, owner.to)}${MEMBER_SEPARATOR}${text.slice(name.from, name.to)}`,
+            from: owner.from,
+        };
+    }
+    function callable(at) {
+        const name = tokens[at];
         const before = tokens[at - 1];
-        if (symbol(text, before, "."))
+        if (symbol(text, before, MEMBER_SEPARATOR))
+            return member(at);
+        const word = upperWord(text, name);
+        if (name === undefined || word === null || !known(word))
             return null;
+        const found = { written: text.slice(name.from, name.to), from: name.from };
         const previous = upperWord(text, before);
         if (previous !== null && NAME_INTRODUCERS.has(previous))
             return null;
         if (!reserved.has(word))
-            return name;
+            return found;
         const operandFits = before === undefined ||
             (before.kind === "symbol" && !symbol(text, before, ")")) ||
             (previous !== null && reserved.has(previous));
-        return operandFits ? name : null;
+        return operandFits ? found : null;
     }
     const frames = [];
     let index = 0;
@@ -61,14 +85,27 @@ export function callAt(text, offset, dialect, reserved, known) {
             break;
         if (symbol(text, token, "(")) {
             const name = callable(index - 1);
-            frames.push({ name, named: name === null && !grouping(text, tokens[index - 1]), open: index, commas: 0 });
+            frames.push({
+                name,
+                named: name === null && !grouping(text, tokens[index - 1]),
+                open: index,
+                commas: 0,
+                separators: [],
+            });
         }
         else if (symbol(text, token, ")"))
             frames.pop();
-        else if (symbol(text, token, ",")) {
+        else if (symbol(text, token, COMMA)) {
             const top = frames.at(-1);
-            if (top !== undefined)
+            if (top !== undefined) {
                 top.commas += 1;
+                top.separators.push(COMMA);
+            }
+        }
+        else {
+            const word = upperWord(text, token);
+            if (word !== null)
+                frames.at(-1)?.separators.push(word);
         }
     }
     for (let depth = frames.length - 1; depth >= 0; depth -= 1) {
@@ -81,8 +118,9 @@ export function callAt(text, offset, dialect, reserved, known) {
             continue;
         }
         return {
-            name: text.slice(frame.name.from, frame.name.to),
+            name: frame.name.written,
             argument: frame.commas,
+            separators: frame.separators,
             from: frame.name.from,
             to: closeOf(text, tokens, index, frames.length - depth) ?? offset,
         };

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { z, type DatasourcePlugin, type KeyChange, type KeyContents, type KeyType, type PluginManifest, type Routine, type RoutineArgument, type Row, type ServerMessage } from "@tablecraft-app/plugin-api";
+import { z, type DatasourcePlugin, type KeyChange, type KeyContents, type KeySource, type KeyType, type PluginManifest, type Routine, type RoutineArgument, type Row, type ServerMessage } from "@tablecraft-app/plugin-api";
 export interface ContractFixture {
     /** The plugin's parsed `table-craft-plugin.json`, whose connection form the suite checks. */
     readonly manifest: PluginManifest;
@@ -201,6 +201,19 @@ export interface KeyspaceFixture {
     };
     /** A scratch key the suite creates, changes and removes. */
     readonly edit: KeyEditFixture;
+    /**
+     * Commands run in a console and the key each reply names as its source, null for none
+     * (decision 119): one that reads a whole key, one that reads part of one, and one that reads
+     * several. Without it the reply-source tests are skipped.
+     */
+    readonly sources?: readonly KeySourceFixture[];
+}
+/** A command and the source its reply names (decision 119). */
+export interface KeySourceFixture {
+    readonly command: string;
+    readonly source: KeySource | null;
+    /** The reply is a value read, which the console opens as a one-row result. */
+    readonly read?: boolean;
 }
 /** How the suite changes one element of a scratch key and reads it back (decision 115). */
 export interface KeyEditFixture {

package/dist/testing/index.js

@@ -1934,6 +1934,17 @@ export function runPluginContract(plugin, fixture) {
                 expect(cursor).toBeNull();
                 return { keys, batches };
             }
+            it.runIf(fixture.keyspace?.sources !== undefined)("givenSingleKeyRead_whenExecute_thenReplyNamesItsSourceKey", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    for (const expected of keyspaceFixture().sources ?? []) {
+                        const result = await session.execute(expected.command);
+                        await collect(result.rows);
+                        expect(result.source ?? null, expected.command).toEqual(expected.source);
+                        if (expected.read !== undefined)
+                            expect(result.reply?.read ?? false, expected.command).toBe(expected.read);
+                    }
+                });
+            });
             it("givenKeyspace_whenDatabases_thenFixtureDatabaseCountedAndOneCurrent", async () => {
                 await withSession(plugin, fixture, async (session) => {
                     const databases = await keyspaceOf(session).databases();

package/dist/version.js

@@ -2,7 +2,7 @@
  * The plugin contract's version, by semver (decision 106): a host loads a plugin built for the same
  * major and an older or equal minor. Typed `string` so a bump does not change the API report.
  */
-export const API_VERSION = "1.2.0";
+export const API_VERSION = "1.4.0";
 const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 /** `major.minor.patch` and nothing else; pre-release and build tags are not accepted. */
 export function parseVersion(text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablecraft-app/plugin-api",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "The datasource plugin contract for TableCraft",
   "license": "MIT",
   "type": "module",