@google-cloud/kcmd 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,1275 @@
+"use strict";
+// Imports a third-party (or first-party) semantic model YAML document into a
+// valid kcmd semantic model document.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importSemanticModelYaml = importSemanticModelYaml;
+const yaml = __importStar(require("yaml"));
+const deployment_target_1 = require("./deployment_target");
+const ir_1 = require("./ir");
+const loader_1 = require("./loader");
+const names_1 = require("./names");
+const resolve_profiles_1 = require("./resolve_profiles");
+const sql_expr_utils_1 = require("./sql_expr_utils");
+const sql_parser_1 = require("./sql_parser");
+const transpile_1 = require("./transpile");
+const yaml_options_1 = require("./yaml_options");
+const yaml_update_1 = require("./yaml_update");
+const STANDARD_AI_CONTEXT_KEYS = new Set(['instructions', 'synonyms', 'examples']);
+// The loader's warning for a source it leaves as written.
+const LOADER_SOURCE_WARNING = /^(.*?): source '(.*)' is not a valid GCP resource name\.$/s;
+// Why no name to write is given when the name holds a quote.
+const NO_QUOTE = 'kcmd cannot name a table whose name holds a quote';
+// Each kind of --source-prefix for the service `prefix` names, or every kind
+// when there is no prefix.
+function prefixKinds(prefix) {
+    const host = prefix?.base.split('/')[0];
+    return SOURCE_PREFIX_PATTERNS.filter(k => host === undefined || k.form.startsWith(`${host}/`));
+}
+// The warning for `source`, which import leaves as written after a run with
+// `prefix`, if any. It gives the name to write when the loader names one,
+// or another --source-prefix run when a prefix of that kind, or of any kind
+// when none ran, completes the name, or else why the table cannot be named.
+function sourceWarning(ctx, source, prefix) {
+    const problem = (0, loader_1.oldSourceForm)(source);
+    if (problem !== undefined) {
+        return `${ctx}: source '${source}' is ${problem}. 'kcmd push' rejects ` +
+            `the file until it is repointed.`;
+    }
+    const kinds = prefixKinds(prefix);
+    const bare = !/[/:]/.test(source);
+    const rerun = bare && completes(source, kinds);
+    const quoted = kinds.some(k => {
+        const parts = prefixSegments(source, k.form);
+        return !parts.length || parts.some(p => /[`"]/.test(p));
+    });
+    const cannot = !bare || rerun ? undefined :
+        /\s/.test(source) ? loader_1.NO_SPACE :
+            quoted ? NO_QUOTE :
+                undefined;
+    const dotted = !bare || rerun || cannot ?
+        undefined :
+        kinds.map(k => ({
+            form: k.form,
+            why: (0, loader_1.dottedPartProblem)(prefixSegments(source, k.form), k.form),
+        }))
+            .find(d => d.why);
+    return `${ctx}: source '${source}' is not a valid GCP resource name` +
+        (cannot ? `, and ${cannot}. ` :
+            dotted ? `; ${dotted.why}. Write the table's GCP resource name ` +
+                `instead, such as '${dotted.form}'. ` :
+                '; ') +
+        `'kcmd push' rejects the file until it is repointed` +
+        (rerun ? `, or until 'kcmd import' runs again with '--source-prefix'.` :
+            '.') +
+        ((0, loader_1.isGoogleCloudForm)(source) ? '' : ` ${loader_1.THIRD_PARTY_SOURCE}`);
+}
+const ALLOWED_DIALECT_SET = new Set(ir_1.ALLOWED_DIALECTS);
+const DIALECT_ALIASES = {
+    GOOGLE_SQL: 'BIGQUERY',
+    GOOGLESQL: 'BIGQUERY',
+    POSTGRESQL: 'POSTGRES',
+    TSQL: 'SQLSERVER',
+};
+// Each kind of --source-prefix: its pattern, the child container a bare name
+// adds under it, if any, and the resource name of a table under it.
+const SOURCE_PREFIX_PATTERNS = [
+    {
+        re: /^bigquery\.googleapis\.com\/projects\/([^/]+)$/,
+        child: 'datasets',
+        form: loader_1.TABLE_FORMS.bigquery,
+    },
+    {
+        re: /^bigquery\.googleapis\.com\/projects\/([^/]+)\/datasets\/([^/.]+)$/,
+        form: loader_1.TABLE_FORMS.bigquery,
+    },
+    {
+        re: /^biglake\.googleapis\.com\/projects\/([^/]+)\/catalogs\/([^/.]+)$/,
+        child: 'namespaces',
+        form: loader_1.TABLE_FORMS.biglake,
+    },
+    {
+        re: /^biglake\.googleapis\.com\/projects\/([^/]+)\/catalogs\/([^/.]+)\/namespaces\/([^/.]+)$/,
+        form: loader_1.TABLE_FORMS.biglake,
+    },
+    {
+        re: /^spanner\.googleapis\.com\/projects\/([^/]+)\/instances\/([^/]+)\/databases\/([^/]+)$/,
+        form: loader_1.TABLE_FORMS.spanner,
+    },
+    {
+        re: /^alloydb\.googleapis\.com\/projects\/[^/]+\/locations\/[^/]+\/clusters\/[^/]+\/databases\/([^/]+)$/,
+        child: 'schemas',
+        form: loader_1.TABLE_FORMS.alloydb,
+    },
+    {
+        re: /^alloydb\.googleapis\.com\/projects\/[^/]+\/locations\/[^/]+\/clusters\/[^/]+\/databases\/([^/]+)\/schemas\/([^/]+)$/,
+        form: loader_1.TABLE_FORMS.alloydb,
+    },
+    {
+        re: /^cloudsql\.googleapis\.com\/projects\/[^/]+\/locations\/[^/]+\/instances\/[^/]+\/databases\/([^/]+)$/,
+        form: loader_1.TABLE_FORMS.cloudsql,
+    },
+    {
+        re: /^cloudsql\.googleapis\.com\/projects\/[^/]+\/locations\/[^/]+\/instances\/[^/]+\/databases\/([^/]+)\/schemas\/([^/]+)$/,
+        form: loader_1.TABLE_FORMS.cloudsqlSchema,
+    },
+];
+/** Filters an unknown array down to its plain-object elements. */
+function asRecords(v) {
+    return Array.isArray(v) ? v.filter(loader_1.isRecord) : [];
+}
+/**
+ * Returns true if any node in `doc` carries a `GOOGLE` `custom_extensions`
+ * block.
+ */
+function documentHasGoogleBlock(doc) {
+    for (const m of asRecords(doc.semantic_model)) {
+        const nodes = [
+            m,
+            ...asRecords(m.datasets),
+            ...asRecords(m.entities),
+            ...asRecords(m.relationships),
+            ...asRecords(m.metrics),
+            ...asRecords(m.datasets).flatMap(ds => asRecords(ds.fields)),
+            ...asRecords(m.entities).flatMap(ds => asRecords(ds.fields)),
+        ];
+        if (nodes.some(n => (0, loader_1.hasGoogleBlock)(asRecords(n.custom_extensions)))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Moves non-standard `ai_context` sibling keys into `ai_context.custom`. */
+function adaptAiContext(ai) {
+    const customKeys = Object.keys(ai).filter(k => !STANDARD_AI_CONTEXT_KEYS.has(k));
+    if (!customKeys.length)
+        return;
+    const custom = {};
+    for (const k of customKeys) {
+        custom[k] = ai[k];
+        delete ai[k];
+    }
+    ai.custom = custom;
+}
+/**
+ * Phase 1 (Parse): Parses raw YAML, verifies the top-level document envelope,
+ * validates `opts.sourcePrefix` when present, refuses a document with a
+ * `GOOGLE` block or a Google-flavor model to convert to vanilla unless
+ * `strict` is set, and constructs the mutable `ImportDocument` (or returns a
+ * fatal error string).
+ */
+function parseImportDocument(rawYaml, opts) {
+    // 1. Parse raw YAML with strict YAML 1.2 options (`YAML_OPTIONS`) so syntax
+    // errors and duplicate keys are caught immediately.
+    const { document, text } = (0, yaml_update_1.parseForUpdate)(rawYaml);
+    let parsedDoc;
+    try {
+        if (document.errors.length > 0)
+            throw document.errors[0];
+        parsedDoc = document.toJS();
+    }
+    catch (err) {
+        return `Semantic model load error: could not parse input: ${err?.message ?? err}`;
+    }
+    // 2. Verify the top-level document envelope (`version` is a recognized format
+    // version and `semantic_model[0]` is a model object). If malformed, delegate
+    // to `loadModels` so the caller receives the loader's canonical schema error.
+    if (!(0, loader_1.isRecord)(parsedDoc) || typeof parsedDoc.version !== 'string' ||
+        !(0, loader_1.isFormatVersion)(parsedDoc.version) ||
+        !Array.isArray(parsedDoc.semantic_model) ||
+        !(0, loader_1.isRecord)(parsedDoc.semantic_model[0])) {
+        try {
+            (0, loader_1.loadModels)(rawYaml, { bindingOptional: true, warnUnacceptedSource: true });
+        }
+        catch (err) {
+            return err?.message ?? String(err);
+        }
+    }
+    // 3. Validate `opts.sourcePrefix` against the 8 supported first-party GCP
+    // container resource name patterns before doing any document work.
+    let sourcePrefix;
+    if (opts.sourcePrefix !== undefined) {
+        const base = opts.sourcePrefix.trim();
+        const match = SOURCE_PREFIX_PATTERNS.map(p => ({ m: base.match(p.re), p }))
+            .find(x => x.m !== null);
+        if (!match?.m) {
+            return `Invalid sourcePrefix '${opts.sourcePrefix}'; expected the GCP ` +
+                `resource name of a BigQuery project or dataset, a BigLake ` +
+                `catalog or namespace, a Spanner database, an AlloyDB database ` +
+                `or schema, or a Cloud SQL database or schema (with no leading '//').`;
+        }
+        sourcePrefix = { base, known: match.m.slice(1), child: match.p.child };
+    }
+    // 4. Reject a document written for kcmd when `strict` is false: one with a
+    // `GOOGLE` block, or a Google-flavor model converting to vanilla.
+    const strict = !!opts.strict;
+    if (!strict && documentHasGoogleBlock(parsedDoc)) {
+        return `Document contains a '${loader_1.GOOGLE_VENDOR}' custom_extensions block ` +
+            `(written for kcmd); use '--input first-party' to convert a ` +
+            `first-party model.`;
+    }
+    if (!strict && opts.flavor === 'ossie' &&
+        parsedDoc.version === loader_1.GOOGLE_VERSION) {
+        return `Document is a '${loader_1.GOOGLE_VERSION}' model (written for kcmd); use ` +
+            `'--input first-party' to convert it to '${loader_1.OSSIE_VERSION}'.`;
+    }
+    // 5. Deep-copy `parsedDoc` via `plainCopy` to decouple shared YAML anchor /
+    // alias references before in-place mutations, and assemble `ImportDocument`.
+    const root = (0, resolve_profiles_1.plainCopy)(parsedDoc);
+    const model = root.semantic_model[0];
+    const inputVersion = root.version;
+    const targetVersion = opts.flavor ?
+        (opts.flavor === 'google' ? loader_1.GOOGLE_VERSION : loader_1.OSSIE_VERSION) :
+        inputVersion;
+    // A model file is YAML, so a JSON file is written as YAML.
+    const fileName = opts.fileName ?? `${model.name}.yaml`;
+    const warnings = text === rawYaml ? [] : [`Converted '${fileName}' to YAML.`];
+    const errors = [];
+    return {
+        text,
+        document,
+        links: (0, yaml_update_1.linkNodes)(root, document.contents),
+        root,
+        model,
+        datasets: asRecords(model.entities ?? model.datasets),
+        relationships: asRecords(model.relationships),
+        metrics: asRecords(model.metrics),
+        inputVersion,
+        targetVersion,
+        sourcePrefix,
+        strict,
+        modified: false,
+        warnings,
+        errors,
+        warnOrError: (msg) => (strict ? errors : warnings).push(msg),
+    };
+}
+/**
+ * Extracts the profile name from a `<model>.profile.<name>.yaml` filename (or
+ * bare `<name>.yaml` / `<name>` identifier).
+ */
+function parseProfileName(fileName) {
+    const stem = fileName.replace(/^.*[/\\]/, '').replace(/\.ya?ml$/i, '');
+    const match = stem.match(/^.+?\.profile(?:\.(.*))?$/i);
+    return match ? (match[1] ?? '') : stem;
+}
+/**
+ * Extracts and parses all valid JSON object payloads from `GOOGLE`
+ * `custom_extensions` blocks on `exts`, leaving malformed JSON to be reported
+ * by `fromDocument`.
+ */
+function parseGoogleBlocks(exts) {
+    const blocks = [];
+    for (const b of asRecords(exts)) {
+        if (!(0, loader_1.isGoogleVendor)(b.vendor_name) || typeof b.data !== 'string')
+            continue;
+        try {
+            const parsed = JSON.parse(b.data);
+            if ((0, loader_1.isRecord)(parsed))
+                blocks.push(parsed);
+        }
+        catch {
+            // Leave malformed JSON to be reported by `fromDocument`.
+        }
+    }
+    return blocks;
+}
+/**
+ * Validates all model, deployment, profile, entity/dataset, field,
+ * relationship, and metric names in `doc` (plus any `googleBlocks` and
+ * `profileFiles`) in a single pass so every invalid or over-length identifier
+ * is reported at once.
+ */
+function validateObjectNames(doc, googleBlocks, modelScope, profileFiles) {
+    // Validates a single identifier `name` against `kind`'s rules via
+    // `nameProblem` and appends any error to `doc.errors`.
+    const validateName = (kind, name, scope) => {
+        if (typeof name !== 'string')
+            return;
+        const problem = (0, names_1.nameProblem)(kind, name);
+        if (problem)
+            doc.errors.push(scope ? `${scope}: ${problem}` : problem);
+    };
+    // Validates the `name` property of every record in `records`.
+    const validateRecords = (kind, records, scope) => {
+        for (const record of records)
+            validateName(kind, record.name, scope);
+    };
+    // 1. Validate model, deployment, and profile names (inline, `GOOGLE` block,
+    // and sibling `profileFiles`).
+    validateName('model', doc.model.name);
+    validateRecords('deployment', asRecords(doc.model.deployments), modelScope);
+    validateRecords('profile', asRecords(doc.model.profiles), modelScope);
+    for (const g of googleBlocks) {
+        validateRecords('deployment', asRecords(g.deployments), modelScope);
+        validateRecords('profile', asRecords(g.profiles), modelScope);
+    }
+    if (doc.targetVersion === loader_1.OSSIE_VERSION) {
+        for (const pf of profileFiles ?? []) {
+            validateName('profile', parseProfileName(pf.fileName), modelScope);
+        }
+    }
+    // 2. Validate dataset/entity, field, relationship, and metric names.
+    for (const ds of doc.datasets) {
+        validateName('entity', ds.name);
+        const dsScope = typeof ds.name === 'string' ? `dataset '${ds.name}'` : 'dataset';
+        validateRecords('field', asRecords(ds.fields), dsScope);
+    }
+    validateRecords('relationship', doc.relationships);
+    validateRecords('metric', doc.metrics);
+}
+/**
+ * Phase 2 (Pre-validation): Validates all identifier names in the input
+ * document and any attached `profileFiles`. The loader rejects a model's
+ * legacy `deploymentTargets`.
+ */
+function validateInputDocument(doc, profileFiles) {
+    const modelScope = typeof doc.model.name === 'string' ?
+        `model '${doc.model.name}'` :
+        'model';
+    const googleBlocks = parseGoogleBlocks(doc.model.custom_extensions);
+    validateObjectNames(doc, googleBlocks, modelScope, profileFiles);
+}
+/**
+ * The parts of a bare dot-separated table name `source` as `prefix` reads
+ * them, each unquoted and marked when it was quoted, or `undefined` when
+ * `source` is not a bare name.
+ */
+function sourceParts(source, prefix) {
+    // Reject empty strings, already-slashed or colon-prefixed sources, and
+    // query-valued sources with unquoted whitespace.
+    const trimmed = source.trim();
+    if (!trimmed || trimmed.includes('/') || trimmed.includes(':') ||
+        (0, loader_1.hasUnquotedWhitespace)(trimmed)) {
+        return undefined;
+    }
+    const segs = prefixParts(trimmed, prefix.base);
+    return segs.length && segs.every(s => s.text.length) ? segs : undefined;
+}
+/**
+ * `text` with its ASCII letters in lower case. PostgreSQL folds only these in a
+ * UTF-8 database.
+ */
+function lowerAscii(text) {
+    return text.replace(/[A-Z]/g, c => c.toLowerCase());
+}
+/**
+ * True when a prefix that starts with `base` names a database that reads
+ * unquoted names in lower case.
+ */
+function foldsUnquotedCase(base) {
+    return base.startsWith('alloydb.googleapis.com/');
+}
+/** `part` as the database of a prefix that starts with `base` reads it. */
+function readPart(base, part) {
+    return foldsUnquotedCase(base) && !part.quoted ? lowerAscii(part.text) :
+        part.text;
+}
+/**
+ * The first unquoted part of `source` that PostgreSQL reads in lower case and
+ * so misses the name with capitals that `prefix` gives it, with the part's
+ * kind and both names. Expects a `source` that matches `prefix` when letter
+ * case is ignored.
+ */
+function foldedPart(source, prefix) {
+    const segs = sourceParts(source, prefix);
+    if (!segs || !foldsUnquotedCase(prefix.base))
+        return undefined;
+    const start = prefix.known.length - segs.length + (prefix.child ? 2 : 1);
+    for (let i = start; i < prefix.known.length; i++) {
+        const s = segs[i - start];
+        const read = lowerAscii(s.text);
+        // An AlloyDB prefix names a database, then perhaps a schema.
+        if (!s.quoted && read !== prefix.known[i]) {
+            return { kind: i ? 'schema' : 'database', name: prefix.known[i], read };
+        }
+    }
+    return undefined;
+}
+/**
+ * Qualifies a bare dot-separated table name `source` against `prefix` into a
+ * GCP resource name when `prefix` supplies the missing hierarchy segments and
+ * any overlapping segments agree, or returns `undefined` if `source` cannot be
+ * qualified. Against an AlloyDB prefix, an unquoted segment is read in lower
+ * case, as PostgreSQL reads it. With `ignoreCase`, every segment agrees in any
+ * letter case.
+ */
+function qualifyTableSource(source, prefix, ignoreCase = false) {
+    // Verify that any leading segments overlapping `prefix.known` match.
+    const segs = sourceParts(source, prefix);
+    if (!segs)
+        return undefined;
+    const needed = prefix.child ? 2 : 1;
+    const overlap = segs.length - needed;
+    if (overlap < 0 || overlap > prefix.known.length)
+        return undefined;
+    const read = (s) => readPart(prefix.base, s);
+    const agrees = (s, k) => read(s) === k || (ignoreCase && lowerAscii(s.text) === lowerAscii(k));
+    const tail = prefix.known.slice(prefix.known.length - overlap);
+    if (tail.some((k, i) => !agrees(segs[i], k)))
+        return undefined;
+    // Append the remaining child container (if any) and table segment onto
+    // `prefix.base` and verify the resulting resource name is accepted.
+    const rest = segs.slice(overlap).map(read);
+    const qualified = prefix.child ?
+        `${prefix.base}/${prefix.child}/${rest[0]}/tables/${rest[1]}` :
+        `${prefix.base}/tables/${rest[0]}`;
+    return (0, loader_1.oldSourceForm)(qualified) === undefined && (0, loader_1.isAcceptedSource)(qualified) ?
+        qualified :
+        undefined;
+}
+// The parts of the bare name `source` as a prefix that begins as `base` does
+// reads them, each with whether quotes wrap it. A BigQuery or BigLake prefix
+// reads a path in one pair of backticks, such as `` `p.d.t` ``, as its parts.
+function prefixParts(source, base) {
+    return (0, loader_1.bareNameParts)(source.trim(), /^(bigquery|biglake)\.googleapis\.com\//.test(base));
+}
+// The text of each part prefixParts gives.
+function prefixSegments(source, base) {
+    return prefixParts(source, base).map(p => p.text);
+}
+// The prefix of `kind` whose containers are the leading parts of a bare name
+// with parts `parts`, or undefined when `kind` has no such prefix.
+function prefixFor(kind, parts) {
+    const base = (0, loader_1.fillForm)(kind.form, parts)?.split('/').slice(0, kind.child ? -4 : -2)
+        .join('/');
+    const known = base?.match(kind.re)?.slice(1);
+    return base && known ? { base, known, child: kind.child } : undefined;
+}
+// True when a --source-prefix of one of `kinds` completes `source`. Each
+// prefix tried is built from the parts as that kind reads them.
+function completes(source, kinds) {
+    return kinds.some(kind => {
+        const parts = prefixParts(source, kind.form).map(p => readPart(kind.form, p));
+        const prefix = prefixFor(kind, parts);
+        return prefix !== undefined &&
+            qualifyTableSource(source, prefix) !== undefined;
+    });
+}
+/**
+ * When the output's flavor rejects `obj.datatype`, writes it in its canonical
+ * casing, such as `Integer` for `integer`, or deletes an `Opaque` in another
+ * casing. The change goes through `warnOrError` when the input's flavor
+ * rejects the value too.
+ */
+function normalizeDatatype(obj, label, doc) {
+    if (typeof obj.datatype !== 'string' ||
+        (0, ir_1.normalizeDataType)(obj.datatype, doc.targetVersion).ok) {
+        return;
+    }
+    const res = (0, ir_1.normalizeDataType)(obj.datatype, loader_1.GOOGLE_VERSION);
+    if (!res.ok)
+        return;
+    if (!(0, ir_1.normalizeDataType)(obj.datatype, doc.inputVersion).ok) {
+        doc.warnOrError(res.type === undefined ?
+            `${label}: removed datatype '${obj.datatype}'.` :
+            `${label}: rewrote datatype '${obj.datatype}' to '${res.type}'.`);
+    }
+    if (res.type === undefined) {
+        delete obj.datatype;
+    }
+    else {
+        obj.datatype = res.type;
+    }
+    doc.modified = true;
+}
+/**
+ * Maps dialect aliases onto the 9 allowed SQL dialects and drops unsupported
+ * non-SQL dialects on a field or metric, returning `'empty'` if all dialect
+ * entries were dropped.
+ */
+function normalizeExpressionDialects(obj, label, doc) {
+    if (!(0, loader_1.isRecord)(obj.expression) || !Array.isArray(obj.expression.dialects) ||
+        obj.expression.dialects.length === 0) {
+        return 'ok';
+    }
+    const kept = [];
+    for (const entry of obj.expression.dialects) {
+        if (!(0, loader_1.isRecord)(entry) || typeof entry.dialect !== 'string') {
+            kept.push(entry);
+            continue;
+        }
+        const upper = entry.dialect.trim().toUpperCase();
+        const mapped = DIALECT_ALIASES[upper] ??
+            (ALLOWED_DIALECT_SET.has(upper) ? upper : undefined);
+        if (mapped !== undefined) {
+            if (entry.dialect !== mapped) {
+                doc.warnOrError(`${label}: rewrote dialect '${entry.dialect}' to '${mapped}'.`);
+                entry.dialect = mapped;
+                doc.modified = true;
+            }
+            kept.push(entry);
+        }
+        else {
+            doc.warnOrError(`${label}: dropped unsupported dialect '${entry.dialect}'.`);
+            doc.modified = true;
+        }
+    }
+    obj.expression.dialects = kept;
+    return kept.length === 0 ? 'empty' : 'ok';
+}
+/**
+ * Returns why an unanchored metric `mt` is rejected by push's
+ * `validateExpressionReferences` (`'reaches no declared entity'` or
+ * `'reaches multiple entities (...)'`), or `undefined` when anchored or valid.
+ */
+function unanchoredMetricProblem(mt, entityNames, impliedDialect) {
+    // 1. Skip metrics that already declare an `entity` anchor natively or inside
+    // a `GOOGLE` `custom_extensions` block.
+    if (mt.entity !== undefined ||
+        (0, loader_1.hasGoogleBlock)(asRecords(mt.custom_extensions))) {
+        return undefined;
+    }
+    // 2. Collect all SQL dialect expressions on the metric; if none are present
+    // or any entry holds no SQL, leave the metric for `loadModels` to diagnose.
+    const sources = typeof mt.expression === 'string' ?
+        [{ text: mt.expression, dialect: 'ANSI_SQL' }] :
+        asRecords(mt.expression?.dialects)
+            .filter(d => typeof d.dialect === 'string' &&
+            typeof d.expression === 'string')
+            .map(d => ({ text: d.expression, dialect: d.dialect }));
+    if (!sources.length ||
+        sources.some(s => (0, loader_1.noSqlReason)(s.text, s.dialect) !== undefined)) {
+        return undefined;
+    }
+    const parsed = sources.map(s => (0, sql_expr_utils_1.columnsForSource)(s.text, s.dialect, impliedDialect));
+    const allColumns = parsed.flatMap(c => c ?? []);
+    // 3. Flag the unanchored metric if its parsed expressions reference zero
+    // columns (e.g. `COUNT(*)`) or span multiple declared entities.
+    const reached = (0, sql_expr_utils_1.entitiesReached)(allColumns, entityNames);
+    if (parsed.every(c => c !== undefined) && allColumns.length === 0) {
+        return 'reaches no declared entity';
+    }
+    if (reached.length > 1) {
+        return `reaches multiple entities (${reached.join(', ')})`;
+    }
+    return undefined;
+}
+/**
+ * Truncates `obj.description`, without its surrounding whitespace, to at most
+ * `MAX_ENTRY_DESCRIPTION` characters when it exceeds the limit, and records a
+ * warning (or error in `strict` mode).
+ */
+function truncateDescription(obj, label, doc) {
+    // Push counts the description without its surrounding whitespace.
+    const text = typeof obj.description === 'string' ? obj.description.trim() : '';
+    if (text.length > names_1.MAX_ENTRY_DESCRIPTION) {
+        // The cut never ends on the first half of a surrogate pair.
+        const cut = text.slice(0, names_1.MAX_ENTRY_DESCRIPTION).replace(/[\uD800-\uDBFF]$/, '');
+        doc.warnOrError(`${label}: truncated 'description' from ${text.length} ` +
+            `to ${cut.length} characters.`);
+        obj.description = cut;
+        doc.modified = true;
+    }
+}
+/**
+ * Normalizes a field's datatype and SQL dialect list, removing `f.expression`
+ * with a warning in the Google version (or recording an error in the vanilla
+ * version) if no supported SQL dialect remains.
+ */
+function repairField(f, dsName, doc) {
+    const fLabel = `field '${dsName}.${f.name}'`;
+    normalizeDatatype(f, fLabel, doc);
+    if (normalizeExpressionDialects(f, fLabel, doc) === 'empty') {
+        if (doc.targetVersion === loader_1.OSSIE_VERSION) {
+            doc.errors.push(`${fLabel}: no supported SQL dialect remains in 'expression', ` +
+                `and version '${loader_1.OSSIE_VERSION}' requires an 'expression' on ` +
+                `every field.`);
+        }
+        else {
+            delete f.expression;
+            doc.modified = true;
+            doc.warnOrError(`${fLabel}: no supported SQL dialect remains; removed ` +
+                `'expression' and left the field unbound.`);
+        }
+    }
+}
+/**
+ * Repairs a dataset's `source` (removing query-valued sources, qualifying bare
+ * table names against `doc.sourcePrefix`, and warning on unaccepted sources),
+ * truncates its `description`, and repairs each of its `fields`.
+ */
+function repairDataset(ds, doc) {
+    // 1. Repair or diagnose `ds.source`: remove query-valued sources (in the
+    // Google version), qualify bare table names against `doc.sourcePrefix`, or
+    // warn on unaccepted source formats.
+    const dsLabel = `dataset '${ds.name}'`;
+    if (typeof ds.source === 'string') {
+        const trimmed = ds.source.trim();
+        const qualified = doc.sourcePrefix ?
+            qualifyTableSource(trimmed, doc.sourcePrefix) :
+            undefined;
+        if ((0, loader_1.hasUnquotedWhitespace)(trimmed)) {
+            if (doc.targetVersion === loader_1.OSSIE_VERSION) {
+                doc.errors.push(`${dsLabel}: query-valued source '${trimmed}' is not supported, ` +
+                    `and version '${loader_1.OSSIE_VERSION}' requires a table 'source' on ` +
+                    `every dataset.`);
+            }
+            else {
+                doc.warnOrError(`${dsLabel}: removed query-valued source '${trimmed}'; ` +
+                    `dataset is now unbound.`);
+                delete ds.source;
+                doc.modified = true;
+            }
+        }
+        else if (qualified !== undefined) {
+            // The author asked for this rewrite with --source-prefix, so it is a
+            // warning in strict mode too.
+            doc.warnings.push(`${dsLabel}: rewrote bare source '${trimmed}' to '${qualified}'.`);
+            ds.source = qualified;
+            doc.modified = true;
+        }
+        else if (!((0, loader_1.oldSourceForm)(trimmed) === undefined &&
+            (0, loader_1.isAcceptedSource)(trimmed))) {
+            // Why a prefix that nearly fits the name cannot complete it.
+            const p = doc.sourcePrefix;
+            const caseOnly = !!p && qualifyTableSource(trimmed, p, true) !== undefined;
+            const folded = p && caseOnly ? foldedPart(trimmed, p) : undefined;
+            let why;
+            if (folded) {
+                const { kind, name, read } = folded;
+                why = `names ${kind} '${read}', since PostgreSQL reads an unquoted ` +
+                    `name in lower case. '--source-prefix' names ${kind} '${name}', ` +
+                    `so import cannot complete the source. If the ${kind} is ` +
+                    `'${name}', write it as '"${name}"' in the source; if it is ` +
+                    `'${read}', write '${read}' in '--source-prefix'.`;
+            }
+            else if (caseOnly) {
+                why = `differs from '--source-prefix' only in letter case, so ` +
+                    `import cannot complete it; correct the letter case of the ` +
+                    `source or of '--source-prefix'.`;
+            }
+            else if (p?.child && sourceParts(trimmed, p)?.length === 1 &&
+                completes(trimmed, prefixKinds(p))) {
+                // The container it lacks: a dataset, namespace or schema.
+                const lacks = p.child.slice(0, -1);
+                why = `names no ${lacks}, and neither does '--source-prefix', so ` +
+                    `import cannot complete it; add the ${lacks} to the source or to ` +
+                    `'--source-prefix'.`;
+            }
+            doc.warnOrError(why ? `${dsLabel}: source '${trimmed}' ${why}` :
+                sourceWarning(dsLabel, trimmed, doc.sourcePrefix));
+        }
+    }
+    // 2. Cap the dataset's `description` at 2,000 characters and repair each of
+    // its `fields`.
+    truncateDescription(ds, dsLabel, doc);
+    for (const f of asRecords(ds.fields)) {
+        repairField(f, String(ds.name ?? ''), doc);
+    }
+}
+/**
+ * Repairs a metric's datatype, SQL dialect list, and description, returning
+ * `false` when the metric is unanchored and reaches 0 or >1 entities so the
+ * caller prunes it from `doc.metrics`.
+ */
+function repairMetric(mt, entityNames, impliedDialect, doc) {
+    const mtLabel = `metric '${mt.name}'`;
+    normalizeDatatype(mt, mtLabel, doc);
+    if (normalizeExpressionDialects(mt, mtLabel, doc) === 'empty') {
+        doc.errors.push(`${mtLabel}: no supported SQL dialect remains in 'expression'.`);
+        return true;
+    }
+    const problem = unanchoredMetricProblem(mt, entityNames, impliedDialect);
+    if (problem) {
+        // In strict mode nothing is written, so the author edits the input.
+        const flavor = doc.strict ? doc.inputVersion : doc.targetVersion;
+        const how = flavor === loader_1.OSSIE_VERSION ?
+            `with 'entity' in a ${loader_1.GOOGLE_VENDOR} custom_extensions block on the ` +
+                `metric (or use version '${loader_1.GOOGLE_VERSION}' and set 'entity' on ` +
+                `the metric)` :
+            `with an 'entity' anchor`;
+        doc.warnOrError(`${mtLabel}: removed unanchored metric whose expression ` +
+            `${problem}; add the metric back ${how}.`);
+        doc.modified = true;
+        return false;
+    }
+    truncateDescription(mt, mtLabel, doc);
+    return true;
+}
+/**
+ * Phase 3 (Repair): Repairs third-party constructs in-place on `doc` (pruning
+ * extra models, repairing datasets and their fields, pruning unanchored
+ * metrics, and truncating descriptions > 2,000 chars).
+ */
+function repairDocument(doc) {
+    // 1. Prune extra models after `semantic_model[0]` because `kcmd` allows only
+    // a single model per document, and cap the model's `description` at 2,000
+    // characters (`MAX_ENTRY_DESCRIPTION`).
+    if (doc.root.semantic_model.length > 1) {
+        for (const extra of doc.root.semantic_model.slice(1)) {
+            const name = (0, loader_1.isRecord)(extra) && typeof extra.name === 'string' ? extra.name : '';
+            doc.warnOrError(`Removed extra model${name ? ` '${name}'` : ''} from ` +
+                `'semantic_model'; the format allows one model per document.`);
+        }
+        doc.root.semantic_model = [doc.root.semantic_model[0]];
+        doc.modified = true;
+    }
+    truncateDescription(doc.model, `model '${doc.model.name}'`, doc);
+    // 2. Repair each dataset (its table `source`, `description`, and `fields`).
+    for (const ds of doc.datasets) {
+        repairDataset(ds, doc);
+    }
+    // 3. Infer the model's source dialect from its repaired datasets via
+    // `sourcesDialect`, and repair or prune each metric (`repairMetric`).
+    const entityNames = doc.datasets.map(ds => ds.name)
+        .filter((n) => typeof n === 'string');
+    const impliedDialect = (0, resolve_profiles_1.sourcesDialect)({
+        entities: doc.datasets.map(ds => ({
+            abstract: Boolean(ds.abstract),
+            authoredSource: typeof ds.source === 'string' ? ds.source : undefined,
+            dataSource: '',
+        })),
+    });
+    doc.metrics = doc.metrics.filter(mt => repairMetric(mt, entityNames, impliedDialect, doc));
+    if (Array.isArray(doc.model.metrics) && doc.model.metrics.length) {
+        doc.model.metrics = doc.metrics.length ? doc.metrics : undefined;
+    }
+    // 4. Cap each relationship's `description`. A `GOOGLE` block comes only in
+    // strict mode, which writes nothing, so its description is only reported.
+    for (const r of doc.relationships) {
+        const rLabel = `relationship '${r.name}'`;
+        truncateDescription(r, rLabel, doc);
+        for (const b of parseGoogleBlocks(r.custom_extensions)) {
+            truncateDescription(b, rLabel, doc);
+        }
+    }
+}
+/**
+ * Sets `version` to `doc.targetVersion`, and names the model's entity list as
+ * that flavor does: `entities:` in the Google flavor, `datasets:` in vanilla.
+ * The renamed key keeps its place among the model's keys.
+ */
+function setTargetVersion(doc) {
+    const [from, to] = doc.targetVersion === loader_1.GOOGLE_VERSION ?
+        ['datasets', 'entities'] :
+        ['entities', 'datasets'];
+    doc.root.version = doc.targetVersion;
+    doc.modified = true;
+    if (doc.model[from] !== undefined && doc.model[to] === undefined) {
+        const entries = Object.entries(doc.model);
+        for (const k of Object.keys(doc.model))
+            delete doc.model[k];
+        for (const [k, v] of entries)
+            doc.model[k === from ? to : k] = v;
+    }
+}
+/**
+ * Converts a plain vanilla (`0.2.0.dev0`) document to the Google version
+ * (`0.2.0.dev0/google`) by updating `version`, renaming `datasets:` to
+ * `entities:`, and moving custom `ai_context` sibling properties under
+ * `ai_context.custom`.
+ */
+function adaptToGoogleVersion(doc) {
+    setTargetVersion(doc);
+    // Move any non-standard sibling keys on `ai_context` objects (at model,
+    // entity, field, relationship, or metric scope) under `ai_context.custom`,
+    // since `0.2.0.dev0/google` uses strict schema validation on `ai_context`.
+    for (const { ai } of (0, loader_1.modelAiContexts)(doc.root)) {
+        adaptAiContext(ai);
+    }
+}
+/**
+ * Adapts `doc` to the vanilla (`0.2.0.dev0`) version: converts a Google file's
+ * version, entity list and custom `ai_context` members, wraps short-form
+ * string expressions into a single-entry `ANSI_SQL` dialect list, and moves
+ * plain relationship `description`s into a `GOOGLE` `custom_extensions` block.
+ * The vanilla flavor rejects the last two forms, so in a vanilla file each of
+ * those changes is a repair and goes through `warnOrError`.
+ */
+function adaptToOssieVersion(doc) {
+    // 0. A Google file takes the vanilla version and entity list, and each
+    // member of an `ai_context`'s `custom` mapping goes beside the standard
+    // members, where `custom` was. An `ai_context` that held only an empty
+    // `custom` is dropped.
+    if (doc.inputVersion === loader_1.GOOGLE_VERSION) {
+        setTargetVersion(doc);
+        for (const owner of [
+            doc.model, ...doc.datasets,
+            ...doc.datasets.flatMap(ds => asRecords(ds.fields)),
+            ...doc.relationships, ...doc.metrics
+        ]) {
+            const ai = owner.ai_context;
+            if (!(0, loader_1.isRecord)(ai) || !(0, loader_1.isRecord)(ai.custom))
+                continue;
+            const entries = Object.entries(ai);
+            for (const k of Object.keys(ai))
+                delete ai[k];
+            for (const [k, v] of entries) {
+                Object.assign(ai, k === 'custom' ? v : { [k]: v });
+            }
+            if (Object.keys(ai).length === 0)
+                delete owner.ai_context;
+        }
+    }
+    // 1. Wrap any short-form string `expression: "<sql>"` on a field or metric
+    // into `{dialects: [{dialect: 'ANSI_SQL', expression: "<sql>"}]}`, since
+    // `0.2.0.dev0` requires the `expression.dialects` object form.
+    const wrapShortForm = (obj, label) => {
+        if (typeof obj.expression !== 'string')
+            return;
+        obj.expression = {
+            dialects: [{ dialect: 'ANSI_SQL', expression: obj.expression }],
+        };
+        doc.modified = true;
+        if (doc.inputVersion === loader_1.OSSIE_VERSION) {
+            doc.warnOrError(`${label}: wrote the string expression as an 'ANSI_SQL' ` +
+                `dialects entry.`);
+        }
+    };
+    for (const ds of doc.datasets) {
+        for (const f of asRecords(ds.fields)) {
+            wrapShortForm(f, `field '${ds.name}.${f.name}'`);
+        }
+    }
+    for (const mt of doc.metrics)
+        wrapShortForm(mt, `metric '${mt.name}'`);
+    // 2. Relocate any top-level `description` on a relationship into a `GOOGLE`
+    // `custom_extensions` block. The vanilla `0.2.0.dev0` schema does not allow
+    // `description` directly on a relationship, but `kcmd` reads and preserves
+    // relationship descriptions from a `{vendor_name: 'GOOGLE', data: ...}`
+    // extension entry (`FORMAT_VERSION_PLACEMENT['0.2.0.dev0'].relationship`).
+    // A conversion from Google has moved them already (`moveConstructs`).
+    for (const r of doc.relationships) {
+        if (typeof r.description !== 'string')
+            continue;
+        putGoogleBlock(r, { description: r.description });
+        delete r.description;
+        doc.modified = true;
+        doc.warnOrError(`relationship '${r.name}': moved 'description' into a ` +
+            `${loader_1.GOOGLE_VENDOR} custom_extensions block for '${loader_1.OSSIE_VERSION}'.`);
+    }
+}
+// Where the Google flavor writes a key that a GOOGLE block carries in vanilla:
+// right after the last of these keys the object has, as `kcmd pull` does.
+const NATIVE_KEY_AFTER = {
+    deployments: ['name', 'description', 'ai_context'],
+    extends: ['name', 'source'],
+    description: ['name', 'from', 'to', 'from_columns', 'to_columns'],
+    entity: ['name'],
+};
+/**
+ * Sets `obj[key]` to `value` right after the last of `after` that `obj` has,
+ * or first. `obj` stays the same object, so the writer keeps its text.
+ */
+function setAfter(obj, after, key, value) {
+    const entries = Object.entries(obj);
+    const at = Math.max(-1, ...after.map(a => entries.findIndex(([k]) => k === a)));
+    entries.splice(at + 1, 0, [key, value]);
+    for (const k of Object.keys(obj))
+        delete obj[k];
+    for (const [k, v] of entries)
+        obj[k] = v;
+}
+/**
+ * Removes the `GOOGLE` blocks from `obj.custom_extensions`, and the list when
+ * no block is left in it, and returns the values the blocks carry.
+ */
+function takeGoogleBlocks(obj) {
+    const values = Object.assign({}, ...parseGoogleBlocks(obj.custom_extensions));
+    if (!(0, loader_1.hasGoogleBlock)(asRecords(obj.custom_extensions)))
+        return values;
+    const kept = obj.custom_extensions.filter((b) => !(0, loader_1.isRecord)(b) || !(0, loader_1.isGoogleVendor)(b.vendor_name));
+    if (kept.length) {
+        obj.custom_extensions = kept;
+    }
+    else {
+        delete obj.custom_extensions;
+    }
+    return values;
+}
+/** True for an empty string, list or mapping. */
+function isEmpty(value) {
+    return value === '' ||
+        (((0, loader_1.isRecord)(value) || Array.isArray(value)) &&
+            Object.keys(value).length === 0);
+}
+/** Appends a `GOOGLE` block that carries `values` to `obj.custom_extensions`. */
+function putGoogleBlock(obj, values) {
+    if (Object.keys(values).length === 0)
+        return;
+    obj.custom_extensions = [
+        ...(Array.isArray(obj.custom_extensions) ? obj.custom_extensions : []),
+        { vendor_name: loader_1.GOOGLE_VENDOR, data: JSON.stringify(values) },
+    ];
+}
+/**
+ * Moves each construct that `doc`'s flavor and its target flavor place
+ * differently (`FORMAT_VERSION_PLACEMENT`) between a native key, a `GOOGLE`
+ * block and the profile files. A key the target flavor has no place for is
+ * dropped, and so is an empty value bound for a `GOOGLE` block. Returns the
+ * profile files the Google flavor writes.
+ */
+function moveConstructs(doc, profileFiles) {
+    const levels = {
+        model: [doc.model],
+        dataset: doc.datasets,
+        relationship: doc.relationships,
+        metric: doc.metrics,
+    };
+    let files = [];
+    for (const [level, objects] of Object.entries(levels)) {
+        const placement = (version) => loader_1.FORMAT_VERSION_PLACEMENT[version][level];
+        const was = placement(doc.inputVersion);
+        for (const obj of objects) {
+            const block = takeGoogleBlocks(obj);
+            const moved = {};
+            for (const [key, place] of Object.entries(placement(doc.targetVersion))) {
+                // A key the input's flavor has no place for stays as written.
+                if (was[key] === place || was[key] === 'none')
+                    continue;
+                const value = was[key] === 'block' ? block[key] :
+                    was[key] === 'file' ?
+                        profileFiles.map(pf => yaml.parse(pf.content, yaml_options_1.YAML_OPTIONS)) :
+                        obj[key];
+                // A third-party file can write natively a key its flavor keeps in a
+                // GOOGLE block. That key stays as written.
+                if (was[key] === 'native')
+                    delete obj[key];
+                if (value === undefined)
+                    continue;
+                if (place === 'native') {
+                    setAfter(obj, NATIVE_KEY_AFTER[key], key, value);
+                }
+                else if (place === 'file') {
+                    files = asRecords(value).map(p => ({
+                        fileName: `${doc.model.name}.profile.${p.name}.yaml`,
+                        content: yaml.stringify(p, {
+                            aliasDuplicateObjects: false,
+                            compat: 'yaml-1.1',
+                            lineWidth: 0,
+                        }),
+                    }));
+                }
+                else if (place === 'block' && !isEmpty(value)) {
+                    moved[key] = value;
+                }
+            }
+            putGoogleBlock(obj, moved);
+        }
+    }
+    return files;
+}
+/**
+ * Loads `doc.root` into the `SemanticModel` IR, runs `transpileModel` to
+ * translate vendor or double-quoted `ANSI_SQL` expressions to `BIGQUERY`, and
+ * writes any newly added `BIGQUERY` dialect entries back onto `doc`.
+ */
+async function transpileDocument(doc) {
+    let preLoaded;
+    try {
+        preLoaded = (0, loader_1.fromDocument)(doc.root, { bindingOptional: true, warnUnacceptedSource: true });
+    }
+    catch (err) {
+        if (!(err instanceof loader_1.SemanticModelError))
+            throw err;
+        return;
+    }
+    // Writes `irDialects` back onto `rawNode.expression` when `transpileModel`
+    // appended a new dialect entry (e.g. `BIGQUERY`).
+    const syncNode = (rawNode, irDialects) => {
+        const prevCount = typeof rawNode.expression === 'string' ?
+            1 :
+            asRecords(rawNode.expression?.dialects).length;
+        if (prevCount > 0 && irDialects && irDialects.length > prevCount) {
+            rawNode.expression = {
+                dialects: irDialects.map(d => ({ dialect: d.dialect, expression: d.expression })),
+            };
+            doc.modified = true;
+        }
+    };
+    for (const m of preLoaded.models) {
+        const transpiled = await (0, transpile_1.transpileModel)(m);
+        doc.warnings.push(...transpiled.warnings);
+        for (const ds of doc.datasets) {
+            const irEntity = transpiled.model.entities.find(e => e.name === ds.name);
+            for (const f of asRecords(ds.fields)) {
+                syncNode(f, irEntity?.fields.find(x => x.name === f.name)?.dialects);
+            }
+        }
+        for (const mt of doc.metrics) {
+            syncNode(mt, transpiled.model.metrics.find(x => x.name === mt.name)?.dialects);
+        }
+    }
+}
+/**
+ * Validates every deployment target on `model` using `googleDeploymentTargets`
+ * and `targetProblem` so invalid targets fail import with `kcmd push`'s exact
+ * message.
+ */
+function validateDeploymentTargets(model, doc) {
+    for (const t of (0, deployment_target_1.googleDeploymentTargets)(model).uris) {
+        if ((0, deployment_target_1.targetProblem)('', t)) {
+            const d = model.deployments?.find(x => x.target === t);
+            doc.errors.push(d ? (0, deployment_target_1.deploymentTargetError)(model, d) :
+                (0, deployment_target_1.googleBlockTargetError)(model, t));
+        }
+    }
+}
+/**
+ * Loads each sibling `<model>.profile.<name>.yaml` entry in `profileFiles` via
+ * `loadProfileFile` and attaches the resulting `ProfileSpec` list to
+ * `model.profiles`, recording any reserved or duplicate profile name or
+ * profile load error in `doc.errors`.
+ */
+function attachProfileFiles(model, profileFiles, doc) {
+    if (!profileFiles?.length)
+        return;
+    const profiles = [];
+    const seen = new Set();
+    for (const pf of profileFiles) {
+        const profileName = parseProfileName(pf.fileName);
+        if ((0, names_1.nameProblem)('profile', profileName))
+            continue;
+        const lower = profileName.toLowerCase();
+        if (lower === resolve_profiles_1.DEFAULT_PROFILE) {
+            doc.errors.push(`model '${model.name}': a profile may not be named ` +
+                `'${profileName}'; '${resolve_profiles_1.DEFAULT_PROFILE}' names the model's inline ` +
+                `bindings.`);
+            continue;
+        }
+        if (seen.has(lower)) {
+            doc.errors.push(`model '${model.name}': duplicate profile name '${profileName}'; ` +
+                `profile names must be unique ignoring case.`);
+            continue;
+        }
+        seen.add(lower);
+        try {
+            profiles.push((0, resolve_profiles_1.loadProfileFile)(pf.content, profileName));
+        }
+        catch (err) {
+            if (!(err instanceof loader_1.SemanticModelError))
+                throw err;
+            doc.errors.push(err.message);
+        }
+    }
+    if (profiles.length > 0) {
+        model.profiles = profiles;
+    }
+}
+/**
+ * Verifies that `model` can be converted to the vanilla (`0.2.0.dev0`) version:
+ * it must declare no `actions`, no `constraints`, and no `abstract` entities,
+ * and every entity must have a `source`, every field an `expression`, and
+ * every relationship its join columns (`from_columns` and `to_columns`).
+ * Appends every gap to `doc.errors`.
+ */
+function validateOssieConversion(model, doc) {
+    const prefix = `Cannot convert '${model.name}' to version '${loader_1.OSSIE_VERSION}'`;
+    // 1. Reject actions and constraints, which have no representation in
+    // `0.2.0.dev0`.
+    for (const a of model.actions ?? []) {
+        doc.errors.push(`${prefix}: action '${a.name}' is not supported in version ` +
+            `'${loader_1.OSSIE_VERSION}'.`);
+    }
+    for (const c of model.constraints ?? []) {
+        doc.errors.push(`${prefix}: constraint '${c.name}' is not supported in version ` +
+            `'${loader_1.OSSIE_VERSION}'.`);
+    }
+    // 2. Reject abstract entities and require every concrete entity and field to
+    // be bound.
+    for (const e of model.entities) {
+        if (e.abstract) {
+            doc.errors.push(`${prefix}: entity '${e.name}' is 'abstract', which version ` +
+                `'${loader_1.OSSIE_VERSION}' does not support.`);
+            continue;
+        }
+        if (!e.authoredSource && !e.dataSource) {
+            doc.errors.push(`${prefix}: entity '${e.name}' has no 'source'.`);
+        }
+        for (const f of e.fields) {
+            if (!(0, ir_1.isFieldBound)(f)) {
+                doc.errors.push(`${prefix}: field '${e.name}.${f.name}' has no 'expression'.`);
+            }
+        }
+    }
+    // 3. Require every relationship to declare its join columns.
+    for (const r of model.relationships) {
+        if (!r.source.columns.length || !r.destination.columns.length) {
+            doc.errors.push(`${prefix}: relationship '${r.name}' has no join columns ` +
+                `('from_columns' and 'to_columns').`);
+        }
+    }
+}
+/**
+ * Loads `doc.root` into the `SemanticModel` IR for cross-version conversion,
+ * recording any `SemanticModelError` on `doc.errors`.
+ */
+function loadSemanticModel(doc) {
+    try {
+        const loaded = (0, loader_1.fromDocument)(doc.root, { bindingOptional: true, warnUnacceptedSource: true });
+        return loaded.models[0];
+    }
+    catch (err) {
+        if (!(err instanceof loader_1.SemanticModelError))
+            throw err;
+        doc.errors.push(err.message);
+        return undefined;
+    }
+}
+/**
+ * Phase 4 (Convert): Checks with the `SemanticModel` IR that `doc` converts to
+ * its target version (`0.2.0.dev0` <-> `0.2.0.dev0/google`), attaching profile
+ * files and checking conversion gaps when targeting `0.2.0.dev0`, then edits
+ * `doc` into that version with `generateAdaptedFiles`.
+ */
+async function generateConvertedFiles(doc, opts) {
+    if (doc.errors.length > 0)
+        return [];
+    const model = loadSemanticModel(doc);
+    if (!model)
+        return [];
+    if (doc.targetVersion === loader_1.OSSIE_VERSION) {
+        attachProfileFiles(model, opts.profileFiles, doc);
+        validateOssieConversion(model, doc);
+        if (doc.errors.length > 0)
+            return [];
+    }
+    return generateAdaptedFiles(doc, !!opts.transpile, opts.profileFiles);
+}
+/**
+ * Phase 4 (Adapt): Adapts `doc` in place to its target version
+ * (`moveConstructs`, then `adaptToGoogleVersion` or `adaptToOssieVersion`),
+ * optionally transpiles expressions via `transpileDocument`, and returns the
+ * output files. Every value these steps do not change keeps its text.
+ */
+async function generateAdaptedFiles(doc, transpile, profileFiles = []) {
+    // 1. Adapt `doc` in place to the target output version (`0.2.0.dev0/google`
+    // or `0.2.0.dev0`).
+    const profiles = doc.inputVersion === doc.targetVersion ?
+        [] :
+        moveConstructs(doc, profileFiles);
+    if (doc.inputVersion === loader_1.OSSIE_VERSION &&
+        doc.targetVersion === loader_1.GOOGLE_VERSION) {
+        adaptToGoogleVersion(doc);
+    }
+    else if (doc.targetVersion === loader_1.OSSIE_VERSION) {
+        adaptToOssieVersion(doc);
+    }
+    // 2. When `transpile` is enabled and no prior errors occurred, translate
+    // vendor or double-quoted `ANSI_SQL` expressions to `BIGQUERY`.
+    if (transpile && doc.errors.length === 0) {
+        await transpileDocument(doc);
+    }
+    // 3. Write `doc.root` into the input's text when modified or preserve the
+    // text verbatim when unmodified.
+    const content = doc.modified ? writeDocument(doc, doc.root) : doc.text;
+    return [{ fileName: `${doc.model.name}.yaml`, content }, ...profiles];
+}
+/**
+ * Returns the input's text changed to hold `root`. What survives from the
+ * input keeps its text, and long SQL stays on one line.
+ */
+function writeDocument(doc, root) {
+    // The vanilla flavor lists a model's entities under `datasets:` and the
+    // Google flavor under `entities:`. Renaming the key keeps the comments of
+    // the list and of every entity in it.
+    const node = doc.document.getIn(['semantic_model', 0]);
+    const model = asRecords(root.semantic_model)[0] ?? {};
+    for (const pair of yaml.isMap(node) ? node.items : []) {
+        if (!yaml.isScalar(pair.key))
+            continue;
+        const from = String(pair.key.value);
+        const to = from === 'datasets' ? 'entities' :
+            from === 'entities' ? 'datasets' :
+                undefined;
+        if (to && to in model && !(from in model))
+            pair.key.value = to;
+    }
+    return (0, yaml_update_1.updateText)(doc.text, doc.document, root, doc.links);
+}
+/**
+ * Phase 5 (Post-validation): Validates the serialized output YAML with
+ * `loadModels` (`warnUnacceptedSource: !doc.strict`) and checks deployment
+ * targets.
+ */
+function validateOutputDocument(content, doc) {
+    try {
+        // 1. Load the serialized output YAML with `loadModels`
+        // (`warnUnacceptedSource: !doc.strict`) to run full schema and semantic
+        // validation while turning unaccepted table sources into warnings in
+        // non-strict mode, deduplicating warnings already recorded.
+        const loaded = (0, loader_1.loadModels)(content, { bindingOptional: true, warnUnacceptedSource: !doc.strict });
+        for (const w of loaded.warnings) {
+            // The repair step has reported each source the loader warns about.
+            if (LOADER_SOURCE_WARNING.test(w))
+                continue;
+            if (!doc.warnings.includes(w) && !doc.errors.includes(w)) {
+                doc.warnings.push(w);
+            }
+        }
+        // 2. Validate every deployment target on the loaded model using
+        // `validateDeploymentTargets`.
+        for (const m of loaded.models) {
+            validateDeploymentTargets(m, doc);
+        }
+    }
+    catch (err) {
+        if (!(err instanceof loader_1.SemanticModelError))
+            throw err;
+        doc.errors.push(err.message);
+    }
+}
+/**
+ * Repairs, converts, optionally transpiles, and validates a semantic model YAML
+ * document, returning the normalized output file(s) along with any warnings or
+ * errors.
+ */
+async function importSemanticModelYaml(rawYaml, opts = {}) {
+    // 1. Initialize the SQL parser and parse/pre-validate the input document.
+    await (0, sql_parser_1.loadSqlEngine)();
+    const doc = parseImportDocument(rawYaml, opts);
+    if (typeof doc === 'string') {
+        return { ok: false, files: [], warnings: [], errors: [doc] };
+    }
+    validateInputDocument(doc, opts.profileFiles);
+    // 2. Run third-party repairs (which record errors in `strict` mode).
+    repairDocument(doc);
+    // 3. Generate the converted or adapted output file(s).
+    const shouldConvert = doc.inputVersion !== doc.targetVersion && doc.strict;
+    const files = shouldConvert ?
+        await generateConvertedFiles(doc, opts) :
+        await generateAdaptedFiles(doc, !!opts.transpile);
+    // 4. Validate the primary output document and return the result.
+    if (files.length > 0 && doc.errors.length === 0) {
+        validateOutputDocument(files[0].content, doc);
+    }
+    return {
+        ok: doc.errors.length === 0,
+        files: doc.errors.length === 0 ? files : [],
+        warnings: doc.warnings,
+        errors: doc.errors,
+    };
+}