@google-cloud/kcmd 0.0.0-stage → 0.2.0

package/build/ts/kcmd/semantic/sql_expr_utils.js

@@ -0,0 +1,394 @@
+"use strict";
+// Helpers for reading and rewriting entity-qualified SQL expressions across the
+// semantic-model layer.
+//
+// An expression names a field of its entity as `<Entity>.<field>`, and a
+// column of its table without a qualifier. The SQL parser
+// (`columnReferences`, `entitiesReached`, `fieldsReadOn`) reads column and
+// entity references across dialects for the loader, validator, profile checks,
+// pull reader, and transpiler. The graph generators read them with the parser
+// too: `measureEntities` places a measure, `singleAggregate` finds its
+// aggregate, `withoutQualifier` makes an expression table-local,
+// `qualifiedColumns` finds the sibling fields it names and
+// `withSiblingsSpliced` puts their SQL in their place, and `requalified` moves
+// an inherited expression onto the entity inheriting it.
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_AGGREGATES = void 0;
+exports.unusedName = unusedName;
+exports.withoutQualifier = withoutQualifier;
+exports.withSiblingsSpliced = withSiblingsSpliced;
+exports.qualifiedColumns = qualifiedColumns;
+exports.selfReferenceMessage = selfReferenceMessage;
+exports.requalified = requalified;
+exports.measureEntities = measureEntities;
+exports.sqlWithoutComments = sqlWithoutComments;
+exports.fieldBindingWithoutComments = fieldBindingWithoutComments;
+exports.columnReferences = columnReferences;
+exports.columnsForSource = columnsForSource;
+exports.entitiesReached = entitiesReached;
+exports.fieldsReadOn = fieldsReadOn;
+exports.singleAggregate = singleAggregate;
+exports.isSingleAggregate = isSingleAggregate;
+exports.isColumnName = isColumnName;
+const ir_1 = require("./ir");
+const sql_identifiers_1 = require("./sql_identifiers");
+const sql_parser_1 = require("./sql_parser");
+// The dialect a graph generator reads `dialect` in: an ANSI_SQL text, or a
+// text with no dialect, is read as BigQuery.
+function graphReading(dialect) {
+    return !dialect || dialect === 'ANSI_SQL' ? 'BIGQUERY' : dialect;
+}
+// Each `<name>.` qualifier that `expression`, read in `dialect`, writes before
+// a column, for a name in `names`, as indexes into the text's tokens, in the
+// order written. A name matches case-sensitively, bare or quoted as the
+// dialect quotes an identifier, and not after a dot, so the second `orders` in
+// the struct path `orders.orders.id` is not one. The SQL parser decides which
+// candidates are qualifiers, so a string literal, a comment or a function
+// namespace such as `NET.` in `NET.HOST(orders.url)` holds none. The parser
+// reads each candidate as a placeholder name, so one it reserves as a keyword,
+// such as `Date` in `Date.days`, still reads as a qualifier. When the parser
+// cannot read the text even so, every candidate is taken as a qualifier.
+// Undefined when the engine cannot tokenize the text.
+function qualifiersIn(expression, names, dialect) {
+    const tokens = (0, sql_parser_1.sqlTokens)(expression, dialect);
+    if (!tokens)
+        return undefined;
+    const chars = Array.from(expression);
+    const asWritten = (t) => chars.slice(t.span.start, t.span.end).join('');
+    const candidates = [];
+    tokens.forEach((t, i) => {
+        if (names.has(t.text) && tokens[i + 1]?.token_type === 'DOT' &&
+            tokens[i - 1]?.token_type !== 'DOT' &&
+            (t.token_type === 'QUOTED_IDENTIFIER' || asWritten(t) === t.text)) {
+            candidates.push(i);
+        }
+    });
+    if (!candidates.length)
+        return { tokens, at: [] };
+    // A placeholder stem the text does not hold.
+    const stem = unusedName(expression, 'kcmd_qualifier_');
+    let text = '';
+    let end = 0;
+    candidates.forEach((i, k) => {
+        text += chars.slice(end, tokens[i].span.start).join('') + stem + k;
+        end = tokens[i].span.end;
+    });
+    text += chars.slice(end).join('');
+    const columns = columnReferences(text, dialect);
+    const at = !columns ? candidates : candidates.filter((_, k) => columns.some(c => c.qualifier?.toLowerCase() === stem + k));
+    return { tokens, at };
+}
+// `base`, a lowercase name, with underscores added until `text` does not hold
+// it in any case.
+function unusedName(text, base) {
+    let name = base;
+    while (text.toLowerCase().includes(name))
+        name += '_';
+    return name;
+}
+// `expression` without each `<qualifier>.` it writes before a column (see
+// qualifiersIn), so it reads the columns of the qualifier's own table. The
+// rest of the text stays as written. The text is read in `dialect`; an
+// ANSI_SQL text, or one with no dialect, is read as BigQuery, as the graph
+// generators read it. Returns `expression` itself when it writes no such
+// qualifier or the engine cannot tokenize it.
+function withoutQualifier(expression, qualifier, dialect) {
+    return spliced(expression, qualifier, graphReading(dialect), new Map());
+}
+// `expression`, BigQuery SQL on `qualifier`'s table, as withoutQualifier gives
+// it, except that each `<qualifier>.<field>` whose field `siblings` holds is
+// replaced, whole, by the SQL it maps to, as given. The graph generators put
+// the SQL of each sibling field an expression names in its place so (see
+// graph_ddl.fieldSql).
+function withSiblingsSpliced(expression, qualifier, siblings) {
+    return spliced(expression, qualifier, 'BIGQUERY', siblings);
+}
+// `expression`, read in `dialect`, without each `<qualifier>.` it writes
+// before a column (see qualifiersIn), and with each `<qualifier>.<column>`
+// whose column `replacements` holds replaced, whole, by the SQL it maps to.
+function spliced(expression, qualifier, dialect, replacements) {
+    const read = qualifiersIn(expression, new Set([qualifier]), dialect);
+    if (!read?.at.length)
+        return expression;
+    const { tokens, at } = read;
+    const chars = Array.from(expression);
+    let out = '';
+    let end = 0;
+    for (const i of at) {
+        out += chars.slice(end, tokens[i].span.start).join('');
+        const column = tokens[i + 2];
+        const replacement = column && replacements.get(nameOf(column, chars));
+        if (replacement !== undefined) {
+            out += replacement;
+            end = column.span.end;
+        }
+        else {
+            // The qualifier, its dot, and what lies between the dot and the column.
+            end = column?.span.start ?? tokens[i + 1].span.end;
+        }
+    }
+    return out + chars.slice(end).join('');
+}
+// The column written after each `<qualifier>.` that `expression` writes before
+// a column (see qualifiersIn), without its quotes, in the order written, so
+// ``orders.a + `orders`.`b`.c`` gives `a` and `b`. The text is read in
+// `dialect`, as withoutQualifier reads it, so a qualifier the parser reserves,
+// such as `Date` in `Date.days`, gives its column too. Undefined when the
+// engine cannot tokenize the text.
+function qualifiedColumns(expression, qualifier, dialect) {
+    const read = qualifiersIn(expression, new Set([qualifier]), graphReading(dialect));
+    if (!read)
+        return undefined;
+    const chars = Array.from(expression);
+    return read.at.filter(i => read.tokens[i + 2])
+        .map(i => nameOf(read.tokens[i + 2], chars));
+}
+// The name token `t` of the text whose characters are `chars` gives, as
+// written, without its quotes.
+function nameOf(t, chars) {
+    return t.token_type === 'QUOTED_IDENTIFIER' ?
+        t.text :
+        chars.slice(t.span.start, t.span.end).join('');
+}
+// The error for a field of `owner` that names itself. `cycle` starts at that
+// field and runs through the fields it names back to it, and `where` follows
+// the field's name, as ` in model 'm' (doc)` does. The graph renders a field
+// that names a sibling field from that sibling's own SQL (see
+// graph_ddl.fieldSql), so a field that reaches itself has none.
+function selfReferenceMessage(owner, cycle, where = '') {
+    const [field, ...through] = cycle;
+    return `field '${owner}.${field}'${where} names itself` +
+        (through.length ?
+            ` through ${through.map(n => `'${owner}.${n}'`).join(', ')}` :
+            '') +
+        `; a field expression may name other fields of its entity, but not ` +
+        `itself, directly or through other fields` +
+        (through.length ? '' :
+            `; to read the column of that name, write it ` +
+                `without the qualifier: '${(0, sql_identifiers_1.quoteIfReserved)(field)}'`);
+}
+// `expression` with each `<from>.` qualifier it writes before a column (see
+// qualifiersIn) renamed `<to>.`, quoted as it was written. The rest of the
+// text stays as written. The text is read in `dialect`, as withoutQualifier
+// reads it. Returns `expression` itself when it writes no such qualifier or
+// the engine cannot tokenize it.
+function requalified(expression, from, to, dialect) {
+    const read = qualifiersIn(expression, new Set([from]), graphReading(dialect));
+    if (!read?.at.length)
+        return expression;
+    const { tokens, at } = read;
+    const chars = Array.from(expression);
+    let out = '';
+    let end = 0;
+    for (const i of at) {
+        const { start, end: after } = tokens[i].span;
+        out += chars.slice(end, start).join('') +
+            chars.slice(start, after).join('').replace(from, () => to);
+        end = after;
+    }
+    return out + chars.slice(end).join('');
+}
+// The entities from `entityNames` whose qualifier a metric's BigQuery SQL
+// `expression` writes before a column (see qualifiersIn), deduplicated in the
+// order written, or else `entity`, the metric's anchor, when given. The
+// BigQuery generator places the metric's measure on the entity this gives
+// when it gives one, and a BigQuery push rejects a metric it gives several or
+// none for (see validate.ts).
+function measureEntities(expression, entityNames, entity) {
+    const read = qualifiersIn(expression, new Set(entityNames), 'BIGQUERY');
+    const reached = [...new Set(read?.at.map(i => read.tokens[i].text) ?? [])];
+    return reached.length || !entity ? reached : [entity];
+}
+// `text`, written in `dialect`, with its comments removed. An ANSI_SQL text, or
+// a text with no dialect, is read as BigQuery, as the loader and the graph
+// generators read it.
+function sqlWithoutComments(text, dialect) {
+    return (0, sql_parser_1.withoutComments)(text, graphReading(dialect));
+}
+// `field`'s binding, as fieldBinding gives it, with its comments removed.
+// Undefined when the field is unbound. The target text is read in
+// `targetDialect`, BigQuery unless given. The parser reads Spanner SQL as
+// BigQuery. Imported vendor SQL, the binding only when there is no target
+// text, is read in its imported dialect, so it keeps what that dialect does
+// not read as a comment.
+function fieldBindingWithoutComments(field, targetDialect) {
+    const text = (0, ir_1.fieldBinding)(field);
+    if (text === undefined)
+        return undefined;
+    return sqlWithoutComments(text, field.expression === undefined ? field.importedDialect : targetDialect);
+}
+// Results of columnReferences by dialect and text, so the checks one push
+// runs read each text once. When full, the oldest entry goes.
+const MAX_COLUMN_CACHE_SIZE = 65536;
+const COLUMN_CACHE = new Map();
+// Every column an expression reads, with the qualifier written before it, in
+// the order written, or undefined when the SQL parser cannot read the
+// expression in `dialect`, one of the dialect names a dialect list uses. The
+// parser handles string literals, comments and each dialect's quoting, so
+// `"orders"."amount"` in a PostgreSQL text reads the column `amount` of
+// `orders`, while in BigQuery the same text is not SQL and gives undefined. A struct path reads
+// as its first two parts: `orders.shipping_address.city` reads
+// `shipping_address` of `orders`.
+function columnReferences(expression, dialect) {
+    const key = `${dialect.toUpperCase()}\0${expression}`;
+    if (COLUMN_CACHE.has(key))
+        return COLUMN_CACHE.get(key);
+    const cols = (0, sql_parser_1.sqlColumns)(expression, dialect);
+    if (COLUMN_CACHE.size >= MAX_COLUMN_CACHE_SIZE) {
+        COLUMN_CACHE.delete(COLUMN_CACHE.keys().next().value);
+    }
+    COLUMN_CACHE.set(key, cols);
+    return cols;
+}
+// Reads the columns of `text` in `dialect`. An `ANSI_SQL` text is read in the
+// dialect the model's sources imply (`impliedDialect`), since the database runs
+// an `ANSI_SQL` entry as its own SQL. When the sources do not imply a single
+// dialect, the generic parser reads the text, and any bare identifier that
+// BigQuery's parser does not also read as a bare column (such as a `MONTH`
+// date part or a double-quoted string literal) is filtered out. When their
+// dialect is null, which no lookup read, an `ANSI_SQL` text is not read.
+function columnsForSource(text, dialect, impliedDialect) {
+    if (dialect === 'ANSI_SQL' && impliedDialect === null)
+        return undefined;
+    if (dialect === 'ANSI_SQL' && impliedDialect) {
+        return columnReferences(text, impliedDialect);
+    }
+    const cols = columnReferences(text, dialect);
+    if (!cols || dialect !== 'ANSI_SQL')
+        return cols;
+    const bqCols = columnReferences(text, 'BIGQUERY');
+    if (!bqCols)
+        return cols;
+    const bqBare = new Set(bqCols.filter(c => c.qualifier === undefined).map(c => c.name));
+    return cols.filter(c => c.qualifier !== undefined || bqBare.has(c.name));
+}
+// The entities from `entityNames` that `columns` read, deduplicated in
+// first-seen order. Matching is case-sensitive.
+function entitiesReached(columns, entityNames) {
+    const known = entityNames instanceof Set ? entityNames : new Set(entityNames);
+    const reached = [];
+    for (const c of columns) {
+        if (c.qualifier && known.has(c.qualifier) &&
+            !reached.includes(c.qualifier)) {
+            reached.push(c.qualifier);
+        }
+    }
+    return reached;
+}
+// The fields `columns` read on `entityName`, written `entityName.field`,
+// deduplicated in first-seen order. Matching is case-sensitive.
+function fieldsReadOn(columns, entityName) {
+    const fields = [];
+    for (const c of columns) {
+        if (c.qualifier === entityName && !fields.includes(c.name)) {
+            fields.push(c.name);
+        }
+    }
+    return fields;
+}
+// The aggregates BigQuery accepts in a MEASURE, its complete list. BigQuery
+// rejects any other there, such as COUNTIF or APPROX_COUNT_DISTINCT.
+exports.SUPPORTED_AGGREGATES = ['SUM', 'AVG', 'COUNT', 'MIN', 'MAX'];
+// When `expression`, read in `dialect`, is one of SUPPORTED_AGGREGATES over
+// one operand, or COUNT(*), with at most DISTINCT or ALL, and the operand holds
+// no other aggregate, window or subquery: the function's name as written, the
+// operand as written without the parentheses around it (so
+// `COUNT(DISTINCT(x))` gives `x`), and whether the call is DISTINCT. COUNT(*)
+// gives the operand `*`. Undefined otherwise.
+function singleAggregate(expression, dialect) {
+    const node = unwrapped((0, sql_parser_1.sqlExpressionTree)(expression, dialect));
+    const kind = node && Object.keys(node).length === 1 ? Object.keys(node)[0] :
+        undefined;
+    if (!kind || !exports.SUPPORTED_AGGREGATES.includes(kind.toUpperCase())) {
+        return undefined;
+    }
+    const call = node[kind];
+    const star = kind === 'count' && call.star === true && !call.this;
+    const operand = unwrapped(call.this);
+    if (!star &&
+        (!operand || operand.star || operand.tuple ||
+            nestsAggregateOrSubquery(operand))) {
+        return undefined;
+    }
+    // The parser keeps the call's name in `name` or `original_name`.
+    const known = new Set(['this', 'star', 'distinct', 'name', 'original_name']);
+    if (!Object.entries(call).every(([key, v]) => known.has(key) || v === null || v === undefined ||
+        v === false || (Array.isArray(v) && v.length === 0))) {
+        return undefined;
+    }
+    // The call as written: its name, `(`, DISTINCT or ALL if written, the
+    // operand and `)`, inside any parentheses around the whole call.
+    const tokens = unparenthesized((0, sql_parser_1.sqlTokens)(expression, dialect) ?? []);
+    if (tokens.length < 4 || tokens[1].token_type !== 'L_PAREN' ||
+        tokens[tokens.length - 1].token_type !== 'R_PAREN') {
+        return undefined;
+    }
+    let inner = tokens.slice(2, -1);
+    if (inner[0]?.token_type === 'DISTINCT' || inner[0]?.token_type === 'ALL') {
+        inner = inner.slice(1);
+    }
+    inner = unparenthesized(inner);
+    if (!inner.length)
+        return undefined;
+    const chars = Array.from(expression);
+    return {
+        fn: tokens[0].text,
+        operand: chars.slice(inner[0].span.start, inner[inner.length - 1].span.end)
+            .join(''),
+        distinct: call.distinct === true,
+    };
+}
+// Whether `expression`, read in `dialect`, is a single aggregate (see
+// singleAggregate), the form a BigQuery measure takes.
+function isSingleAggregate(expression, dialect) {
+    return singleAggregate(expression, dialect) !== undefined;
+}
+// `tokens` without the parentheses around all of them.
+function unparenthesized(tokens) {
+    while (tokens.length >= 2 && tokens[0].token_type === 'L_PAREN') {
+        let depth = 0;
+        let closesAt = -1;
+        for (let i = 0; i < tokens.length && closesAt < 0; i++) {
+            if (tokens[i].token_type === 'L_PAREN')
+                depth++;
+            if (tokens[i].token_type === 'R_PAREN' && --depth === 0)
+                closesAt = i;
+        }
+        if (closesAt !== tokens.length - 1)
+            break;
+        tokens = tokens.slice(1, -1);
+    }
+    return tokens;
+}
+// The parser's tree `node` without the parentheses and comments around it.
+function unwrapped(node) {
+    while (node?.paren || node?.annotated) {
+        node = (node.paren ?? node.annotated).this;
+    }
+    return node;
+}
+// Whether the parser's tree `node` holds an aggregate, a window or a subquery
+// at any depth. The parser gives an aggregate call `distinct` and `filter`
+// keys, or the kind `aggregate_function`.
+function nestsAggregateOrSubquery(node) {
+    if (Array.isArray(node))
+        return node.some(nestsAggregateOrSubquery);
+    if (node === null || typeof node !== 'object')
+        return false;
+    return Object.entries(node).some(([kind, value]) => kind === 'aggregate_function' ||
+        kind === 'window_function' || kind === 'subquery' ||
+        kind === 'select' ||
+        (value !== null && typeof value === 'object' && 'distinct' in value &&
+            'filter' in value) ||
+        nestsAggregateOrSubquery(value));
+}
+// Whether a key or join column is a physical column name rather than an
+// expression. A value that starts and ends with a backtick, with none between,
+// passes whatever it holds. An unquoted value may not contain whitespace,
+// parentheses, a dot, a comma, a backtick or a SQL operator. Nothing else about
+// the character set is checked; the database rejects a bad name.
+function isColumnName(value) {
+    return typeof value === 'string' &&
+        (/^`[^`]+`$/.test(value) || /^[^\s().+\-*/%=<>!|&^~,`]+$/.test(value));
+}

