@google-cloud/kcmd 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,346 @@
+"use strict";
+// Resolves entity-level inheritance (`extends`) into self-contained entities.
+//
+// The IR records inheritance AS DECLARED: an entity's `extends` names its
+// direct supertypes, and its `fields` are only the ones it declares itself (see
+// ir.Entity.extends). That is faithful but not directly consumable -- an
+// emitter that wants to publish a subclass as a first-class node needs the
+// supertype's fields present on the child, and the full ancestor set (not just
+// the direct parents) to label it. This pass performs that resolution,
+// mirroring the shape of ./transpile: it `structuredClone`s the model and NEVER
+// mutates its input, returning a resolved clone plus warnings.
+//
+// What it does, per entity:
+//   - Fields FLOW DOWN (flattening). The entity's own fields come first
+//     (declared order), then every field it inherits. An inherited field is
+//     MERGED down the chain that declares it: the farthest declaration supplies
+//     the definition (type, label, description, ai_context, ...), and each
+//     nearer redeclaration, the entity's own included, supplies only its
+//     binding. A subtype that rebinds a field to another column therefore keeps
+//     everything its parent said about it.
+//   - `extends` is expanded from the direct parents to the full, de-duplicated
+//     TRANSITIVE ancestor set, ordered nearest-first (a diamond lists each
+//     ancestor once). An emitter reads labels straight off this list.
+//
+// What it deliberately does NOT do:
+//   - Keys are NOT inherited: each entity keeps its own KEY (a node table is
+//     identified by its own grain, not its supertype's).
+//   - Relationships (edges) are NOT inherited: a subclass does not gain its
+//     supertype's edges. Only node properties flow down.
+//   - It does not classify abstract vs concrete or drop anything -- that is the
+//     consuming leg's concern (see graph_ddl.ts). This pass is leg-agnostic.
+//
+// Errors, all thrown: a cycle in `extends`; a parent that is not an entity in
+// the model; a field inherited from two ancestors that each declare it with
+// neither extending the other, since nothing says which definition wins; and
+// two fields of one entity, declared or inherited, whose names differ only in
+// case. A diamond is not the third case: two paths reaching ONE declaration
+// resolve to it, and an exact redeclaration of an inherited field rebinds it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InheritanceError = void 0;
+exports.declaredConceptFields = declaredConceptFields;
+exports.resolveInheritance = resolveInheritance;
+const ir_1 = require("./ir");
+const sql_expr_utils_1 = require("./sql_expr_utils");
+/**
+ * Why inheritance cannot be resolved. `unknown-parent` can be a pruning
+ * artefact, since a profile can drop a supertype whole; a cycle or an
+ * ambiguously inherited field cannot, because pruning only removes things.
+ */
+class InheritanceError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+    }
+}
+exports.InheritanceError = InheritanceError;
+function declaredConceptFields(model) {
+    const inherits = (model.entities ?? []).some(e => e.extends?.length);
+    const entities = (inherits ? resolveInheritance(model).model : model).entities ?? [];
+    const concepts = new Map();
+    for (const e of entities) {
+        concepts.set(e.name, {
+            kind: 'entity',
+            fields: new Map((e.fields ?? []).map(f => [f.name, f])),
+        });
+    }
+    for (const r of model.relationships ?? []) {
+        if (concepts.has(r.name))
+            continue;
+        concepts.set(r.name, {
+            kind: 'relationship',
+            fields: new Map((r.association?.fields ?? []).map(f => [f.name, f])),
+        });
+    }
+    return concepts;
+}
+/**
+ * Returns a clone of `model` with every entity's `extends` expanded to its full
+ * transitive ancestor set and its `fields` flattened to include inherited
+ * fields, less any a profile excludes on that entity. The input is never
+ * mutated. An entity with no `extends` keeps its own fields, so a model with no
+ * 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. 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, options = {}) {
+    const clone = structuredClone(model);
+    const warnings = [];
+    const entities = clone.entities ?? [];
+    const byName = new Map(entities.map(e => [e.name, e]));
+    // Snapshot the AS-DECLARED direct parents and own fields BEFORE mutating any
+    // entity, so resolution reads a stable view regardless of iteration order
+    // (each entity is flattened from originals, not from an already-flattened
+    // ancestor).
+    const directParents = new Map();
+    const ownFields = new Map();
+    for (const e of entities) {
+        directParents.set(e.name, [...(e.extends ?? [])]);
+        ownFields.set(e.name, [...e.fields]);
+    }
+    // Every entity's ancestors, nearest-first, computed once: the merge below
+    // needs to know whether one declaring ancestor descends from another.
+    const ancestorsOf = new Map();
+    for (const e of entities) {
+        ancestorsOf.set(e.name, transitiveAncestors(e.name, byName, directParents));
+    }
+    for (const entity of entities) {
+        const ancestors = ancestorsOf.get(entity.name) ?? [];
+        // Which ancestors declare each inherited field name, nearest-first. An
+        // ancestor that redeclares a field it inherits and sets nothing on it
+        // changes nothing, so it is not a declarer. Counting it would make a
+        // diamond ambiguous over a line that has no effect.
+        const declarers = new Map();
+        const inheritedByLower = new Map();
+        for (const anc of ancestors) {
+            for (const f of ownFields.get(anc) ?? []) {
+                const lower = f.name.toLowerCase();
+                const prior = inheritedByLower.get(lower);
+                if (prior && prior.name !== f.name) {
+                    throw new InheritanceError('ambiguous-field', `entity '${entity.name}' inherits field '${prior.name}' from '${prior.from}' and field '${f.name}' from '${anc}' (case-insensitive collision); field names on an ` +
+                        `entity must be unique ignoring case`);
+                }
+                if (setsNothing(f) &&
+                    (ancestorsOf.get(anc) ?? [])
+                        .some(a => ownFields.get(a)?.some(g => g.name === f.name))) {
+                    continue;
+                }
+                if (!prior)
+                    inheritedByLower.set(lower, { name: f.name, from: anc });
+                const list = declarers.get(f.name) ?? [];
+                if (!list.includes(anc))
+                    list.push(anc);
+                declarers.set(f.name, list);
+            }
+        }
+        for (const [name, list] of declarers) {
+            requireOneChain(entity.name, name, list, ancestorsOf);
+        }
+        // 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. 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) ?? []) {
+            const inherited = inheritedByLower.get(f.name.toLowerCase());
+            if (inherited && inherited.name !== f.name) {
+                throw new InheritanceError('ambiguous-field', `entity '${entity.name}' declares field '${f.name}', which collides ignoring case with field '${inherited.name}' inherited from '${inherited.from}'; field names on an entity must be unique ` +
+                    `ignoring case`);
+            }
+            if (seenField.has(f.name))
+                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, 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, 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
+        // it.
+        const excluded = new Set(entity.excludedFields ?? []);
+        entity.fields = excluded.size ?
+            flattened.filter(f => !excluded.has(f.name)) :
+            flattened;
+        // Expand `extends` to the resolved ancestor list. Drop the key when the
+        // entity has no parents, so a consumer reads `extends` as the exact label
+        // set.
+        if (ancestors.length) {
+            entity.extends = ancestors;
+        }
+        else {
+            delete entity.extends;
+        }
+    }
+    return { model: clone, warnings: [...new Set(warnings)] };
+}
+// 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`
+// 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.
+// Without this the descendant would render `<Ancestor>.col AS col` while the
+// ancestor renders `col`, and an emitter that reuses one label across both
+// 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, reading each sibling it
+// names (see graph_ddl.renderFieldPropertyCore). Both find the qualifier with
+// the SQL parser (see sql_expr_utils.qualifiersIn).
+//
+// 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) => {
+        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);
+    }
+    if (clone.importedExpression !== undefined) {
+        clone.importedExpression =
+            local(clone.importedExpression, clone.importedDialect);
+    }
+    if (clone.dialects) {
+        const read = (d) => d === 'ANSI_SQL' ? targetDialect : d;
+        clone.dialects = clone.dialects.map(d => ({ ...d, expression: local(d.expression, read(d.dialect)) }));
+    }
+    return clone;
+}
+// `over` laid onto `base`: every property `over` sets wins, and every one it
+// leaves unset comes from `base`. When `over` carries SQL, `base`'s binding is
+// dropped whole, so an expression and a dialect list from two different
+// declarations never end up on one field. When it carries none, its binding
+// properties (a lone `stringForm` or `importedDialect`) are ignored and
+// `base`'s binding stands.
+function mergeBinding(base, over) {
+    const merged = structuredClone(base);
+    const bound = (0, ir_1.isFieldBound)(over);
+    if (bound) {
+        for (const k of ir_1.FIELD_BINDING_KEYS)
+            delete merged[k];
+    }
+    const binding = new Set(ir_1.FIELD_BINDING_KEYS);
+    for (const [k, v] of Object.entries(over)) {
+        if (v === undefined || (!bound && binding.has(k)))
+            continue;
+        merged[k] = structuredClone(v);
+    }
+    return merged;
+}
+// The field `name` as inherited down `chain`, the ancestors that declare it.
+// The chain is folded in order of descent, root first: the root's declaration
+// is the definition, and each descendant's lays its binding over it.
+// Breadth-first
+// distance is not that order when two paths to the entity differ in length, so
+// 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`, 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, into);
+        merged = merged ? mergeBinding(merged, local) : local;
+    }
+    return merged;
+}
+// Whether a field declaration carries neither a binding nor any part of a
+// definition. Redeclaring an inherited field this way is a no-op.
+function setsNothing(field) {
+    return !(0, ir_1.isFieldBound)(field) &&
+        ir_1.FIELD_DEFINITION_KEYS.every(k => field[k] === undefined);
+}
+// Throws unless every ancestor in `declaring` lies on one line of descent, so
+// that one declaration plainly overrides another. Two ancestors that each
+// declare the field, with neither extending the other, leave its definition
+// ambiguous.
+function requireOneChain(entity, field, declaring, ancestorsOf) {
+    for (let i = 0; i < declaring.length; i++) {
+        for (let j = i + 1; j < declaring.length; j++) {
+            const a = declaring[i], b = declaring[j];
+            const related = (ancestorsOf.get(a) ?? []).includes(b) ||
+                (ancestorsOf.get(b) ?? []).includes(a);
+            if (!related) {
+                throw new InheritanceError('ambiguous-field', `entity '${entity}' inherits field '${field}' from '${a}' and ` +
+                    `from '${b}', and neither extends the other, so nothing says ` +
+                    `which wins; declare or rebind '${field}' on only one of them`);
+            }
+        }
+    }
+}
+// Computes the de-duplicated transitive ancestor set for `start`, ORDERED
+// NEAREST-FIRST (breadth-first by distance): direct parents in declared order,
+// then grandparents, and so on. Nearest-first is what makes field flattening's
+// "nearest definition wins" correct -- a field defined by both a direct parent
+// and a grandparent must resolve to the direct parent's. Direct parents are
+// read from the pre-mutation snapshot so resolution is order-independent.
+//
+// A parent edge that points back to `start` is a cycle, and a parent that is
+// not an entity in the model is a typo; both are hard errors. A cycle that does
+// not pass through `start` is caught when an entity on it is resolved, and
+// every entity is. A node re-reached through a second path (a diamond) is
+// simply skipped -- it is already included at its nearest distance.
+function transitiveAncestors(start, byName, directParents) {
+    const result = [];
+    const seen = new Set([start]);
+    // Queue of (child that declared the edge, parent) so a cycle error can name
+    // the offending child. Seeded with `start`'s direct parents in declared
+    // order.
+    const queue = (directParents.get(start) ?? []).map(name => ({ from: start, name }));
+    while (queue.length) {
+        const { from, name } = queue.shift();
+        if (name === start) {
+            throw new InheritanceError('cycle', `entity '${from}' extends '${name}', which is already a supertype ` +
+                `on this chain; 'extends' must not form a cycle`);
+        }
+        if (!byName.has(name)) {
+            throw new InheritanceError('unknown-parent', `entity '${from}' extends unknown entity '${name}'; it is not ` +
+                `defined in the model`);
+        }
+        if (seen.has(name))
+            continue; // diamond: already included at its nearest
+        seen.add(name);
+        result.push(name);
+        for (const gp of directParents.get(name) ?? []) {
+            queue.push({ from: name, name: gp });
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,291 @@
+import { Entity, Field, ProfileSpec, SemanticModel } from './ir';
+import { LoadOptions, SemanticModelError } from './loader';
+export declare const DEFAULT_PROFILE = "default";
+export declare function plainCopy(value: unknown): any;
+export interface AvailabilityReport {
+    profile: string;
+    unboundFields: string[];
+    excludedFields: string[];
+    droppedEntities: {
+        name: string;
+        reason: string;
+    }[];
+    droppedMetrics: {
+        name: string;
+        reason: string;
+        field?: string;
+    }[];
+    droppedRelationships: {
+        name: string;
+        reason: string;
+    }[];
+    droppedActions: {
+        name: string;
+        reason: string;
+    }[];
+    droppedFields: {
+        name: string;
+        reason: string;
+    }[];
+    warnings: string[];
+}
+/**
+ * Returns a clone of `model` reduced to what `profileName` can answer: unbound
+ * and excluded fields taken off their entities, with every field that reads
+ * one of them, directly or through other fields; every excluded metric and
+ * every metric that reads an unavailable field dropped; and every action with
+ * no executor dropped. A field counts whether the entity declares or inherits
+ * 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. 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 | null | undefined): {
+    model: SemanticModel;
+    report: AvailabilityReport;
+};
+export declare function withoutExclusions(model: SemanticModel): SemanticModel;
+export declare function resolvedEntities(model: SemanticModel): Entity[];
+export declare function inheritedNamesOf(model: SemanticModel, entityName: string, byName?: Map<string, Entity>): Set<string>;
+/**
+ * Reads a profile file into the IR's `ProfileSpec`. Throws on anything a
+ * profile may not say: an unknown key at any level, a value of the wrong shape,
+ * a field in both `fields` and `fields_exclude`, `"*"` inside a
+ * `metrics_exclude` list, or a `name` other than `profileName`. A field
+ * expression and an action's executor are read by the loader's own readers, so
+ * each follows the rules it follows in a model file. A source is kept as
+ * written, and applyProfile reads it with the loader's reader too. A field
+ * expression's short form means `ANSI_SQL` in either flavor. Actions are out of
+ * scope for the preview, so nothing more is checked. With `skipActions`, the
+ * profile's actions are not read.
+ */
+export declare function loadProfileFile(text: string, profileName: string, opts?: {
+    skipActions?: boolean;
+}): ProfileSpec;
+export type DialectLoad = Pick<LoadOptions, 'sourceDialects'> & {
+    sourceDatabases?: ReadonlyMap<string, string>;
+};
+/** How a profile's values are read, matching the load of the model. */
+export interface ApplyProfileOptions {
+    load?: Pick<LoadOptions, 'dialect' | 'sourceDialects'>;
+    warnings?: string[];
+    from?: {
+        document: string;
+        warnings: string[];
+    };
+}
+/**
+ * Returns a copy of `model` with `profile` applied: each named entity's
+ * source, its keys where the profile states them, its field bindings, as a
+ * binding-only redeclaration for a field the entity inherits, and its
+ * `fields_exclude`; each relationship's join columns; `metrics_exclude`; and
+ * each action's executor, which is taken as given, since actions are out of
+ * preview scope. A field a profile binds keeps every dialect text the profile
+ * wrote. An excluded field is marked in `excludedFields`, and loses its
+ * binding when no entity inherits it. The input is never mutated.
+ *
+ * Throws, naming the profile, when the profile repeats a name, leaves a field
+ * entry with nothing to bind, both binds and excludes a field, puts "*" inside
+ * a list, names something the model does not declare, binds an abstract
+ * entity, states one of a relationship's join column lists without the
+ * other or gives both lists with different lengths, gives a source or
+ * expression the loader's readers reject, or is applied to a model that
+ * declares a `sql` executor, which belongs in each profile.
+ */
+export declare function applyProfile(model: SemanticModel, profile: ProfileSpec, opts?: Omit<ApplyProfileOptions, 'from'>): SemanticModel;
+/**
+ * Reads the profile file `text` and applies it to `model`, or returns the
+ * error that stops it, naming the profile. The warnings are those of the
+ * model file's load (`opts.from`), less the ones about values the profile
+ * replaces, followed by those for the values it sets, each prefixed with the
+ * document name.
+ */
+export declare function applyProfileFile(model: SemanticModel, text: string, profileName: string, opts?: Omit<ApplyProfileOptions, 'warnings'>): {
+    model: SemanticModel;
+    warnings: string[];
+} | {
+    error: string;
+};
+/** A profile applied to a model document loaded on its own. */
+export interface AppliedProfile {
+    model: SemanticModel;
+    warnings: string[];
+}
+/**
+ * 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. 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;
+    text: string;
+} | {
+    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
+ * the layout orders profile files. Push, `kcmd profiles` and the runtime all
+ * read them here, so they agree. Throws SemanticModelError, naming the
+ * document as a load does, when googleBlockProfiles throws, such as on block
+ * profiles a load rejects.
+ */
+export declare function declaredProfiles(doc: {
+    name: string;
+    text: string;
+}, files: Array<{
+    name: string;
+    text: string;
+}>): DeclaredProfile[];
+/** A profile applied to one model document. */
+export type DocumentProfile = ({
+    kind: 'file';
+} & AppliedProfile) | {
+    kind: 'error';
+    error: string;
+    stage: 'load' | 'apply';
+} | {
+    kind: 'missing';
+    declared: string[];
+};
+/**
+ * Finds the profile `profileName` among `profiles`, the ones the model
+ * document `doc` declares, and applies it, as push, `kcmd profiles` and the
+ * runtime do. It applies to the document loaded on its own.
+ */
+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
+ * a profile file names that file, as the profile checks do. An error applying
+ * a profile from a GOOGLE block names the model document.
+ */
+export declare function profileErrorMessage(docName: string, res: Extract<DocumentProfile, {
+    kind: 'error';
+}>, profileName: string, profileFiles: Array<{
+    name: string;
+    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;
+/**
+ * The error for a model document `docName` whose `profiles` include one named
+ * `default` in any letter case. Push refuses every graph push of such a
+ * model, and the runtime refuses the model too. Undefined when no profile has
+ * that name.
+ */
+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 | null | undefined): Array<{
+    text: string;
+    dialect: string;
+}>;
+export declare function noTextFor(f: Parameters<typeof textsFor>[0], dialects: string[]): boolean;
+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<{
+    entity: Entity;
+    field: Field;
+    table: TableDialects;
+}>;
+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 | null | undefined;
+/** What the caller of validateProfileCompleteness checks itself. */
+export interface CompletenessOptions extends DialectLoad {
+    ownSqlOnly?: {
+        dialect?: string | null;
+    };
+}
+/**
+ * Returns one message per reason `profile` cannot be deployed against
+ * `baseModel`, or an empty list. Checks a single profile: nothing unknown,
+ * every field it binds holding SQL on each entity that inherits it, every
+ * concrete entity bound and all in one database, its own keys where the model
+ * file states keys, every relationship bound, every field the model file
+ * leaves unbound accounted for, every field whose expression reads a column
+ * restated or excluded, and exclusions closed under dependency, metrics
+ * included. The check that join columns cover a key of the target is in
+ * validateProfileConsistency. An expression the SQL parser cannot read
+ * is skipped by the rules that read references, with a message in `warnings`.
+ * `opts` says what the caller checks itself, so that nothing is reported
+ * twice.
+ */
+export declare function validateProfileCompleteness(baseModel: SemanticModel, profile: ProfileSpec, warnings?: string[], opts?: CompletenessOptions): string[];
+/**
+ * Returns one message for each binding, the model file's included, whose
+ * `to_columns` for a relationship cover no primary or unique key of its
+ * target, or an empty list. A superset of a key covers it (see coversKey).
+ * Keys and join columns are compared as written. A binding whose key or join
+ * columns are not all column names (isColumnName) is left out. `applied` names
+ * the profile the push applies. The "covers no key" check then leaves out that
+ * 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 | null): {
+    owner: string;
+    column: string;
+} | undefined;
+export declare function statesKey(primaryKey: string[] | undefined, uniqueKeys: string[][] | undefined): boolean;
+export {};