neonctl 2.22.2 → 2.23.0

package/psql/complete/index.js

@@ -0,0 +1,104 @@
+/**
+ * Public entrypoint for psql tab completion.
+ *
+ * The `LineEditor` (WP-24) accepts a `Completer` of shape
+ * `(input, cursor) => Promise<CompletionResult>`. We return a CURRIED
+ * factory `psqlCompleter(ctx)` that captures the settings reference so the
+ * completer can read `ctx.settings.db` lazily on every call — important
+ * because `\c` swaps out the live connection.
+ *
+ * `CompletionResult` (defined in lineEditor/complete.ts):
+ *
+ *   - candidates:    string[]   the list shown / inserted
+ *   - commonPrefix:  string     longest prefix the editor can insert without
+ *                               making a choice (`apply` walks this)
+ *   - replaceLength: number     code-points to chop off the buffer before
+ *                               inserting `candidates[i]` / commonPrefix
+ *
+ * Our `findCompletions` returns raw candidate strings; we compute the common
+ * prefix here. `replaceLength` is the code-point length of the partial word
+ * the cursor was sitting on (`currentWord`), which we already compute in
+ * `splitForCompletion` during tokenization.
+ */
+import { splitForCompletion } from './matcher.js';
+import { findCompletions } from './rules.js';
+/**
+ * Build a completer bound to the given settings. The settings reference is
+ * captured by closure; we never snapshot, so changes to `settings.db` (via
+ * `\c`) take effect immediately.
+ */
+export const psqlCompleter = (ctx) => {
+    const completer = async (input, cursor) => {
+        const { prevWords, currentWord, replaceLength } = splitForCompletion(input, cursor);
+        const ruleCtx = {
+            settings: ctx.settings,
+            queryBuf: ctx.getQueryBuf?.() ?? '',
+        };
+        const { candidates } = await findCompletions(prevWords, currentWord, ruleCtx);
+        // De-duplicate while preserving order.
+        const seen = new Set();
+        const deduped = [];
+        for (const c of candidates) {
+            if (!seen.has(c)) {
+                seen.add(c);
+                deduped.push(c);
+            }
+        }
+        // Stable sort so the listing is predictable. The first-character sort
+        // key uses lowercase so case-mixed candidate lists don't look chaotic.
+        deduped.sort((a, b) => {
+            const la = a.toLowerCase();
+            const lb = b.toLowerCase();
+            if (la < lb)
+                return -1;
+            if (la > lb)
+                return 1;
+            return 0;
+        });
+        const commonPrefix = longestCommonPrefix(deduped, currentWord);
+        return {
+            candidates: deduped,
+            commonPrefix,
+            replaceLength,
+        };
+    };
+    return completer;
+};
+// ---------------------------------------------------------------------------
+// Helpers.
+// ---------------------------------------------------------------------------
+/**
+ * Return the longest common prefix of all candidates, but never shorter
+ * than the user's partial input (so we don't backtrack the buffer when the
+ * completion is a no-op).
+ *
+ * If there's a single candidate, returns it whole.
+ */
+const longestCommonPrefix = (candidates, fallback) => {
+    if (candidates.length === 0)
+        return fallback;
+    if (candidates.length === 1)
+        return candidates[0];
+    // Use code-point iteration so multi-byte characters don't get cut.
+    const arrs = candidates.map((c) => Array.from(c));
+    const minLen = arrs.reduce((m, a) => Math.min(m, a.length), Infinity);
+    const out = [];
+    for (let i = 0; i < minLen; i++) {
+        const first = arrs[0][i];
+        let ok = true;
+        for (let j = 1; j < arrs.length; j++) {
+            if (arrs[j][i] !== first) {
+                ok = false;
+                break;
+            }
+        }
+        if (!ok)
+            break;
+        out.push(first);
+    }
+    // Common prefix should not be shorter than what's already typed.
+    const candidatePrefix = out.join('');
+    if (candidatePrefix.length >= fallback.length)
+        return candidatePrefix;
+    return fallback;
+};

package/psql/complete/matcher.js

