@google-cloud/kcmd 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,581 @@
+"use strict";
+// Adds translated target-dialect SQL entries to a Semantic Model's expressions
+// by transpiling vendor SQL or ANSI_SQL that double-quotes column names.
+//
+// The loader (./loader) keeps every entry in `dialects` (and records
+// `stringForm`), while still picking a target/canonical `expression` valid
+// against the target (GoogleSQL/ANSI) and, when the source supplied a vendor
+// variant, the first vendor SQL in `importedExpression` (+ `importedDialect`).
+// When a node carries ONLY vendor entries (with no target or `ANSI_SQL` entry)
+// or carries an `ANSI_SQL` entry that quotes column names with double quotes
+// (which BigQuery reads as string literals), this pass translates that source
+// SQL into the target dialect, appends `{dialect: target, expression: sql}` to
+// `dialects`, and sets `stringForm` to `false`.
+//
+// It never overwrites an existing dialect entry or `expression`: a node that
+// already has a target-dialect entry, or an `ANSI_SQL` entry without
+// double-quoted column names, is untouched, so a model authored in
+// GoogleSQL/unquoted ANSI is unaffected and its goldens are stable.
+//
+// Design:
+//   - Target-agnostic and non-mutating: `transpileModel(model, {target,
+//     transpiler})` returns a `structuredClone`, so the portable IR is
+//     preserved. The mechanism is injectable so tests run hermetically; the
+//     default adapter is the @polyglot-sql/sdk Rust/WASM engine, bundled into
+//     the tool -- there is no external runtime dependency to install.
+//   - Graceful degradation: if the engine fails to initialize, errors, writes a
+//     date form BigQuery rejects that the adapter cannot repair (see "BigQuery
+//     repairs" below), or would alter which entities an expression references
+//     (the qualifier-preservation guard), the node is left as it is and a
+//     warning is emitted -- never a throw.
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.polyglotTranspiler = void 0;
+exports.hasDoubleQuotedColumn = hasDoubleQuotedColumn;
+exports.doubleQuotedNames = doubleQuotedNames;
+exports.transpileModel = transpileModel;
+exports.translatesToBigQuery = translatesToBigQuery;
+const sql_expr_utils_1 = require("./sql_expr_utils");
+const sql_identifiers_1 = require("./sql_identifiers");
+const sql_parser_1 = require("./sql_parser");
+// The target dialect this pass rewrites into. The whole point of the pass is to
+// reach GoogleSQL/BigQuery, so it is fixed rather than a knob; the polyglot
+// adapter still accepts any target token for reuse/testing.
+const DEFAULT_TARGET = 'BIGQUERY';
+/**
+ * Returns true if `expression`, read as generic SQL (`ANSI_SQL`), quotes a
+ * column, table qualifier, or struct field with double quotes (`"..."`).
+ *
+ * The `ANSI_SQL` parser marks both `"..."` and `` `...` `` column identifiers
+ * with `quoted: true`, whereas `BIGQUERY` marks only `` `...` `` as `quoted:
+ * true` and treats `"..."` as a string literal (or fails to parse `."..."`).
+ * Comparing how many `quotedNames` the two ASTs hold yields three cases:
+ *   - `ANSI_SQL > BIGQUERY`: at least one column identifier is double-quoted
+ *     (e.g., `"orders"."amount"` or `"amount"`).
+ *   - `ANSI_SQL < BIGQUERY`: `expression` uses BigQuery-only syntax (such as a
+ *     `# "comment"` line comment in `` `orders`.`col` # "comment" ``) that
+ *     `BIGQUERY` parses while `ANSI_SQL` fails to parse (`count = 0`).
+ *   - `ANSI_SQL === BIGQUERY`: any `"` is inside a string literal or comment
+ *     (e.g., `` `orders`.`note` = 'a "quoted" ` string' ``), and any quoted
+ *     column identifiers use backticks in both dialects.
+ */
+function hasDoubleQuotedColumn(expression) {
+    if (!expression.includes('"'))
+        return false;
+    return quotedNames((0, sql_parser_1.sqlExpressionTree)(expression, 'ANSI_SQL')).length >
+        quotedNames((0, sql_parser_1.sqlExpressionTree)(expression, 'BIGQUERY')).length;
+}
+/**
+ * Returns the names that `expression` double-quotes, each once, for a
+ * message: those the `ANSI_SQL` parser marks quoted that `expression` writes
+ * in double quotes, else the first name it marks quoted.
+ */
+function doubleQuotedNames(expression) {
+    const names = quotedNames((0, sql_parser_1.sqlExpressionTree)(expression, 'ANSI_SQL'));
+    const written = names.filter(n => expression.includes(`"${n.replaceAll('"', '""')}"`));
+    return [...new Set(written.length ? written : names.slice(0, 1))];
+}
+/**
+ * Returns the names of the quoted column, table qualifier, and struct field
+ * identifiers (`quoted: true`) in a `@polyglot-sql/sdk` AST `node`, in tree
+ * order, with a table qualifier before its column name.
+ *
+ * `@polyglot-sql/sdk` represents simple or table-qualified column references as
+ * `{column: {name: {name, quoted}, table?: {name, quoted}}}` and chained
+ * struct field accesses (such as `orders.addr."city"`) as
+ * `{dot: {this: <base>, field: {name, quoted}}}`. When `sqlExpressionTree`
+ * cannot parse an expression in the requested dialect, it returns `undefined`,
+ * for which this function returns `[]`.
+ */
+function quotedNames(node) {
+    // Base case: `undefined` (when `sqlExpressionTree` fails to parse), `null`,
+    // or primitive AST leaf values (`string`, `number`, `boolean`) have no quoted
+    // column identifiers.
+    if (!node || typeof node !== 'object')
+        return [];
+    const obj = node;
+    const quoted = (id) => id?.quoted === true ? [id.name] : [];
+    // A `{column: {name, table}}` node represents a bare (`"col"`) or
+    // table-qualified (`"orders"."col"`) column reference; take the optional
+    // table qualifier and the column name separately whenever `quoted === true`.
+    if (obj.column) {
+        return [...quoted(obj.column.table), ...quoted(obj.column.name)];
+    }
+    // A `{dot: {this, field}}` node represents a struct subfield access (e.g.
+    // `orders.addr."city"`); recurse into `this` for the base column or outer
+    // struct path, and take `field` if `quoted === true`.
+    if (obj.dot) {
+        return [...quotedNames(obj.dot.this), ...quoted(obj.dot.field)];
+    }
+    // For any other AST container node (such as `sum`, `eq`, `case`) or array of
+    // child AST nodes, recursively collect the names across all child values.
+    return Object.values(obj).flatMap(quotedNames);
+}
+/**
+ * Returns the source `{dialect, expression}` to translate into `target` for
+ * `node`, or `undefined` when `node` should be left untouched.
+ *
+ * A field or metric is queued for translation in either of two cases:
+ *   1. Its only texts are in vendor dialects, with no `target` or `ANSI_SQL`
+ *      entry -> translate from the vendor dialect.
+ *   2. It has an `ANSI_SQL` text that double-quotes a column identifier and no
+ *      `target` entry -> translate from `ANSI_SQL`.
+ */
+function sourceToTranspile(node, target) {
+    // Parsed models store per-dialect SQL expressions in `node.dialects`.
+    if (node.dialects?.length) {
+        // Skip if `node` already has an explicit entry for the target dialect.
+        if (node.dialects.some(d => d.dialect === target))
+            return undefined;
+        // If `node` has a generic `ANSI_SQL` entry, `expressionForDialect` already
+        // falls back to it for `target` unless it double-quotes a column
+        // identifier (which `BIGQUERY` would read as a string literal). Only
+        // transpile `ANSI_SQL` when it uses double-quoted columns; otherwise skip
+        // transpilation even if vendor dialect entries are also present.
+        const ansi = node.dialects.find(d => d.dialect === 'ANSI_SQL');
+        if (ansi) {
+            return hasDoubleQuotedColumn(ansi.expression) ?
+                { dialect: 'ANSI_SQL', expression: ansi.expression } :
+                undefined;
+        }
+        // Otherwise `node.dialects` contains only non-target vendor entries (e.g.
+        // `SNOWFLAKE`), so transpile from the first vendor entry.
+        const first = node.dialects[0];
+        return { dialect: first.dialect, expression: first.expression };
+    }
+    // Hand-built in-memory IR may omit `node.dialects` and set a bare
+    // `node.expression` (implicitly `ANSI_SQL`); only transpile it when it
+    // double-quotes a column identifier.
+    if (node.expression !== undefined) {
+        return hasDoubleQuotedColumn(node.expression) ?
+            { dialect: 'ANSI_SQL', expression: node.expression } :
+            undefined;
+    }
+    // Hand-built in-memory IR may omit `node.dialects` and carry only a
+    // vendor-specific `importedExpression`; transpile it from `importedDialect`
+    // (falling back to `ANSI_SQL` if `importedDialect` was omitted).
+    if (node.importedExpression) {
+        return {
+            dialect: node.importedDialect || 'ANSI_SQL',
+            expression: node.importedExpression,
+        };
+    }
+    // The node has no SQL expression of any kind, so leave it untouched.
+    return undefined;
+}
+/**
+ * Adds a translated `opts.target` dialect entry to every field, metric and
+ * profile field binding in `model` whose only texts are in vendor dialects or
+ * whose `ANSI_SQL` text double-quotes a column name, returning a cloned model
+ * plus diagnostics.
+ *
+ * The input model is never mutated. When no node needs transpilation, the clone
+ * is returned unchanged and the transpiler is not invoked. The
+ * qualifier-preservation guard parses the transpiled output with
+ * `columnReferences`, which requires the SQL parser to be loaded even when a
+ * custom `opts.transpiler` is injected (`loadSqlEngine()` is awaited before
+ * running the guard).
+ */
+async function transpileModel(model, opts = {}) {
+    const target = opts.target ?? DEFAULT_TARGET;
+    const transpiler = opts.transpiler ?? exports.polyglotTranspiler;
+    const clone = structuredClone(model);
+    const entityNames = clone.entities.map(e => e.name);
+    const warnings = [];
+    await (0, sql_parser_1.loadSqlEngine)();
+    const pending = [];
+    const add = (node, ctx) => {
+        const source = sourceToTranspile(node, target);
+        if (!source)
+            return;
+        const id = String(pending.length);
+        pending.push({
+            request: { id, dialect: source.dialect, expression: source.expression },
+            ctx,
+            accept: (sql) => {
+                node.dialects = [
+                    ...(node.dialects ?? []),
+                    { dialect: target, expression: sql },
+                ];
+                node.stringForm = false;
+            },
+        });
+    };
+    for (const e of clone.entities) {
+        for (const f of e.fields)
+            add(f, `field '${e.name}.${f.name}'`);
+    }
+    for (const r of clone.relationships) {
+        // Direct FK edges carry no expressions; only an association (junction
+        // table) has edge-property fields, and only when hand-built IR supplies
+        // them.
+        for (const f of r.association?.fields ?? []) {
+            add(f, `relationship '${r.name}' field '${f.name}'`);
+        }
+    }
+    for (const m of clone.metrics)
+        add(m, `metric '${m.name}'`);
+    for (const p of clone.profiles ?? []) {
+        if (opts.translatesProfile && !opts.translatesProfile(p, clone))
+            continue;
+        for (const pe of p.entities) {
+            for (const f of pe.fields ?? []) {
+                add(f, `profile '${p.name}': field '${pe.name}.${f.name}'`);
+            }
+        }
+    }
+    if (!pending.length)
+        return { model: clone, warnings };
+    const responses = await transpiler(pending.map(p => p.request), target);
+    const byId = new Map(responses.map(r => [r.id, r]));
+    for (const p of pending) {
+        const { ctx, request } = p;
+        const res = byId.get(request.id);
+        if (!res || res.sql === undefined) {
+            const reason = res?.error ?? 'no result returned';
+            warnings.push(`${ctx}: could not transpile '${request.dialect}' -> '${target}' (${reason}); left untranslated`);
+            continue;
+        }
+        // Qualifier-preservation guard: the BigQuery emitter locates measures and
+        // strips qualifiers by matching `<Entity>.` case-sensitively (see
+        // ./sql_expr_utils). A transpiler that re-cases a qualifier (`orders.` ->
+        // `Orders.`) leaves SQL the emitter can no longer match, so the measure
+        // would silently drop or misplace. Detect that on the OUTPUT with
+        // `columnReferences`: every entity the transpiled SQL references
+        // case-insensitively must also be matched case-sensitively -- i.e. kept in
+        // the exact case the emitter needs. Comparing the output against itself
+        // (rather than the vendor input) avoids false positives from dialect-
+        // specific identifier quoting.
+        const reached = qualifiersReached(res.sql, target, entityNames);
+        if (!reached) {
+            warnings.push(`${ctx}: transpiled '${request.dialect}' -> '${target}' could not ` +
+                `be parsed; qualifier check was skipped`);
+        }
+        else if (!sameSet(reached.exact, reached.anyCase)) {
+            warnings.push(`${ctx}: transpiled '${request.dialect}' -> '${target}' but it ` +
+                `re-cased an entity qualifier the emitter matches case-sensitively ` +
+                `(${fmtSet(reached.exact)} vs ${fmtSet(reached.anyCase)}); left ` +
+                `untranslated`);
+            continue;
+        }
+        p.accept(res.sql);
+        warnings.push(`${ctx}: transpiled '${request.dialect}' -> '${target}'`);
+        if (request.dialect === 'SQLSERVER') {
+            warnings.push(`${ctx}: SQL Server text is translated to BigQuery on a ` +
+                `best-effort basis, and the translator can get some T-SQL wrong; ` +
+                `check the ${target} entry.`);
+        }
+    }
+    return { model: clone, warnings };
+}
+// The entities among `entityNames` that `sql`, in `target`, qualifies a
+// column with in their exact case and in any case, or undefined when the
+// parser cannot read `sql`.
+function qualifiersReached(sql, target, entityNames) {
+    const cols = (0, sql_expr_utils_1.columnReferences)(sql, target);
+    if (cols === undefined)
+        return undefined;
+    const anyCase = new Set(cols.flatMap(c => {
+        const lower = c.qualifier?.toLowerCase();
+        return entityNames.filter(n => n.toLowerCase() === lower);
+    }));
+    return { exact: (0, sql_expr_utils_1.entitiesReached)(cols, entityNames), anyCase: [...anyCase] };
+}
+/**
+ * Whether `transpileModel`, with the default translator, gives `node` a
+ * BIGQUERY text in a model whose entities are `entityNames`. False until
+ * `loadSqlEngine()` has loaded the engine.
+ */
+function translatesToBigQuery(node, entityNames) {
+    const source = sourceToTranspile(node, DEFAULT_TARGET);
+    const engine = (0, sql_parser_1.loadedSqlEngine)();
+    if (!source || !engine)
+        return false;
+    const { sql } = transpileWith(engine, { id: '', ...source }, polyglotDialect(DEFAULT_TARGET));
+    if (sql === undefined)
+        return false;
+    const reached = qualifiersReached(sql, DEFAULT_TARGET, entityNames);
+    return !reached || sameSet(reached.exact, reached.anyCase);
+}
+function sameSet(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const s = new Set(a);
+    return b.every(x => s.has(x));
+}
+function fmtSet(names) {
+    return names.length ? `{${names.join(', ')}}` : '{}';
+}
+// --- polyglot-sql adapter (the default mechanism) ----------------------------
+// Maps our dialect tokens (as authored in the AI-first format) to the
+// @polyglot-sql/sdk dialect names (lower-case). ANSI_SQL maps to the engine's
+// dialect-neutral 'generic' parser. An unknown token has no mapping and
+// degrades to a per-request error (the imported form + warning).
+const POLYGLOT_DIALECTS = {
+    ANSI_SQL: 'generic', // the engine's dialect-neutral parser
+    BIGQUERY: 'bigquery',
+    SPANNER: 'bigquery',
+    POSTGRES: 'postgresql',
+    ALLOYDB: 'postgresql',
+    MYSQL: 'mysql',
+    SQLSERVER: 'tsql',
+    SNOWFLAKE: 'snowflake',
+    DATABRICKS: 'databricks',
+};
+function polyglotDialect(token) {
+    if (!token)
+        return undefined;
+    return POLYGLOT_DIALECTS[token.toUpperCase()];
+}
+/**
+ * The default {@link SqlTranspiler}: transpiles via the embedded
+ * @polyglot-sql/sdk Rust/WASM engine. There is no external runtime dependency
+ * -- the WASM blob is bundled into the tool. It never throws: an engine that
+ * fails to initialize yields an `error` response for every request, and a
+ * per-request parse failure or unsupported dialect yields an `error` for just
+ * that request, so the caller degrades to the imported form + warning.
+ */
+const polyglotTranspiler = async (requests, target) => {
+    if (!requests.length)
+        return [];
+    // Map the target to the engine's write dialect. A known token that maps to
+    // 'generic' (ANSI_SQL) means dialect-neutral output and must be preserved.
+    // An unknown target is an error for every request (symmetric with an unknown
+    // source dialect below) rather than a silent fallback to BigQuery, which would
+    // emit the wrong dialect while the caller's warning claimed the requested one.
+    const write = polyglotDialect(target);
+    if (write === undefined)
+        return requests.map(r => ({ id: r.id, error: `unsupported target dialect '${target}'` }));
+    let engine;
+    try {
+        engine = await (0, sql_parser_1.loadSqlEngine)();
+    }
+    catch (err) {
+        const reason = `SQL transpiler engine unavailable: ${errMessage(err)}`;
+        return requests.map(r => ({ id: r.id, error: reason }));
+    }
+    return requests.map(r => transpileWith(engine, r, write));
+};
+exports.polyglotTranspiler = polyglotTranspiler;
+// The engine's answer to `r`, with `write` as the engine's target dialect.
+function transpileWith(engine, r, write) {
+    const read = polyglotDialect(r.dialect);
+    if (read === undefined)
+        return { id: r.id, error: `unsupported source dialect '${r.dialect}'` };
+    try {
+        const res = engine.transpile(r.expression, read, write);
+        if (!res.success || !res.sql || res.sql.length === 0)
+            return { id: r.id, error: res.error ?? 'transpilation produced no output' };
+        // A field/metric is a single scalar expression, so the engine should
+        // return exactly one statement. More than one means the input was not a
+        // lone expression; taking [0] would silently drop the rest, so reject it.
+        if (res.sql.length > 1)
+            return {
+                id: r.id,
+                error: `expected a single expression but got ${res.sql.length} statements`
+            };
+        if (write !== 'bigquery')
+            return { id: r.id, sql: res.sql[0] };
+        const repaired = repairForBigQuery(engine, res.sql[0], read);
+        return 'error' in repaired ? { id: r.id, error: repaired.error } :
+            { id: r.id, sql: repaired.sql };
+    }
+    catch (err) {
+        return { id: r.id, error: errMessage(err) };
+    }
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// --- BigQuery repairs ---------------------------------------------------------
+//
+// The engine (@polyglot-sql/sdk 0.9.1, and still 0.13.4) reads DATE_TRUNC,
+// DATE_PART and TO_CHAR as functions it does not know and writes them to
+// BigQuery as they were. It also keeps a PostgreSQL interval string such as
+// `INTERVAL '1 day'`, and T-SQL's YEAR, MONTH and DAY. BigQuery rejects each of
+// these, and the engine reports success. So the adapter reads the engine's
+// BigQuery output back, rewrites the forms it can translate, and refuses the
+// rest, so that no entry claims a translation BigQuery cannot run.
+// BigQuery's DATE_TRUNC part for each part name PostgreSQL, Snowflake,
+// Databricks and T-SQL take. PostgreSQL, Snowflake and Databricks start a week
+// on Monday, as ISOWEEK does. T-SQL's DATETRUNC reaches this map too, and its
+// `week` starts on the DATEFIRST day, so it is refused. Left out: `m`, which is
+// month in T-SQL and minute in Snowflake.
+const TRUNC_PARTS = {
+    microsecond: 'MICROSECOND',
+    microseconds: 'MICROSECOND',
+    millisecond: 'MILLISECOND',
+    milliseconds: 'MILLISECOND',
+    second: 'SECOND',
+    minute: 'MINUTE',
+    hour: 'HOUR',
+    day: 'DAY',
+    dd: 'DAY',
+    week: 'ISOWEEK',
+    iso_week: 'ISOWEEK',
+    month: 'MONTH',
+    mm: 'MONTH',
+    quarter: 'QUARTER',
+    year: 'YEAR',
+    yyyy: 'YEAR',
+    yy: 'YEAR',
+};
+// The engine's EXTRACT field for each DATE_PART part whose number BigQuery's
+// EXTRACT gives too. Left out: `second`, which PostgreSQL gives with its
+// fraction; `dow`, which PostgreSQL counts from 0; and `week`, which T-SQL's
+// DATEPART does not count as ISO weeks. Day of year is a custom field because
+// the engine writes its own `DayOfYear` field as `DOY`, which BigQuery rejects.
+const EXTRACT_FIELDS = {
+    year: 'Year',
+    quarter: 'Quarter',
+    month: 'Month',
+    day: 'Day',
+    hour: 'Hour',
+    minute: 'Minute',
+    doy: { Custom: 'DAYOFYEAR' },
+    dayofyear: { Custom: 'DAYOFYEAR' },
+    isoyear: { Custom: 'ISOYEAR' },
+};
+// The engine's interval unit for each unit a PostgreSQL interval string names.
+// Left out: `month` and `year`. BigQuery cannot add them to a TIMESTAMP, and
+// fails each query that does, though a dry run passes. kcmd cannot see whether
+// the value is a TIMESTAMP, so it refuses them.
+const INTERVAL_UNITS = {
+    second: 'Second',
+    minute: 'Minute',
+    hour: 'Hour',
+    day: 'Day',
+    week: 'Week',
+};
+// `sql`, the engine's BigQuery output from SQL in the engine's dialect `read`,
+// with the forms above rewritten, or an error naming a form kcmd cannot
+// translate. A text the engine cannot read back is returned as it is;
+// transpileModel's qualifier check reports it.
+function repairForBigQuery(engine, sql, read) {
+    const tree = (0, sql_parser_1.sqlExpressionTree)(sql, 'BIGQUERY');
+    if (!tree)
+        return { sql };
+    let changed = false;
+    let refused;
+    const walk = (node) => {
+        if (!node || typeof node !== 'object')
+            return node;
+        if (Array.isArray(node))
+            return node.map(walk);
+        const out = {};
+        for (const [k, v] of Object.entries(node))
+            out[k] = walk(v);
+        // The engine reads BigQuery's TIMESTAMP as a timestamp without time zone,
+        // which it writes as DATETIME.
+        if (out.data_type === 'timestamp')
+            out.timezone = true;
+        const repaired = repairNode(out, read);
+        if (typeof repaired === 'string') {
+            refused ??= repaired;
+            return out;
+        }
+        if (repaired === undefined)
+            return out;
+        changed = true;
+        return repaired;
+    };
+    const result = walk(tree);
+    if (refused)
+        return { error: `kcmd cannot translate ${refused} to BigQuery` };
+    if (!changed)
+        return { sql };
+    const written = engine.generate([result], 'bigquery');
+    if (!written.success || written.sql?.length !== 1) {
+        return { error: written.error ?? 'the repaired SQL could not be written' };
+    }
+    return { sql: written.sql[0] };
+}
+// The node to put in place of `node`, a string naming a form kcmd cannot
+// translate, or undefined to keep `node`. `read` is the engine's dialect for
+// the source SQL.
+function repairNode(node, read) {
+    const fn = node.function;
+    if (fn) {
+        const name = String(fn.name).toUpperCase();
+        const args = fn.args ?? [];
+        if (name === 'TO_CHAR')
+            return 'TO_CHAR';
+        // BigQuery's own DATE_TRUNC(d, MONTH) names its part last, unquoted.
+        if (name === 'DATE_TRUNC' && args.length === 2 &&
+            args[0].literal?.literal_type === 'string') {
+            const part = args[0].literal.value;
+            const bqPart = TRUNC_PARTS[part.toLowerCase()];
+            if (!bqPart || (read === 'tsql' && part.toLowerCase() === 'week')) {
+                return `DATE_TRUNC with part '${part}'`;
+            }
+            // The engine reads a lone name in the part position as a `var` node
+            // without its quotes, so put it back as a column, quoted if it must be.
+            const col = args[1].var?.this;
+            const date = col === undefined ? args[1] : {
+                column: { name: { name: col, quoted: !(0, sql_identifiers_1.isSimpleIdentifier)(col) }, table: null },
+            };
+            return { function: { ...fn, args: [date, { var: { this: bqPart } }] } };
+        }
+        if (name === 'DATE_PART') {
+            const part = args.length === 2 ? partName(args[0]) : undefined;
+            const field = part && EXTRACT_FIELDS[part.toLowerCase()];
+            if (!field)
+                return `DATE_PART with part '${part ?? '?'}'`;
+            if (isDifference(args[1]))
+                return 'DATE_PART of a difference';
+            return { extract: { this: args[1], field } };
+        }
+        return undefined;
+    }
+    if (node.extract && read !== 'bigquery') {
+        // A Spanner text already uses BigQuery's arithmetic.
+        if (isDifference(node.extract.this))
+            return 'EXTRACT of a difference';
+        // PostgreSQL and Databricks number weeks as ISO weeks.
+        if (node.extract.field === 'Week' &&
+            (read === 'postgresql' || read === 'databricks')) {
+            return { extract: { ...node.extract, field: { Custom: 'ISOWEEK' } } };
+        }
+    }
+    // The engine's nodes for YEAR(d), MONTH(d) and DAY(d).
+    for (const kind of ['year', 'month', 'day']) {
+        if (node[kind]?.this) {
+            return { extract: { this: node[kind].this, field: EXTRACT_FIELDS[kind] } };
+        }
+    }
+    // PostgreSQL's '1 day'::interval reaches here as a CAST to INTERVAL.
+    const interval = node.cast?.to?.data_type === 'interval' ?
+        { this: node.cast.this, unit: null } :
+        node.interval;
+    if (interval && interval.unit === null &&
+        interval.this?.literal?.literal_type === 'string') {
+        const text = interval.this.literal.value;
+        const [, amount, unit] = /^\s*([+-]?\d+)\s*([a-z]+?)s?\s*$/i.exec(text) ?? [];
+        const bqUnit = unit && INTERVAL_UNITS[unit.toLowerCase()];
+        if (!bqUnit)
+            return `INTERVAL '${text}'`;
+        return {
+            interval: {
+                this: { literal: { literal_type: 'number', value: amount } },
+                unit: { type: 'simple', unit: bqUnit, use_plural: false },
+            },
+        };
+    }
+    return undefined;
+}
+// Whether `arg` subtracts one value from another, other than an interval.
+// BigQuery holds a TIMESTAMP difference in hours, so a day of it is 0 where
+// PostgreSQL counts the days.
+function isDifference(arg) {
+    const value = arg.paren?.this ?? arg;
+    return !!value.sub && !value.sub.right?.interval;
+}
+// The part a DATE_PART names: a string, or a bare name as Snowflake and
+// T-SQL's DATEPART write it, which the engine reads as a column.
+function partName(arg) {
+    if (arg.literal?.literal_type === 'string')
+        return arg.literal.value;
+    if (arg.column && !arg.column.table)
+        return arg.column.name?.name;
+    return undefined;
+}

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

@@ -0,0 +1,70 @@
+import { BigQueryClient } from '../gcp/bigquery';
+import { SpannerClient } from '../gcp/spanner';
+import { ResolvedDeployment } from './deployment_target';
+import { SemanticModel } from './ir';
+import { LoadedModel } from './loader';
+import { AvailabilityReport, DeclaredProfiles, DialectLoad, LocalCheckError, ProfileFiles } from './resolve_profiles';
+export declare function validatePushRequirements(models: LoadedModel[], opts?: {
+    fieldsPruned?: boolean;
+    warnings?: string[];
+    v2Aspects?: boolean;
+}): string[];
+export declare function validateDeployments(model: SemanticModel, document: string, load?: DialectLoad): string[];
+export declare function validateInlineDialects(model: SemanticModel, document: string): string[];
+export declare function validateInheritedColumns(model: SemanticModel, document: string): string[];
+export declare function inlineBindingWarnings(model: SemanticModel, document: string, namedProfiles: boolean): string[];
+export declare function validateActions(model: SemanticModel, document: string, fieldsPruned: boolean, checkDescriptions: boolean): string[];
+/**
+ * Returns one message per broken inheritance or concrete-leaf rule, or an
+ * empty list: a cycle, an unknown parent, a field inherited from two
+ * unrelated ancestors, or two fields of one entity whose names differ only in
+ * case; a redeclared inherited field; an
+ * abstract entity with a table; and a relationship or metric on an entity that
+ * is not a concrete leaf. Pruning can remove the field a rule is about, so a
+ * push that prunes runs this on the model before pruning as well as after.
+ */
+export declare function validateInheritance(models: LoadedModel[]): string[];
+export declare function validateExpressionReferences(models: LoadedModel[], fieldsPruned?: boolean, warnings?: string[], flaggedMetrics?: Set<string>): string[];
+export declare function deploymentTableErrors(document: string, model: SemanticModel, deployment: ResolvedDeployment): string[];
+export declare function spannerMetricsErrors(document: string, model: SemanticModel, deployment: ResolvedDeployment): string[];
+export declare function kcV2Aspects(): boolean;
+export interface LocalCheckScope {
+    docs: Array<{
+        name: string;
+        text: string;
+    }>;
+    loaded: {
+        models: LoadedModel[];
+        warnings: string[];
+    };
+    models: LoadedModel[];
+    profileDocs: ProfileFiles;
+    declaredBy: DeclaredProfiles;
+    load: DialectLoad;
+}
+export interface DeploymentPlan {
+    deployment: ResolvedDeployment;
+    at: string;
+    model: LoadedModel;
+    report: AvailabilityReport;
+    generated?: {
+        ddl: string[];
+        warnings: string[];
+    };
+}
+export declare function withProfileFiles(base: LoadedModel, profileDocs: ProfileFiles): LoadedModel | {
+    errors: LocalCheckError[];
+};
+export declare function localChecks(scope: LocalCheckScope, warn: (w: string) => void, selected?: string[]): Promise<{
+    plans: DeploymentPlan[];
+} | {
+    errors: LocalCheckError[];
+}>;
+export declare function pruningLines({ deployment, model, report: r }: DeploymentPlan): string[];
+export declare function validateBigQueryDataSources(models: LoadedModel[], bq: BigQueryClient, defaultProject: string, graph?: {
+    at: string;
+    dataset: string;
+    location: string;
+}): Promise<string[]>;
+export declare function validateSpannerActionStatements(models: LoadedModel[], spanner: SpannerClient): Promise<string[]>;
+export declare function validateBigQueryActionStatements(models: LoadedModel[], bq: BigQueryClient, defaultProject: string): Promise<string[]>;