@google-cloud/kcmd 0.1.0 → 0.2.1

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

@@ -50,6 +50,7 @@ exports.undefinedEndpointProblem = undefinedEndpointProblem;
 exports.isFormatVersion = isFormatVersion;
 exports.noSqlReason = noSqlReason;
 exports.listed = listed;
+exports.plural = plural;
 exports.expressionDocOf = expressionDocOf;
 exports.noSqlProblemOf = noSqlProblemOf;
 exports.inheritedNoSqlProblems = inheritedNoSqlProblems;
@@ -85,9 +86,9 @@ exports.sourceToDataSource = sourceToDataSource;
 exports.thirdPartyEntryOf = thirdPartyEntryOf;
 exports.bindsThirdPartyTable = bindsThirdPartyTable;
 exports.dialectLookupKey = dialectLookupKey;
+exports.spannerDatabaseOf = spannerDatabaseOf;
 exports.isGoogleCloudForm = isGoogleCloudForm;
 exports.parseSource = parseSource;
-exports.unquote = unquote;
 exports.bareNameSegments = bareNameSegments;
 exports.bareNameParts = bareNameParts;
 exports.loadSemanticModels = loadSemanticModels;
@@ -131,9 +132,6 @@ function sourceRequiredMessage(dataset) {
     return `dataset '${dataset}': a non-abstract dataset requires a ` +
         `source; set 'source', or mark it 'abstract: true' if it has no table`;
 }
-function noPrimaryKeyWarning(dataset) {
-    return `dataset '${dataset}': no primary_key; the entity's KEY will be empty (invalid for graph generation)`;
-}
 function ansiFallbackNote(preferred) {
     return `note: no '${preferred}' dialect for one or more expressions; using the portable ` +
         `'${FALLBACK_DIALECT}' dialect verbatim ('${preferred}' accepts the ANSI core subset — ` +
@@ -261,7 +259,7 @@ function noSqlReason(text, dialect, entity) {
         return 'is only a comment';
     if (entity === undefined)
         return undefined;
-    const onlyQualifier = (d) => (0, sql_expr_utils_1.stripQualifier)((0, sql_parser_1.withoutComments)(text, d), entity).trim() === '';
+    const onlyQualifier = (d) => (0, sql_expr_utils_1.withoutQualifier)((0, sql_parser_1.withoutComments)(text, d), entity, d).trim() === '';
     return readers.some(onlyQualifier) ? `is only the qualifier '${entity}.'` :
         undefined;
 }
@@ -280,10 +278,15 @@ function noSqlProblem(raw, entity) {
     }));
 }
 // `problems` as one list, "a, b and c", or undefined when there are none.
