@google-cloud/kcmd 0.1.0 → 0.2.1

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

@@ -4,10 +4,10 @@
 // Runs once over the shared, already-parsed models (see loadSemanticModels)
 // before any destination leg, so a real `kcmd push` AND a `--validate-only` dry
 // run enforce the same requirements. Returns one message per violation (an
-// empty array means valid); the caller (commands.ts) prints them and aborts the
-// push. Kept separate from the loader -- which validates a document against the
-// schema -- because these are deployment requirements, not schema rules, and
-// they read the GOOGLE deployment-target extension the BigQuery leg owns.
+// empty array means valid); push prints them and aborts, and `kcmd import`
+// reports them. Kept separate from the loader -- which validates a document
+// against the schema -- because these are deployment requirements, not schema
+// rules.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validatePushRequirements = validatePushRequirements;
 exports.validateDeployments = validateDeployments;
@@ -18,12 +18,18 @@ exports.validateActions = validateActions;
 exports.validateInheritance = validateInheritance;
 exports.validateExpressionReferences = validateExpressionReferences;
 exports.deploymentTableErrors = deploymentTableErrors;
+exports.spannerMetricsErrors = spannerMetricsErrors;
+exports.kcV2Aspects = kcV2Aspects;
+exports.withProfileFiles = withProfileFiles;
+exports.localChecks = localChecks;
+exports.pruningLines = pruningLines;
 exports.validateBigQueryDataSources = validateBigQueryDataSources;
-exports.storeMessage = storeMessage;
 exports.validateSpannerActionStatements = validateSpannerActionStatements;
 exports.validateBigQueryActionStatements = validateBigQueryActionStatements;
+const context_1 = require("../gcp/context");
 const bigquery_1 = require("./bigquery");
 const deploy_bigquery_1 = require("./deploy_bigquery");
+const deploy_spanner_1 = require("./deploy_spanner");
 const deployment_target_1 = require("./deployment_target");
 const ir_1 = require("./ir");
 const kc_ids_1 = require("./kc_ids");
@@ -34,7 +40,6 @@ const resolve_inheritance_1 = require("./resolve_inheritance");
 const resolve_profiles_1 = require("./resolve_profiles");
 const sql_expr_utils_1 = require("./sql_expr_utils");
 const sql_identifiers_1 = require("./sql_identifiers");
-const sql_parser_1 = require("./sql_parser");
 // Checks every model against the push requirements and returns the collected
 // error messages (empty when all models pass), each tagged with the model's
 // source document so the author can find it.
@@ -49,23 +54,12 @@ const sql_parser_1 = require("./sql_parser");
 // caller to print.
 //
 // `v2Aspects` says push writes the second-generation Knowledge Catalog types
