@bridgeline-digital/hawk-app-cli 0.1.0-dev.20261020202308 → 0.1.0

package/src/queries.mjs

@@ -1,289 +1,289 @@
-import { existsSync } from 'node:fs';
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { join } from 'node:path';
-
-// App queries (`data:read`): queries/<name>.sql + queries/<name>.json, deployed with each version and run by the
-// platform against the current client's data. Same rules as the platform, which validates again on deploy.
-export const QUERIES_DIR = 'queries';
-export const DATA_SCOPE = 'data:read';
-export const MAX_QUERIES = 50;
-export const MAX_SQL_BYTES = 64 * 1024;
-export const MAX_STRING_LENGTH = 1000;
-export const MAX_LIST_ITEMS = 100;
-export const PARAM_TYPES = ['string', 'int', 'decimal', 'date', 'timestamp', 'boolean', 'string[]'];
-
-const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
-const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
-const PARAM_KEYS = ['name', 'type', 'required', 'default', 'min', 'max', 'maxItems'];
-const DATE = /^\d{4}-\d{2}-\d{2}$/;
-const TIMESTAMP = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
-
-/**
- * Reads and checks `<projectDir>/queries`. `files` are the upload entries (`queries/<name>.sql|.json`, size, full
- * path); `queries` the parsed definitions by name. Returns null when the folder doesn't exist.
- * @returns {Promise<{ files: { path: string, size: number, full: string }[], queries: { name: string, sql: string, params: object[] }[], errors: string[] } | null>}
- */
-export async function loadQueries(projectDir) {
-    const dir = join(projectDir, QUERIES_DIR);
-    if (!existsSync(dir)) return null;
-    const errors = [];
-    const files = [];
-    const byName = new Map();
-
-    for (const entry of await readdir(dir, { withFileTypes: true })) {
-        if (entry.name.startsWith('.')) continue;
-        if (!entry.isFile()) {
-            errors.push(`${QUERIES_DIR}/${entry.name}: queries can't be in subfolders; put <name>.sql and <name>.json straight in ${QUERIES_DIR}/.`);
-            continue;
-        }
-        const match = /^(.*)\.(sql|json)$/.exec(entry.name);
-        if (!match) {
-            errors.push(`${QUERIES_DIR}/${entry.name}: only .sql and .json files belong in ${QUERIES_DIR}/.`);
-            continue;
-        }
-        const [, name, ext] = match;
-        const full = join(dir, entry.name);
-        files.push({ path: `${QUERIES_DIR}/${entry.name}`, size: (await stat(full)).size, full });
-        const pair = byName.get(name) ?? {};
-        pair[ext] = await readFile(full, 'utf8');
-        byName.set(name, pair);
-    }
-
-    const queries = [];
-    for (const [name, pair] of [...byName].sort(([a], [b]) => a.localeCompare(b))) {
-        if (!NAME.test(name) || name.length > 64) {
-            errors.push(`${QUERIES_DIR}/${name}: query names must be 1-64 lowercase letters, digits and single dashes (e.g. "top-searches").`);
-            continue;
-        }
-        if (pair.sql === undefined) {
-            errors.push(`${QUERIES_DIR}/${name}.json has no ${name}.sql.`);
-            continue;
-        }
-        if (pair.json === undefined) {
-            errors.push(`${QUERIES_DIR}/${name}.sql has no ${name}.json (declare its parameters there, e.g. { "params": [] }).`);
-            continue;
-        }
-        let definition;
-        try {
-            definition = JSON.parse(pair.json);
-        } catch (error) {
-            errors.push(`${QUERIES_DIR}/${name}.json is not valid JSON: ${error.message}`);
-            continue;
-        }
-        const queryErrors = validateQuery(name, pair.sql, definition);
-        errors.push(...queryErrors);
-        if (!queryErrors.length) queries.push({ name, sql: pair.sql, params: definition.params ?? [] });
-    }
-    if (byName.size > MAX_QUERIES) errors.push(`${QUERIES_DIR}/: at most ${MAX_QUERIES} queries per app (found ${byName.size}).`);
-    if (!byName.size && !errors.length) errors.push(`${QUERIES_DIR}/ is empty: add <name>.sql and <name>.json, or remove the folder.`);
-
-    files.sort((a, b) => a.path.localeCompare(b.path));
-    return { files, queries, errors };
-}
-
-/**
- * Checks one query: its SQL text and its parsed .json definition. Error messages start with the file they're about.
- * @returns {string[]}
- */
-export function validateQuery(name, sql, definition) {
-    const errors = [];
-    const sqlFile = `${QUERIES_DIR}/${name}.sql`;
-    const jsonFile = `${QUERIES_DIR}/${name}.json`;
-
-    const params = checkParams(definition, jsonFile, errors);
-
-    if (Buffer.byteLength(sql, 'utf8') > MAX_SQL_BYTES) {
-        errors.push(`${sqlFile} is larger than ${MAX_SQL_BYTES / 1024} KB.`);
-        return errors;
-    }
-    const code = stripLiterals(sql);
-    if (code === null) {
-        errors.push(`${sqlFile}: unterminated string, quoted identifier or comment.`);
-        return errors;
-    }
-    if (!code.trim()) {
-        errors.push(`${sqlFile} is empty.`);
-        return errors;
-    }
-    if (code.includes(';')) {
-        errors.push(`${sqlFile}: one statement only, without ";".`);
-    }
-    if (!/^(select|with)\b/i.test(code.trimStart())) {
-        errors.push(`${sqlFile}: must be a SELECT (or WITH … SELECT) statement.`);
-    }
-
-    // Macros: {{partitions(from, to)}} or {{partitions(from, to, alias)}}; the params must be declared dates.
-    const macro = /\{\{([\s\S]*?)\}\}/g;
-    for (const [whole, inner] of code.matchAll(macro)) {
-        const call = /^\s*partitions\s*\(([^()]*)\)\s*$/.exec(inner);
-        if (!call) {
-            errors.push(`${sqlFile}: unknown macro ${whole.trim()}; the only one is {{partitions(fromParam, toParam)}}.`);
-            continue;
-        }
-        const args = call[1].split(',').map((a) => a.trim());
-        if (args.length < 2 || args.length > 3 || args.some((a) => !a)) {
-            errors.push(`${sqlFile}: write {{partitions(fromParam, toParam)}} or {{partitions(fromParam, toParam, tableAlias)}}.`);
-            continue;
-        }
-        for (const arg of args.slice(0, 2)) {
-            const param = params?.find((p) => p.name === arg);
-            if (!param) errors.push(`${sqlFile}: {{partitions(…)}} uses "${arg}", which isn't a parameter in ${jsonFile}.`);
-            else if (param.type !== 'date') errors.push(`${sqlFile}: {{partitions(…)}} parameter "${arg}" must be declared "date" (it is "${param.type}").`);
-        }
-        if (args[2] !== undefined && !IDENTIFIER.test(args[2])) errors.push(`${sqlFile}: {{partitions(…)}} table alias "${args[2]}" is not a plain identifier.`);
-    }
-    const withoutMacros = code.replace(macro, ' ');
-    if (/\{\{|\}\}/.test(withoutMacros)) errors.push(`${sqlFile}: unbalanced {{ }} macro.`);
-
-    if (params) {
-        const placeholders = (withoutMacros.match(/\?/g) ?? []).length;
-        if (placeholders !== params.length) {
-            errors.push(
-                `${sqlFile} has ${placeholders} "?" placeholder${placeholders === 1 ? '' : 's'} but ${jsonFile} declares ${params.length} parameter${params.length === 1 ? '' : 's'}; they must match, in order (a string[] parameter is one "?", written as IN ?).`,
-            );
-        }
-    }
-    return errors;
-}
-
-function checkParams(definition, file, errors) {
-    if (!definition || typeof definition !== 'object' || Array.isArray(definition)) {
-        errors.push(`${file} must be an object: { "params": [ { "name": "from", "type": "date" } ] }.`);
-        return null;
-    }
-    const unknown = Object.keys(definition).filter((k) => k !== 'params');
-    if (unknown.length) errors.push(`${file}: unknown field${unknown.length === 1 ? '' : 's'} ${unknown.join(', ')} (only "params").`);
-    const params = definition.params ?? [];
-    if (!Array.isArray(params)) {
-        errors.push(`${file}: "params" must be a list.`);
-        return null;
-    }
-    const seen = new Set();
-    params.forEach((param, i) => {
-        const at = `${file} params[${i}]`;
-        if (!param || typeof param !== 'object' || Array.isArray(param)) {
-            errors.push(`${at} must be an object with "name" and "type".`);
-            return;
-        }
-        const label = typeof param.name === 'string' ? `${file} "${param.name}"` : at;
-        if (typeof param.name !== 'string' || !PARAM_NAME.test(param.name) || param.name.length > 64) {
-            errors.push(`${at}: "name" must be letters, digits and _ (starting with a letter or _).`);
-        } else if (seen.has(param.name)) {
-            errors.push(`${file}: parameter "${param.name}" is declared more than once.`);
-        } else {
-            seen.add(param.name);
-        }
-        const extra = Object.keys(param).filter((k) => !PARAM_KEYS.includes(k));
-        if (extra.length) errors.push(`${label}: unknown field${extra.length === 1 ? '' : 's'} ${extra.join(', ')} (allowed: ${PARAM_KEYS.join(', ')}).`);
-        if (!PARAM_TYPES.includes(param.type)) {
-            errors.push(`${label}: "type" must be one of ${PARAM_TYPES.join(', ')}.`);
-            return;
-        }
-        if (param.required !== undefined && typeof param.required !== 'boolean') errors.push(`${label}: "required" must be true or false.`);
-        const numeric = param.type === 'int' || param.type === 'decimal';
-        for (const key of ['min', 'max']) {
-            if (param[key] === undefined) continue;
-            if (!numeric) errors.push(`${label}: "${key}" only applies to int and decimal parameters.`);
-            else if (typeof param[key] !== 'number' || !Number.isFinite(param[key]) || (param.type === 'int' && !Number.isInteger(param[key]))) {
-                errors.push(`${label}: "${key}" must be ${param.type === 'int' ? 'an integer' : 'a number'}.`);
-            }
-        }
-        if (typeof param.min === 'number' && typeof param.max === 'number' && param.min > param.max) errors.push(`${label}: "min" is greater than "max".`);
-        if (param.maxItems !== undefined) {
-            if (param.type !== 'string[]') errors.push(`${label}: "maxItems" only applies to string[] parameters.`);
-            else if (!Number.isInteger(param.maxItems) || param.maxItems < 1 || param.maxItems > MAX_LIST_ITEMS) errors.push(`${label}: "maxItems" must be 1-${MAX_LIST_ITEMS}.`);
-        }
-        if (param.default !== undefined) {
-            const problem = checkValue(param, param.default);
-            if (problem) errors.push(`${label}: "default" ${problem}.`);
-        }
-    });
-    return params.filter((p) => p && typeof p === 'object' && typeof p.name === 'string');
-}
-
-/**
- * Checks a value against a declared parameter. Returns a reason ("must be …") or null when it's fine.
- */
-export function checkValue(param, value) {
-    if (value === null) return null;
-    switch (param.type) {
-        case 'string':
-            return typeof value === 'string' && value.length <= MAX_STRING_LENGTH ? null : `must be a string of up to ${MAX_STRING_LENGTH} characters`;
-        case 'int':
-        case 'decimal': {
-            if (typeof value !== 'number' || !Number.isFinite(value) || (param.type === 'int' && !Number.isInteger(value))) return `must be ${param.type === 'int' ? 'an integer' : 'a number'}`;
-            if (typeof param.min === 'number' && value < param.min) return `must be at least ${param.min}`;
-            if (typeof param.max === 'number' && value > param.max) return `must be at most ${param.max}`;
-            return null;
-        }
-        case 'date':
-            return typeof value === 'string' && DATE.test(value) && !Number.isNaN(Date.parse(value)) ? null : 'must be a date (YYYY-MM-DD)';
-        case 'timestamp':
-            return typeof value === 'string' && TIMESTAMP.test(value) && !Number.isNaN(Date.parse(value)) ? null : 'must be an ISO 8601 timestamp';
-        case 'boolean':
-            return typeof value === 'boolean' ? null : 'must be true or false';
-        case 'string[]': {
-            const max = param.maxItems ?? MAX_LIST_ITEMS;
-            if (!Array.isArray(value) || value.some((v) => typeof v !== 'string' || v.length > MAX_STRING_LENGTH)) return 'must be a list of strings';
-            return value.length <= max ? null : `must have at most ${max} items`;
-        }
-        default:
-            return 'has an unknown type';
-    }
-}
-
-/** Turns a command-line value (`--param name=value`) into the declared type: numbers, booleans, comma-separated lists. */
-export function parseParamValue(param, text) {
-    switch (param.type) {
-        case 'int':
-        case 'decimal':
-            return text.trim() === '' ? NaN : Number(text);
-        case 'boolean':
-            return text === 'true' ? true : text === 'false' ? false : text;
-        case 'string[]':
-            return text === '' ? [] : text.split(',').map((v) => v.trim());
-        default:
-            return text;
-    }
-}
-
-/**
- * The SQL with string literals, quoted identifiers and comments blanked out (same length), so `?`, `;`, macros and
- * the first keyword can be found without being fooled by text. Null when something is left open.
- */
-export function stripLiterals(sql) {
-    let out = '';
-    let i = 0;
-    while (i < sql.length) {
-        const c = sql[i];
-        const next = sql[i + 1];
-        if (c === '-' && next === '-') {
-            const end = sql.indexOf('\n', i);
-            const stop = end === -1 ? sql.length : end;
-            out += ' '.repeat(stop - i);
-            i = stop;
-        } else if (c === '/' && next === '*') {
-            const end = sql.indexOf('*/', i + 2);
-            if (end === -1) return null;
-            out += ' '.repeat(end + 2 - i);
-            i = end + 2;
-        } else if (c === "'" || c === '"') {
-            // '' and "" escape the quote inside.
-            let j = i + 1;
-            for (;;) {
-                if (j >= sql.length) return null;
-                if (sql[j] === c) {
-                    if (sql[j + 1] === c) j += 2;
-                    else break;
-                } else j++;
-            }
-            out += ' '.repeat(j + 1 - i);
-            i = j + 1;
-        } else {
-            out += c;
-            i++;
-        }
-    }
-    return out;
-}
+import { existsSync } from 'node:fs';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// App queries (`data:read`): queries/<name>.sql + queries/<name>.json, deployed with each version and run by the
+// platform against the current client's data. Same rules as the platform, which validates again on deploy.
+export const QUERIES_DIR = 'queries';
+export const DATA_SCOPE = 'data:read';
+export const MAX_QUERIES = 50;
+export const MAX_SQL_BYTES = 64 * 1024;
+export const MAX_STRING_LENGTH = 1000;
+export const MAX_LIST_ITEMS = 100;
+export const PARAM_TYPES = ['string', 'int', 'decimal', 'date', 'timestamp', 'boolean', 'string[]'];
+
+const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PARAM_KEYS = ['name', 'type', 'required', 'default', 'min', 'max', 'maxItems'];
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+/**
+ * Reads and checks `<projectDir>/queries`. `files` are the upload entries (`queries/<name>.sql|.json`, size, full
+ * path); `queries` the parsed definitions by name. Returns null when the folder doesn't exist.
+ * @returns {Promise<{ files: { path: string, size: number, full: string }[], queries: { name: string, sql: string, params: object[] }[], errors: string[] } | null>}
+ */
+export async function loadQueries(projectDir) {
+    const dir = join(projectDir, QUERIES_DIR);
+    if (!existsSync(dir)) return null;
+    const errors = [];
+    const files = [];
+    const byName = new Map();
+
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.')) continue;
+        if (!entry.isFile()) {
+            errors.push(`${QUERIES_DIR}/${entry.name}: queries can't be in subfolders; put <name>.sql and <name>.json straight in ${QUERIES_DIR}/.`);
+            continue;
+        }
+        const match = /^(.*)\.(sql|json)$/.exec(entry.name);
+        if (!match) {
+            errors.push(`${QUERIES_DIR}/${entry.name}: only .sql and .json files belong in ${QUERIES_DIR}/.`);
+            continue;
+        }
+        const [, name, ext] = match;
+        const full = join(dir, entry.name);
+        files.push({ path: `${QUERIES_DIR}/${entry.name}`, size: (await stat(full)).size, full });
+        const pair = byName.get(name) ?? {};
+        pair[ext] = await readFile(full, 'utf8');
+        byName.set(name, pair);
+    }
+
+    const queries = [];
+    for (const [name, pair] of [...byName].sort(([a], [b]) => a.localeCompare(b))) {
+        if (!NAME.test(name) || name.length > 64) {
+            errors.push(`${QUERIES_DIR}/${name}: query names must be 1-64 lowercase letters, digits and single dashes (e.g. "top-searches").`);
+            continue;
+        }
+        if (pair.sql === undefined) {
+            errors.push(`${QUERIES_DIR}/${name}.json has no ${name}.sql.`);
+            continue;
+        }
+        if (pair.json === undefined) {
+            errors.push(`${QUERIES_DIR}/${name}.sql has no ${name}.json (declare its parameters there, e.g. { "params": [] }).`);
+            continue;
+        }
+        let definition;
+        try {
+            definition = JSON.parse(pair.json);
+        } catch (error) {
+            errors.push(`${QUERIES_DIR}/${name}.json is not valid JSON: ${error.message}`);
+            continue;
+        }
+        const queryErrors = validateQuery(name, pair.sql, definition);
+        errors.push(...queryErrors);
+        if (!queryErrors.length) queries.push({ name, sql: pair.sql, params: definition.params ?? [] });
+    }
+    if (byName.size > MAX_QUERIES) errors.push(`${QUERIES_DIR}/: at most ${MAX_QUERIES} queries per app (found ${byName.size}).`);
+    if (!byName.size && !errors.length) errors.push(`${QUERIES_DIR}/ is empty: add <name>.sql and <name>.json, or remove the folder.`);
+
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return { files, queries, errors };
+}
+
+/**
+ * Checks one query: its SQL text and its parsed .json definition. Error messages start with the file they're about.
+ * @returns {string[]}
+ */
+export function validateQuery(name, sql, definition) {
+    const errors = [];
+    const sqlFile = `${QUERIES_DIR}/${name}.sql`;
+    const jsonFile = `${QUERIES_DIR}/${name}.json`;
+
+    const params = checkParams(definition, jsonFile, errors);
+
+    if (Buffer.byteLength(sql, 'utf8') > MAX_SQL_BYTES) {
+        errors.push(`${sqlFile} is larger than ${MAX_SQL_BYTES / 1024} KB.`);
+        return errors;
+    }
+    const code = stripLiterals(sql);
+    if (code === null) {
+        errors.push(`${sqlFile}: unterminated string, quoted identifier or comment.`);
+        return errors;
+    }
+    if (!code.trim()) {
+        errors.push(`${sqlFile} is empty.`);
+        return errors;
+    }
+    if (code.includes(';')) {
+        errors.push(`${sqlFile}: one statement only, without ";".`);
+    }
+    if (!/^(select|with)\b/i.test(code.trimStart())) {
+        errors.push(`${sqlFile}: must be a SELECT (or WITH … SELECT) statement.`);
+    }
+
+    // Macros: {{partitions(from, to)}} or {{partitions(from, to, alias)}}; the params must be declared dates.
+    const macro = /\{\{([\s\S]*?)\}\}/g;
+    for (const [whole, inner] of code.matchAll(macro)) {
+        const call = /^\s*partitions\s*\(([^()]*)\)\s*$/.exec(inner);
+        if (!call) {
+            errors.push(`${sqlFile}: unknown macro ${whole.trim()}; the only one is {{partitions(fromParam, toParam)}}.`);
+            continue;
+        }
+        const args = call[1].split(',').map((a) => a.trim());
+        if (args.length < 2 || args.length > 3 || args.some((a) => !a)) {
+            errors.push(`${sqlFile}: write {{partitions(fromParam, toParam)}} or {{partitions(fromParam, toParam, tableAlias)}}.`);
+            continue;
+        }
+        for (const arg of args.slice(0, 2)) {
+            const param = params?.find((p) => p.name === arg);
+            if (!param) errors.push(`${sqlFile}: {{partitions(…)}} uses "${arg}", which isn't a parameter in ${jsonFile}.`);
+            else if (param.type !== 'date') errors.push(`${sqlFile}: {{partitions(…)}} parameter "${arg}" must be declared "date" (it is "${param.type}").`);
+        }
+        if (args[2] !== undefined && !IDENTIFIER.test(args[2])) errors.push(`${sqlFile}: {{partitions(…)}} table alias "${args[2]}" is not a plain identifier.`);
+    }
+    const withoutMacros = code.replace(macro, ' ');
+    if (/\{\{|\}\}/.test(withoutMacros)) errors.push(`${sqlFile}: unbalanced {{ }} macro.`);
+
+    if (params) {
+        const placeholders = (withoutMacros.match(/\?/g) ?? []).length;
+        if (placeholders !== params.length) {
+            errors.push(
+                `${sqlFile} has ${placeholders} "?" placeholder${placeholders === 1 ? '' : 's'} but ${jsonFile} declares ${params.length} parameter${params.length === 1 ? '' : 's'}; they must match, in order (a string[] parameter is one "?", written as IN ?).`,
+            );
+        }
+    }
+    return errors;
+}
+
+function checkParams(definition, file, errors) {
+    if (!definition || typeof definition !== 'object' || Array.isArray(definition)) {
+        errors.push(`${file} must be an object: { "params": [ { "name": "from", "type": "date" } ] }.`);
+        return null;
+    }
+    const unknown = Object.keys(definition).filter((k) => k !== 'params');
+    if (unknown.length) errors.push(`${file}: unknown field${unknown.length === 1 ? '' : 's'} ${unknown.join(', ')} (only "params").`);
+    const params = definition.params ?? [];
+    if (!Array.isArray(params)) {
+        errors.push(`${file}: "params" must be a list.`);
+        return null;
+    }
+    const seen = new Set();
+    params.forEach((param, i) => {
+        const at = `${file} params[${i}]`;
+        if (!param || typeof param !== 'object' || Array.isArray(param)) {
+            errors.push(`${at} must be an object with "name" and "type".`);
+            return;
+        }
+        const label = typeof param.name === 'string' ? `${file} "${param.name}"` : at;
+        if (typeof param.name !== 'string' || !PARAM_NAME.test(param.name) || param.name.length > 64) {
+            errors.push(`${at}: "name" must be letters, digits and _ (starting with a letter or _).`);
+        } else if (seen.has(param.name)) {
+            errors.push(`${file}: parameter "${param.name}" is declared more than once.`);
+        } else {
+            seen.add(param.name);
+        }
+        const extra = Object.keys(param).filter((k) => !PARAM_KEYS.includes(k));
+        if (extra.length) errors.push(`${label}: unknown field${extra.length === 1 ? '' : 's'} ${extra.join(', ')} (allowed: ${PARAM_KEYS.join(', ')}).`);
+        if (!PARAM_TYPES.includes(param.type)) {
+            errors.push(`${label}: "type" must be one of ${PARAM_TYPES.join(', ')}.`);
+            return;
+        }
+        if (param.required !== undefined && typeof param.required !== 'boolean') errors.push(`${label}: "required" must be true or false.`);
+        const numeric = param.type === 'int' || param.type === 'decimal';
+        for (const key of ['min', 'max']) {
+            if (param[key] === undefined) continue;
+            if (!numeric) errors.push(`${label}: "${key}" only applies to int and decimal parameters.`);
+            else if (typeof param[key] !== 'number' || !Number.isFinite(param[key]) || (param.type === 'int' && !Number.isInteger(param[key]))) {
+                errors.push(`${label}: "${key}" must be ${param.type === 'int' ? 'an integer' : 'a number'}.`);
+            }
+        }
+        if (typeof param.min === 'number' && typeof param.max === 'number' && param.min > param.max) errors.push(`${label}: "min" is greater than "max".`);
+        if (param.maxItems !== undefined) {
+            if (param.type !== 'string[]') errors.push(`${label}: "maxItems" only applies to string[] parameters.`);
+            else if (!Number.isInteger(param.maxItems) || param.maxItems < 1 || param.maxItems > MAX_LIST_ITEMS) errors.push(`${label}: "maxItems" must be 1-${MAX_LIST_ITEMS}.`);
+        }
+        if (param.default !== undefined) {
+            const problem = checkValue(param, param.default);
+            if (problem) errors.push(`${label}: "default" ${problem}.`);
+        }
+    });
+    return params.filter((p) => p && typeof p === 'object' && typeof p.name === 'string');
+}
+
+/**
+ * Checks a value against a declared parameter. Returns a reason ("must be …") or null when it's fine.
+ */
+export function checkValue(param, value) {
+    if (value === null) return null;
+    switch (param.type) {
+        case 'string':
+            return typeof value === 'string' && value.length <= MAX_STRING_LENGTH ? null : `must be a string of up to ${MAX_STRING_LENGTH} characters`;
+        case 'int':
+        case 'decimal': {
+            if (typeof value !== 'number' || !Number.isFinite(value) || (param.type === 'int' && !Number.isInteger(value))) return `must be ${param.type === 'int' ? 'an integer' : 'a number'}`;
+            if (typeof param.min === 'number' && value < param.min) return `must be at least ${param.min}`;
+            if (typeof param.max === 'number' && value > param.max) return `must be at most ${param.max}`;
+            return null;
+        }
+        case 'date':
+            return typeof value === 'string' && DATE.test(value) && !Number.isNaN(Date.parse(value)) ? null : 'must be a date (YYYY-MM-DD)';
+        case 'timestamp':
+            return typeof value === 'string' && TIMESTAMP.test(value) && !Number.isNaN(Date.parse(value)) ? null : 'must be an ISO 8601 timestamp';
+        case 'boolean':
+            return typeof value === 'boolean' ? null : 'must be true or false';
+        case 'string[]': {
+            const max = param.maxItems ?? MAX_LIST_ITEMS;
+            if (!Array.isArray(value) || value.some((v) => typeof v !== 'string' || v.length > MAX_STRING_LENGTH)) return 'must be a list of strings';
+            return value.length <= max ? null : `must have at most ${max} items`;
+        }
+        default:
+            return 'has an unknown type';
+    }
+}
+
+/** Turns a command-line value (`--param name=value`) into the declared type: numbers, booleans, comma-separated lists. */
+export function parseParamValue(param, text) {
+    switch (param.type) {
+        case 'int':
+        case 'decimal':
+            return text.trim() === '' ? NaN : Number(text);
+        case 'boolean':
+            return text === 'true' ? true : text === 'false' ? false : text;
+        case 'string[]':
+            return text === '' ? [] : text.split(',').map((v) => v.trim());
+        default:
+            return text;
+    }
+}
+
+/**
+ * The SQL with string literals, quoted identifiers and comments blanked out (same length), so `?`, `;`, macros and
+ * the first keyword can be found without being fooled by text. Null when something is left open.
+ */
+export function stripLiterals(sql) {
+    let out = '';
+    let i = 0;
+    while (i < sql.length) {
+        const c = sql[i];
+        const next = sql[i + 1];
+        if (c === '-' && next === '-') {
+            const end = sql.indexOf('\n', i);
+            const stop = end === -1 ? sql.length : end;
+            out += ' '.repeat(stop - i);
+            i = stop;
+        } else if (c === '/' && next === '*') {
+            const end = sql.indexOf('*/', i + 2);
+            if (end === -1) return null;
+            out += ' '.repeat(end + 2 - i);
+            i = end + 2;
+        } else if (c === "'" || c === '"') {
+            // '' and "" escape the quote inside.
+            let j = i + 1;
+            for (;;) {
+                if (j >= sql.length) return null;
+                if (sql[j] === c) {
+                    if (sql[j + 1] === c) j += 2;
+                    else break;
+                } else j++;
+            }
+            out += ' '.repeat(j + 1 - i);
+            i = j + 1;
+        } else {
+            out += c;
+            i++;
+        }
+    }
+    return out;
+}