@@ -0,0 +1,314 @@
+/**
+ * Matches / TailMatches / HeadMatches DSL.
+ *
+ * TypeScript port of the pattern-matching helpers in psql's tab-complete.in.c.
+ * The C source uses a varargs macro layered on top of `word_matches()` to
+ * decide whether a sequence of "previous words" matches a pattern. We
+ * reproduce the same shape with plain functions because (a) JS has no
+ * preprocessor macros and (b) array spread is the natural varargs analogue.
+ *
+ *   Matches('SELECT', MatchAny, 'FROM')       — exact word-count match.
+ *   TailMatches('SELECT', MatchAny, 'FROM')   — match the last N words.
+ *   HeadMatches('ALTER', 'TABLE')             — match the first N words.
+ *
+ * Wildcards and special tokens (mirroring the upstream constants):
+ *
+ *   MatchAny             — any single word (`NULL` upstream).
+ *   MatchAnyExcept(x)    — any word that doesn't match `x` (upstream `"!x"`).
+ *   '*' inside a pattern — wildcard within a single word (e.g. `'pg_*'`).
+ *   '|' inside a pattern — alternation (e.g. `'TABLE|VIEW'`).
+ *
+ * Comparisons are case-insensitive by default (SQL keywords); pass
+ * `caseSensitive: true` to the DSL helpers when matching strictly.
+ *
+ * The tokenizer is exported separately because the `index.ts` entry point
+ * needs to do the same word-split-then-match dance.
+ */
+export const MatchAny = null;
+export const MatchAnyExcept = (pattern) => '!' + pattern;
+const cimatch = (s1, s2, n, caseSensitive) => {
+    if (s1.length < n || s2.length < n)
+        return false;
+    const a = s1.slice(0, n);
+    const b = s2.slice(0, n);
+    if (caseSensitive)
+        return a === b;
+    return a.toLowerCase() === b.toLowerCase();
+};
+/**
+ * Return true iff `word` matches `pattern`. `null`/`MatchAny` matches
+ * everything. A leading `!` inverts the match. `|` separates alternatives.
+ * `*` is a single-word wildcard.
+ */
+export const wordMatches = (pattern, word, caseSensitive = false) => {
+    if (pattern === null)
+        return true;
+    if (pattern.startsWith('!')) {
+        return !wordMatches(pattern.slice(1), word, caseSensitive);
+    }
+    const wordlen = word.length;
+    let cursor = pattern;
+    for (;;) {
+        let starIdx = -1;
+        let i = 0;
+        while (i < cursor.length && cursor[i] !== '|') {
+            if (cursor[i] === '*')
+                starIdx = i;
+            i++;
+        }
+        if (starIdx >= 0) {
+            const beforeLen = starIdx;
+            const afterLen = i - starIdx - 1;
+            if (wordlen >= beforeLen + afterLen &&
+                cimatch(word, cursor, beforeLen, caseSensitive) &&
+                cimatch(word.slice(wordlen - afterLen), cursor.slice(starIdx + 1), afterLen, caseSensitive)) {
+                return true;
+            }
+        }
+        else {
+            if (wordlen === i && cimatch(word, cursor, wordlen, caseSensitive)) {
+                return true;
+            }
+        }
+        if (i >= cursor.length)
+            break;
+        cursor = cursor.slice(i + 1);
+    }
+    return false;
+};
+/**
+ * Exact-length match: every word in `words` must match the corresponding
+ * pattern. `words` here is "previous words" — i.e. the words BEFORE the
+ * current (in-progress) word.
+ *
+ * The upstream uses `previous_words_count + 1 == narg` because the C array
+ * includes both prev words AND the current. Our representation only stores
+ * prev words; the caller passes the in-progress word separately.
+ *
+ *   prev = ['SELECT'], pattern = ['SELECT']         → true   (1 == 1)
+ *   prev = ['SELECT', 'a'], pattern = ['SELECT']    → false  (2 != 1)
+ */
+export const Matches = (prev, patterns, caseSensitive = false) => {
+    if (prev.length !== patterns.length)
+        return false;
+    for (let k = 0; k < patterns.length; k++) {
+        if (!wordMatches(patterns[k], prev[k], caseSensitive))
+            return false;
+    }
+    return true;
+};
+/**
+ * Tail match: the LAST N words of `prev` must match the patterns.
+ *
+ *   prev = ['SELECT', 'a', 'FROM'], patterns = ['FROM']   → true
+ *   prev = ['SELECT'], patterns = ['SELECT', 'FROM']     → false (too few)
+ */
+export const TailMatches = (prev, patterns, caseSensitive = false) => {
+    if (prev.length < patterns.length)
+        return false;
+    const offset = prev.length - patterns.length;
+    for (let k = 0; k < patterns.length; k++) {
+        if (!wordMatches(patterns[k], prev[offset + k], caseSensitive))
+            return false;
+    }
+    return true;
+};
+/**
+ * Head match: the FIRST N words of `prev` must match.
+ *
+ *   prev = ['ALTER', 'TABLE', 'foo'], patterns = ['ALTER', 'TABLE']  → true
+ */
+export const HeadMatches = (prev, patterns, caseSensitive = false) => {
+    if (prev.length < patterns.length)
+        return false;
+    for (let k = 0; k < patterns.length; k++) {
+        if (!wordMatches(patterns[k], prev[k], caseSensitive))
+            return false;
+    }
+    return true;
+};
+/**
+ * Split `input` into psql-style words for completion purposes.
+ *
+ *   - Whitespace is the basic separator.
+ *   - "..."           treated as ONE word (quoted identifier).
+ *   - '...'           treated as ONE word (string literal).
+ *   - \backslash...   treated as ONE word (the backslash command).
+ *   - Punctuation (commas, parens, semicolons) is broken into its own word.
+ *   - Embedded `.` (schema-qualifier) keeps the dotted name as a single word
+ *     so completion sees `pg_catalog.pg_class` whole.
+ *
+ * The tokenizer is intentionally pragmatic — it doesn't validate SQL, it
+ * just slices well enough for the rule body to inspect previous words.
+ */
+export const tokenize = (input) => {
+    const out = [];
+    let i = 0;
+    while (i < input.length) {
+        const ch = input[i];
+        // Whitespace.
+        if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+            i++;
+            continue;
+        }
+        // Backslash command. Capture the entire backslash word as one token.
+        if (ch === '\\') {
+            const start = i;
+            i++;
+            // Single-char commands like `\!` and `\?` are valid; otherwise read
+            // letters until we hit whitespace or punctuation.
+            if (i < input.length && /[!?]/.test(input[i])) {
+                i++;
+            }
+            else {
+                while (i < input.length && /[A-Za-z_]/.test(input[i]))
+                    i++;
+                // Fold a trailing `+` run (the verbose suffix) into the command word
+                // so `\dt+ <TAB>` tokenizes as a single word and the describe rules
+                // that key on `prevWords.length === 1` still fire. The
+                // `S` (system-objects) suffix is already a letter, so it's consumed
+                // above; only `+` needs explicit handling here.
+                while (i < input.length && input[i] === '+')
+                    i++;
+            }
+            out.push({
+                text: input.slice(start, i),
+                raw: input.slice(start, i),
+                start,
+                end: i,
+            });
+            continue;
+        }
+        // Double-quoted identifier.
+        if (ch === '"') {
+            const start = i;
+            i++;
+            while (i < input.length) {
+                if (input[i] === '"') {
+                    // "" inside quotes is an escaped quote.
+                    if (input[i + 1] === '"') {
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            out.push({
+                text: input.slice(start, i),
+                raw: input.slice(start, i),
+                start,
+                end: i,
+            });
+            continue;
+        }
+        // Single-quoted string literal.
+        if (ch === "'") {
+            const start = i;
+            i++;
+            while (i < input.length) {
+                if (input[i] === '\\' && i + 1 < input.length) {
+                    i += 2;
+                    continue;
+                }
+                if (input[i] === "'") {
+                    if (input[i + 1] === "'") {
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            out.push({
+                text: input.slice(start, i),
+                raw: input.slice(start, i),
+                start,
+                end: i,
+            });
+            continue;
+        }
+        // Punctuation that splits words.
+        if (ch === ',' ||
+            ch === ';' ||
+            ch === '(' ||
+            ch === ')' ||
+            ch === '[' ||
+            ch === ']') {
+            out.push({ text: ch, raw: ch, start: i, end: i + 1 });
+            i++;
+            continue;
+        }
+        // Bareword: letters, digits, underscore, `.` (schema qualifier), `:` (var
+        // expansion marker is kept inside the word), `$` (positional param).
+        const start = i;
+        while (i < input.length) {
+            const c = input[i];
+            if (c === ' ' ||
+                c === '\t' ||
+                c === '\n' ||
+                c === '\r' ||
+                c === ',' ||
+                c === ';' ||
+                c === '(' ||
+                c === ')' ||
+                c === '[' ||
+                c === ']' ||
+                c === '"' ||
+                c === "'" ||
+                c === '\\') {
+                break;
+            }
+            i++;
+        }
+        out.push({
+            text: input.slice(start, i),
+            raw: input.slice(start, i),
+            start,
+            end: i,
+        });
+    }
+    return out;
+};
+/**
+ * Slice `input` at `cursor`, then determine what's being completed:
+ *
+ *   - `prevWords`: the completed words ENTIRELY before the cursor.
+ *   - `currentWord`: the partial word the cursor is sitting in (may be '').
+ *   - `replaceLength`: number of code points to chop off the input before
+ *      inserting the completion (= length of currentWord in code points).
+ *
+ * The tokenizer is run on `input.slice(0, cursor)` and the LAST token, if
+ * it ends exactly at cursor and didn't start with whitespace/punctuation,
+ * becomes the current word. Otherwise the current word is empty (the user
+ * just typed a space and is starting a new word).
+ */
+export const splitForCompletion = (input, cursor) => {
+    const head = input.slice(0, cursor);
+    const tokens = tokenize(head);
+    if (tokens.length === 0) {
+        return { prevWords: [], currentWord: '', replaceLength: 0 };
+    }
+    const last = tokens[tokens.length - 1];
+    // The cursor is sitting inside the last token if (a) it ends exactly at
+    // cursor AND (b) the last char before cursor isn't whitespace.
+    const charBefore = head[head.length - 1];
+    const inWhitespace = charBefore === ' ' ||
+        charBefore === '\t' ||
+        charBefore === '\n' ||
+        charBefore === '\r';
+    if (last.end === head.length && !inWhitespace) {
+        return {
+            prevWords: tokens.slice(0, -1).map((t) => t.text),
+            currentWord: last.text,
+            replaceLength: Array.from(last.text).length,
+        };
+    }
+    return {
+        prevWords: tokens.map((t) => t.text),
+        currentWord: '',
+        replaceLength: 0,
+    };
+};

package/psql/complete/psqlVars.js

@@ -0,0 +1,247 @@
+/**
+ * Static-list completion candidates for psql special variables, settings,
+ * and the small enums their values take.
+ *
+ * The values come from `pset_lookup_option` and the var-hook table in psql
+ * (`src/bin/psql/variables.c` + `command.c`). We keep this module pure data
+ * so it's trivial to extend as new variables are added in later WPs.
+ */
+/** All psql special variables (anything that has a hook in variables.c). */
+export const SPECIAL_VARIABLES = [
+    'AUTOCOMMIT',
+    'COMP_KEYWORD_CASE',
+    'DBNAME',
+    'ECHO',
+    'ECHO_HIDDEN',
+    'ENCODING',
+    'ERROR',
+    'FETCH_COUNT',
+    'HIDE_TABLEAM',
+    'HIDE_TOAST_COMPRESSION',
+    'HISTCONTROL',
+    'HISTFILE',
+    'HISTSIZE',
+    'HOST',
+    'IGNOREEOF',
+    'LASTOID',
+    'LAST_ERROR_MESSAGE',
+    'LAST_ERROR_SQLSTATE',
+    'ON_ERROR_ROLLBACK',
+    'ON_ERROR_STOP',
+    'PORT',
+    'PROMPT1',
+    'PROMPT2',
+    'PROMPT3',
+    'QUIET',
+    'ROW_COUNT',
+    'SERVER_VERSION_NAME',
+    'SERVER_VERSION_NUM',
+    'SHELL_ERROR',
+    'SHELL_EXIT_CODE',
+    'SHOW_ALL_RESULTS',
+    'SHOW_CONTEXT',
+    'SINGLELINE',
+    'SINGLESTEP',
+    'SQLSTATE',
+    'USER',
+    'VERBOSITY',
+    'VERSION',
+    'VERSION_NAME',
+    'VERSION_NUM',
+];
+/** `\pset` option names. */
+export const PSET_OPTIONS = [
+    'border',
+    'columns',
+    'csv_fieldsep',
+    'expanded',
+    'fieldsep',
+    'fieldsep_zero',
+    'footer',
+    'format',
+    'linestyle',
+    'null',
+    'numericlocale',
+    'pager',
+    'pager_min_lines',
+    'recordsep',
+    'recordsep_zero',
+    'tableattr',
+    'title',
+    'tuples_only',
+    'unicode_border_linestyle',
+    'unicode_column_linestyle',
+    'unicode_header_linestyle',
+    'xheader_width',
+];
+/** Output formats accepted by `\pset format`. */
+export const PSET_FORMATS = [
+    'aligned',
+    'asciidoc',
+    'csv',
+    'html',
+    'latex',
+    'latex-longtable',
+    'troff-ms',
+    'unaligned',
+    'wrapped',
+];
+/** Line styles accepted by `\pset linestyle`. */
+export const PSET_LINESTYLES = [
+    'ascii',
+    'old-ascii',
+    'unicode',
+];
+/** Unicode border/column/header line styles. */
+export const PSET_UNICODE_STYLES = ['single', 'double'];
+/** `xheader_width` argument forms. */
+export const PSET_XHEADER_WIDTHS = [
+    'column',
+    'full',
+    'page',
+];
+/** On/off/auto enum, used by many variables. */
+export const ON_OFF = ['on', 'off'];
+export const ON_OFF_AUTO = ['on', 'off', 'auto'];
+/** Echo modes. */
+export const ECHO_MODES = [
+    'none',
+    'errors',
+    'queries',
+    'all',
+];
+export const ECHO_HIDDEN_MODES = ['off', 'on', 'noexec'];
+export const ON_ERROR_ROLLBACK_MODES = [
+    'off',
+    'on',
+    'interactive',
+];
+export const VERBOSITY_MODES = [
+    'default',
+    'verbose',
+    'terse',
+    'sqlstate',
+];
+export const SHOW_CONTEXT_MODES = [
+    'never',
+    'errors',
+    'always',
+];
+export const COMP_KEYWORD_CASE_MODES = [
+    'lower',
+    'upper',
+    'preserve-lower',
+    'preserve-upper',
+];
+export const HIST_CONTROL_MODES = [
+    'none',
+    'ignorespace',
+    'ignoredups',
+    'ignoreboth',
+];
+/** A handful of common client encodings — enough to be useful at `\encoding`. */
+export const ENCODINGS = [
+    'BIG5',
+    'EUC_CN',
+    'EUC_JIS_2004',
+    'EUC_JP',
+    'EUC_KR',
+    'EUC_TW',
+    'GB18030',
+    'GBK',
+    'ISO_8859_5',
+    'ISO_8859_6',
+    'ISO_8859_7',
+    'ISO_8859_8',
+    'JOHAB',
+    'KOI8R',
+    'KOI8U',
+    'LATIN1',
+    'LATIN2',
+    'LATIN3',
+    'LATIN4',
+    'LATIN5',
+    'LATIN6',
+    'LATIN7',
+    'LATIN8',
+    'LATIN9',
+    'LATIN10',
+    'MULE_INTERNAL',
+    'SJIS',
+    'SHIFT_JIS_2004',
+    'SQL_ASCII',
+    'UHC',
+    'UTF8',
+    'WIN866',
+    'WIN874',
+    'WIN1250',
+    'WIN1251',
+    'WIN1252',
+    'WIN1253',
+    'WIN1254',
+    'WIN1255',
+    'WIN1256',
+    'WIN1257',
+    'WIN1258',
+];
+/**
+ * For a given `\pset` option, return the list of values it accepts. Returns
+ * `null` for free-form options (title, fieldsep, etc.).
+ */
+export const psetValuesFor = (option) => {
+    switch (option) {
+        case 'format':
+            return PSET_FORMATS;
+        case 'linestyle':
+            return PSET_LINESTYLES;
+        case 'unicode_border_linestyle':
+        case 'unicode_column_linestyle':
+        case 'unicode_header_linestyle':
+            return PSET_UNICODE_STYLES;
+        case 'xheader_width':
+            return PSET_XHEADER_WIDTHS;
+        case 'expanded':
+        case 'pager':
+            return ON_OFF_AUTO;
+        case 'footer':
+        case 'tuples_only':
+        case 'numericlocale':
+        case 'fieldsep_zero':
+        case 'recordsep_zero':
+            return ON_OFF;
+        default:
+            return null;
+    }
+};
+/**
+ * For a given special variable, return acceptable values, or `null` if free-form.
+ */
+export const variableValuesFor = (name) => {
+    switch (name) {
+        case 'AUTOCOMMIT':
+        case 'ON_ERROR_STOP':
+        case 'QUIET':
+        case 'SINGLELINE':
+        case 'SINGLESTEP':
+        case 'SHOW_ALL_RESULTS':
+        case 'HIDE_TOAST_COMPRESSION':
+        case 'HIDE_TABLEAM':
+            return ON_OFF;
+        case 'ECHO':
+            return ECHO_MODES;
+        case 'ECHO_HIDDEN':
+            return ECHO_HIDDEN_MODES;
+        case 'ON_ERROR_ROLLBACK':
+            return ON_ERROR_ROLLBACK_MODES;
+        case 'VERBOSITY':
+            return VERBOSITY_MODES;
+        case 'SHOW_CONTEXT':
+            return SHOW_CONTEXT_MODES;
+        case 'COMP_KEYWORD_CASE':
+            return COMP_KEYWORD_CASE_MODES;
+        case 'HISTCONTROL':
+            return HIST_CONTROL_MODES;
+        default:
+            return null;
+    }
+};