@google-cloud/kcmd 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,247 @@
+"use strict";
+// Defines the Semantic Model intermediate representation (IR).
+//
+// The IR is the in-memory contract for a semantic model. It represents
+// semantics only: a graph of entities (nodes) connected by relationships
+// (edges), plus model-level metrics.
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONSTRAINT_SEVERITIES = exports.VIOLATION_EFFECTS = exports.SQL_EXECUTOR_VERBS = exports.CONCEPT_OPERATIONS = exports.FIELD_DEFINITION_KEYS = exports.FIELD_BINDING_KEYS = exports.DATA_TYPES = exports.ALLOWED_DIALECTS = void 0;
+exports.normalizeDataType = normalizeDataType;
+exports.isTimeDimension = isTimeDimension;
+exports.fieldBinding = fieldBinding;
+exports.isFieldBound = isFieldBound;
+exports.coversKey = coversKey;
+exports.expressionForDialect = expressionForDialect;
+exports.ALLOWED_DIALECTS = [
+    'ANSI_SQL', 'BIGQUERY', 'SPANNER', 'MYSQL',
+    'POSTGRES', 'ALLOYDB', 'SQLSERVER', 'SNOWFLAKE', 'DATABRICKS',
+];
+/**
+ * The open format's `datatype` vocabulary, mirroring Apache Ossie's `DataType`:
+ * a CLOSED, case-sensitive set of logical types, independent of physical
+ * representation. It is optional; omit it when the type is unknown. `Opaque`
+ * marks an unknown type: the loader reads it as no type, and the catalog stores
+ * it where a type is required. No custom extension supplies a real type for
+ * it. The loader enforces this set at parse time, so a `type` on the IR is
+ * always one of these.
+ */
+exports.DATA_TYPES = [
+    'String',
+    'Integer',
+    'Decimal',
+    'Float',
+    'Boolean',
+    'Date',
+    'Time',
+    'DateTime',
+    'DateTimeTz',
+    'Opaque',
+];
+const CANONICAL_DATA_TYPES = exports.DATA_TYPES.filter((t) => t !== 'Opaque');
+/**
+ * Normalizes a raw `datatype` string according to the document's flavor.
+ *
+ * In `0.2.0.dev0`, matching is strictly case-sensitive. In `0.2.0.dev0/google`,
+ * matching is case-insensitive and returns the canonical spelling. In both
+ * flavors, an omitted `datatype` and `Opaque` normalize to `type: undefined`.
+ */
+function normalizeDataType(raw, version) {
+    if (raw === undefined) {
+        return { ok: true, type: undefined };
+    }
+    const caseInsensitive = version === '0.2.0.dev0/google';
+    const matches = (a, b) => caseInsensitive ? a.toLowerCase() === b.toLowerCase() : a === b;
+    if (matches(raw, 'Opaque')) {
+        return { ok: true, type: undefined };
+    }
+    const found = CANONICAL_DATA_TYPES.find(t => matches(raw, t));
+    if (found) {
+        return { ok: true, type: found };
+    }
+    return { ok: false };
+}
+// The temporal subset of DataType (Date / Time / DateTime / DateTimeTz); a
+// field of one of these types is a time dimension by default (see
+// isTimeDimension).
+const TEMPORAL_TYPES = new Set([
+    'Date',
+    'Time',
+    'DateTime',
+    'DateTimeTz',
+]);
+/**
+ * A field's effective temporal-dimension role, mirroring the open format's
+ * `is_time_dimension()` (e.g. Apache Ossie's `OSIField`): a field must carry
+ * `dimension` metadata to be a dimension at all; within it an explicit `isTime`
+ * takes precedence, otherwise the role defaults from a temporal `type`.
+ */
+function isTimeDimension(field) {
+    if (!field.dimension)
+        return false;
+    if (field.dimension.isTime !== undefined)
+        return field.dimension.isTime;
+    return field.type !== undefined && TEMPORAL_TYPES.has(field.type);
+}
+// The physical column (or SQL) a field binds to when no engine is named, or
+// undefined when it carries neither expression. A field's target/canonical
+// `expression` wins; a field awaiting transpilation falls back to its imported
+// vendor expression, which still names a real column. Undefined here is not
+// the same as unbound: a field bound only through a `dialects` list has no
+// text here yet counts as bound (see isFieldBound). The graph generators ask
+// for their own engine's text through `expressionForDialect` instead.
+function fieldBinding(field) {
+    return field.expression ?? field.importedExpression;
+}
+// The properties of a field that bind it to a column, and the ones that define
+// what it is. A subtype that redeclares an inherited field may set binding
+// properties and never definition properties. Together with `name` they are
+// every property a field has; the check below fails to compile if a property
+// is added to Field without being placed in one list or the other.
+exports.FIELD_BINDING_KEYS = [
+    'expression', 'dialects', 'stringForm', 'importedExpression',
+    'importedDialect',
+];
+exports.FIELD_DEFINITION_KEYS = [
+    'type', 'label', 'dimension', 'description', 'aiContext', 'customExtensions',
+];
+const everyFieldKeyListed = true;
+void everyFieldKeyListed;
+/**
+ * Whether a field is bound to a column under the current binding: it carries an
+ * expression, an imported vendor expression, or a non-empty dialect list.
+ * `stringForm` and `importedDialect` describe a binding and are not one on
+ * their own. Inheritance, profile pruning and push validation use this test.
+ * A graph generator asks a narrower question, whether the field has SQL for its
+ * engine (see expressionForDialect), so a bound field can still be left out of
+ * one engine's graph.
+ */
+function isFieldBound(field) {
+    return fieldBinding(field) !== undefined || (field.dialects?.length ?? 0) > 0;
+}
+/**
+ * Whether a relationship's `to_columns` cover the primary key or a unique key.
+ * A key is covered when every one of its columns is among `to_columns`, so a
+ * superset of a key covers it, since each row still matches at most one target
+ * row. Column names compare as BigQuery compares them: ignoring case, and
+ * without the backticks that only quote a name.
+ */
+function coversKey(toColumns, primaryKey, uniqueKeys) {
+    const columnKey = (c) => c.replace(/^`(.*)`$/, '$1').toLowerCase();
+    const has = new Set(toColumns.map(columnKey));
+    return [primaryKey, ...uniqueKeys].some(key => key.length > 0 && key.every(c => has.has(columnKey(c))));
+}
+/**
+ * Selects the SQL expression for a target engine from a Field or Metric.
+ *
+ * With a non-empty `dialects` list, returns the entry matching `targetDialect`;
+ * failing that, and where the target is not already `ANSI_SQL`, falls back to
+ * the `ANSI_SQL` entry; failing both, returns `undefined`. With `dialects`
+ * empty or absent, returns `item.importedExpression` when `importedDialect` is
+ * the target, and `item.expression` otherwise.
+ */
+function expressionForDialect(item, targetDialect) {
+    if (item.dialects && item.dialects.length > 0) {
+        const exact = item.dialects.find(d => d.dialect === targetDialect);
+        if (exact)
+            return exact.expression;
+        if (targetDialect !== 'ANSI_SQL') {
+            const ansi = item.dialects.find(d => d.dialect === 'ANSI_SQL');
+            if (ansi)
+                return ansi.expression;
+        }
+        return undefined;
+    }
+    if (item.importedExpression !== undefined &&
+        item.importedDialect === targetDialect) {
+        return item.importedExpression;
+    }
+    return item.expression;
+}
+/**
+ * What an action does to a concept it affects.
+ *
+ * One vocabulary covers entities and relationships alike, because both admit
+ * the same three acts. An edge is not only added and removed: a many-to-many
+ * relationship is backed by a junction table with fields of its own (see
+ * Association), so modifying an enrollment's grade is as ordinary as modifying
+ * an order's total. Splitting the vocabulary by kind would make that change
+ * inexpressible and would buy a policy predicate nothing.
+ */
+exports.CONCEPT_OPERATIONS = ['create', 'modify', 'delete'];
+// The verbs a SQL executor's statement may begin with. A statement is one write,
+// so there is no SELECT here and no DDL: a statement that reads is a query and
+// belongs in a metric, and a statement that reshapes the schema is not an action.
+exports.SQL_EXECUTOR_VERBS = ['INSERT', 'UPDATE', 'DELETE'];
+/**
+ * What a violated constraint does to the write that tripped it.
+ *
+ *   - `reject`   the write is refused. Nobody is allowed to approve it, which
+ *                is what makes the rule an invariant rather than a policy.
+ *   - `escalate` the write is held and a person decides. The rule is a business
+ *                threshold, so somebody is allowed to say yes.
+ *   - `warn`     the write proceeds and the violation is reported.
+ *
+ * An engine reading the catalog needs this in order to route. Without it every
+ * rule publishes with the same shape, and a $30 credit that needs a supervisor
+ * is indistinguishable from one that is simply forbidden.
+ *
+ * This is a disposition, not a magnitude, and the two are deliberately separate
+ * keys. `escalate` is not "between" reject and warn on a scale of badness: it is
+ * a different control flow, and what it really states is that an approver
+ * exists. Two rules can be equally grave -- both guarding a million-dollar write
+ * -- and differ only in whether anyone in the organization is entitled to say
+ * yes. See CONSTRAINT_SEVERITIES for the magnitude.
+ *
+ * `escalate` names that an approver exists. It does not name who: an approver
+ * role is not modeled yet.
+ *
+ * The consequence is a field rather than something a `judgment` states in its
+ * own prose, because three things need it without running a judge. An
+ * unrunnable judge -- none configured, a failed call, a timeout -- still has to
+ * route the breach it could not evaluate. A search for the rules that can stop
+ * a write cannot read prose. And a policy DSL states its effect in the rule
+ * head, so a rule whose consequence is only implied by its wording cannot be
+ * lowered into OPA or Cedar.
+ *
+ * A judgment may declare any of the three, `reject` included. What settles a
+ * judgment can decide two identical proposals differently, and `reject` leaves
+ * no appeal, so that pairing is the riskiest thing this model can express. It
+ * is still a bet an organization is entitled to place, and refusing to
+ * represent it would move the policy out of the catalog rather than prevent it.
+ * It is made auditable instead: `evaluation` publishes `judged` beside the
+ * word, so "unappealable rules settled by a model" is one query. `onViolation`
+ * is required on a judgment rather than defaulted, because a forgotten word
+ * would produce exactly that pairing silently.
+ *
+ * A constraint's word is the consequence of the one condition it states. A
+ * policy whose conditions carry different consequences is written as several
+ * constraints, which `guards` on an action lists together; the strictest
+ * consequence among the violated ones is what the action does. See
+ * docs/semantic-model/actions.md for a worked policy.
+ *
+ * STATUS: the declared word is published, read back, and routed on for the
+ * rules something settles. A judgment is settled where an action names it in
+ * `guards`, and `warn` reports while `reject` and `escalate` stop the call;
+ * `escalate` says so in the refusal, because nothing here has an approver to
+ * route to. An expression is still text nothing computes, so its word decides
+ * nothing yet.
+ */
+exports.VIOLATION_EFFECTS = ['reject', 'escalate', 'warn'];
+/**
+ * How grave a violation of a constraint is, independent of what the engine does
+ * about it.
+ *
+ * Ranking and reporting want this: which of forty violations in a batch to show
+ * a human first, which to page on. Enforcement does not -- that is
+ * `onViolation`, and the split is the point. A `low` rule may still be an
+ * absolute `reject`, and a `critical` one may be a `warn` because the
+ * organization is not ready to block on it yet.
+ *
+ * The scale is the ordinary four-point one, and it avoids `warning` on purpose:
+ * a severity called `warning` sitting beside an effect called `warn` would read
+ * as the same statement made twice.
+ *
+ * STATUS: authored, published and read back. Nothing ranks or routes on it yet.
+ */
+exports.CONSTRAINT_SEVERITIES = ['critical', 'high', 'medium', 'low'];

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