package/build/ts/kcmd/semantic/sql_identifiers.d.ts

@@ -0,0 +1,6 @@
+export declare function isSimpleIdentifier(s: string): boolean;
+export declare function isReservedKeyword(name: string): boolean;
+export declare function quoteIdentifier(name: string): string;
+export declare function quoteIfReserved(name: string): string;
+export declare function referencedParameters(text: string): string[];
+export declare function leadingDmlVerb(sql: string): string;

package/build/ts/kcmd/semantic/sql_identifiers.js

@@ -0,0 +1,267 @@
+"use strict";
+// Quoting for GoogleSQL identifiers emitted into generated graph DDL.
+//
+// The graph generator (./graph_ddl) lowers logical names -- entity and
+// relationship labels, property names, key columns -- into identifier
+// positions of a `CREATE OR REPLACE PROPERTY GRAPH` statement. A name that is a
+// GoogleSQL RESERVED KEYWORD (e.g. an entity named `Order`) is a valid model
+// name but, emitted bare as `... AS Order`, makes the DDL a syntax error
+// ("Unexpected keyword ORDER"). Backticking it (`... AS `Order``) is always
+// safe, so these helpers quote a name exactly when it would otherwise be
+// misread. Both BigQuery and Spanner Graph share the GoogleSQL grammar, so one
+// reserved set serves both.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSimpleIdentifier = isSimpleIdentifier;
+exports.isReservedKeyword = isReservedKeyword;
+exports.quoteIdentifier = quoteIdentifier;
+exports.quoteIfReserved = quoteIfReserved;
+exports.referencedParameters = referencedParameters;
+exports.leadingDmlVerb = leadingDmlVerb;
+// The GoogleSQL reserved keywords. A reserved keyword may not appear as an
+// identifier unless quoted. Non-reserved keywords are deliberately absent: they
+// are legal bare identifiers, so quoting them would churn existing output for no
+// reason. That absence extends to the graph-DDL CONTEXTUAL keywords (KEY, VALUE,
+// SOURCE, DESTINATION, LABEL, NODE, EDGE, PROPERTIES, MEASURE): they are
+// keywords only inside a CREATE PROPERTY GRAPH clause, and BigQuery accepts them
+// bare in every identifier position -- alias, property, KEY/SOURCE
+// KEY/DESTINATION KEY column, and REFERENCES label (verified live 2026-08-30).
+// Kept uppercase; lookups uppercase first.
+//
+// Source of truth: the GoogleSQL reserved-keyword lists published for BigQuery
+// and Spanner (their lexical-structure docs). This set is their UNION so one
+// table serves both engines: the two lists differ only in QUALIFY (BigQuery
+// reserves it; Spanner does not, and over-quoting it on Spanner is harmless),
+// and both reserve GRAPH_TABLE. NOTE: the @polyglot-sql/sdk transpiler is
+// deliberately NOT the oracle -- its reserved set diverges from BigQuery's in
+// both directions (misses EXTRACT, over-quotes user/view/column), so delegating
+// would emit incorrect DDL. See sql_identifiers.test.ts.
+const RESERVED_KEYWORDS = new Set([
+    'ALL',
+    'AND',
+    'ANY',
+    'ARRAY',
+    'AS',
+    'ASC',
+    'ASSERT_ROWS_MODIFIED',
+    'AT',
+    'BETWEEN',
+    'BY',
+    'CASE',
+    'CAST',
+    'COLLATE',
+    'CONTAINS',
+    'CREATE',
+    'CROSS',
+    'CUBE',
+    'CURRENT',
+    'DEFAULT',
+    'DEFINE',
+    'DESC',
+    'DISTINCT',
+    'ELSE',
+    'END',
+    'ENUM',
+    'ESCAPE',
+    'EXCEPT',
+    'EXCLUDE',
+    'EXISTS',
+    'EXTRACT',
+    'FALSE',
+    'FETCH',
+    'FOLLOWING',
+    'FOR',
+    'FROM',
+    'FULL',
+    'GRAPH_TABLE',
+    'GROUP',
+    'GROUPING',
+    'GROUPS',
+    'HASH',
+    'HAVING',
+    'IF',
+    'IGNORE',
+    'IN',
+    'INNER',
+    'INTERSECT',
+    'INTERVAL',
+    'INTO',
+    'IS',
+    'JOIN',
+    'LATERAL',
+    'LEFT',
+    'LIKE',
+    'LIMIT',
+    'LOOKUP',
+    'MERGE',
+    'NATURAL',
+    'NEW',
+    'NO',
+    'NOT',
+    'NULL',
+    'NULLS',
+    'OF',
+    'ON',
+    'OR',
+    'ORDER',
+    'OUTER',
+    'OVER',
+    'PARTITION',
+    'PRECEDING',
+    'PROTO',
+    'QUALIFY',
+    'RANGE',
+    'RECURSIVE',
+    'RESPECT',
+    'RIGHT',
+    'ROLLUP',
+    'ROWS',
+    'SELECT',
+    'SET',
+    'SOME',
+    'STRUCT',
+    'TABLESAMPLE',
+    'THEN',
+    'TO',
+    'TREAT',
+    'TRUE',
+    'UNBOUNDED',
+    'UNION',
+    'UNNEST',
+    'USING',
+    'WHEN',
+    'WHERE',
+    'WINDOW',
+    'WITH',
+    'WITHIN',
+]);
+// A bare (unquoted) GoogleSQL identifier: a letter or underscore followed by
+// letters, digits, or underscores. Anything else (a hyphen, a dot, a leading
+// digit) must be quoted to appear as an identifier.
+function isSimpleIdentifier(s) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(s);
+}
+// Whether `name` is a GoogleSQL reserved keyword (case-insensitive), and so
+// cannot appear as a bare identifier.
+function isReservedKeyword(name) {
+    return RESERVED_KEYWORDS.has(name.toUpperCase());
+}
+// Backticks `name`, escaping any embedded backtick.
+function backtick(name) {
+    return `\`${name.replace(/`/g, '\\`')}\``;
+}
+// Quotes a name that would otherwise be MISREAD as a bare identifier: a simple
+// identifier is left bare unless it is a reserved keyword; anything non-simple
+// (a hyphen, a dot, a leading digit) is backticked. Use for a full identifier
+// token -- a table or graph name.
+function quoteIdentifier(name) {
+    if (isSimpleIdentifier(name)) {
+        return isReservedKeyword(name) ? backtick(name) : name;
+    }
+    return backtick(name);
+}
+// Quotes ONLY a simple identifier that collides with a reserved keyword, and
+// passes everything else through unchanged. Use at identifier positions whose
+// input is expected to be a simple name already (an alias, a label reference, a
+// key column): a non-simple value there is a separate error the generators
+// detect and warn about, so this must not rewrite it. A non-reserved name is
+// returned byte-for-byte, so existing output is unaffected.
+function quoteIfReserved(name) {
+    return isSimpleIdentifier(name) && isReservedKeyword(name) ? backtick(name) :
+        name;
+}
+// The distinct `@name` references in a SQL statement, ignoring the ones inside
+// a single-quoted string so a literal containing an '@' is not read as a
+// binding. Used to check that every parameter a statement reads is one the
+// caller will bind, and to bind only the parameters a statement actually reads.
+function referencedParameters(text) {
+    const withoutStrings = text.replace(/'(?:[^'\\]|\\.)*'/g, "''");
+    const names = new Set();
+    for (const m of withoutStrings.matchAll(/@([A-Za-z_]\w*)/g))
+        names.add(m[1]);
+    return [...names];
+}
+// The DML verb a statement leads with, or '' when none can be read.
+//
+// Reading the first six characters is not enough: a statement opening with a
+// `--` comment, or with a `WITH` clause ahead of its UPDATE, reports a verb
+// that is not the statement's. So this walks the text instead, skipping what
+// cannot hold the verb -- comments, quoted strings, and anything nested in
+// parentheses -- and returns the first DML keyword left standing at the top
+// level. For `WITH x AS (SELECT ...) UPDATE ...` that is the UPDATE, because
+// the CTE body is inside parentheses; for `UPDATE t SET note = 'DELETE'` it is
+// the UPDATE, because the literal is not read as a keyword.
+//
+// BOTH line-comment forms are skipped. GoogleSQL takes `#` as well as `--`, and
+// action DML runs against Spanner, so `# credit the account` ahead of an INSERT
+// would otherwise hand back whatever verb the prose happened to use.
+//
+// It lives here, rather than beside the one caller that refuses a zero-row
+// write, because validation reads the same statements to decide what a model
+// may PUBLISH. Two readers meant the library accepted an authored `sql`
+// executor -- a leading comment, a CTE -- that `kcmd push` and `kcmd action
+// run` then refused before the runtime ever saw it. The verb SET stays wider
+// than what an executor may declare: MERGE is read so a caller can be told a
+// MERGE matched nothing, and rejected at publish time by SQL_EXECUTOR_VERBS,
+// which does not list it.
+//
+// WHAT A MISREAD COSTS runs one way only, and it is worth knowing which. Since
+// noRowMatched refuses everything except a recognized INSERT, failing to read a
+// verb cannot hide a write that did nothing -- it can only refuse one that was
+// fine. The expensive direction is therefore a real INSERT this misses, and the
+// cheap direction is anything else it cannot parse. That is deliberate: a false
+// refusal is a failed run someone looks at, and a missed refusal is a caller
+// told its write landed when it did not.
+//
+// This is a scanner, not a parser, and the repo does bundle a real one
+// (`@polyglot-sql/sdk`, used by transpile.ts and sql_identifiers.ts). It is not
+// used here because it has no Spanner dialect and action DML targets Spanner
+// and AlloyDB, so it would have to parse Spanner statements as something else
+// and would reject valid ones. Given which direction a misread now falls, a
+// scanner that recognizes a leading INSERT is enough; if that stops being true,
+// the parser is the thing to reach for rather than more cases here.
+function leadingDmlVerb(sql) {
+    const verbs = new Set(['INSERT', 'UPDATE', 'DELETE', 'MERGE']);
+    let depth = 0;
+    for (let i = 0; i < sql.length; i++) {
+        const c = sql[i];
+        if ((c === '-' && sql[i + 1] === '-') || c === '#') {
+            const end = sql.indexOf('\n', i);
+            if (end < 0)
+                break;
+            i = end;
+        }
+        else if (c === '/' && sql[i + 1] === '*') {
+            const end = sql.indexOf('*/', i + 2);
+            if (end < 0)
+                break;
+            i = end + 1;
+        }
+        else if (c === '\'' || c === '"' || c === '`') {
+            for (i++; i < sql.length; i++) {
+                if (sql[i] === '\\') {
+                    i++;
+                }
+                else if (sql[i] === c) {
+                    break;
+                }
+            }
+        }
+        else if (c === '(') {
+            depth++;
+        }
+        else if (c === ')') {
+            if (depth > 0)
+                depth--;
+        }
+        else if (depth === 0 && /[A-Za-z_]/.test(c)) {
+            let j = i;
+            while (j < sql.length && /[A-Za-z0-9_]/.test(sql[j]))
+                j++;
+            const word = sql.slice(i, j).toUpperCase();
+            if (verbs.has(word))
+                return word;
+            i = j - 1;
+        }
+    }
+    return '';
+}