-// (selected via KC_V2_ASPECTS=1).
+// (the CLI sets it unless KC_V2_ASPECTS=0).
 function validatePushRequirements(models, opts = {}) {
     const errors = [];
     for (const { document, model } of models) {
         errors.push(...nameAndDescriptionErrors(model, document, !!opts.v2Aspects));
-        let deployInfo;
-        try {
-            // One pass over the model's GOOGLE extension(s): both checks below read
-            // the same parse rather than re-parsing the JSON per reader.
-            deployInfo = (0, deploy_bigquery_1.googleDeploymentTargets)(model);
-        }
-        catch (err) {
-            // Malformed GOOGLE extension JSON: surface it as a validation error here
-            // rather than letting it throw out of a later leg as an uncaught stack.
-            errors.push(`${err.message || err} (${document})`);
-            continue;
-        }
+        const deployInfo = (0, deploy_bigquery_1.googleDeploymentTargets)(model);
         // A model that targets a graph (BigQuery OR Spanner) must have every
         // relationship's join columns bound. The loader accepts a column-less
         // relationship so a purely logical model (an OWL import) loads and pushes
@@ -94,7 +88,7 @@ function validatePushRequirements(models, opts = {}) {
         const flaggedMetrics = new Set();
         errors.push(...validateExpressionReferences([{ document, model }], !!opts.fieldsPruned, opts.warnings, flaggedMetrics));
         if (deployInfo.bigQuery.length > 0) {
-            errors.push(...validateBigQueryMetrics(model, document, flaggedMetrics));
+            errors.push(...measurePlacementErrors(model, document, flaggedMetrics));
         }
         // An action reaches Knowledge Catalog only, so its checks are
         // target-independent: each parameter's type must resolve to something in
@@ -171,7 +165,7 @@ function nameAndDescriptionErrors(model, document, v2Aspects) {
 // Checks each deployment of `model` against the rules of its engine, under the
 // profile it names in `model.profiles` or the model file's own bindings, and
 // returns one message per problem, naming every deployment it applies to.
-function validateDeployments(model, document) {
+function validateDeployments(model, document, load = {}) {
     // The deployments each problem applies to, keyed by the text that follows
     // their names in the message.
     const problems = new Map();
@@ -193,7 +187,7 @@ function validateDeployments(model, document) {
         // The model the deployment's bindings give, less what they leave
         // unavailable. The completeness check reports a named profile that does
         // not apply, and the fields its metrics read.
-        const bound = named ? profiled(model, named) : (0, resolve_profiles_1.pruneUnavailable)(model, resolve_profiles_1.DEFAULT_PROFILE, alloyDb ? 'ALLOYDB' : (0, resolve_profiles_1.sourcesDialect)(model));
+        const bound = named ? profiled(model, named, load) : (0, resolve_profiles_1.pruneUnavailable)(model, resolve_profiles_1.DEFAULT_PROFILE, alloyDb ? 'ALLOYDB' : (0, resolve_profiles_1.sourcesDialect)(model));
         if (!bound)
             continue;
         const available = bound.model.metrics ?? [];
@@ -251,9 +245,9 @@ function validateDeployments(model, document) {
 }
 // `model` with `profile` applied and what it leaves unavailable pruned, or
 // undefined when the profile does not apply.
-function profiled(model, profile) {
+function profiled(model, profile, load) {
     try {
-        return (0, resolve_profiles_1.pruneUnavailable)((0, resolve_profiles_1.applyProfile)(model, profile), profile.name);
+        return (0, resolve_profiles_1.pruneUnavailable)((0, resolve_profiles_1.applyProfile)(model, profile, { load }), profile.name);
     }
     catch (err) {
         if (!(err instanceof loader_1.SemanticModelError))
@@ -262,7 +256,7 @@ function profiled(model, profile) {
     }
 }
 // Why `metric` cannot be a BigQuery measure, or undefined when it can. Leaves
-// out a metric that validateBigQueryMetrics or the inheritance rules report:
+// out a metric that measurePlacementErrors or the inheritance rules report:
 // one that reads several entities or none, or one on an abstract or extended
 // entity.
 function measureProblem(model, metric) {
@@ -273,15 +267,10 @@ function measureProblem(model, metric) {
     if (!columns)
         return undefined;
     const entities = model.entities ?? [];
-    const names = entities.map(e => e.name);
-    // Read `text` (from `expressionForDialect(metric, 'BIGQUERY')`), the SQL the
-    // BigQuery graph runs.
-    const matched = (0, sql_expr_utils_1.referencedEntityNames)((0, sql_parser_1.withoutComments)(text, 'BIGQUERY'), names);
-    if (matched.length > 1 || !matched.length && !metric.entity)
+    const placed = (0, sql_expr_utils_1.measureEntities)(text, entities.map(e => e.name), metric.entity);
+    if (placed.length !== 1)
         return undefined;
-    const reached = (0, sql_expr_utils_1.entitiesReached)(columns, names);
-    const name = reached.length > 1 ? undefined : reached[0] ?? metric.entity;
-    const entity = entities.find(e => e.name === name);
+    const entity = entities.find(e => e.name === placed[0]);
     if (!entity || entity.abstract ||
         entities.some(e => e.extends?.includes(entity.name))) {
         return undefined;
@@ -295,17 +284,73 @@ function measureProblem(model, metric) {
     }
     return undefined;
 }
-// Checks that each bound field of the model file has a text for the dialect
-// of its entity's source, and returns one message per field.
+// The BigQuery graph's rules for placing each metric of `model` as a measure,
+// one message per metric that breaks them, skipping each one in
+// `alreadyFlagged`, which validateExpressionReferences has reported. The
+// generator (`bigquery.ts`) places a measure on the one entity whose
+// qualifier its BigQuery SQL writes before a column, or on its anchor when the
+// SQL writes none (see measureEntities), and skips a metric that has no
+// BigQuery or ANSI_SQL text. validateExpressionReferences reads every dialect
+// entry together and lets an authored anchor settle SQL that reads two
+// entities, so it does not catch each metric the generator would skip.
+function measurePlacementErrors(model, document, alreadyFlagged) {
+    const errors = [];
+    const entityNames = (model.entities ?? []).map(e => e.name);
+    for (const metric of model.metrics ?? []) {
+        if (alreadyFlagged.has(metric.name))
+            continue;
+        const prefix = `metric '${metric.name}' in model '${model.name}' (${document})`;
+        // The text BigQuery runs: its `BIGQUERY` entry, else its `ANSI_SQL` one,
+        // else `expression` for a metric held without a dialect list.
+        const bqText = (0, ir_1.expressionForDialect)(metric, 'BIGQUERY');
+        if (bqText === undefined && metric.importedExpression !== undefined) {
+            errors.push(`${prefix} targets a BigQuery graph with only a '${metric.importedDialect ?? 'vendor'}' expression; supply a ` +
+                `'BIGQUERY' or 'ANSI_SQL' expression${(0, resolve_profiles_1.importTranspiles)(metric, 'BIGQUERY', model) ?
+                    `, or add one with '${(0, resolve_profiles_1.importCommand)('--transpile', model.version)}'` :
+                    ''}.`);
+            continue;
+        }
+        const placed = (0, sql_expr_utils_1.measureEntities)(bqText ?? '', entityNames, metric.entity);
+        if (placed.length > 1) {
+            errors.push(`${prefix} targets a BigQuery graph and its BigQuery SQL reads ` +
+                `several entities (${placed.join(', ')}); a BigQuery measure ` +
+                `belongs to one entity's node table, so scope its expression to ` +
+                `one entity.`);
+        }
+        else if (placed.length === 0) {
+            const anchor = model.version === loader_1.OSSIE_VERSION ?
+                `'entity' in a GOOGLE custom_extensions block on the metric` :
+                `top-level 'entity'`;
+            errors.push(`${prefix} targets a BigQuery graph but does not resolve to a ` +
+                `single entity; the BigQuery generator places a measure on the ` +
+                `entity its BigQuery SQL reads, or on ${anchor}.`);
+        }
+    }
+    return errors;
+}
+// Checks that the model file's Spanner tables are all in one database, so they
+// share one dialect, and that each bound field has a text for the dialect of
+// its entity's source. Returns one message per problem.
 function validateInlineDialects(model, document) {
     const errors = [];
+    const databases = new Map();
+    for (const e of model.entities ?? []) {
+        const db = (0, loader_1.databaseOf)(e.authoredSource ?? '');
+        if (db?.startsWith('spanner/') && !databases.has(db)) {
+            databases.set(db, e.name);
+        }
+    }
+    if (databases.size > 1) {
+        const named = [...databases.values()].map(n => `'${n}'`).join(', ');
+        errors.push(`model '${model.name}' (${document}) binds entities in more than one ` +
+            `Spanner database (${named}); bind the model file's entities to ` +
+            `tables in one Spanner database.`);
+    }
     for (const { entity: e, field: f, table: { name: dialect } } of (0, resolve_profiles_1.fieldsOnTables)(model)) {
         if (!(0, resolve_profiles_1.noTextFor)(f, [dialect]))
             continue;
-        const hint = (0, resolve_profiles_1.importTranspiles)(f, dialect) ?
-            `; give it one, or add one with '${resolve_profiles_1.IMPORT_TRANSPILE_COMMAND}'` : '';
         errors.push(`field '${e.name}.${f.name}' in model '${model.name}' (${document}) has no expression for ${dialect} or ANSI_SQL, and ` +
-            `the model file binds entity '${e.name}' to ${/^[AEIOU]/.test(dialect) ? 'an' : 'a'} ${dialect} source${hint}.`);
+            `the model file binds entity '${e.name}' to ${/^[AEIOU]/.test(dialect) ? 'an' : 'a'} ${dialect} source${(0, resolve_profiles_1.importHint)(f, dialect, model)}.`);
     }
     return errors;
 }
@@ -1292,6 +1337,94 @@ function fieldNoSqlErrors(model, document) {
     }
     return errors;
 }
+// The errors for the fields of `entity` that name themselves, directly or
+// through other fields of `entity`. The graph renders a field that names a
+// sibling as `<entity>.<field>` from that sibling's own SQL, so a field that
+// reaches itself that way has no SQL to render. A field expression that writes
+// its own column as `<entity>.<field>` names itself too: write the bare column
+// instead. Each dialect is read on its own, from the text an engine of that
+// dialect renders (its entry, else the ANSI_SQL one), so two texts that no one
+// engine reads together do not form a cycle.
+//
+// `resolved` is `entity` with the fields it inherits, which name its fields
+// as the graph renders them (see resolve_inheritance.localizeInheritedField),
+// so a field can reach itself through one it inherits. A cycle is reported on
+// an entity only when a field on it is bound there, so one an ancestor forms on
+// its own is reported on that ancestor alone.
+function selfReferenceErrors(entity, resolved, model, document, impliedDialect) {
+    const own = entity.fields ?? [];
+    const inherited = resolved.fields ?? [];
+    // A field a profile excludes is left off `resolved`, but still checked.
+    const fields = [
+        ...inherited,
+        ...own.filter(f => !inherited.some(r => r.name === f.name)),
+    ];
+    const bound = new Set(own.filter(f => (0, ir_1.isFieldBound)(f)).map(f => f.name));
+    const names = new Set(fields.map(f => f.name));
+    const dialects = new Set(['ANSI_SQL']);
+    for (const f of fields) {
+        for (const d of f.dialects ?? [])
+            dialects.add(d.dialect);
+        if (f.importedDialect)
+            dialects.add(f.importedDialect);
+    }
+    const errors = new Set();
+    for (const dialect of dialects) {
+        // The fields of `entity` each field names, in this dialect, read as the
+        // graph generators read them (see graph_ddl.siblingsRead), so a qualifier
+        // the parser reserves, such as `Date` in `Date.days`, names them too. An
+        // ANSI_SQL text is read in the dialect the sources imply, as
+        // columnsForSource reads it, and not at all when their dialect is null.
+        if (dialect === 'ANSI_SQL' && impliedDialect === null)
+            continue;
+        const readIn = dialect === 'ANSI_SQL' && impliedDialect ? impliedDialect : dialect;
+        const reads = new Map();
+        for (const f of fields) {
+            const text = (0, ir_1.expressionForDialect)(f, dialect);
+            if (text === undefined ||
+                (0, loader_1.noSqlReason)(text, dialect, entity.name) !== undefined) {
+                continue;
+            }
+            reads.set(f.name, [...new Set((0, sql_expr_utils_1.qualifiedColumns)(text, entity.name, readIn) ?? [])]
+                .filter(n => names.has(n)));
+        }
+        for (const f of fields) {
+            const through = pathBack(f.name, reads);
+            if (!through || ![f.name, ...through].some(n => bound.has(n)))
+                continue;
+            errors.add((0, sql_expr_utils_1.selfReferenceMessage)(entity.name, [f.name, ...through], ` in model '${model.name}' (${document})`) +
+                '.');
+        }
+    }
+    return [...errors];
+}
+// The shortest run of other fields through which `start` reaches itself in
+// `reads`, empty when it names itself directly, or undefined when it does not
+// reach itself.
+function pathBack(start, reads) {
+    const via = new Map();
+    const queue = [];
+    for (const next of reads.get(start) ?? []) {
+        if (next === start)
+            return [];
+        if (!via.has(next)) {
+            via.set(next, [next]);
+            queue.push(next);
+        }
+    }
+    while (queue.length) {
+        const name = queue.shift();
+        for (const next of reads.get(name) ?? []) {
+            if (next === start)
+                return via.get(name);
+            if (!via.has(next)) {
+                via.set(next, [...via.get(name), next]);
+                queue.push(next);
+            }
+        }
+    }
+    return undefined;
+}
 // The error for a metric with no SQL, or undefined. A metric is rejected when
 // none of its texts holds SQL, with or without an anchor, since the graph
 // would drop it. It is also rejected when any one of its texts holds none, as
@@ -1332,10 +1465,13 @@ function metricNoSqlError(metric, model, document) {
 //        differs only in case from a declared entity.
 //     2. For references to E itself, every field named must be declared or
 //        inherited on E (gated on `!fieldsPruned`, and run before pruning).
+//     3. Reject a field that names itself, directly or through other fields of
+//        E, declared or inherited, since the graph renders a field that names
+//        a sibling from that sibling's SQL (see selfReferenceErrors).
 //
-// Exported so `commands.ts` can also run it on the unpruned model before
-// `pruneUnavailable` drops unbound fields and metrics on a graph push. When
-// given, `flaggedMetrics` collects the name of each metric it reports.
+// deploymentPlan also runs it on the unpruned model before `pruneUnavailable`
+// drops unbound fields and metrics on a graph push. When given,
+// `flaggedMetrics` collects the name of each metric it reports.
 function validateExpressionReferences(models, fieldsPruned = false, warnings = [], flaggedMetrics) {
     const errors = [];
     for (const { document, model } of models) {
@@ -1352,8 +1488,18 @@ function validateExpressionReferences(models, fieldsPruned = false, warnings = [
             continue;
         }
         const entityNames = [...fieldsByEntity.keys()];
+        // Each entity's fields as the graph renders them (see selfReferenceErrors).
+        const resolvedByName = new Map((ifResolvable(() => (0, resolve_inheritance_1.resolveInheritance)(model, undefined, { requalify: true })
+            .model.entities) ??
+            model.entities ?? [])
+            .map(e => [e.name, e]));
         const impliedDialect = (0, resolve_profiles_1.sourcesDialect)(model);
-        const addUnreadableWarning = (what, total, unreadDialects) => {
+        const addUnreadableWarning = (what, total, unread) => {
+            // A caller that looked up no table's dialect reads no ANSI_SQL
+            // text when every table needs the lookup, so it warns about none.
+            const unreadDialects = impliedDialect === null ?
+                unread.filter(d => d !== 'ANSI_SQL') :
+                unread;
             if (!unreadDialects.length)
                 return;
             if (unreadDialects.length === total) {
@@ -1406,6 +1552,7 @@ function validateExpressionReferences(models, fieldsPruned = false, warnings = [
                     }
                 }
             }
+            errors.push(...selfReferenceErrors(entity, resolvedByName.get(entity.name) ?? entity, model, document, impliedDialect));
         }
         for (const metric of model.metrics ?? []) {
             const before = errors.length;
@@ -1496,53 +1643,6 @@ function validateExpressionReferences(models, fieldsPruned = false, warnings = [
     }
     return errors;
 }
-// Temporary BigQuery-only metric check, until the BigQuery generator places
-// measures with the SQL parser. Rejects a metric that the generator
-// (`bigquery.ts`) would skip: one with only another engine's SQL, which the
-// generator does not emit, or one it drops because its regex
-// (`referencedEntityNames`) disagrees with the parser or because
-// `metric.entity` is unset. Reports only metrics that
-// `validateExpressionReferences` has not already flagged.
-function validateBigQueryMetrics(model, document, alreadyFlagged) {
-    const errors = [];
-    const entityNames = (model.entities ?? []).map(e => e.name);
-    for (const metric of model.metrics ?? []) {
-        if (alreadyFlagged.has(metric.name))
-            continue;
-        const prefix = `metric '${metric.name}' in model '${model.name}' (${document})`;
-        // The text BigQuery runs: its `BIGQUERY` entry, else its `ANSI_SQL` one,
-        // else `expression` for a metric held without a dialect list.
-        const bqText = (0, ir_1.expressionForDialect)(metric, 'BIGQUERY');
-        if (bqText === undefined && metric.importedExpression !== undefined) {
-            errors.push(`${prefix} targets a BigQuery graph with only a '${metric.importedDialect ?? 'vendor'}' expression; supply a ` +
-                `'BIGQUERY' or 'ANSI_SQL' expression, or add one with '${resolve_profiles_1.IMPORT_TRANSPILE_COMMAND}'.`);
-            continue;
-        }
-        // The generator reads the resolved BigQuery expression (`bqText`) with its
-        // comments removed.
-        const expr = (0, sql_parser_1.withoutComments)(bqText ?? metric.importedExpression ?? '', 'BIGQUERY');
-        let referenced = (0, sql_expr_utils_1.referencedEntityNames)(expr, entityNames);
-        if (referenced.length === 0 && metric.entity) {
-            referenced = [metric.entity];
-        }
-        if (referenced.length > 1) {
-            errors.push(`${prefix} targets a BigQuery graph and references multiple ` +
-                `entities (${referenced.join(', ')}); the BigQuery generator ` +
-                `reads every '<entity>.' outside comments as a qualifier, ` +
-                `including a function namespace such as 'NET.', so remove the ` +
-                `extra '<entity>.' match or scope its expression to one entity.`);
-        }
-        else if (referenced.length === 0) {
-            const anchor = model.version === loader_1.OSSIE_VERSION ?
-                `'entity' in a GOOGLE custom_extensions block on the metric` :
-                `top-level 'entity'`;
-            errors.push(`${prefix} targets a BigQuery graph but does not resolve to a ` +
-                `single entity; the BigQuery generator reads '<entity>.' ` +
-                `qualifiers in the expression or ${anchor}.`);
-        }
-    }
-    return errors;
-}
 // Every field each entity has, inherited and profile-excluded ones included so
 // an unpruned check before `pruneUnavailable` does not report a profile-excluded
 // inherited field as undeclared. Inheritance is resolved through the same pass
@@ -1608,6 +1708,20 @@ function deploymentTableErrors(document, model, deployment) {
     }
     return errors;
 }
+// The error for a Spanner `deployment` on the model file's own bindings when
+// `model` declares metrics, which a Spanner graph cannot hold.
+function spannerMetricsErrors(document, model, deployment) {
+    if (deployment.engine !== 'spanner' ||
+        deployment.profile !== resolve_profiles_1.DEFAULT_PROFILE || !model.metrics?.length) {
+        return [];
+    }
+    return [
+        `[${document}] deployment '${deployment.name}' targets a Spanner graph ` +
+            `and uses the model file's own bindings, but the model declares ` +
+            `metrics, which a Spanner graph cannot hold; name a profile with ` +
+            `metrics_exclude: "*".`,
+    ];
+}
 // The database the tables of a deployment target must be in, as databaseOf
 // gives it, and how an error names the target and a table outside it.
 function targetDatabase({ engine, coordinates: c }) {
@@ -1621,6 +1735,265 @@ function targetDatabase({ engine, coordinates: c }) {
     return { database: `${engine}/${name}`, target: `${system} database '${name}'`,
         outside: 'which is not a table in that database' };
 }
+// Whether Knowledge Catalog push and pull use the second-generation built-in
+// aspect fields and entry-id layout. They do unless `KC_V2_ASPECTS=0`; every
+// other value, including unset and `''`, is on. `KC_V2_ASPECTS=0` is a
+// temporary escape hatch to the first-generation path, removed with that path
+// (b/575695037).
+function kcV2Aspects() {
+    return process.env.KC_V2_ASPECTS !== '0';
+}
+// Adds the profile files of the model in `base` to `model.profiles`, without
+// their actions. Returns the error of the first profile file that breaks a
+// file rule. A profile file that does not load is left out, for
+// namedProfileErrors to report.
+function withProfileFiles(base, profileDocs) {
+    const { document, model } = base;
+    const profiles = [...(model.profiles ?? [])];
+    let files;
+    try {
+        files = profileDocs(document);
+    }
+    catch (err) {
+        return { errors: [{ error: err.message || String(err), document }] };
+    }
+    const reserved = (0, resolve_profiles_1.reservedProfileNameError)(document, files);
+    if (reserved)
+        return { errors: [{ error: reserved, document }] };
+    for (const p of files) {
+        try {
+            profiles.push((0, resolve_profiles_1.loadProfileFile)(p.text, p.name, { skipActions: true }));
+        }
+        catch (err) {
+            if (!(err instanceof loader_1.SemanticModelError))
+                throw err;
+        }
+    }
+    return { document, model: profiles.length ? { ...model, profiles } : model };
+}
+// Runs push's offline checks that follow withProfileFiles and the UTF-8 and
+// sidecar checks, through the graph generation. Returns the errors of the
+// first stage that finds any, or else a plan for each deployment `selected`
+// names, or for every deployment when it is unset.
+async function localChecks(scope, warn, selected) {
+    const { docs, loaded, models, profileDocs, declaredBy, load } = scope;
+    const stop = (errors) => ({ errors });
+    const ofModel = (document, ...errors) => errors.map(error => ({ error, document }));
+    const ofProfile = (document, profile, ...errors) => errors.map(error => ({ error, document, profile }));
+    const declaredNames = (document) => declaredBy(docs.find(d => d.name === document)).map(p => p.name);
+    // Every deployment's target must be in an accepted form, and its profile one
+    // the model declares, whether or not this push selects the deployment.
+    const selectedByDoc = new Map();
+    const everyByDoc = new Map();
+    for (const { document, model } of models) {
+        const every = (0, deployment_target_1.resolveModelDeployments)(model);
+        if ('error' in every)
+            return stop(ofModel(document, every.error));
+        const resolved = (0, deployment_target_1.resolveModelDeployments)(model, selected);
+        if ('error' in resolved)
+            return stop(ofModel(document, resolved.error));
+        const undeclared = (0, resolve_profiles_1.undeclaredProfileError)(document, model, declaredNames(document));
+        if (undeclared)
+            return stop(ofModel(document, undeclared));
+        everyByDoc.set(document, every.deployments);
+        selectedByDoc.set(document, resolved.deployments);
+    }
+    // Every named profile is checked on its own against the model file, and so
+    // are the model file's own bindings and each deployment. The catalog's model
+    // is checked as a model that deploys nowhere. A selected deployment's own
+    // checks run only after these pass, so these give every error and every
+    // warning about SQL kcmd cannot read.
+    const profileWarnings = [];
+    const profileErrors = (0, resolve_profiles_1.namedProfileErrors)(docs, new Map(loaded.models.map(m => [m.document, m.model])), profileDocs, declaredBy, profileWarnings, load);
+    for (const { document, model } of models) {
+        profileErrors.push(...ofProfile(document, resolve_profiles_1.DEFAULT_PROFILE, ...validateInlineDialects(model, document), ...validateInheritedColumns(model, document)), 
+        // One call per profile, so each error carries its deployments' profile.
+        ...[...new Set(everyByDoc.get(document).map(d => d.profile))].flatMap(profile => ofProfile(document, profile, ...validateDeployments({
+            ...model,
+            deployments: model.deployments.filter(d => (d.profile ?? resolve_profiles_1.DEFAULT_PROFILE) === profile),
+        }, document, load))));
+        const doc = docs.find(d => d.name === document);
+        const declared = declaredBy(doc);
+        const named = declared.some(p => p.name.toLowerCase() !== resolve_profiles_1.DEFAULT_PROFILE);
+        profileWarnings.push(...inlineBindingWarnings(model, document, named));
+        // A profile that no selected deployment applies still goes to Knowledge
+        // Catalog, so its load warnings print here, less those the model file's
+        // load gave, unless a check above recorded an error for that profile. A
+        // selected deployment prints its own profile's warnings.
+        const applied = selectedByDoc.get(document).map(d => d.profile);
+        for (const { name } of declared) {
+            if (applied.includes(name))
+                continue;
+            if (profileErrors.some(e => e.document === document && e.profile === name)) {
+                continue;
+            }
+            profileWarnings.push(...(0, resolve_profiles_1.appliedProfileWarnings)(doc, declared, name, loaded.warnings, load));
+        }
+    }
+    const kcWarnings = [];
+    const kcErrors = models.flatMap(m => ofModel(m.document, ...validatePushRequirements([{ ...m, model: { ...m.model, deployments: [] } }], {
+        warnings: kcWarnings,
+        v2Aspects: kcV2Aspects(),
+    })));
+    for (const w of [...profileWarnings, ...kcWarnings])
+        warn(w);
+    if (profileErrors.length || kcErrors.length) {
+        return stop([...profileErrors, ...kcErrors]);
+    }
+    // Each deployment's tables must be in the database it deploys to, whether
+    // or not this push selects the deployment.
+    const tableErrors = models.flatMap(({ document, model }) => (everyByDoc.get(document) ?? []).flatMap(d => ofProfile(document, d.profile, ...deploymentTableErrors(document, model, d))));
+    if (tableErrors.length)
+        return stop(tableErrors);
+    // Spanner creates no property graph in a PostgreSQL-dialect database, so a
+    // selected Spanner deployment there is refused by the dialect already read.
+    const dialectErrors = models.flatMap(({ document }) => (selectedByDoc.get(document) ?? []).flatMap(d => {
+        if (d.engine !== 'spanner')
+            return [];
+        const { project, instance, database } = d.coordinates;
+        const key = `spanner.googleapis.com/projects/${project}/instances/${instance}/databases/${database}`;
+        if (load.sourceDialects?.get(key) !== 'POSTGRES')
+            return [];
+        return ofProfile(document, d.profile, `[${document}] deployment '${d.name}': database ${project}/${instance}/${database} has the PostgreSQL dialect, and ` +
+            `Spanner creates no property graph in a PostgreSQL-dialect ` +
+            `database. Remove the deployment; push still publishes the ` +
+            `model to Knowledge Catalog.`);
+    }));
+    if (dialectErrors.length)
+        return stop(dialectErrors);
+    const plans = [];
+    for (const base of models) {
+        for (const deployment of selectedByDoc.get(base.document) ?? []) {
+            const plan = await deploymentPlan(base, profileDocs(base.document), deployment, load, warn);
+            if ('errors' in plan) {
+                return stop(ofProfile(base.document, deployment.profile, ...plan.errors));
+            }
+            plans.push(plan);
+        }
+    }
+    return { plans };
+}
+// Builds and checks the model `deployment` deploys from `base`, reading its
+// profile file in `files` again with its actions, and generates its DDL
+// offline. The profile applies with the source dialects in `load`. Returns
+// the plan, or the errors that stop the push.
+async function deploymentPlan(base, files, deployment, load, warn) {
+    const { document, model } = base;
+    const at = `[${document}] deployment '${deployment.name}'`;
+    const fail = (...errors) => ({ errors });
+    const spanner = spannerMetricsErrors(document, model, deployment);
+    if (spanner.length)
+        return fail(...spanner);
+    let applied = model;
+    if (deployment.profile !== resolve_profiles_1.DEFAULT_PROFILE) {
+        // localChecks has checked that the model declares the profile and that
+        // its file loads, so `model.profiles` holds it.
+        let spec = model.profiles.find(p => p.name === deployment.profile);
+        const file = files.find(p => p.name === deployment.profile);
+        const warnings = [];
+        try {
+            // A profile in a GOOGLE block has no file and applies as loaded.
+            if (file)
+                spec = (0, resolve_profiles_1.loadProfileFile)(file.text, file.name);
+        }
+        catch (err) {
+            if (!(err instanceof loader_1.SemanticModelError))
+                throw err;
+            return fail(`[${file.fileName}] ${err.message}`);
+        }
+        try {
+            applied = (0, resolve_profiles_1.applyProfile)(model, spec, { load, warnings });
+        }
+        catch (err) {
+            if (!(err instanceof loader_1.SemanticModelError))
+                throw err;
+            return fail(`${at}: ${err.message}`);
+        }
+        for (const w of warnings) {
+            warn(`profile '${deployment.profile}': [${document}] ${w}`);
+        }
+    }
+    // Messages name the deployment.
+    const label = `${document}, deployment '${deployment.name}'`;
+    const checked = { document: label, model: applied };
+    // Pruning can remove the field these rules are about, so they run first.
+    // localChecks has already warned about the SQL they cannot read.
+    const unprunedErrors = [
+        ...validateInheritance([checked]),
+        ...validateExpressionReferences([checked]),
+    ];
+    const { model: pruned, report } = (0, resolve_profiles_1.pruneUnavailable)(checked.model, deployment.profile);
+    // Keeps only this deployment, so every reader sees its target alone.
+    const narrowed = {
+        document: checked.document,
+        model: {
+            ...pruned,
+            deployments: (model.deployments ?? []).filter(d => d.name === deployment.name),
+        },
+    };
+    const errors = [
+        ...unprunedErrors,
+        ...validatePushRequirements([narrowed], {
+            fieldsPruned: true,
+            v2Aspects: kcV2Aspects(),
+        }),
+    ];
+    if (errors.length)
+        return { errors };
+    // An AlloyDB database holds no graph.
+    if (deployment.engine === 'alloydb') {
+        return { deployment, at, model: narrowed, report };
+    }
+    const generated = await generateOffline(deployment.engine === 'bigquery' ? deploy_bigquery_1.deployBigQuery : deploy_spanner_1.deploySpanner, [narrowed]);
+    if (typeof generated === 'string')
+        return fail(`${at}: ${generated}`);
+    return { deployment, at, model: narrowed, report, generated };
+}
+// The warnings and the note push prints on what pruning leaves out of the
+// model `plan` deploys. Each line names the model, and the document and the
+// deployment.
+function pruningLines({ deployment, model, report: r }) {
+    const where = `model '${model.model.name}' (${model.document})`;
+    // What becomes of a field left out. An AlloyDB database holds no graph.
+    const outcome = deployment.engine === 'alloydb' ? 'it is unavailable there' :
+        'the graph omits it';
+    const excluded = new Set(r.excludedFields);
+    const omits = (field, why) => `Warning: field '${field}' in ${where} ${why}, so ${outcome}.`;
+    // Such as "metric 'a'" or "metrics 'a' and 'b'", or '' for no names.
+    const named = (kind, names) => names.length ?
+        `${(0, loader_1.plural)(names.length, kind, `${kind}s`)} ${(0, loader_1.listed)(names.map(n => `'${n}'`))}` :
+        '';
+    const unavailable = [
+        named('metric', r.droppedMetrics.map(m => m.name)),
+        named('action', r.droppedActions.map(a => a.name)),
+    ].filter(n => n).join(r.droppedMetrics.length > 1 ? ', and ' : ' and ');
+    const note = [
+        excluded.size ? `excludes ${named('field', [...excluded])}.` : '',
+        unavailable && `leaves ${unavailable} unavailable.`,
+    ].filter(p => p).join(' It ');
+    return [
+        ...r.unboundFields.filter(f => !excluded.has(f))
+            .map(f => omits(f, 'has no expression')),
+        ...r.droppedFields.map(d => omits(d.name, d.reason)),
+        ...note ? [`Note: ${where} ${note}`] : [],
+    ];
+}
+// A validate-only deploy builds the DDL and calls no service, so it needs no
+// project or token.
+const NO_SERVICE = new context_1.ApiContext('', '', '');
+// Generates a graph leg's DDL without calling a service, or gives why it
+// cannot be generated.
+async function generateOffline(deployLeg, models) {
+    try {
+        const result = await deployLeg(models, NO_SERVICE, { validateOnly: true });
+        if (result.success)
+            return result;
+        return result.details ?? 'the graph could not be generated';
+    }
+    catch (err) {
+        return err.message || String(err);
+    }
+}
 // Live pre-flight over the BigQuery-targeting models: confirms every entity's
 // BigQuery source table is reachable BEFORE any destination leg runs, so a push
 // fails fast when the model could not deploy, rather than surfacing a missing
@@ -1704,16 +2077,8 @@ async function validateBigQueryDataSources(models, bq, defaultProject, graph) {
 // bills to: the project of the model's first BigQuery Graph deployment target
 // (where the CREATE PROPERTY GRAPH runs), falling back to the scope's default
 // project when the model declares no parseable BigQuery Graph target.
-// googleDeploymentTargets is safe here: validatePushRequirements ran first and
-// already rejected a malformed GOOGLE extension.
 function billingProject(model, defaultProject) {
-    try {
-        return (0, deploy_bigquery_1.googleDeploymentTargets)(model).bigQuery[0]?.project ??
-            defaultProject;
-    }
-    catch {
-        return defaultProject;
-    }
+    return (0, deploy_bigquery_1.googleDeploymentTargets)(model).bigQuery[0]?.project ?? defaultProject;
 }
 // A source that can be probed as a BigQuery table: the canonical `dataSource`,
 // trimmed, or null when it is empty or a non-BigQuery resource URI. Unlike a
@@ -1781,24 +2146,6 @@ function rejectedStatement(pending, store, detail) {
     return `action '${pending.action.name}' in model '${pending.model}' (${pending.document}): statement ${pending.index + 1} of its sql executor was rejected by ${store}: ${detail} Statements reach the store exactly as written, so every ` +
         `table and column has to be the name the database uses.`;
 }
-// The first line of a multi-line diagnosis. The lines after it echo the
-// statement and point a caret at the offending token, which is worth nothing
-// here: the author has the statement open in the profile, the position in
-// `[at 1:54]` survives, and a caret counted from column 1 lands in the wrong
-// place once the message is embedded in a longer sentence.
-//
-// `\n` is matched in both its forms because Spanner's top-level `error.message`
-// arrives with its newlines ESCAPED -- a literal backslash and an n survive
-// JSON.parse -- while every other message uses real ones.
-function firstLine(message) {
-    return message.replace(/\\n/g, '\n').split('\n')[0].trim();
-}
-// An API error's message reduced to its first line as a sentence, such as
-// "Unrecognized name: accountId; Did you mean account_id? [at 1:54]."
-function storeMessage(message, status) {
-    const text = (message ?? '').trim();
-    return text ? (0, parameters_1.sentence)(firstLine(text)) : `HTTP ${status}.`;
-}
 // The Spanner arm. Each distinct database gets one session, reused across every
 // statement bound to it and deleted at the end -- which also discards the
 // read-write transactions PLAN had to begin and never committed. Returns one
@@ -1814,13 +2161,7 @@ async function validateSpannerActionStatements(models, spanner) {
         // The database an action writes to is the one this profile deploys its
         // graph to: on Spanner the published graph and the operational rows live in
         // the same database. A model with no Spanner target contributes nothing.
-        let target;
-        try {
-            target = (0, deployment_target_1.spannerGraphTargets)(loaded.model).targets[0];
-        }
-        catch {
-            continue;
-        }
+        const target = (0, deployment_target_1.spannerGraphTargets)(loaded.model).targets[0];
         if (!target)
             continue;
         const key = `${target.project}/${target.instance}/${target.database}`;
@@ -1838,7 +2179,7 @@ async function validateSpannerActionStatements(models, spanner) {
             // is reported rather than skipped: a push that could not verify its
             // statements must not proceed as though it had.
             errors.push(`could not open a session on ${store} to verify the sql executor ` +
-                `statements in model '${statements[0].model}' (${statements[0].document}): ${storeMessage(opened.message, opened.status)}`);
+                `statements in model '${statements[0].model}' (${statements[0].document}): ${(0, parameters_1.storeMessage)(opened.message, opened.status)}`);
             continue;
         }
         try {
@@ -1853,7 +2194,7 @@ async function validateSpannerActionStatements(models, spanner) {
                 const res = await spanner.planDml(session, pending.sql, params, paramTypes);
                 if (res.status === 200)
                     continue;
-                errors.push(rejectedStatement(pending, store, storeMessage(res.message, res.status)));
+                errors.push(rejectedStatement(pending, store, (0, parameters_1.storeMessage)(res.message, res.status)));
             }
         }
         finally {
@@ -1892,7 +2233,7 @@ async function validateBigQueryActionStatements(models, bq, defaultProject) {
             const res = await bq.query(project, pending.sql, undefined, true, statementParameterTypes(pending.action, pending.sql));
             if (res.status === 200)
                 continue;
-            errors.push(rejectedStatement(pending, store, storeMessage(res.message, res.status)));
+            errors.push(rejectedStatement(pending, store, (0, parameters_1.storeMessage)(res.message, res.status)));
         }
     }
     return errors;