@google-cloud/kcmd 0.1.0 → 0.2.1

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

@@ -23,7 +23,8 @@ export interface PolyglotEngine {
         error?: string;
     };
 }
-interface SqlToken {
+export interface SqlToken {
+    token_type: string;
     text: string;
     span: {
         start: number;
@@ -33,12 +34,14 @@ interface SqlToken {
     trailing_comments: string[];
 }
 export declare function loadSqlEngine(): Promise<PolyglotEngine>;
+export declare function loadedSqlEngine(): PolyglotEngine | undefined;
 export interface SqlColumn {
     qualifier?: string;
     name: string;
 }
 export declare function sqlColumns(expression: string, dialect: string): SqlColumn[] | undefined;
+export declare function soleColumn(expression: string, dialect: string): SqlColumn | undefined;
 export declare function sqlExpressionTree(expression: string, dialect: string): any;
+export declare function sqlTokens(expression: string, dialect: string): SqlToken[] | undefined;
 export declare function holdsNoSql(expression: string, dialect: string): boolean;
 export declare function withoutComments(expression: string, dialect: string): string;
-export {};

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

@@ -8,8 +8,11 @@
 // first, and so does a test.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadSqlEngine = loadSqlEngine;
+exports.loadedSqlEngine = loadedSqlEngine;
 exports.sqlColumns = sqlColumns;
+exports.soleColumn = soleColumn;
 exports.sqlExpressionTree = sqlExpressionTree;
+exports.sqlTokens = sqlTokens;
 exports.holdsNoSql = holdsNoSql;
 exports.withoutComments = withoutComments;
 const node_fs_1 = require("node:fs");
@@ -42,6 +45,10 @@ function loadSqlEngine() {
     }
     return enginePromise;
 }
+// The engine loadSqlEngine has loaded, or undefined before it has.
+function loadedSqlEngine() {
+    return loadedEngine;
+}
 // The engine's dialect for each kcmd dialect. The engine has no Spanner
 // dialect, so Spanner's GoogleSQL is read as BigQuery's.
 const PARSER_DIALECTS = {
@@ -73,6 +80,21 @@ function sqlColumns(expression, dialect) {
     collectColumns(tree, columns, new Set(), PARSER_DIALECTS[dialect.toUpperCase()] ?? 'generic');
     return columns;
 }
+// The column `expression` is, read in `dialect`, when it is one column and
+// nothing else, perhaps in parentheses: `orders.amount`, `` (`order`) `` or
+// `amount`, but not a struct path such as `orders.address.city` or any other
+// expression. Undefined otherwise, or when the engine cannot read it. Throws
+// when the engine is not loaded.
+function soleColumn(expression, dialect) {
+    let tree = sqlExpressionTree(expression, dialect);
+    const kind = (node) => node && Object.keys(node).length === 1 ? Object.keys(node)[0] : undefined;
+    while (kind(tree) === 'paren')
+        tree = tree.paren.this;
+    if (kind(tree) !== 'column')
+        return undefined;
+    const columns = sqlColumns(expression, dialect);
+    return columns?.length === 1 ? columns[0] : undefined;
+}
 // The engine's tree of `expression` read as one expression in `dialect`, or
 // undefined when it cannot be read so or is empty. A text that starts with a
 // keyword, such as `Order.amount`, is read again inside parentheses on lines

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

@@ -1,4 +1,4 @@
-import { SemanticModel } from './ir';
+import { Field, ProfileSpec, SemanticModel } from './ir';
 export interface TranspileRequest {
     id: string;
     dialect: string;
@@ -13,11 +13,13 @@ export type SqlTranspiler = (requests: TranspileRequest[], target: string) => Pr
 export interface TranspileOptions {
     target?: string;
     transpiler?: SqlTranspiler;
+    translatesProfile?: (profile: ProfileSpec, model: SemanticModel) => boolean;
 }
 export interface TranspileResult {
     model: SemanticModel;
     warnings: string[];
 }
+type TranspileNode = Pick<Field, 'expression' | 'dialects' | 'stringForm' | 'importedExpression' | 'importedDialect'>;
 /**
  * Returns true if `expression`, read as generic SQL (`ANSI_SQL`), quotes a
  * column, table qualifier, or struct field with double quotes (`"..."`).
@@ -43,9 +45,10 @@ export declare function hasDoubleQuotedColumn(expression: string): boolean;
  */
 export declare function doubleQuotedNames(expression: string): string[];
 /**
- * Adds a translated `opts.target` dialect entry to every field or metric 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.
+ * 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
@@ -56,13 +59,11 @@ export declare function doubleQuotedNames(expression: string): string[];
  */
 export declare function transpileModel(model: SemanticModel, opts?: TranspileOptions): Promise<TranspileResult>;
 /**
- * Returns true if the default translator reads SQL written in `dialect`
- * (treating an empty string as `ANSI_SQL`).
- *
- * `transpileModel` leaves a text in any other dialect as written, with a
- * warning.
+ * 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.
  */
-export declare function transpilesFrom(dialect: string): boolean;
+export declare function translatesToBigQuery(node: TranspileNode, entityNames: string[]): boolean;
 /**
  * The default {@link SqlTranspiler}: transpiles via the embedded
  * @polyglot-sql/sdk Rust/WASM engine. There is no external runtime dependency
@@ -72,3 +73,4 @@ export declare function transpilesFrom(dialect: string): boolean;
  * that request, so the caller degrades to the imported form + warning.
  */
 export declare const polyglotTranspiler: SqlTranspiler;
+export {};

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

@@ -34,7 +34,7 @@ exports.polyglotTranspiler = void 0;
 exports.hasDoubleQuotedColumn = hasDoubleQuotedColumn;
 exports.doubleQuotedNames = doubleQuotedNames;
 exports.transpileModel = transpileModel;
-exports.transpilesFrom = transpilesFrom;
+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");
@@ -164,9 +164,10 @@ function sourceToTranspile(node, target) {
     return undefined;
 }
 /**
- * Adds a translated `opts.target` dialect entry to every field or metric 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.
+ * 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
@@ -214,6 +215,15 @@ async function transpileModel(model, opts = {}) {
     }
     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);
@@ -236,27 +246,17 @@ async function transpileModel(model, opts = {}) {
         // 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 cols = (0, sql_expr_utils_1.columnReferences)(res.sql, target);
-        if (cols === undefined) {
+        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 {
-            const emitterVisible = (0, sql_expr_utils_1.entitiesReached)(cols, entityNames);
-            const anyCase = [
-                ...new Set(cols.flatMap(c => {
-                    if (!c.qualifier)
-                        return [];
-                    const lower = c.qualifier.toLowerCase();
-                    return entityNames.filter(n => n.toLowerCase() === lower);
-                })),
-            ];
-            if (!sameSet(emitterVisible, anyCase)) {
-                warnings.push(`${ctx}: transpiled '${request.dialect}' -> '${target}' but it re-cased an entity qualifier the emitter matches ` +
-                    `case-sensitively (${fmtSet(emitterVisible)} vs ${fmtSet(anyCase)}); ` +
-                    `left untranslated`);
-                continue;
-            }
+        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}'`);
@@ -268,6 +268,35 @@ async function transpileModel(model, opts = {}) {
     }
     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;
@@ -298,16 +327,6 @@ function polyglotDialect(token) {
         return undefined;
     return POLYGLOT_DIALECTS[token.toUpperCase()];
 }
-/**
- * Returns true if the default translator reads SQL written in `dialect`
- * (treating an empty string as `ANSI_SQL`).
- *
- * `transpileModel` leaves a text in any other dialect as written, with a
- * warning.
- */
-function transpilesFrom(dialect) {
-    return polyglotDialect(dialect || 'ANSI_SQL') !== undefined;
-}
 /**
  * The default {@link SqlTranspiler}: transpiles via the embedded
  * @polyglot-sql/sdk Rust/WASM engine. There is no external runtime dependency
@@ -335,37 +354,36 @@ const polyglotTranspiler = async (requests, target) => {
         const reason = `SQL transpiler engine unavailable: ${errMessage(err)}`;
         return requests.map(r => ({ id: r.id, error: reason }));
     }
-    return requests.map(r => {
-        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) };
-        }
-    });
+    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);
 }

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

@@ -3,12 +3,13 @@ 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): 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[];
@@ -25,11 +26,45 @@ export declare function validateActions(model: SemanticModel, document: string,
 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 storeMessage(message: string | undefined, status: number): string;
 export declare function validateSpannerActionStatements(models: LoadedModel[], spanner: SpannerClient): Promise<string[]>;
 export declare function validateBigQueryActionStatements(models: LoadedModel[], bq: BigQueryClient, defaultProject: string): Promise<string[]>;