@google-cloud/kcmd 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,221 @@
+"use strict";
+// Helpers for reading and rewriting entity-qualified SQL expressions across the
+// semantic-model layer.
+//
+// Expressions reference columns as `<Entity>.<column>`. 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 still use the literal-
+// aware regex helpers (`referencedEntityNames`, `stripQualifier`).
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_AGGREGATES = exports.STRING_LITERAL = void 0;
+exports.escapeRegExp = escapeRegExp;
+exports.blankStringLiterals = blankStringLiterals;
+exports.mapOutsideStringLiterals = mapOutsideStringLiterals;
+exports.referencedEntityNames = referencedEntityNames;
+exports.stripQualifier = stripQualifier;
+exports.sqlWithoutComments = sqlWithoutComments;
+exports.fieldBindingWithoutComments = fieldBindingWithoutComments;
+exports.columnReferences = columnReferences;
+exports.columnsForSource = columnsForSource;
+exports.entitiesReached = entitiesReached;
+exports.fieldsReadOn = fieldsReadOn;
+exports.isSingleAggregate = isSingleAggregate;
+exports.isColumnName = isColumnName;
+const ir_1 = require("./ir");
+const sql_parser_1 = require("./sql_parser");
+// Matches a single- or double-quoted SQL string literal, honoring backslash
+// escapes. (Triple-quoted / raw literals are uncommon in these expressions and
+// are treated as ordinary text.)
+exports.STRING_LITERAL = /'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"/g;
+// Escapes a string so it can be embedded literally in a RegExp.
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// Replaces string-literal contents with blanks of equal length, so scanning sees
+// literal-free text without shifting any offsets.
+function blankStringLiterals(expression) {
+    return expression.replace(exports.STRING_LITERAL, m => ' '.repeat(m.length));
+}
+// Applies `fn` only to the parts of `expression` that lie outside string
+// literals, leaving each literal verbatim.
+function mapOutsideStringLiterals(expression, fn) {
+    let out = '';
+    let last = 0;
+    for (const m of expression.matchAll(exports.STRING_LITERAL)) {
+        out += fn(expression.slice(last, m.index));
+        out += m[0];
+        last = m.index + m[0].length;
+    }
+    out += fn(expression.slice(last));
+    return out;
+}
+// Builds a regex matching an `<entity>.` qualifier, including the BigQuery
+// backtick-quoted form (`` `entity`. ``). A negative lookbehind keeps the name
+// from matching inside a larger identifier (e.g. `customer_orders.`) or after a
+// dot in a struct path (e.g. `orders.customer.id`), and the optional backticks
+// let it match whether or not the identifier is quoted.
+function entityQualifier(name, flags = '') {
+    return new RegExp(`(?<![\\w\`.])\`?${escapeRegExp(name)}\`?\\.`, flags);
+}
+// Returns the entity names whose `<name>.` qualifier appears in an expression,
+// in the order they first appear, ignoring text inside string literals.
+// Matching is case-sensitive (the emitter's behavior).
+function referencedEntityNames(expression, entityNames) {
+    const scannable = blankStringLiterals(expression);
+    const hits = [];
+    for (const name of entityNames) {
+        const m = entityQualifier(name).exec(scannable);
+        if (m)
+            hits.push({ name, at: m.index });
+    }
+    return hits.sort((a, b) => a.at - b.at).map(h => h.name);
+}
+// Removes the `<entity>.` qualifier (bare or backtick-quoted) so an expression
+// references table-local columns, without touching text inside string literals.
+function stripQualifier(expression, entity) {
+    const re = entityQualifier(entity, 'g');
+    return mapOutsideStringLiterals(expression, seg => seg.replace(re, ''));
+}
+// `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, !dialect || dialect === 'ANSI_SQL' ? 'BIGQUERY' : 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.
+function columnsForSource(text, dialect, impliedDialect) {
+    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'];
+// Whether `expression`, read in `dialect`, is one of SUPPORTED_AGGREGATES over
+// one operand, or COUNT(*), with at most DISTINCT or ALL. The operand holds no
+// other aggregate, window or subquery.
+function isSingleAggregate(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 false;
+    }
+    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 false;
+    }
+    // The parser keeps the call's name in `name` or `original_name`.
+    const known = new Set(['this', 'star', 'distinct', 'name', 'original_name']);
+    return Object.entries(call).every(([key, v]) => known.has(key) || v === null || v === undefined ||
+        v === false || (Array.isArray(v) && v.length === 0));
+}
+// 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 '';
+}

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

@@ -0,0 +1,44 @@
+export interface PolyglotEngine {
+    init(opts: {
+        wasmUrl: string;
+    }): Promise<void>;
+    transpile(sql: string, read: string, write: string): {
+        success: boolean;
+        sql?: string[];
+        error?: string;
+    };
+    parse(sql: string, dialect: string): {
+        success: boolean;
+        ast?: unknown[];
+        error?: string;
+    };
+    generate(ast: unknown[], dialect: string): {
+        success: boolean;
+        sql?: string[];
+        error?: string;
+    };
+    tokenize(sql: string, dialect: string): {
+        success: boolean;
+        tokens?: SqlToken[];
+        error?: string;
+    };
+}
+interface SqlToken {
+    text: string;
+    span: {
+        start: number;
+        end: number;
+    };
+    comments: string[];
+    trailing_comments: string[];
+}
+export declare function loadSqlEngine(): Promise<PolyglotEngine>;
+export interface SqlColumn {
+    qualifier?: string;
+    name: string;
+}
+export declare function sqlColumns(expression: string, dialect: string): SqlColumn[] | undefined;
+export declare function sqlExpressionTree(expression: string, dialect: string): any;
+export declare function holdsNoSql(expression: string, dialect: string): boolean;
+export declare function withoutComments(expression: string, dialect: string): string;
+export {};