@google-cloud/kcmd 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,10 @@
+export type NameKind = 'model' | 'profile' | 'deployment' | 'entity' | 'metric' | 'relationship' | 'field';
+export declare function nameProblem(kind: NameKind, name: string): string | undefined;
+export declare const MAX_ENTRY_DESCRIPTION = 2000;
+export declare const MAX_BIGQUERY_DESCRIPTION = 1024;
+export declare const MAX_BIGQUERY_SYNONYM_COUNT = 8;
+export declare const MAX_BIGQUERY_SYNONYM_LENGTH = 300;
+export declare function qualifierCaseError(where: string, col: {
+    qualifier?: string;
+    name: string;
+}, entityNames: string[]): string | undefined;

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

@@ -0,0 +1,85 @@
+"use strict";
+// The names a semantic model may give its parts. A name does not stay in the
+// model file: it is joined into a Knowledge Catalog entry id, written into
+// SQL and graph queries, used as a profile's filename and passed on a
+// comma-separated flag. One pattern per kind keeps a name safe in all of them,
+// so there is no list of forbidden characters to keep up to date.
+//
+// - A model, profile or deployment name may contain a hyphen, as in
+//   `sales-analytics`: none of them appears in SQL or a graph query.
+// - An entity, metric or relationship name appears in expressions, the graph
+//   DDL and graph queries, so it may not.
+// - A field name is a BigQuery column name, so it may begin with an underscore
+//   and is capped shorter.
+// The 500-character cap is a Knowledge Catalog limit.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BIGQUERY_SYNONYM_LENGTH = exports.MAX_BIGQUERY_SYNONYM_COUNT = exports.MAX_BIGQUERY_DESCRIPTION = exports.MAX_ENTRY_DESCRIPTION = void 0;
+exports.nameProblem = nameProblem;
+exports.qualifierCaseError = qualifierCaseError;
+const WITH_HYPHEN = {
+    pattern: /^[A-Za-z][A-Za-z0-9_-]*$/,
+    shown: '^[A-Za-z][A-Za-z0-9_-]*$',
+    says: 'a letter, then letters, digits, underscores or hyphens',
+    max: 500,
+};
+const IN_SQL = {
+    pattern: /^[A-Za-z][A-Za-z0-9_]*$/,
+    shown: '^[A-Za-z][A-Za-z0-9_]*$',
+    says: 'a letter, then letters, digits or underscores',
+    max: 500,
+};
+const FIELD = {
+    pattern: /^[A-Za-z_][A-Za-z0-9_]*$/,
+    shown: '^[A-Za-z_][A-Za-z0-9_]{0,299}$',
+    says: 'a letter or underscore, then letters, digits or underscores',
+    max: 300,
+};
+const RULES = {
+    model: WITH_HYPHEN,
+    profile: WITH_HYPHEN,
+    deployment: WITH_HYPHEN,
+    entity: IN_SQL,
+    metric: IN_SQL,
+    relationship: IN_SQL,
+    field: FIELD,
+};
+const LABEL = {
+    model: 'Model',
+    profile: 'Profile',
+    deployment: 'Deployment',
+    entity: 'Entity',
+    metric: 'Metric',
+    relationship: 'Relationship',
+    field: 'Field',
+};
+// Why `name` is not a valid name for a `kind`, or undefined when it is. A name
+// over the length limit is shown cut short, so the message stays readable.
+function nameProblem(kind, name) {
+    const rule = RULES[kind];
+    if (name.length > rule.max) {
+        return `${LABEL[kind]} name '${Array.from(name).slice(0, 40).join('')}...' is ${name.length} characters long; names may be at most ${rule.max} characters.`;
+    }
+    if (!rule.pattern.test(name)) {
+        return `${LABEL[kind]} name '${name}' is not valid; names must match ${rule.shown}: ${rule.says}.`;
+    }
+    return undefined;
+}
+// The most characters a description stored as a Knowledge Catalog entry's
+// description may have: the model's, an entity's, a metric's and a
+// relationship's.
+exports.MAX_ENTRY_DESCRIPTION = 2000;
+// BigQuery's limits on the OPTIONS of a graph label or property.
+exports.MAX_BIGQUERY_DESCRIPTION = 1024;
+exports.MAX_BIGQUERY_SYNONYM_COUNT = 8;
+exports.MAX_BIGQUERY_SYNONYM_LENGTH = 300;
+// The error for a reference whose qualifier matches one of `entityNames` only
+// when case is ignored, or undefined. `where` names the field or metric.
+function qualifierCaseError(where, col, entityNames) {
+    const q = col.qualifier;
+    if (q === undefined || entityNames.includes(q))
+        return undefined;
+    const entity = entityNames.find(n => n.toLowerCase() === q.toLowerCase());
+    return entity &&
+        `${where}: '${q}.${col.name}' uses qualifier '${q}', which differs in ` +
+            `case from entity '${entity}'; entity names are case-sensitive.`;
+}

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

