@google-cloud/kcmd 0.1.0 → 0.2.1

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

@@ -83,15 +83,13 @@ exports.modelDocument = modelDocument;
 exports.compact = compact;
 exports.nonEmpty = nonEmpty;
 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_inheritance_1 = require("./resolve_inheritance");
 const resolve_profiles_1 = require("./resolve_profiles");
 // The vendor tag for Google-specific extension blocks on the IR (kept in sync
-// with loader.GOOGLE_VENDOR). In the Google flavor, a model-level deployment
-// target list rides in one as a folded shim alongside `model.deployments`.
+// with loader.GOOGLE_VENDOR).
 const GOOGLE_VENDOR = 'GOOGLE';
 // The dialect label for the IR's target/canonical `expression` when `dialects`
 // is absent and `stringForm` is not set. BIGQUERY is the loader's default
@@ -340,17 +338,16 @@ function modelDoc(model, warnings, logical, version) {
             `at least one and will not load until an entity is present.`);
     }
     const tableKey = isGoogleVersion ? 'entities' : 'datasets';
-    // Under GOOGLE_VERSION, deployments come from `model.deployments`, or from a
-    // GOOGLE `deploymentTargets` block when that is empty. Under OSSIE_VERSION,
-    // named deployments and profiles go in a GOOGLE block on the model.
+    // Under GOOGLE_VERSION, deployments come from `model.deployments`. Under
+    // OSSIE_VERSION, named deployments and profiles go in a GOOGLE block on the
+    // model.
     const namedDeployments = (model.deployments ?? []).map(d => compact({
         name: d.name,
         target: d.target,
         profile: d.profile
     }));
     const deployments = placement.model.deployments === 'native' ?
-        nonEmpty(namedDeployments.length ? namedDeployments :
-            deploymentsFromGoogleExtensions(model)) :
+        nonEmpty(namedDeployments) :
         undefined;
     const blockProfiles = placement.model.profiles === 'block' ?
         nonEmpty(profileDocuments(model, warnings).map(p => p.doc)) :
@@ -385,8 +382,7 @@ function modelDoc(model, warnings, logical, version) {
         constraints: placement.model.constraints === 'native' ?
             nonEmpty((model.constraints ?? []).map(c => constraintDoc(c))) :
             undefined,
-        custom_extensions: customExtensionsDoc(model.customExtensions, `model '${model.name}'`, isGoogleVersion, 
-        /* isModel= */ true, warnings, /* isField= */ false, blockPayload),
+        custom_extensions: customExtensionsDoc(model.customExtensions, `model '${model.name}'`, isGoogleVersion, warnings, /* isField= */ false, blockPayload),
     });
 }
 // Warns about each IR construct OSSIE_VERSION has no representation for,
@@ -436,8 +432,7 @@ function datasetDoc(entity, warnings, logical, version) {
         name: entity.name,
         // An abstract entity has no physical table, so its source is empty; omit
         // the key rather than emit `source: ""` (which the loader rejects). The
-        // source as written survives serialization; a legacy bare name is written
-        // as the name the load qualified it to.
+        // source as written survives serialization.
         source: (0, loader_1.writtenSource)(entity) || undefined,
         // Supertype entities (entity-level inheritance); native under
         // GOOGLE_VERSION, or in the dataset's GOOGLE block under OSSIE_VERSION.
@@ -450,8 +445,7 @@ function datasetDoc(entity, warnings, logical, version) {
         ai_context: aiContextDoc(entity.aiContext, isGoogleVersion),
         fields: nonEmpty((entity.fields ?? [])
             .map(f => fieldDoc(f, warnings, logical || (isGoogleVersion && !!entity.abstract), isGoogleVersion))),
-        custom_extensions: customExtensionsDoc(entity.customExtensions, `entity '${entity.name}'`, isGoogleVersion, 
-        /* isModel= */ false, warnings, /* isField= */ false, blockPayload),
+        custom_extensions: customExtensionsDoc(entity.customExtensions, `entity '${entity.name}'`, isGoogleVersion, warnings, /* isField= */ false, blockPayload),
     });
 }
 // Filters out the IR's `'Opaque'` placeholder so untyped fields and metrics