@@ -0,0 +1,45 @@
+import { Entry } from '../gcp/dataplex';
+import { Action, SemanticModel } from './ir';
+export declare function actionEntryTypeName(dest: {
+    project: string;
+}): string;
+export declare function actionAspectTypeName(dest: {
+    project: string;
+}): string;
+export declare function actionAspectKey(dest: {
+    project: string;
+}): string;
+export interface ActionEmitContext {
+    project: string;
+    entry(entryId: string): string;
+    anchor: string;
+    claim(entryId: string, label: string): boolean;
+    publishedEntities: Set<string>;
+}
+export declare function actionEntryId(modelId: string, actionName: string): string;
+export declare function actionOwnedPrefix(modelId: string): string;
+/**
+ * One entry per action, to append to the model's entries.
+ *
+ * Empty when the model declares no actions, so a model without actions is
+ * unchanged from before actions existed. Warns once when it is non-empty:
+ * actions reach Knowledge Catalog and nowhere else, which is worth saying out
+ * loud on a push that also deploys a graph.
+ */
+export declare function actionEntries(model: SemanticModel, modelId: string, ctx: ActionEmitContext, warnings: string[]): Entry[];
+export declare function isActionEntry(entry: Entry): boolean;
+export declare function actionAspectTypes(entryTypeBase: string): string[];
+/**
+ * Recovers one action from its entry, the inverse of actionEntries.
+ *
+ * A parameter recovers exactly what was stored, projection and all. Nothing is
+ * re-derived here: a derived parameter's type was resolved once, at load, and
+ * the aspect carries the answer, so a pull that recovered the concept and one
+ * that did not produce the same parameter rather than two different ones.
+ *
+ * An entry with NO executor recovers as an action with none: that is a legal
+ * published state, not damage. An entry whose executor names a kind but lacks
+ * the coordinates that kind needs is malformed, and returns undefined with a
+ * warning, so one bad entry degrades itself rather than the pull.
+ */
+export declare function readAction(entry: Entry, warnings: string[]): Action | undefined;