@google-cloud/kcmd 0.1.0 → 0.2.0

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

@@ -436,8 +436,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.

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;

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

@@ -1,5 +1,5 @@
 import { Entity, Field, ProfileSpec, SemanticModel } from './ir';
-import { LoadOptions } from './loader';
+import { LoadOptions, SemanticModelError } from './loader';
 export declare const DEFAULT_PROFILE = "default";
 export declare function plainCopy(value: unknown): any;
 export interface AvailabilityReport {
@@ -38,12 +38,13 @@ export interface AvailabilityReport {
  * it. What a field or metric reads comes from the text `dialect` evaluates
  * (see textsFor). `dialect` defaults to the dialect the model's sources
  * imply. When the sources are in systems of different dialects, or one names
- * no system, there is no dialect and every text counts.
+ * no system, there is no dialect and every text counts. When no lookup read
+ * the dialect, it is null and no text counts.
  * The input is never mutated. The report names each dropped block
  * and the unbound field that stops it, so a caller can state the withheld
  * coverage. A model with nothing unbound resolves unchanged.
  */
-export declare function pruneUnavailable(model: SemanticModel, profileName: string, dialect?: string | undefined): {
+export declare function pruneUnavailable(model: SemanticModel, profileName: string, dialect?: string | null | undefined): {
     model: SemanticModel;
     report: AvailabilityReport;
 };
@@ -116,7 +117,9 @@ export interface AppliedProfile {
 }
 /**
  * A profile a model declares: the text of a profile file, or a profile already
- * read, such as one a vanilla model carries in its GOOGLE block.
+ * read, such as one a vanilla model carries in its GOOGLE block. A profile
+ * already read may carry `label`, the file that holds it, which
+ * namedProfileErrors names in place of the model document.
  */
 export type DeclaredProfile = {
     name: string;
@@ -124,7 +127,17 @@ export type DeclaredProfile = {
 } | {
     name: string;
     spec: ProfileSpec;
+    label?: string;
 };
+export type DeclaredProfiles = (doc: {
+    name: string;
+    text: string;
+}) => DeclaredProfile[];
+export type ProfileFiles = (model: string) => Array<{
+    name: string;
+    text: string;
+    fileName: string;
+}>;
 /**
  * The profiles the model document `doc` declares: `files`, its profile files,
  * then the profiles a vanilla model carries in its GOOGLE block, by name, as
@@ -160,6 +173,16 @@ export declare function profileForDocument(doc: {
     name: string;
     text: string;
 }, profiles: DeclaredProfile[], profileName: string, load?: DialectLoad): DocumentProfile;
+/**
+ * The warnings that applying the profile `profileName` among `profiles` to the
+ * model document `doc` gives, each labeled with the profile. The warnings in
+ * `own`, which the document's own load gives, are left out. Empty unless
+ * profileForDocument applies the profile as a profile file.
+ */
+export declare function appliedProfileWarnings(doc: {
+    name: string;
+    text: string;
+}, profiles: DeclaredProfile[], profileName: string, own: string[], load?: DialectLoad): string[];
 /**
  * The error a command gives when a profile cannot be applied to the model
  * document `docName`, whose profile files are `profileFiles`. An error applying
@@ -173,6 +196,12 @@ export declare function profileErrorMessage(docName: string, res: Extract<Docume
     text: string;
     fileName: string;
 }>): string;
+/**
+ * Why `model` cannot be used because a deployment names a binding profile
+ * `declared` does not hold, or undefined when each names `default` or a
+ * declared profile. `document` is the model's document, for the message.
+ */
+export declare function undeclaredProfileError(document: string, model: SemanticModel, declared: string[]): string | undefined;
 /** The error for a profile name a model document does not declare. */
 export declare function unknownProfileMessage(profileName: string, model: string, declared: string[]): string;
 /**
@@ -184,12 +213,13 @@ export declare function unknownProfileMessage(profileName: string, model: string
 export declare function reservedProfileNameError(docName: string, profiles: {
     name: string;
 }[]): string | undefined;
+export declare function readerMessage(err: SemanticModelError): string;
 export declare function profileSpecOf(doc: any, profileName: string): ProfileSpec;
 export declare function expressionSources(f: Pick<Field, 'expression' | 'dialects' | 'importedExpression' | 'importedDialect'>): Array<{
     text: string;
     dialect: string;
 }>;
-declare function textsFor(f: Pick<Field, 'expression' | 'dialects' | 'importedExpression' | 'importedDialect'>, dialect: string | undefined): Array<{
+declare function textsFor(f: Pick<Field, 'expression' | 'dialects' | 'importedExpression' | 'importedDialect'>, dialect: string | null | undefined): Array<{
     text: string;
     dialect: string;
 }>;
@@ -198,6 +228,7 @@ export interface TableDialects {
     name: string;
     dialects: string[];
     unread?: boolean;
+    guessed?: boolean;
 }
 export declare function tableDialects(entity: Pick<Entity, 'abstract' | 'authoredSource' | 'dataSource' | 'sourceDialect'>, withUnread: boolean): TableDialects | undefined;
 export declare function fieldsOnTables(model: SemanticModel, withUnread?: boolean): Array<{
@@ -205,15 +236,16 @@ export declare function fieldsOnTables(model: SemanticModel, withUnread?: boolea
     field: Field;
     table: TableDialects;
 }>;
-export declare const IMPORT_TRANSPILE_COMMAND = "kcmd import <file> --input first-party --flavor <ossie|google> --transpile";
-export declare function importTranspiles(f: Parameters<typeof textsFor>[0], dialect: string | undefined): boolean;
+export declare function importCommand(flags: string, version?: string): string;
+export declare function importTranspiles(f: Parameters<typeof textsFor>[0], dialect: string | undefined, model: Pick<SemanticModel, 'entities'>): boolean;
+export declare function importHint(f: Parameters<typeof textsFor>[0], dialect: string, model: Pick<SemanticModel, 'entities' | 'version'>): string;
 export declare function sourcesDialect(model: {
     entities?: ReadonlyArray<Pick<Entity, 'abstract' | 'authoredSource' | 'dataSource' | 'sourceDialect'>>;
-}): string | undefined;
+}): string | null | undefined;
 /** What the caller of validateProfileCompleteness checks itself. */
 export interface CompletenessOptions extends DialectLoad {
     ownSqlOnly?: {
-        dialect?: string;
+        dialect?: string | null;
     };
 }
 /**
@@ -241,8 +273,17 @@ export declare function validateProfileCompleteness(baseModel: SemanticModel, pr
  * profile's join, or the model file's when the profile states none.
  */
 export declare function validateProfileConsistency(baseModel: SemanticModel, profiles: ProfileSpec[], applied?: string): string[];
+export interface LocalCheckError {
+    error: string;
+    document?: string;
+    profile?: string;
+}
+export declare function namedProfileErrors(docs: Array<{
+    name: string;
+    text: string;
+}>, baseByDoc: Map<string, SemanticModel>, profileDocs: ProfileFiles, declared: DeclaredProfiles, warnings: string[], load: DialectLoad): LocalCheckError[];
 export declare function inheritanceErrorOf(model: SemanticModel): string | undefined;
-export declare function columnBinding(model: SemanticModel, entityName: string, field: string, dialect?: string): {
+export declare function columnBinding(model: SemanticModel, entityName: string, field: string, dialect?: string | null): {
     owner: string;
     column: string;
 } | undefined;