@@ -483,8 +477,7 @@ function fieldDoc(field, warnings, logical, isGoogleVersion) {
         dimension: dimensionDoc(field),
         description: field.description,
         ai_context: aiContextDoc(field.aiContext, isGoogleVersion),
-        custom_extensions: customExtensionsDoc(field.customExtensions, `field '${field.name}'`, isGoogleVersion, 
-        /* isModel= */ false, warnings, /* isField= */ true),
+        custom_extensions: customExtensionsDoc(field.customExtensions, `field '${field.name}'`, isGoogleVersion, warnings, /* isField= */ true),
     });
 }
 function metricDoc(metric, warnings, version) {
@@ -509,8 +502,7 @@ function metricDoc(metric, warnings, version) {
         datatype: datatypeDoc(metric.type),
         description: metric.description,
         ai_context: aiContextDoc(metric.aiContext, isGoogleVersion),
-        custom_extensions: customExtensionsDoc(metric.customExtensions, `metric '${metric.name}'`, isGoogleVersion, 
-        /* isModel= */ false, warnings, /* isField= */ false, blockPayload),
+        custom_extensions: customExtensionsDoc(metric.customExtensions, `metric '${metric.name}'`, isGoogleVersion, warnings, /* isField= */ false, blockPayload),
     });
 }
 // The `Concept.field` pairs this document will still resolve on reload. A
@@ -698,8 +690,7 @@ function relationshipDoc(rel, warnings, version) {
         description: placement.relationship.description === 'native' ? description :
             undefined,
         ai_context: aiContextDoc(rel.aiContext, isGoogleVersion),
-        custom_extensions: customExtensionsDoc(rel.customExtensions, `relationship '${rel.name}'`, isGoogleVersion, 
-        /* isModel= */ false, warnings, /* isField= */ false, blockPayload),
+        custom_extensions: customExtensionsDoc(rel.customExtensions, `relationship '${rel.name}'`, isGoogleVersion, warnings, /* isField= */ false, blockPayload),
     });
 }
 // Renders a field or metric `expression` for the target version. The IR comes
@@ -797,24 +788,14 @@ function aiContextDoc(ai, isGoogleVersion) {
     }
     return isGoogleVersion ? { ...base, custom } : { ...custom, ...base };
 }
-// The deployments a vanilla model lists only as targets in its GOOGLE blocks,
-// named as a pull names them. A block whose data is not valid JSON gives none,
-// and customExtensionsDoc warns that it was dropped. The other blocks still
-// give theirs.
-function deploymentsFromGoogleExtensions(model) {
-    const targets = (model.customExtensions ??
-        []).flatMap(ext => blockTargets(ext, model.name));
-    return (0, deployment_target_1.unnamedDeployments)(targets);
-}
 // Serializes `custom_extensions` for one IR element. Under OSSIE_VERSION,
 // third-party extensions are emitted, followed by a synthesized GOOGLE block
-// when `blockPayload` carries any keys. Any other raw GOOGLE block on the IR
+// when `blockPayload` carries any keys. Any raw GOOGLE block on the IR
 // is dropped with a warning so it cannot collide with the synthesized block or
 // write keys the loader rejects. Under GOOGLE_VERSION,
 // third-party extensions are written out unchanged without warning, while