-function listed(problems) {
+// `conjunction` replaces the "and".
+function listed(problems, conjunction = 'and') {
     if (problems.length < 2)
         return problems[0];
-    return `${problems.slice(0, -1).join(', ')} and ${problems[problems.length - 1]}`;
+    return `${problems.slice(0, -1).join(', ')} ${conjunction} ${problems[problems.length - 1]}`;
+}
+// Selects the singular or plural form based on `n` (English count agreement).
+function plural(n, one, many) {
+    return n === 1 ? one : many;
 }
 // Whether reading `doc` for a field of `entity` names `text`, or finds every
 // problem that reading `text` in `dialect` finds. The string form and an
@@ -417,10 +420,7 @@ const googleAiContextSchema = z.union([
     z.string(),
     z.object({
         ...aiContextMembers,
-        custom: z.record(z.string(), z.unknown(), {
-            error: `ai_context 'custom' must be a mapping of custom ` +
-                `member names to values`,
-        }).optional(),
+        custom: z.record(z.string(), z.unknown()).optional(),
     })
         .strict()
         .superRefine((ai, ctx) => {
@@ -707,10 +707,6 @@ const modelBase = z.object({
     datasets: z.array(datasetBase).min(1),
     relationships: z.array(relationshipSchema).optional(),
     metrics: z.array(metricSchema).optional(),
-    // A native deployment-target key (GOOGLE_VERSION only, under
-    // allowLegacyBareSource). Folded into a GOOGLE `custom_extensions` block on
-    // the IR after validation (see convertModel).
-    deployment_target: z.string().optional(),
     // Named deployment targets (GOOGLE_VERSION only).
     deployments: z.array(deploymentSchema).optional(),
     // Model-level write operations, also GOOGLE_VERSION only (see actionSchema).
@@ -723,6 +719,14 @@ const modelBase = z.object({
 // separately. Actions and constraints are extended-profile constructs with no
 // `custom_extensions` encoding, so they do not take it.
 const customExtensionsKey = { custom_extensions: z.array(customExtensionSchema).optional() };
+// The schemas of keys a document schema accepts only so that the loader can
+// reject them with its own message. A message about an unknown key does not
+// list them among the keys an object takes.
+const UNLISTED_KEYS = new WeakSet();
+function unlisted(schema) {
+    UNLISTED_KEYS.add(schema);
+    return schema;
+}
 // Builds the document schema for one (bindingOptional, extended) combination.
 // Every object is `.strict()`, so an unknown key is a hard error rather than
 // silently dropped. Two axes shape it:
@@ -770,10 +774,10 @@ function buildDocumentSchema(bindingOptional, extended) {
         // dataset and the fix, not a bare "unrecognized key".
         extends: placement.dataset.extends === 'native' ?
             z.array(z.string()).optional() :
-            z.unknown().optional(),
+            unlisted(z.unknown().optional()),
         abstract: placement.dataset.abstract === 'native' ?
             z.boolean().optional() :
-            z.unknown().optional(),
+            unlisted(z.unknown().optional()),
     })
         .strict()
         .superRefine((ds, ctx) => {
@@ -821,7 +825,7 @@ function buildDocumentSchema(bindingOptional, extended) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ['source'],
-                message: `dataset '${ds.name}': an abstract dataset has no table; ` +
+                message: `entity '${ds.name}': an abstract entity has no table; ` +
                     `remove 'source', or drop 'abstract: true' to bind it to that table`,
             });
         }
@@ -855,7 +859,10 @@ function buildDocumentSchema(bindingOptional, extended) {
         to: z.string(),
         from_columns: z.array(z.string()).min(1).optional(),
         to_columns: z.array(z.string()).min(1).optional(),
-        description: z.string().optional(),
+        // Vanilla rejects a relationship's description after the schema.
+        description: placement.relationship.description === 'native' ?
+            z.string().optional() :
+            unlisted(z.unknown().optional()),
         ai_context: aiContext.optional(),
         ...customExtensionsKey,
     })
@@ -880,8 +887,9 @@ function buildDocumentSchema(bindingOptional, extended) {
         // An authored anchor is a native extension: extended profile only.
         // Vanilla still declares the key so the refinement below can reject it
         // with a message that names the fix, not a bare "unrecognized key".
-        entity: placement.metric.entity === 'native' ? z.string().optional() :
-            z.unknown().optional(),
+        entity: placement.metric.entity === 'native' ?
+            z.string().optional() :
+            unlisted(z.unknown().optional()),
     })
         .strict()
         .superRefine((mt, ctx) => {
@@ -935,7 +943,7 @@ function buildDocumentSchema(bindingOptional, extended) {
     // rejectExpressionBody, which is what turns it into a useful error.
     const constraint = z.object({
         name: z.string(),
-        expression: z.string().optional(),
+        expression: unlisted(z.unknown().optional()),
         judgment: z.string().optional(),
         description: z.string().optional(),
         // What a violation does; required. See
@@ -950,7 +958,6 @@ function buildDocumentSchema(bindingOptional, extended) {
         .superRefine(rejectExpressionBody);
     const modelExtensions = {
         ...(placement.model.deployments === 'native' ? {
-            deployment_target: z.string().optional(),
             deployments: z.array(deploymentSchema).optional(),
         } :
             {}),
@@ -1058,18 +1065,15 @@ function composeDescription(...parts) {
         .filter((p) => !!p);
     return kept.length ? kept.join('\n\n') : undefined;
 }
-// The vendor tag for Google-specific extension blocks (kept in sync with the
-// deploy leg's reader). A model-level `deployments:` list folds into one.
+// The vendor tag for Google-specific extension blocks.
 exports.GOOGLE_VENDOR = 'GOOGLE';
 // Rewrites the author-friendly sugar forms into the canonical wire shape the
 // schema validates, and rejects deprecated or flavor-mismatched model keys up
 // front with actionable messages: the removed `deployment_target:` key,
 // inline `profiles:` in either flavor, and `deployments:` or
 // `entities:` in vanilla. Under the extended profile, `entities:` is rewritten
-// to `datasets:` and `deployments:` is left in place here and folded into a
-// GOOGLE `custom_extensions` block on the IR after validation (see
-// convertModel). Operates on the parsed document before validation.
-function normalizeDocumentSugars(doc, extended, allowLegacyBareSource = false) {
+// to `datasets:`. Operates on the parsed document before validation.
+function normalizeDocumentSugars(doc, extended) {
     if (!doc || typeof doc !== 'object')
         return doc;
     const cloned = structuredClone(doc);
@@ -1078,31 +1082,17 @@ function normalizeDocumentSugars(doc, extended, allowLegacyBareSource = false) {
         return cloned;
     for (const m of models) {
         if (m && typeof m === 'object') {
-            normalizeModelSugars(m, extended, allowLegacyBareSource);
+            normalizeModelSugars(m, extended);
         }
     }
     return cloned;
 }
-function normalizeModelSugars(m, extended, allowLegacyBareSource = false) {
+function normalizeModelSugars(m, extended) {
     const label = typeof m.name === 'string' ? `model '${m.name}'` : 'model';
     const placement = exports.FORMAT_VERSION_PLACEMENT[extended ? exports.GOOGLE_VERSION : exports.OSSIE_VERSION];
-    // Only a load that still accepts the legacy key can be left holding both.
-    // Elsewhere the `deployment_target:` rejection below speaks to it. The open
-    // format has neither key, so a vanilla document is told to switch flavor.
-    if (allowLegacyBareSource && m.deployment_target !== undefined &&
-        m.deployments !== undefined) {
-        throw new SemanticModelError(extended ?
-            `Semantic model load error: ${label}: set either 'deployments' ` +
-                `or 'deployment_target', not both.` :
-            `Semantic model load error: ${label}: neither 'deployments' nor ` +
-                `'deployment_target' is in the open format ` +
-                `('${exports.OSSIE_VERSION}'); set version: '${exports.GOOGLE_VERSION}', ` +
-                `keep 'deployments' and remove 'deployment_target'.`);
-    }
     // `deployment_target` has been replaced by the named `deployments:` list in
-    // the extended profile (and was never in vanilla). Reject it unless
-    // `allowLegacyBareSource` is set for legacy fixtures and profile files.
-    if (m.deployment_target !== undefined && !allowLegacyBareSource) {
+    // the extended profile (and was never in vanilla).
+    if (m.deployment_target !== undefined) {
         if (!extended) {
             throw new SemanticModelError(`Semantic model load error: ${label}: 'deployment_target' is not ` +
                 `in the open format ('${exports.OSSIE_VERSION}'); ` +
@@ -1161,18 +1151,6 @@ function normalizeModelSugars(m, extended, allowLegacyBareSource = false) {
         delete m.entities;
     }
 }
-// Builds the GOOGLE custom-extension block that carries a model's deployment
-// target URIs on the IR (the form the deploy leg reads). Both the native
-// `deployments:` list and (under `allowLegacyBareSource`) the legacy
-// `deployment_target:` key fold into this block after validation (see
-// convertModel). The extended profile rejects any authored GOOGLE block (see
-// rejectGoogleBlock), so there is never a pre-existing one to reconcile with.
-function deploymentTargetsExtension(targets) {
-    return {
-        vendorName: exports.GOOGLE_VENDOR,
-        data: JSON.stringify({ deploymentTargets: targets }),
-    };
-}
 // True when `vendorName` names the GOOGLE vendor, in any letter case.
 function isGoogleVendor(vendorName) {
     return typeof vendorName === 'string' &&
@@ -1282,7 +1260,7 @@ function readGoogleBlocks(exts, version, level, ctx) {
             }
             const parsed = GOOGLE_BLOCK_SCHEMAS[key].safeParse(value);
             if (!parsed.success) {
-                throw error(`'${key}' in a ${block}: ${issueList(parsed.error)}`);
+                throw error(keyProblems(parsed.error, GOOGLE_BLOCK_SCHEMAS[key], key, value, `the ${block}`).replaceAll('\n', `\n${ctx}: `));
             }
             values[key] = parsed.data;
         }
@@ -1756,11 +1734,14 @@ function fromDocument(doc, opts = {}) {
     if (proto) {
         throw new SemanticModelError(`Semantic model load error: ${proto}`);
     }
-    const normalized = normalizeDocumentSugars(doc, extended, opts.allowLegacyBareSource);
-    const result = makeDocumentSchema(opts.bindingOptional ?? false, extended)
-        .safeParse(normalized);
+    const normalized = normalizeDocumentSugars(doc, extended);
+    const schema = makeDocumentSchema(opts.bindingOptional ?? false, extended);
+    const result = schema.safeParse(normalized);
     if (!result.success) {
-        throw new SemanticModelError(`Semantic model load error: ${result.error.message}`);
+        throw new SemanticModelError(`Semantic model load error: ${schemaProblems(result.error.issues, {
+            schema, doc: normalized, authored: doc, extended,
+            subject: 'the document',
+        })}`);
     }
     const warnings = [];
     const parsed = result.data;
@@ -1823,16 +1804,19 @@ function runsDialect(entity, dialect) {
     return (0, resolve_profiles_1.sourcesDialect)({ entities: [entity] }) === dialect.toUpperCase();
 }
 // The warning `item` gives on `table`, the table of `entity`:
-// expressionWarning's when the load knows the table's dialect, or, unless
-// `profiled`, one saying the table has no text to run. On a table of the
+// expressionWarning's when the load knows the table's dialect, or one saying
+// the table has no text to run. With `profiled`, the second is given only on a
+// Cloud SQL, Spanner or third-party table no lookup has read. On a table of the
 // `preferred` dialect, expressionWarning's transpilation warning already says
 // so.
 function tableWarning(item, subject, table, entity, preferred, profiled) {
     const w = table.unread ?
         undefined :
         expressionWarning(item, subject, table.name, preferred);
-    if (w || profiled || !(0, resolve_profiles_1.noTextFor)(item, table.dialects))
+    if (w || (profiled && !table.unread && !table.guessed) ||
+        !(0, resolve_profiles_1.noTextFor)(item, table.dialects)) {
         return w;
+    }
     const own = table.dialects.map(d => `'${d}'`).join(', ');
     return `${subject.ctx}: no ${own} or '${FALLBACK_DIALECT}' dialect, so the ${table.name} table of entity '${entity}' cannot run it`;
 }
@@ -1865,19 +1849,13 @@ function metricWarning(metric, reached, entities, preferred, profiled) {
     }
     return undefined;
 }
-// The warning a concrete entity with neither a primary key nor a unique key
-// gives, or undefined. A unique key is enough, as the graph keys the entity's
-// node by the first one.
-function keyWarning(entity) {
-    return !(0, resolve_profiles_1.statesKey)(entity.keys, entity.uniqueKeys) && !entity.abstract ?
-        noPrimaryKeyWarning(entity.name) :
-        undefined;
-}
 // Infers the entities a metric's expressions reach across all dialect entries,
 // and returns the warning the metric gives when an expression could not be
 // parsed or when it states no `entity` and its expressions name none. An
 // authored anchor, which vanilla writes in a GOOGLE block, settles which entity
-// the metric belongs to, so a `COUNT(*)` with one is not warned about.
+// the metric belongs to, so a `COUNT(*)` with one is not warned about. An
+// ANSI_SQL text whose `impliedDialect` no lookup read (null) is read as
+// generic SQL, the closest reading there is.
 function inferMetricEntities(metric, entityNames, preferred = exports.DEFAULT_DIALECT, impliedDialect, version) {
     const ctx = `metric '${metric.name}'`;
     const sources = (metric.dialects ?? [])
@@ -1895,7 +1873,7 @@ function inferMetricEntities(metric, entityNames, preferred = exports.DEFAULT_DI
     for (const { text, dialect } of sources) {
         if (!text)
             continue;
-        const cols = (0, sql_expr_utils_1.columnsForSource)(text, dialect, impliedDialect);
+        const cols = (0, sql_expr_utils_1.columnsForSource)(text, dialect, impliedDialect ?? undefined);
         if (cols === undefined) {
             unparsed = true;
         }
@@ -1923,16 +1901,14 @@ function inferMetricEntities(metric, entityNames, preferred = exports.DEFAULT_DI
     return { referenced };
 }
 // Every warning a load gives about `model`'s entities and metrics, in the
-// order a load gives them: each concrete entity's missing key, each field's
-// expression warning, then each metric's expression warning and its warning
-// when it names no entity. A metric a profile excludes gives none. With
-// `profiled`, the profile check reports a field or metric its tables cannot
-// run, so no warning repeats it. A profile changes only these; a load's other
-// warnings, about actions, come after them.
+// order a load gives them: each field's expression warning, then each metric's
+// expression warning and its warning when it names no entity. A metric a
+// profile excludes gives none. With `profiled`, the profile check reports a
+// field or metric its tables cannot run, so no warning repeats it. A profile
+// changes only these; a load's other warnings, about actions, come after them.
 function entityAndMetricWarnings(model, preferred = exports.DEFAULT_DIALECT, profiled = false) {
     const entities = model.entities ?? [];
-    const out = entities.map(keyWarning).filter((w) => !!w);
-    out.push(...fieldWarnings(model, preferred, profiled));
+    const out = fieldWarnings(model, preferred, profiled);
     const entityNames = entities.map(e => e.name);
     const impliedDialect = (0, resolve_profiles_1.sourcesDialect)(model);
     const excluded = new Set(model.excludedMetrics);
@@ -2074,10 +2050,6 @@ function convertModel(m, version, opts, warnings) {
         }
         seenTargets.set(d.target, d.name);
     }
-    // A blank `deployment_target` names no target, as push reads it.
-    if (!deployments.length && m.deployment_target?.trim()) {
-        deployments.push({ name: 'default', target: m.deployment_target.trim() });
-    }
     const description = composeDescription(m.description);
     // `version` records the flavor the document was written in, so a consumer
     // (e.g. a pull) can return the model in that same flavor.
@@ -2095,20 +2067,9 @@ function convertModel(m, version, opts, warnings) {
     const ai = aiContextOrUndefined(m.ai_context);
     if (ai)
         model.aiContext = ai;
-    // The blocks the model keeps are carried verbatim. Under the extended
-    // profile the native `deployments` list (or legacy `deployment_target` key)
-    // is folded into a GOOGLE block appended after them; no authored GOOGLE block
-    // can collide with it, since that flavor rejects one (see rejectGoogleBlock).
-    // Vanilla deployments, read from a GOOGLE block, are not folded.
+    // The blocks the model keeps are carried verbatim.
     if (block.kept)
         model.customExtensions = block.kept;
-    const foldedTargets = version === exports.GOOGLE_VERSION ? deployments.map(d => d.target) : [];
-    if (foldedTargets.length) {
-        model.customExtensions = [
-            ...(model.customExtensions ?? []),
-            deploymentTargetsExtension(foldedTargets),
-        ];
-    }
     return model;
 }
 // Converts the dataset `ds`, whose GOOGLE blocks convertModel has read into
@@ -2118,15 +2079,12 @@ function convertDataset(ds, block, version, opts, warnings, dialect) {
     const ctxLabel = `dataset '${ds.name}'`;
     // An abstract entity has no physical table, so it carries no source (empty
     // dataSource) and no key -- both are meaningless for a class never
-    // materialized. Only a concrete entity is parsed/warned for those.
+    // materialized. Only a concrete entity's source is parsed.
     const parsedSource = ds.source !== undefined ?
-        parseSource(ds.source, opts, ctxLabel, warnings, /* importHint= */ true) :
+        parseSource(ds.source, opts, ctxLabel, warnings, version) :
         undefined;
     const dataSource = parsedSource ? parsedSource.dataSource : '';
     const keys = ds.primary_key ?? [];
-    const kw = keyWarning({ name: ds.name, keys, uniqueKeys: ds.unique_keys, abstract: ds.abstract });
-    if (kw)
-        warnings.push(kw);
     const fields = (ds.fields ?? []).map(f => convertField(f, ds.name, version, dialect));
     rejectDuplicateNames(fields.map(f => f.name), 'field name', `dataset '${ds.name}'`, true);
     const entity = { name: ds.name, dataSource, keys, fields };
@@ -2231,7 +2189,7 @@ function readFieldExpression(raw, where, dialect, problemOf) {
         z.string().safeParse(raw) :
         expressionObjectSchema.safeParse(raw);
     if (!result.success) {
-        throw new SemanticModelError(`${where}: 'expression': ${issueList(result.error)}`);
+        throw new SemanticModelError(keyProblems(result.error, expressionObjectSchema, 'expression', raw, where));
     }
     const problem = problemOf(result.data);
     if (problem) {
@@ -2645,11 +2603,178 @@ function convertParameter(p, actionName, concepts, warnings, inheritanceResolved
     }
     return param;
 }
-// A schema error's problems on one line, each led by its path.
-function issueList(error) {
-    return error.issues
-        .map(i => (i.path.length ? `${i.path.join('.')}: ` : '') + i.message)
-        .join('; ');
+// One line per problem that `schema` finds in the value of `key` on
+// `subject`.
+function keyProblems(error, schema, key, value, subject) {
+    const doc = { [key]: value };
+    return schemaProblems(error.issues.map(i => ({ ...i, path: [key, ...i.path] })), { schema: z.object({ [key]: schema }), doc, authored: doc, extended: true,
+        subject });
+}
+// The noun a message gives an entry of each list of named objects in a model
+// document. An entry of `datasets` is an entity in the Google flavor.
+const ENTRY_NOUNS = new Map([
+    ['semantic_model', 'model'], ['datasets', 'dataset'], ['fields', 'field'],
+    ['relationships', 'relationship'], ['metrics', 'metric'],
+    ['actions', 'action'], ['parameters', 'parameter'],
+    ['constraints', 'constraint'], ['deployments', 'deployment'],
+]);
+// What a message says a schema expects.
+const EXPECTED = {
+    string: 'a string',
+    boolean: 'true or false',
+    array: 'a list',
+    object: 'a mapping',
+    record: 'a mapping',
+};
+// A value as a message describes it.
+function described(value) {
+    if (value === undefined)
+        return 'missing';
+    if (value === null)
+        return 'empty';
+    if (Array.isArray(value))
+        return 'a list';
+    if (typeof value === 'object')
+        return 'a mapping';
+    if (typeof value !== 'string')
+        return String(value);
+    return value.includes('\n') ? 'a string' : `'${value}'`;
+}
+// The keys the object at `path` in `schema` takes, apart from unlisted keys.
+function keysAt(schema, path) {
+    // `s` without its optional, nullable and pipe wrappers. Of a union, the
+    // member that is a `kind`.
+    const unwrapped = (s, kind) => {
+        if (s instanceof z.ZodOptional || s instanceof z.ZodNullable) {
+            return unwrapped(s.unwrap(), kind);
+        }
+        if (s instanceof z.ZodPipe)
+            return unwrapped(s.in, kind);
+        if (s instanceof z.ZodUnion) {
+            return s.options.map(o => unwrapped(o, kind))
+                .find(o => o instanceof kind);
+        }
+        return s;
+    };
+    let node = schema;
+    for (const seg of path) {
+        const holder = unwrapped(node, typeof seg === 'number' ? z.ZodArray : z.ZodObject);
+        node = holder instanceof z.ZodArray ? holder.element :
+            holder instanceof z.ZodObject ? holder.shape[String(seg)] :
+                undefined;
+    }
+    const object = unwrapped(node, z.ZodObject);
+    if (!(object instanceof z.ZodObject))
+        return [];
+    return Object.keys(object.shape)
+        .filter(k => !UNLISTED_KEYS.has(object.shape[k]));
+}
+// Where `path` points in `input.doc`: the innermost named object, as messages
+// name it, and the key below it, such as "'data' of entry 1 of
+// 'custom_extensions'". `spelled` gives a key as the author wrote it: a
+// Google-flavor model's `datasets` is `entities` unless the author wrote
+// `datasets`.
+function schemaLocation(path, input) {
+    let subject = input.subject;
+    let name;
+    let entity;
+    let datasets = 'datasets';
+    let rest = [];
+    let node = input.doc;
+    for (const seg of path) {
+        node = node?.[seg];
+        const list = rest.length === 1 ? String(rest[0]) : '';
+        const noun = list === 'datasets' && input.extended ?
+            'entity' :
+            ENTRY_NOUNS.get(list);
+        if (typeof seg !== 'number' || !noun) {
+            rest.push(seg);
+            continue;
+        }
+        rest = [];
+        name = typeof node?.name === 'string' ? node.name : undefined;
+        const named = name === undefined ? `${noun} number ${seg + 1}` : `${noun} '${name}'`;
+        if (list === 'semantic_model') {
+            const written = input.authored?.semantic_model?.[seg];
+            datasets = input.extended && written?.datasets === undefined ?
+                'entities' :
+                'datasets';
+        }
+        if (list === 'datasets')
+            entity = name;
+        if (list === 'fields' && name !== undefined && entity !== undefined) {
+            name = `${entity}.${name}`;
+            subject = `field '${name}'`;
+        }
+        else {
+            subject = list === 'fields' || list === 'parameters' ?
+                `${named} of ${subject}` :
+                named;
+        }
+    }
+    const spelled = (key) => key === 'datasets' ? datasets : String(key);
+    const place = rest.map(s => typeof s === 'number' ? `entry ${s + 1}` :
+        `'${spelled(s)}'`)
+        .reverse()
+        .join(' of ');
+    return { subject, name, place, value: node, spelled };
+}
+// One line per problem of a schema error, naming the object and the key and
+// saying how to fix it.
+function schemaProblems(issues, input) {
+    // zod also checks the length of a value of the wrong type, as for
+    // `target: []`. The type is what to fix, so that check gives no line.
+    const mistyped = new Set(issues.filter(i => i.code === 'invalid_type')
+        .map(i => JSON.stringify(i.path)));
+    return issues
+        .filter(i => i.code !== 'too_small' || !mistyped.has(JSON.stringify(i.path)))
+        .map(i => schemaProblem(i, input))
+        .join('\n');
+}
+function schemaProblem(issue, input) {
+    if (issue.code === 'invalid_union') {
+        // When only one alternative takes the value's type, report its problems.
+        const typed = issue.errors.filter(b => !b.every(i => i.code === 'invalid_type' && !i.path.length));
+        if (typed.length === 1) {
+            return schemaProblems(typed[0].map(i => ({ ...i, path: [...issue.path, ...i.path] })), input);
+        }
+    }
+    const { subject, name, place, value, spelled } = schemaLocation(issue.path, input);
+    const at = place ? `${subject}: ${place}` : subject;
+    const takes = (what) => `${at} is ${described(value)}; it takes ${what}`;
+    const expected = (type) => EXPECTED[type] ?? type;
+    switch (issue.code) {
+        case 'unrecognized_keys': {
+            const keys = keysAt(input.schema, issue.path).map(k => `'${spelled(k)}'`);
+            return `${subject}: unknown key${issue.keys.length > 1 ? 's' : ''} ${listed(issue.keys.map(k => `'${k}'`))}${place ? ` in ${place}` : ''}; it takes ${listed(keys)}`;
+        }
+        case 'invalid_type':
+            return takes(expected(issue.expected));
+        case 'invalid_union': {
+            // A vanilla document writes an expression only as a mapping.
+            const types = issue.errors.flatMap(b => b.flatMap(i => i.code === 'invalid_type' ? [i.expected] : []));
+            const offered = types.filter(t => input.extended || t !== 'string' ||
+                issue.path.at(-1) !== 'expression');
+            return takes(listed([...new Set(offered.map(expected))], 'or'));
+        }
+        case 'invalid_value':
+            return takes(listed(issue.values.map(v => `'${String(v)}'`), 'or'));
+        case 'too_small':
+            if (issue.origin === 'array') {
+                return `${at} is an empty list; it takes at least one entry`;
+            }
+            if (issue.origin === 'string') {
+                return `${at} is empty; it takes a non-empty string`;
+            }
+            break;
+        case 'custom':
+            // A rule on a named object quotes the object's name in its message.
+            if (name !== undefined && issue.message.includes(`'${name}'`)) {
+                return issue.message;
+            }
+            return `${subject}: ${issue.message}`;
+    }
+    return `${at}: ${issue.message}`;
 }
 // An executor written outside a model document, such as in a profile file,
 // checked against the loader's schema and converted as a load converts one.
@@ -2657,7 +2782,7 @@ function issueList(error) {
 function parseExecutor(raw, where) {
     const result = executorSchema.safeParse(raw);
     if (!result.success) {
-        throw new SemanticModelError(`${where} 'executor': ${issueList(result.error)}`);
+        throw new SemanticModelError(keyProblems(result.error, executorSchema, 'executor', raw, where));
     }
     return convertExecutor(result.data);
 }
@@ -2703,7 +2828,9 @@ function pickDialect(expr, preferred) {
 }
 const MAX_CATALOG_NAME_LENGTH = 4000;
 const BIGQUERY_TABLE_URI = /^\/\/bigquery\.googleapis\.com\/projects\/([^/]+)\/datasets\/([^/.]+)\/tables\/([^/.]+)$/;
-const BIGLAKE_TABLE_URI = /^\/\/biglake\.googleapis\.com\/projects\/([^/]+)\/catalogs\/([^/.]+)\/namespaces\/([^/.]+)\/tables\/([^/.]+)$/;
+// A BigLake table sits in a namespace of an Iceberg REST catalog, or in a
+// database of a Hive catalog.
+const BIGLAKE_TABLE_URI = /^\/\/biglake\.googleapis\.com\/projects\/([^/]+)\/catalogs\/([^/.]+)\/(namespaces|databases)\/([^/.]+)\/tables\/([^/.]+)$/;
 const SPANNER_TABLE_URI = /^\/\/spanner\.googleapis\.com\/projects\/([^/]+)\/instances\/([^/]+)\/databases\/([^/]+)\/tables\/[^/]+$/;
 const ALLOYDB_TABLE_URI = /^\/\/alloydb\.googleapis\.com\/projects\/([^/]+)\/locations\/([^/]+)\/clusters\/([^/]+)\/databases\/([^/]+)\/schemas\/[^/]+\/tables\/[^/]+$/;
 const LEGACY_ALLOYDB_INSTANCE_URI = /^\/\/alloydb\.googleapis\.com\/projects\/([^/]+)\/locations\/([^/]+)\/clusters\/([^/]+)\/instances\/[^/]+\/databases\/([^/]+)\/tables\/([^/]+)$/;
@@ -2742,8 +2869,10 @@ function sourceTableOf(source) {
         };
     }
     m = uri.match(BIGLAKE_TABLE_URI);
-    if (m)
-        return { system: 'biglake', resourceName, project: m[1], catalog: m[2] };
+    if (m) {
+        const hive = m[3] === 'databases';
+        return { system: 'biglake', resourceName, project: m[1], catalog: m[2], hive };
+    }
     m = uri.match(SPANNER_TABLE_URI);
     if (m)
         return { system: 'spanner', resourceName, project: m[1], instance: m[2] };
@@ -2829,7 +2958,8 @@ function oldSourceForm(source) {
 exports.NO_SPACE = 'kcmd cannot name a table whose name holds a space';
 // The resource name of a table in each Google Cloud service a source can
 // name, with a placeholder for each name in it. A Cloud SQL table has one
-// form without a schema and one with.
+// form without a schema and one with, and a BigLake table one for each kind
+// of catalog.
 exports.TABLE_FORMS = {
     bigquery: 'bigquery.googleapis.com/projects/<project>/datasets/<dataset>/tables/<table>',
     spanner: 'spanner.googleapis.com/projects/<project>/instances/<instance>/databases/<database>/tables/<table>',
@@ -2837,11 +2967,14 @@ exports.TABLE_FORMS = {
     cloudsql: 'cloudsql.googleapis.com/projects/<project>/locations/<location>/instances/<instance>/databases/<database>/tables/<table>',
     cloudsqlSchema: 'cloudsql.googleapis.com/projects/<project>/locations/<location>/instances/<instance>/databases/<database>/schemas/<schema>/tables/<table>',
     biglake: 'biglake.googleapis.com/projects/<project>/catalogs/<catalog>/namespaces/<namespace>/tables/<table>',
+    biglakeHive: 'biglake.googleapis.com/projects/<project>/catalogs/<catalog>/databases/<database>/tables/<table>',
 };
-// The databases each Cloud SQL form in TABLE_FORMS is for.
-const CLOUD_SQL_DATABASES = {
+// What each form in TABLE_FORMS is for, where its service has two.
+const FORM_USES = {
     cloudsql: 'MySQL',
     cloudsqlSchema: 'PostgreSQL, SQL Server',
+    biglake: 'Iceberg REST catalog',
+    biglakeHive: 'Hive catalog',
 };
 // `form` with its last placeholders replaced by `parts`, in order, or
 // undefined when `form` has fewer placeholders than `parts`.
@@ -3095,9 +3228,8 @@ function isAcceptedSource(source) {
     return source !== undefined && databaseOf(source) !== undefined;
 }
 // The source an entity is written with: its `authoredSource` when that names a
-// table in a form `databaseOf` reads, and otherwise its `dataSource`, which is
-// how the load completes a legacy bare table name, shown as a resource name. A
-// model is serialized, shown and judged by it.
+// table in a form `databaseOf` reads, and otherwise its `dataSource`, shown as
+// a resource name. A model is serialized, shown and judged by it.
 function writtenSource(entity) {
     const authored = entity.authoredSource?.trim();
     return authored !== undefined && isAcceptedSource(authored) ?
@@ -3119,8 +3251,8 @@ function sourceToDataSource(source) {
         return `${bqUri[1]}.${bqUri[2]}.${bqUri[3]}`;
     const biglakeUri = value.match(BIGLAKE_TABLE_URI);
     if (biglakeUri) {
-        const [, project, catalog, namespace, table] = biglakeUri;
-        return `${project}.${catalog}.${namespace}.${table}`;
+        const [, project, catalog, , parent, table] = biglakeUri;
+        return `${project}.${catalog}.${parent}.${table}`;
     }
     return value;
 }
@@ -3160,11 +3292,19 @@ function bindsThirdPartyTable(entity) {
     return thirdPartyEntryOf(entity.authoredSource ?? '') !== undefined;
 }
 // The key LoadOptions.sourceDialects holds a source's dialect under: a Cloud
-// SQL table's resource name, or a third-party table's entry name. Undefined
-// for a source whose own name gives its dialect.
+// SQL table's resource name, a third-party table's entry name, or a Spanner
+// table's database. Undefined for a source whose own name gives its dialect.
 function dialectLookupKey(source) {
     return cloudSqlTableOf(source)?.resourceName ??
-        thirdPartyEntryOf(source)?.name;
+        thirdPartyEntryOf(source)?.name ?? spannerDatabaseOf(source);
+}
+// The resource name of the database the Spanner table `source` is in.
+// Undefined for any other source and for a name with quotes.
+function spannerDatabaseOf(source) {
+    const uri = asResourceUri(source.trim());
+    return !QUOTE.test(uri) && SPANNER_TABLE_URI.test(uri) ?
+        uri.slice(2, uri.lastIndexOf('/tables/')) :
+        undefined;
 }
 // Why `source` is not accepted when it is a Knowledge Catalog entry name in a
 // system entry group, one whose id starts with `@`, such as `@bigquery`.
@@ -3234,14 +3374,12 @@ function thirdPartyNameError(source, ctx) {
 // Reads an entity's `source` into the dotted name the generators use and the
 // source as written. Throws on a form the loader does not accept. A profile
 // file's sources are read here too, so they follow the same rules. With
-// `importHint`, for a model file's source, a bare table name's error also
-// names `kcmd import`, which completes a model file's bare names but not a
-// profile file's.
-function parseSource(source, opts, ctx, warnings, importHint = false) {
+// `importVersion`, the version of the model file the source is in, a bare
+// table name's error also names `kcmd import`, which completes a model file's
+// bare names but not a profile file's.
+function parseSource(source, opts, ctx, warnings, importVersion) {
     const trimmed = source.trim();
-    // Under the legacy wrapper, a space inside double quotes also marks a query.
-    if (hasUnquotedWhitespace(trimmed) || (opts.allowLegacyBareSource &&
-        hasUnquotedWhitespace(trimmed.replaceAll('"', '')))) {
+    if (hasUnquotedWhitespace(trimmed)) {
         throw new SemanticModelError(`Semantic model load error: ${ctx}: source '${trimmed}' looks like a ` +
             `SQL query; a query-valued source is not supported yet. Bind 'source' ` +
             `to a physical table using its GCP resource name (e.g. ` +
@@ -3288,27 +3426,12 @@ function parseSource(source, opts, ctx, warnings, importHint = false) {
         !trimmed.includes(':');
     let dotted;
     if (isBareTableName) {
-        // The legacy wrapper splits at every dot outside backticks.
-        const rawSegs = catalogNameSegments(trimmed);
-        if (opts.allowLegacyBareSource && rawSegs.length > 0) {
-            const parts = rawSegs.map(unquote);
-            if (parts.length === 1 && opts.defaultDataset) {
-                parts.unshift(opts.defaultDataset);
-            }
-            if (parts.length < 3 && opts.defaultProject) {
-                parts.unshift(opts.defaultProject);
-            }
-            return {
-                authoredSource: trimmed,
-                dataSource: parts.join('.'),
-            };
-        }
-        // With `importHint`, the example also names the command that completes a
-        // model file's bare names.
-        const viaImport = importHint ?
-            `\nOr run 'kcmd import <file> --flavor <ossie|google> ` +
-                `--source-prefix <prefix>' to complete each bare table name ` +
-                `from the database that <prefix> names.` :
+        // With `importVersion`, the example also names the command that completes
+        // a model file's bare names.
+        const viaImport = importVersion ?
+            `\nOr run '${(0, resolve_profiles_1.importCommand)('--source-prefix <prefix>', importVersion)}' to ` +
+                `complete each bare table name from the database or Knowledge ` +
+                `Catalog entry group that <prefix> names.` :
             '';
         // A name holding a space gets no name to write. Any other name gets an
         // example built from its parts when the loader accepts the example, and
@@ -3334,11 +3457,11 @@ function parseSource(source, opts, ctx, warnings, importHint = false) {
         }
     }
     // Each table form with its placeholders shortened, such as <p> for
-    // <project>, and the databases a Cloud SQL form is for.
+    // <project>, and what it is for where its service has two.
     const forms = Object.entries(exports.TABLE_FORMS).map(([kind, form]) => {
         const short = form.replace(/<(\w+)>/g, (_, name) => `<${name === 'database' ? 'db' : name[0]}>`);
-        const databases = CLOUD_SQL_DATABASES[kind];
-        return `'${short}'${databases ? ` (${databases})` : ''}`;
+        const use = FORM_USES[kind];
+        return `'${short}'${use ? ` (${use})` : ''}`;
     });
     throw new SemanticModelError(`Semantic model load error: ${ctx}: source '${trimmed}' is not a valid ` +
         `table reference${dotted ? `; ${dotted}` : ''}. Expected a GCP ` +
@@ -3346,9 +3469,6 @@ function parseSource(source, opts, ctx, warnings, importHint = false) {
         `or, for a table outside Google Cloud, the entry name of its ` +
         `Knowledge Catalog entry ('${exports.ENTRY_NAME_FORM}').`);
 }
-function unquote(part) {
-    return part.replace(/^[`"]/, '').replace(/[`"]$/, '');
-}
 // The parts of a bare table name, without their quotes. A part in backticks
 // or double quotes is one name, dots included, and a doubled quote character
 // in it, as in "a""b", is one literal quote. The quotes are those
@@ -3401,9 +3521,6 @@ function bareNameParts(name, bigQuery) {
  * thrown, mirroring how the deploy legs previously reported it; loader warnings
  * are prefixed with their document name.
  *
- * A document's `allowLegacyBareSource` sets that load option for that document
- * alone.
- *
  * Each document needs the SQL parser as loadModels does, so call
  * `loadSqlEngine()` first. Without it, this throws the parser's plain Error.
  */
@@ -3412,14 +3529,8 @@ function loadSemanticModels(docs, opts = {}) {
     const warnings = [];
     for (const doc of docs) {
         let loaded;
-        const docOpts = {
-            ...opts,
-            ...(doc.allowLegacyBareSource !== undefined ?
-                { allowLegacyBareSource: doc.allowLegacyBareSource } :
-                {}),
-        };
         try {
-            loaded = loadModels(doc.text, docOpts);
+            loaded = loadModels(doc.text, opts);
         }
         catch (err) {
             if (!(err instanceof SemanticModelError))