@@ -0,0 +1,60 @@
+import { SemanticModel } from './ir';
+export interface SerializedFile {
+    fileName: string;
+    content: string;
+}
+export interface SerializeFilesResult {
+    files: SerializedFile[];
+    warnings: string[];
+}
+export interface SerializeResult {
+    yaml: string;
+    warnings: string[];
+}
+export interface SerializeOptions {
+    logical?: boolean;
+    compactFlow?: boolean;
+    /**
+     * The column at which a long string is folded onto the next line; 0 keeps
+     * every value on one line. Defaults to 80.
+     */
+    lineWidth?: number;
+}
+/**
+ * Serializes a semantic model and its sidecar profile files. The returned
+ * `files` list always starts with `<model.name>.yaml`. Under `GOOGLE_VERSION`,
+ * each entry in `model.profiles` follows as
+ * `<model.name>.profile.<profile.name>.yaml`, except that a reserved
+ * (`default`), invalid, or case-insensitively repeated name is skipped with a
+ * warning. Under `OSSIE_VERSION`, valid profiles are written into the model's
+ * `GOOGLE` `custom_extensions` block and no profile files are emitted.
+ */
+export declare function serializeModelFiles(model: SemanticModel, opts?: SerializeOptions): SerializeFilesResult;
+/**
+ * Serializes a single semantic model to a YAML document string in the open
+ * AI-first semantics format. The document contains exactly this one model;
+ * `pull` writes one file per model
+ * (catalog/EntryGroups/<entryGroup>/<model>.yaml). It is the first file
+ * `serializeModelFiles` returns, with the warnings for every file it builds.
+ *
+ * Warnings flag IR content that has no loadable representation (an association
+ * relationship's junction detail, an imported expression in an unknown dialect,
+ * dropped `GOOGLE` blocks under GOOGLE_VERSION, Google-only constructs and
+ * missing join columns under OSSIE_VERSION, or loader-invalid gaps), so the
+ * caller can surface the lossy edge.
+ *
+ * `logical` marks the model as a purely logical one (no physical binding).
+ * Under GOOGLE_VERSION it suppresses the missing-source and missing-expression
+ * warnings, which flag a lossy pull of a bound model. OSSIE_VERSION requires
+ * both, so they are still given. An OWL import sets it, and so does a
+ * second-generation pull, which loses no binding.
+ *
+ * `compactFlow` renders leaf collections (scalar sequences, all-scalar maps) in
+ * flow style so the output matches the compact convention the semantic-model
+ * guides author by hand and is byte-for-byte reproducible there. An OWL import
+ * sets it; `pull` does not.
+ */
+export declare function serializeModel(model: SemanticModel, opts?: SerializeOptions): SerializeResult;
+export declare function modelDocument(model: SemanticModel, warnings?: string[], logical?: boolean): Record<string, any>;
+export declare function compact<T extends Record<string, any>>(obj: T): T;
+export declare function nonEmpty<T>(items: T[] | undefined): T[] | undefined;