@google-cloud/kcmd 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,188 @@
+"use strict";
+// Knowledge Catalog resource naming and ID helpers.
+//
+// Provides a shared set of rules for constructing and parsing Knowledge Catalog
+// resource names across the emitter, model validation, the catalog reader, and
+// the deployment pipeline. This module imports only the IR to avoid circular
+// dependencies.
+//
+// Terminology used in this module:
+// - A "full resource name" includes the GCP container path, e.g.
+//   `projects/<p>/locations/<l>/entryGroups/<eg>/entries/<entryId>`.
+// - A "bare entry ID" (or "entry-link ID") is the trailing `<entryId>`
+//   (or `<linkId>`) segment without the container prefix, e.g.
+//   `retail_sales.entities.store_orders` (V1) or
+//   `retail_sales/entities/store_orders` (V2).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Namer = exports.DEFAULT_TYPE_LOCATION = exports.DEFAULT_TYPE_PROJECT = void 0;
+exports.relationshipLinkId = relationshipLinkId;
+exports.semanticLinkId = semanticLinkId;
+exports.ownedEntryIdPrefixes = ownedEntryIdPrefixes;
+exports.entryIdOf = entryIdOf;
+exports.slug = slug;
+exports.linkSlug = linkSlug;
+const node_crypto_1 = require("node:crypto");
+// Where the `semantic-*` and `schema` system types live: built-in types in
+// project `dataplex-types`, location `global`. Callers may override to
+// reference them from a staging project.
+exports.DEFAULT_TYPE_PROJECT = 'dataplex-types';
+exports.DEFAULT_TYPE_LOCATION = 'global';
+// Matches the container path and trailing bare ID of any Knowledge Catalog
+// resource name:
+// - Entry-group paths (`ENTRY_GROUP_PATH_RE`):
+//   `projects/<p>/locations/<l>/entryGroups/<eg>/(entries|entryLinks)/<id>`
+// - Type paths (`TYPE_PATH_RE`):
+//   `projects/<p>/locations/<l>/(entryTypes|aspectTypes|entryLinkTypes)/<id>`
+const ENTRY_GROUP_PATH_RE = /entryGroups\/[^/]+\/(?:entries|entryLinks)/;
+const TYPE_PATH_RE = /entryTypes|aspectTypes|entryLinkTypes/;
+const RESOURCE_ID_RE = new RegExp(`^projects/[^/]+/locations/[^/]+/` +
+    `(?:${ENTRY_GROUP_PATH_RE.source}|${TYPE_PATH_RE.source})/(.+)$`);
+/**
+ * Builds the fully-qualified resource names and bare entry/link IDs for a
+ * destination. Kept in one place so entry/type name construction is consistent
+ * and the emitter body reads as pure mapping.
+ */
+class Namer {
+    typeProject;
+    typeLocation;
+    container;
+    v2Aspects;
+    constructor(opts) {
+        this.typeProject = opts.systemTypeProject ?? exports.DEFAULT_TYPE_PROJECT;
+        this.typeLocation = opts.systemTypeLocation ?? exports.DEFAULT_TYPE_LOCATION;
+        this.container = `projects/${opts.project}/locations/${opts.location}/entryGroups/${opts.entryGroup}`;
+        this.v2Aspects = opts.v2Aspects ?? false;
+    }
+    /** Full resource name of a system type. `kind` selects the collection. */
+    typeName(kind, name) {
+        return `projects/${this.typeProject}/locations/${this.typeLocation}/${kind}Types/${name}`;
+    }
+    /**
+     * Aspect-map key: the `project.location.type` reference form the client keys
+     * an entry's aspects by (see dataplex._nameToTypeRef / _fixEntry).
+     */
+    aspectRef(name) {
+        return `${this.typeProject}.${this.typeLocation}.${name}`;
+    }
+    /** Full resource name of an entry in the destination entry group. */
+    entry(entryId) {
+        return `${this.container}/entries/${entryId}`;
+    }
+    /** Full resource name of an entry link in the destination entry group. */
+    entryLink(linkId) {
+        return `${this.container}/entryLinks/${linkId}`;
+    }
+    /**
+     * Bare entry ID for a semantic model, used as the `semantic-model` anchor
+     * entry's ID and as the prefix for action and constraint entry IDs.
+     *
+     * V1 sanitizes `model.name` with `slug()` because `model.name` may contain
+     * characters (e.g. spaces) that Knowledge Catalog disallows in entry IDs.
+     * V2 returns `model.name` verbatim because V2 model names are restricted to
+     * letters, digits, underscores and hyphens, all of which `slug()` keeps. This
+     * means `slug(model.name)` and `model.name` are equal for valid V2 models.
+     */
+    modelId(model) {
+        return this.v2Aspects ? model.name : slug(model.name);
+    }
+    /** Bare entry ID for an entity within a semantic model. */
+    entityId(model, entity) {
+        return this.v2Aspects ?
+            `${model.name}/entities/${entity.name}` :
+            `${slug(model.name)}.entities.${slug(entity.name)}`;
+    }
+    /** Bare entry ID for a metric within a semantic model. */
+    metricId(model, metric) {
+        return this.v2Aspects ?
+            `${model.name}/metrics/${metric.name}` :
+            `${slug(model.name)}.metrics.${slug(metric.name)}`;
+    }
+    /** Bare V2 entry ID for a relationship within a semantic model. */
+    relationshipId(model, rel) {
+        return `${model.name}/relationships/${rel.name}`;
+    }
+    /**
+     * Entry link IDs are more restricted than entry IDs: lowercase letters,
+     * numbers and hyphens only, starting with a letter (see `linkSlug`). Does not
+     * branch on `v2Aspects`.
+     */
+    linkId(model, rel) {
+        return relationshipLinkId(model.name, rel.name);
+    }
+}
+exports.Namer = Namer;
+/** Entry-link ID for a relationship on a model. */
+function relationshipLinkId(modelName, relName) {
+    return linkSlug(`${modelName}-${relName}`);
+}
+/**
+ * ID of a link push writes: `semantic-<kind>-` and the first 32 hex characters
+ * of the SHA-256 of `parts` joined by '/'. It must stay the same across
+ * releases, so that push finds the links it wrote.
+ */
+function semanticLinkId(kind, ...parts) {
+    const digest = (0, node_crypto_1.createHash)('sha256').update(parts.join('/'), 'utf8').digest('hex');
+    return `semantic-${kind}-${digest.slice(0, 32)}`;
+}
+/**
+ * Entry-ID prefixes owned by `modelName` across both the first-generation
+ * dotted layout and the second-generation slash layout.
+ *
+ * The dotted prefixes use `slug(modelName)` to match V1 entries, while the
+ * slash prefixes use `modelName` verbatim to match V2 entity, metric and
+ * relationship entries. Because V2 model names are restricted to letters,
+ * digits, underscores and hyphens, all of which `slug()` keeps,
+ * `slug(modelName)` and `modelName` are equal for valid V2 models.
+ *
+ * No push writes under `.files.` any more: an older kcmd stored a copy of
+ * each model and profile file there. The prefix stays so the next push
+ * deletes those copies.
+ */
+function ownedEntryIdPrefixes(modelName) {
+    const s = slug(modelName);
+    return [
+        `${s}.entities.`,
+        `${s}.metrics.`,
+        `${s}.actions.`,
+        `${s}.constraints.`,
+        `${s}.files.`,
+        `${modelName}/entities/`,
+        `${modelName}/metrics/`,
+        `${modelName}/relationships/`,
+    ];
+}
+/**
+ * Extracts the bare resource ID from a full Knowledge Catalog resource name
+ * (entry, entry link, or type), or returns `resourceName` unchanged if it does
+ * not match a known resource container.
+ *
+ * Matches known container collections via `RESOURCE_ID_RE` and leaves
+ * non-matching strings untouched, rather than falling back to
+ * `.split('/').pop()` (which would corrupt an already-bare V2 slash entry ID
+ * like `'retail_sales/entities/store_orders'` into `'store_orders'`).
+ */
+function entryIdOf(resourceName) {
+    const m = resourceName.match(RESOURCE_ID_RE);
+    return m ? m[1] : resourceName;
+}
+/**
+ * Entry IDs allow letters, numbers, underscores, hyphens, and periods; maps
+ * anything else to an underscore.
+ */
+function slug(s) {
+    return s.replace(/[^A-Za-z0-9_.-]/g, '_');
+}
+/**
+ * Entry link IDs allow only lowercase letters, numbers and hyphens, must start
+ * with a letter, must end with a letter or number, and are capped at 63 chars.
+ */
+function linkSlug(s) {
+    const out = s.toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^[^a-z]+/, '')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 63)
+        .replace(/-+$/, '');
+    return out || 'link';
+}

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

@@ -0,0 +1,29 @@
+import type { Entry, EntryLink } from '../gcp/dataplex';
+import type { OverviewSidecar } from '../layouts/semantic-model';
+import { SemanticModel } from './ir';
+export interface KcGenerateOptions {
+    project: string;
+    location: string;
+    entryGroup: string;
+    systemTypeProject?: string;
+    systemTypeLocation?: string;
+    emitExpressions?: boolean;
+    v2Aspects?: boolean;
+    overviews?: ReadonlyMap<string, OverviewSidecar>;
+}
+export interface KcResources {
+    entries: Entry[];
+    entryLinks: EntryLink[];
+    warnings: string[];
+    ownedPrefixes: string[];
+}
+/**
+ * Generates the Knowledge Catalog resources for a semantic model.
+ *
+ * Returns the entries (model anchor first, then entities, metrics and, with
+ * v2Aspects, relationships), the entry links of the relationships and, with
+ * v2Aspects, of each entity's parents, and any warnings collected while
+ * mapping the IR (missing keys, un-typed metrics, skipped M:N relationships).
+ * The resources reference the built-in system types; they do not create them.
+ */
+export declare function generateCatalogResources(model: SemanticModel, opts: KcGenerateOptions): KcResources;