-// `GOOGLE` blocks are skipped (silently for the model's `deploymentTargets`
-// block, and with a warning for any other `GOOGLE` block).
-function customExtensionsDoc(exts, where, isGoogleVersion, isModel, warnings, isField = false, blockPayload) {
+// `GOOGLE` blocks are skipped with a warning.
+function customExtensionsDoc(exts, where, isGoogleVersion, warnings, isField = false, blockPayload) {
     const payload = blockPayload ? { ...blockPayload } : {};
     if (!exts?.length && Object.keys(payload).length === 0)
         return undefined;
@@ -826,12 +807,6 @@ function customExtensionsDoc(exts, where, isGoogleVersion, isModel, warnings, is
                 kept.push({ vendor_name: e.vendorName, data: e.data });
                 continue;
             }
-            // The loader's copy of the model's `deployments`, which the GOOGLE
-            // block below writes in their own form.
-            if (isModel && payload.deployments !== undefined &&
-                isDeploymentTargetsBlock(e)) {
-                continue;
-            }
             droppedGoogle += 1;
         }
         if (droppedGoogle > 0) {
@@ -860,8 +835,6 @@ function customExtensionsDoc(exts, where, isGoogleVersion, isModel, warnings, is
             kept.push({ vendor_name: ext.vendorName, data: ext.data });
             continue;
         }
-        if (isModel && blockTargets(ext, '').length > 0)
-            continue;
         droppedGoogle += 1;
     }
     if (droppedGoogle > 0) {
@@ -870,30 +843,6 @@ function customExtensionsDoc(exts, where, isGoogleVersion, isModel, warnings, is
     }
     return nonEmpty(kept);
 }
-/**
- * Returns true if `e.data` is a JSON object with a `'deploymentTargets'`
- * property.
- *
- * The loader folds a Google-flavor model's `deployments` into such a block.
- */
-function isDeploymentTargetsBlock(e) {
-    try {
-        const d = JSON.parse(e.data);
-        return !!d && typeof d === 'object' &&
-            Object.hasOwn(d, 'deploymentTargets');
-    }
-    catch {
-        return false;
-    }
-}
-function blockTargets(ext, modelName) {
-    try {
-        return (0, deployment_target_1.googleBlockTargets)([ext], modelName);
-    }
-    catch {
-        return [];
-    }
-}
 // Drops undefined-valued keys so the emitted YAML only shows fields the model
 // actually set (matching the emitters' `compact` convention).
 function compact(obj) {

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

@@ -2,6 +2,7 @@ import { ActionParameter } from './ir';
 export declare function isParameterRequired(param: ActionParameter): boolean;
 export declare function storeCodeFor(dataType: string): string;
 export declare function sentence(text: string): string;
+export declare function storeMessage(message: string | undefined, status: number): string;
 /**
  * One value, parsed to the store type its declared ontology type implies.
  *

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

@@ -1,11 +1,12 @@
 "use strict";
-// Leaf helpers for action parameter optionality, scalar type checking, and
-// store type codes -- shared by deploy-time validation and run-time execution
-// without pulling store clients into the validation layer.
+// Leaf helpers for action parameter optionality, scalar type checking, store
+// type codes and message sentences -- shared by deploy-time validation and
+// run-time execution without pulling store clients into the validation layer.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isParameterRequired = isParameterRequired;
 exports.storeCodeFor = storeCodeFor;
 exports.sentence = sentence;
+exports.storeMessage = storeMessage;
 exports.bindScalar = bindScalar;
 function isParameterRequired(param) {
     if (param.required !== undefined)
@@ -36,6 +37,24 @@ function sentence(text) {
     const trimmed = text.trim();
     return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
 }
+// The first line of a multi-line diagnosis. The lines after it echo the
+// statement and point a caret at the offending token, which is worth nothing
+// here: the author has the statement open in the profile, the position in
+// `[at 1:54]` survives, and a caret counted from column 1 lands in the wrong
+// place once the message is embedded in a longer sentence.
+//
+// `\n` is matched in both its forms because Spanner's top-level `error.message`
+// arrives with its newlines ESCAPED -- a literal backslash and an n survive
+// JSON.parse -- while every other message uses real ones.
+function firstLine(message) {
+    return message.replace(/\\n/g, '\n').split('\n')[0].trim();
+}
+// An API error's message reduced to its first line as a sentence, such as
+// "Unrecognized name: accountId; Did you mean account_id? [at 1:54]."
+function storeMessage(message, status) {
+    const text = (message ?? '').trim();
+    return text ? sentence(firstLine(text)) : `HTTP ${status}.`;
+}
 // What Spanner accepts for a DATE and a TIMESTAMP parameter. The zone is
 // required rather than defaulted, because a timestamp written without one
 // means a different instant to every reader who supplies the missing part.

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

@@ -1,6 +1,5 @@
 import { CatalogClient } from '../gcp/dataplex';
 import { ReadResult } from './kc_converter';
-import { FileCopy } from './kc_custom_types';
 export interface KcPullOptions {
     project: string;
     location: string;
@@ -8,7 +7,4 @@ export interface KcPullOptions {
     v2Aspects?: boolean;
     systemTypeProject?: string;
 }
-export interface KcPullResult extends ReadResult {
-    rawFiles?: FileCopy[];
-}
-export declare function pullKnowledgeCatalog(cat: CatalogClient, opts: KcPullOptions): Promise<KcPullResult>;
+export declare function pullKnowledgeCatalog(cat: CatalogClient, opts: KcPullOptions): Promise<ReadResult>;

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

@@ -8,9 +8,9 @@
 // (a BASIC list omits aspect data, so each entry is re-fetched with its aspect
 // types -- an entity needs BOTH its `semantic-entity` aspect and the built-in
 // `schema` aspect), and hands the hydrated entries to the pure reader
-// (`kc_converter.modelsFromCatalogResources`). With the first-generation
-// aspects it also returns the file copies a push stored of the model and
-// profile files, for the caller to write instead of the rebuilt model.
+// (`kc_converter.modelsFromCatalogResources`). With the second-generation
+// types, a model an older kcmd pushed with the first-generation ones is left
+// out, and a warning names it.
 //
 // TODO(#278): Layer 2 push/pull symmetry. This is the pull half over the
 // pure `kc_converter` codec; the push half (`deployKnowledgeCatalog`) still
@@ -32,21 +32,17 @@ const HYDRATE_CONCURRENCY = 8;
 // Reads the semantic model back from a Knowledge Catalog entry group. Emits no
 // console output; soft warnings (from the reader) are returned for the caller
 // to print. Hard failures -- more than one model in the group, a fetch error
-// on any entry or its links, or file copies that are not one finished push's
+// on any entry or its links, or a model entry still labeled as being written
 // -- throw, so the pull aborts rather than write a partial model.
 async function pullKnowledgeCatalog(cat, opts) {
     await (0, sql_parser_1.loadSqlEngine)();
     const destination = `${opts.project}.${opts.location}.${opts.entryGroup}`;
-    const warnings = [];
     // Enumerate the group (paging is inherently sequential) and pick the semantic
     // entries, then hydrate their aspects concurrently: a BASIC list omits aspect
     // data, so each entry needs its own lookupEntry, and those fetches are
     // independent. The pool preserves input order so warnings stay deterministic.
     const targets = [];
     for await (const entry of cat.listEntries(opts.project, opts.location, opts.entryGroup)) {
-        // With v2Aspects on, a pull returns no file copies, so it fetches none.
-        if (opts.v2Aspects && isFileCopyEntry(entry))
-            continue;
         const aspectTypes = semanticAspectTypes(entry.entryType, opts.v2Aspects);
         if (aspectTypes)
             targets.push({ entry, aspectTypes });
@@ -96,76 +92,42 @@ async function pullKnowledgeCatalog(cat, opts) {
         }
     }
     const read = (0, kc_converter_1.modelsFromCatalogResources)(hydrated, entryLinks, { v2Aspects: opts.v2Aspects });
-    if (opts.v2Aspects) {
-        warnings.push(...read.warnings);
-        return { ...read, warnings: [...new Set(warnings)] };
+    // Every push labels the model entry as writing when it writes the model entry
+    // and as finished with its last. The hydrated entries keep the order of
+    // `targets`.
+    const anchor = anchors.length ? hydrated[targets.indexOf(anchors[0])] : undefined;
+    const writingReason = anchor?.entrySource?.labels?.[kc_custom_types_1.PUSH_STATE_LABEL] === kc_custom_types_1.PUSH_WRITING ?
+        `its model entry's ${kc_custom_types_1.PUSH_STATE_LABEL} label still says ${kc_custom_types_1.PUSH_WRITING}` :
+        undefined;
+    if (writingReason) {
+        // With v2Aspects on, a model an older kcmd pushed is not in `read.models`,
+        // so the model is named from its entry, as the reader names it.
+        throw notFinished(anchor.entrySource?.displayName ?? (0, kc_ids_1.entryIdOf)(anchor.name), writingReason);
     }
-    // A copy belongs to the group's one model, so with no model there are none.
-    if (!read.models.length) {
-        warnings.push(...read.warnings);
-        return { models: [], rawFiles: [], warnings: [...new Set(warnings)] };
+    const warnings = [...read.warnings];
+    for (const m of read.firstGeneration ?? []) {
+        warnings.push(firstGenerationWarning(opts, m));
     }
-    // The first-generation aspects cannot hold the whole model, so the caller
-    // writes these copies instead of the model rebuilt from the aspects. That
-    // needs the copy of the model file, `<model>.yaml`, which is where pull
-    // writes the model. Without it the rebuilt model is written, as for a model
-    // pushed before copies were stored.
-    const model = read.models[0].name;
-    // The model's own copies sit under its anchor's `.files.` prefix. A copy
-    // another model left behind is not one of them.
-    const own = `${(0, kc_ids_1.entryIdOf)(anchors[0].entry.name)}.files.`;
-    const before = warnings.length;
-    const copies = readFileCopies(hydrated.filter(e => (0, kc_ids_1.entryIdOf)(e.name).startsWith(own)), warnings);
-    const skipped = warnings.slice(before);
-    // Every copy one push stores carries that push's id and how many copies it
-    // stored. Copies whose ids differ, or of which only some carry one, or a
-    // number of copies other than that count, mean the last push stopped
-    // partway. Writing them would mix files from two pushes or leave one out.
-    // A push that stores copies also labels the model entry with its push id,
-    // and writes that entry first. A labeled model whose copies are missing or
-    // carry another id means the last push stopped before storing them.
-    // Writing the copies of an earlier push, or rebuilding, would overwrite
-    // the local files. The hydrated entries keep the order of `targets`.
-    const count = copies[0]?.pushFileCount;
-    const anchor = hydrated[targets.indexOf(anchors[0])];
-    const label = anchor.entrySource?.labels?.[kc_custom_types_1.PUSH_ID_LABEL];
-    const unfinished = new Set(copies.map(f => f.pushId)).size > 1 ?
-        'its file copies in the catalog come from different pushes' :
-        count !== undefined && copies.length < count ?
-            `the catalog holds ${copies.length} of its ${count} file copies` :
-            count !== undefined && copies.length > count ?
-                `the catalog holds ${copies.length} file copies, but the push stored ` +
-                    `${count}` :
-                label !== undefined && !copies.length ?
-                    (skipped.length ? 'the catalog holds no readable file copy' :
-                        'the catalog holds none of its file copies') :
-                    label !== undefined && copies[0].pushId !== label ?
-                        'its model entry and its file copies come from different pushes' :
-                        undefined;
-    if (unfinished) {
-        // A skipped copy is often why the count is off, so its warning goes with
-        // the error.
-        throw new Error(`the last push of model '${model}' did not finish: ${unfinished}, ` +
-            `so pull writes nothing. Push again, then pull.` +
-            skipped.map(w => ` ${w}.`).join(''));
-    }
-    if (copies.some(f => f.fileName === `${model}.yaml`)) {
-        // The rebuilt model is not written, so its warnings are left out.
-        return {
-            models: read.models,
-            rawFiles: copies,
-            warnings: [...new Set(warnings)],
-        };
-    }
-    warnings.push(...read.warnings);
-    warnings.push(copies.length ?
-        `the stored copies of model '${model}' hold no '${model}.yaml', so ` +
-            `the model file is rebuilt from the catalog's aspects and may ` +
-            `differ from what was pushed` :
-        'no stored copy of the model file was found, so it is rebuilt from ' +
-            'the catalog\'s aspects and may differ from what was pushed; ' +
-            'push it again to store a copy');
-    return { models: read.models, rawFiles: [], warnings: [...new Set(warnings)] };
+    return { ...read, warnings: [...new Set(warnings)] };
+}
+// The error for a model whose last push stopped partway, for `reason`.
+function notFinished(model, reason) {
+    return new Error(`the last push of model '${model}' did not finish: ${reason}, so pull ` +
+        `writes nothing. Push again, then pull.`);
+}
+// The model, entity and metric aspect types a first-generation push writes, in
+// the order the warning names them.
+const FIRST_GEN_ASPECTS = ['semantic-model', 'semantic-entity', 'semantic-metric'];
+// The warning for a model an older kcmd pushed, which a pull with v2Aspects
+// on leaves out. It names the first-generation aspect types found on the
+// model's entries.
+function firstGenerationWarning(opts, model) {
+    const found = new Set(model.entries.flatMap(e => Object.values(e.aspects ?? {})
+        .map(a => a.aspectType?.split('/aspectTypes/')[1])));
+    const types = FIRST_GEN_ASPECTS.filter(t => found.has(t));
+    return `model '${model.name}' in entry group '${opts.entryGroup}' was ` +
+        `pushed by an older kcmd (first-generation aspects: ${types.join(', ')}). Pull wrote nothing for it; push it again ` +
+        `with the current kcmd`;
 }
 // Fetches `entry` with the aspects of `aspectTypes`, at `paths` when given.
 // Throws on a failed fetch.
@@ -233,39 +195,6 @@ function pathBatches(opts, entry, type, paths) {
     }
     return [...batches, batch];
 }
-// True when an entry is a file copy, matched by its entry type's id suffix so
-// the project the custom type lives in need not be known.
-function isFileCopyEntry(entry) {
-    return entry.entryType?.endsWith(`/entryTypes/${kc_custom_types_1.FILE_COPY_TYPE_ID}`) ?? false;
-}
-// The file copies among the hydrated entries, sorted by file name, each with
-// the push id and copy count it carries. A copy whose aspect holds no file
-// name or no content is skipped with a warning.
-function readFileCopies(entries, warnings) {
-    const files = [];
-    for (const entry of entries) {
-        if (!isFileCopyEntry(entry))
-            continue;
-        const aspect = Object.entries(entry.aspects ?? {}).find(([key, a]) => key.endsWith(`.${kc_custom_types_1.FILE_COPY_TYPE_ID}`) ||
-            (a.aspectType ?? '').endsWith(`/aspectTypes/${kc_custom_types_1.FILE_COPY_TYPE_ID}`));
-        const data = aspect?.[1].data;
-        if (typeof data?.fileName !== 'string' || data.fileName === '' ||
-            typeof data.content !== 'string') {
-            warnings.push(`file copy '${(0, kc_ids_1.entryIdOf)(entry.name)}' holds no file name or no ` +
-                `content; it is skipped`);
-            continue;
-        }
-        files.push({
-            fileName: data.fileName,
-            content: data.content,
-            ...(typeof data.pushId === 'string' ? { pushId: data.pushId } : {}),
-            ...(typeof data.pushFileCount === 'number' ?
-                { pushFileCount: data.pushFileCount } :
-                {}),
-        });
-    }
-    return files.sort((a, b) => a.fileName < b.fileName ? -1 : a.fileName > b.fileName ? 1 : 0);
-}
 // The aspect types each second-generation entry type is read with.
 const OBJECT_ASPECTS = ['guidelines', 'semantic-extensions', 'overview'];
 const V2_ASPECT_TYPES = new Map([
@@ -312,9 +241,6 @@ function semanticAspectTypes(entryType, v2Aspects) {
         case kc_custom_types_1.CONSTRAINT_TYPE_ID:
             // Custom for the same reason, and named through the same `typeBase`.
             return (0, kc_constraints_1.constraintAspectTypes)(typeBase);
-        case kc_custom_types_1.FILE_COPY_TYPE_ID:
-            // Custom too: one aspect holding the file's name and text.
-            return [aspectType(kc_custom_types_1.FILE_COPY_TYPE_ID)];
         default:
             return undefined;
     }

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

@@ -12,6 +12,9 @@ export interface ResolveResult {
     model: SemanticModel;
     warnings: string[];
 }
+export interface ResolveOptions {
+    requalify?: boolean;
+}
 /**
  * What a `concept` name may refer to, and the fields it declares.
  *
@@ -46,9 +49,11 @@ export declare function declaredConceptFields(model: SemanticModel): Map<string,
  * inheritance and no exclusions resolves to an equivalent model.
  * `targetDialect` is the SQL that an inherited field's target text and its
  * ANSI_SQL entries are read in to find their comments. It is BigQuery unless
- * given, as the graph generators read the target text.
+ * given, as the graph generators read the target text. With
+ * `options.requalify`, an inherited expression keeps naming the fields it
+ * names on its ancestor, under the inheriting entity's qualifier.
  *
  * Reading an inherited field's SQL needs the SQL parser, so call
  * `loadSqlEngine()` first. Without it, this throws the parser's plain Error.
  */
-export declare function resolveInheritance(model: SemanticModel, targetDialect?: string): ResolveResult;
+export declare function resolveInheritance(model: SemanticModel, targetDialect?: string, options?: ResolveOptions): ResolveResult;

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

@@ -83,12 +83,14 @@ function declaredConceptFields(model) {
  * inheritance and no exclusions resolves to an equivalent model.
  * `targetDialect` is the SQL that an inherited field's target text and its
  * ANSI_SQL entries are read in to find their comments. It is BigQuery unless
- * given, as the graph generators read the target text.
+ * given, as the graph generators read the target text. With
+ * `options.requalify`, an inherited expression keeps naming the fields it
+ * names on its ancestor, under the inheriting entity's qualifier.
  *
  * Reading an inherited field's SQL needs the SQL parser, so call
  * `loadSqlEngine()` first. Without it, this throws the parser's plain Error.
  */
-function resolveInheritance(model, targetDialect) {
+function resolveInheritance(model, targetDialect, options = {}) {
     const clone = structuredClone(model);
     const warnings = [];
     const entities = clone.entities ?? [];
@@ -143,7 +145,9 @@ function resolveInheritance(model, targetDialect) {
         }
         // Own fields first, then every inherited field, each merged down its
         // declaring chain. A subtype's redeclaration of an inherited field merges
-        // over that chain too, contributing only its binding.
+        // over that chain too, contributing only its binding. With `requalify`,
+        // each inherited expression names this entity's fields.
+        const into = options.requalify ? entity.name : undefined;
         const seenField = new Set();
         const flattened = [];
         for (const f of ownFields.get(entity.name) ?? []) {
@@ -156,14 +160,14 @@ function resolveInheritance(model, targetDialect) {
                 continue; // a self-duplicate; keep the first
             seenField.add(f.name);
             const chain = declarers.get(f.name);
-            flattened.push(chain ? mergeBinding(mergeChain(f.name, chain, ownFields, ancestorsOf, targetDialect), f) :
+            flattened.push(chain ? mergeBinding(mergeChain(f.name, chain, ownFields, ancestorsOf, targetDialect, into), f) :
                 f);
         }
         for (const [name, chain] of declarers) {
             if (seenField.has(name))
                 continue;
             seenField.add(name);
-            flattened.push(mergeChain(name, chain, ownFields, ancestorsOf, targetDialect));
+            flattened.push(mergeChain(name, chain, ownFields, ancestorsOf, targetDialect, into));
         }
         // A field the binding profile excludes on this entity is left off it.
         // Descendants read the snapshot of declared fields, so they still inherit
@@ -186,7 +190,7 @@ function resolveInheritance(model, targetDialect) {
 }
 // Clones an ancestor's field for a descendant, rewriting its expression to be
 // TABLE-LOCAL. A field expression written on the ancestor as `<Ancestor>.col`
-// means "the `col` column of the ancestor's own table"; inherited onto a
+// names the ancestor's field `col`; inherited onto a
 // descendant -- whose backing table carries the same column, since inherited
 // fields must physically exist on the child -- it must reference the
 // DESCENDANT's column, so the ancestor's own-name qualifier is stripped.
@@ -195,23 +199,35 @@ function resolveInheritance(model, targetDialect) {
 // tables (e.g. BigQuery's shared labels) would see two different definitions of
 // the same property and reject the graph.
 //
+// Given `into`, the descendant, the ancestor's qualifier is renamed to `into`'s
+// instead. `<Ancestor>.x` names the ancestor's field `x`, and the graph
+// renders such a name from that field's own SQL, so inherited it must name the
+// descendant's `x`, which may bind another column; stripped, it would read a
+// column `x` the descendant's table may not have. The graph
+// generators, and the checks that guard them, ask for this.
+//
 // This composes with (does not duplicate) the emitter's own qualifier
 // stripping: this pass normalizes an inherited expression INTO the child's
 // frame once here, and the emitter's table-local renderer then strips the
-// child's own qualifier uniformly for every field (see
-// graph_ddl.renderFieldPropertyCore). Both route through the same
-// `stripQualifier` primitive; they differ only in which qualifier they remove.
+// child's own qualifier uniformly for every field, reading each sibling it
+// names (see graph_ddl.renderFieldPropertyCore). Both find the qualifier with
+// the SQL parser (see sql_expr_utils.qualifiersIn).
 //
-// Comments come out first. A quote inside a comment would otherwise pair with a
-// string literal's, and the qualifier between them would stay. The target text
-// is read in `targetDialect`, BigQuery unless given, and so are the ANSI_SQL
-// entries, which a database of that dialect runs as its own SQL. The imported
-// text is read in its imported dialect, and every other dialect entry in its
-// own. A vendor entry that holds the same text as the target does not change
-// how the target is read.
-function localizeInheritedField(field, ancestor, targetDialect) {
+// The text comes out without its comments, and the rest stays as written. The
+// target text is read in `targetDialect`, BigQuery unless given, and so are
+// the ANSI_SQL entries, which a database of that dialect runs as its own SQL.
+// The imported text is read in its imported dialect, and every other dialect
+// entry in its own, so a quoted qualifier (`"Person".name` in PostgreSQL) is
+// found as that dialect quotes it; renamed, it keeps its quotes. A vendor
+// entry that holds the same text as the target does not change how the target
+// is read.
+function localizeInheritedField(field, ancestor, targetDialect, into) {
     const clone = structuredClone(field);
-    const local = (text, dialect) => (0, sql_expr_utils_1.stripQualifier)((0, sql_expr_utils_1.sqlWithoutComments)(text, dialect), ancestor);
+    const local = (text, dialect) => {
+        const bare = (0, sql_expr_utils_1.sqlWithoutComments)(text, dialect);
+        return into === undefined ? (0, sql_expr_utils_1.withoutQualifier)(bare, ancestor, dialect) :
+            (0, sql_expr_utils_1.requalified)(bare, ancestor, into, dialect);
+    };
     if (clone.expression !== undefined) {
         clone.expression = local(clone.expression, targetDialect);
     }
@@ -254,13 +270,13 @@ function mergeBinding(base, over) {
 // the chain is sorted by how many ancestors each member has; requireOneChain
 // has already checked that every member descends from the next. Every
 // expression is localized to the declaring ancestor's frame first, its target
-// text read in `targetDialect`.
-function mergeChain(name, chain, ownFields, ancestorsOf, targetDialect) {
+// text read in `targetDialect`, and moved onto `into` when given.
+function mergeChain(name, chain, ownFields, ancestorsOf, targetDialect, into) {
     const depth = (n) => (ancestorsOf.get(n) ?? []).length;
     let merged;
     for (const anc of [...chain].sort((a, b) => depth(a) - depth(b))) {
         const own = (ownFields.get(anc) ?? []).find(f => f.name === name);
-        const local = localizeInheritedField(own, anc, targetDialect);
+        const local = localizeInheritedField(own, anc, targetDialect, into);
         merged = merged ? mergeBinding(merged, local) : local;
     }
     return merged;