@google-cloud/kcmd 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,155 @@
+import { Entry, EntryLink, EntryReference } from '../gcp/dataplex';
+import { KcResources } from './knowledge_catalog';
+/** Options overriding the system-type project, location, and V2 aspect mode. */
+export interface SystemTypeOptions {
+    systemTypeProject?: string;
+    systemTypeLocation?: string;
+    v2Aspects?: boolean;
+}
+/**
+ * A model anchor ID paired with the child entry-ID prefixes it owns across the
+ * V1 dotted (`<anchorId>.`) and V2/LookML slash (`<anchorId>/`) ID schemes.
+ */
+export interface KcAnchor {
+    readonly anchorId: string;
+    readonly ownedPrefixes: readonly string[];
+}
+/**
+ * A model owner representation (`KcResources` or `KcAnchor`) used to test entry
+ * and entry-link ownership.
+ */
+export type KcOwner = KcResources | KcAnchor;
+/**
+ * Returns the bare entry ID of `entry` (everything after `/entries/`).
+ *
+ * Examples:
+ * - `'projects/p/locations/us/entryGroups/eg/entries/sales.entities.orders'`
+ *   -> `'sales.entities.orders'`
+ * - `'projects/p/locations/us/entryGroups/eg/entries/sales/entities/orders'`
+ *   -> `'sales/entities/orders'`
+ */
+export declare function entryId(entry: Entry | EntryReference): string;
+/**
+ * Returns the bare entry-type ID of `entry` (everything after `/entryTypes/`).
+ *
+ * Example:
+ * - `'projects/dataplex-types/locations/global/entryTypes/semantic-entity'`
+ *   -> `'semantic-entity'`
+ */
+export declare function entryTypeId(entry: Entry): string;
+/**
+ * Returns the bare entry-link ID of `link` (everything after `/entryLinks/`).
+ *
+ * Example:
+ * - `'projects/p/locations/us/entryGroups/eg/entryLinks/sales-orders-to-users'`
+ *   -> `'sales-orders-to-users'`
+ */
+export declare function linkId(link: EntryLink): string;
+/**
+ * Returns the bare entry-link-type ID of `link` (everything after
+ * `/entryLinkTypes/`).
+ *
+ * Example:
+ * - `'projects/dataplex-types/locations/global/entryLinkTypes/schema-join'`
+ *   -> `'schema-join'`
+ */
+export declare function linkTypeId(link: EntryLink): string;
+/**
+ * Returns true when `entry` is a `semantic-model` entry.
+ */
+export declare function isModelEntry(entry: Entry): boolean;
+/**
+ * Returns true when `entry` is a model anchor entry (`semantic-model`).
+ *
+ * Alias for `isModelEntry`.
+ */
+export declare const isAnchorEntry: typeof isModelEntry;
+/**
+ * Returns the bare entry ID of `entry` if it is a model anchor entry
+ * (`isAnchorEntry(entry)`), or `undefined` otherwise.
+ */
+export declare function anchorId(entry: Entry | undefined): string | undefined;
+/**
+ * Returns true when `entry` is a `semantic-entity` entry.
+ */
+export declare function isEntityEntry(entry: Entry): boolean;
+/**
+ * Returns true when `entry` is a `semantic-metric` entry.
+ */
+export declare function isMetricEntry(entry: Entry): boolean;
+/**
+ * Returns true when `entry` is the entry of a model, entity, metric or
+ * relationship.
+ */
+export declare function isSemanticObjectEntry(entry: Entry): boolean;
+/**
+ * Returns true when `entry` is a `semantic-explore` entry.
+ */
+export declare function isExploreEntry(entry: Entry): boolean;
+/**
+ * Returns true when `entry` depends on a `semantic-entity` entry.
+ *
+ * Dependent entries (`semantic-metric` and `semantic-explore`) reference
+ * entity entries by name and must be written in the second wave after entity
+ * entries exist.
+ */
+export declare function isDependentEntry(entry: Entry): boolean;
+/**
+ * Returns true when `link` is of a kind push writes for a model: `schema-join`
+ * in V1, and in V2 `semantic-link` or a `reference` link whose ID starts with
+ * `semantic-relationship-` or `semantic-extends-`.
+ *
+ * Includes both V1 and V2 regardless of `v2Aspects`, so a model pushed with V1
+ * and then V2 still discovers and cleans up its old `schema-join` links
+ * without passing a link type in a server-side `lookupEntryLinks` filter.
+ */
+export declare function isModelLink(link: EntryLink): boolean;
+/**
+ * Returns the full resource names of all `semantic-entity` entries in
+ * `entries`.
+ */
+export declare function collectEntityNames(entries: readonly Entry[]): string[];
+/**
+ * Returns true when `entry` is owned by `owner`:
+ *   * For `KcResources`, matches child entries under `owner.ownedPrefixes`
+ *     (the model anchor itself is not a child prefix).
+ *   * For `KcAnchor`, matches both the model anchor entry (`owner.anchorId`)
+ *     and child entries under `owner.ownedPrefixes`.
+ */
+export declare function isEntryOwner(owner: KcOwner, entry: Entry | EntryReference): boolean;
+/**
+ * Filters `entries` to those owned by `owner` (`KcResources` or `KcAnchor`).
+ */
+export declare function collectOwnedEntries(owner: KcOwner, entries: readonly Entry[]): Entry[];
+/**
+ * Returns the endpoint references of `link` that belong to `link`'s own entry
+ * group (when `link.name` carries a full resource container) and are owned by
+ * `owner` (`KcResources` or `KcAnchor`).
+ *
+ * `link.name` and its references must spell the project the same way.
+ */
+export declare function collectOwnedReferences(owner: KcOwner, link: EntryLink): EntryReference[];
+/**
+ * Returns true when both endpoints of `link` are in `link`'s entry group and
+ * owned by `owner` (`KcResources` or `KcAnchor`).
+ */
+export declare function isLinkOwner(owner: KcOwner, link: EntryLink): boolean;
+/**
+ * Returns the set of aspect keys to include when updating `entry`.
+ *
+ * Includes every aspect key present on `entry.aspects` plus the optional
+ * `<proj>.<loc>.guidelines` aspect. When `opts?.v2Aspects` is true:
+ *   * Adds `<proj>.<loc>.semantic-extensions` and `<proj>.<loc>.overview` on
+ *     model, entity, metric and relationship entries, so Dataplex removes the
+ *     aspect when the object no longer has content for it.
+ *   * Adds `<proj>.<loc>.sql-expressions` on entity and metric entries.
+ *   * Adds `<proj>.<loc>.<type>@*` for guidelines, semantic-extensions and
+ *     overview on entity entries, so Dataplex writes each field's instance
+ *     `entry` carries and removes the others. A field's own key is left out.
+ */
+export declare function entryAspectKeys(entry: Entry, opts?: SystemTypeOptions): Set<string>;
+/**
+ * Compares the `entryReferences` of two entry links by bare entry ID, reference
+ * type, and path, independent of reference order.
+ */
+export declare function sameLinkReferences(a: EntryLink, b: EntryLink): boolean;

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

@@ -0,0 +1,284 @@
+"use strict";
+// Pure helper operations on Knowledge Catalog `Entry` and `EntryLink` objects.
+//
+// Centralizes ID/type extraction, entry/link type predicates, ownership
+// checks, and aspect-key extraction for entries and entry links.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAnchorEntry = void 0;
+exports.entryId = entryId;
+exports.entryTypeId = entryTypeId;
+exports.linkId = linkId;
+exports.linkTypeId = linkTypeId;
+exports.isModelEntry = isModelEntry;
+exports.anchorId = anchorId;
+exports.isEntityEntry = isEntityEntry;
+exports.isMetricEntry = isMetricEntry;
+exports.isSemanticObjectEntry = isSemanticObjectEntry;
+exports.isExploreEntry = isExploreEntry;
+exports.isDependentEntry = isDependentEntry;
+exports.isModelLink = isModelLink;
+exports.collectEntityNames = collectEntityNames;
+exports.isEntryOwner = isEntryOwner;
+exports.collectOwnedEntries = collectOwnedEntries;
+exports.collectOwnedReferences = collectOwnedReferences;
+exports.isLinkOwner = isLinkOwner;
+exports.entryAspectKeys = entryAspectKeys;
+exports.sameLinkReferences = sameLinkReferences;
+const kc_ids_1 = require("./kc_ids");
+// ---------------------------------------------------------------------------
+// 1. Bare ID and Type-ID Extraction
+// ---------------------------------------------------------------------------
+/**
+ * Returns the bare entry ID of `entry` (everything after `/entries/`).
+ *
+ * Examples:
+ * - `'projects/p/locations/us/entryGroups/eg/entries/sales.entities.orders'`
+ *   -> `'sales.entities.orders'`
+ * - `'projects/p/locations/us/entryGroups/eg/entries/sales/entities/orders'`
+ *   -> `'sales/entities/orders'`
+ */
+function entryId(entry) {
+    return (0, kc_ids_1.entryIdOf)(entry.name);
+}
+/**
+ * Returns the bare entry-type ID of `entry` (everything after `/entryTypes/`).
+ *
+ * Example:
+ * - `'projects/dataplex-types/locations/global/entryTypes/semantic-entity'`
+ *   -> `'semantic-entity'`
+ */
+function entryTypeId(entry) {
+    return (0, kc_ids_1.entryIdOf)(entry.entryType ?? '');
+}
+/**
+ * Returns the bare entry-link ID of `link` (everything after `/entryLinks/`).
+ *
+ * Example:
+ * - `'projects/p/locations/us/entryGroups/eg/entryLinks/sales-orders-to-users'`
+ *   -> `'sales-orders-to-users'`
+ */
+function linkId(link) {
+    return (0, kc_ids_1.entryIdOf)(link.name ?? '');
+}
+/**
+ * Returns the bare entry-link-type ID of `link` (everything after
+ * `/entryLinkTypes/`).
+ *
+ * Example:
+ * - `'projects/dataplex-types/locations/global/entryLinkTypes/schema-join'`
+ *   -> `'schema-join'`
+ */
+function linkTypeId(link) {
+    return (0, kc_ids_1.entryIdOf)(link.entryLinkType ?? '');
+}
+// ---------------------------------------------------------------------------
+// 2. Entry & EntryLink Type Predicates & Anchor Extraction
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when `entry` is a `semantic-model` entry.
+ */
+function isModelEntry(entry) {
+    return entryTypeId(entry) === 'semantic-model';
+}
+/**
+ * Returns true when `entry` is a model anchor entry (`semantic-model`).
+ *
+ * Alias for `isModelEntry`.
+ */
+exports.isAnchorEntry = isModelEntry;
+/**
+ * Returns the bare entry ID of `entry` if it is a model anchor entry
+ * (`isAnchorEntry(entry)`), or `undefined` otherwise.
+ */
+function anchorId(entry) {
+    return entry && (0, exports.isAnchorEntry)(entry) ? entryId(entry) : undefined;
+}
+/**
+ * Returns true when `entry` is a `semantic-entity` entry.
+ */
+function isEntityEntry(entry) {
+    return entryTypeId(entry) === 'semantic-entity';
+}
+/**
+ * Returns true when `entry` is a `semantic-metric` entry.
+ */
+function isMetricEntry(entry) {
+    return entryTypeId(entry) === 'semantic-metric';
+}
+/**
+ * Returns true when `entry` is the entry of a model, entity, metric or
+ * relationship.
+ */
+function isSemanticObjectEntry(entry) {
+    return isModelEntry(entry) || isEntityEntry(entry) || isMetricEntry(entry) ||
+        entryTypeId(entry) === 'semantic-relationship';
+}
+/**
+ * Returns true when `entry` is a `semantic-explore` entry.
+ */
+function isExploreEntry(entry) {
+    return entryTypeId(entry) === 'semantic-explore';
+}
+/**
+ * Returns true when `entry` depends on a `semantic-entity` entry.
+ *
+ * Dependent entries (`semantic-metric` and `semantic-explore`) reference
+ * entity entries by name and must be written in the second wave after entity
+ * entries exist.
+ */
+function isDependentEntry(entry) {
+    return isMetricEntry(entry) || isExploreEntry(entry);
+}
+/**
+ * Returns true when `link` is of a kind push writes for a model: `schema-join`
+ * in V1, and in V2 `semantic-link` or a `reference` link whose ID starts with
+ * `semantic-relationship-` or `semantic-extends-`.
+ *
+ * Includes both V1 and V2 regardless of `v2Aspects`, so a model pushed with V1
+ * and then V2 still discovers and cleans up its old `schema-join` links
+ * without passing a link type in a server-side `lookupEntryLinks` filter.
+ */
+function isModelLink(link) {
+    const type = linkTypeId(link);
+    return type === 'schema-join' || type === 'semantic-link' ||
+        (type === 'reference' &&
+            /^semantic-(relationship|extends)-/.test(linkId(link)));
+}
+// ---------------------------------------------------------------------------
+// 3. Ownership & Filtering Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when `str` starts with any non-empty prefix in `prefixes`.
+ */
+function startsWithAny(str, prefixes) {
+    return prefixes.some(p => p.length > 0 && str.startsWith(p));
+}
+/**
+ * Returns the full resource names of all `semantic-entity` entries in
+ * `entries`.
+ */
+function collectEntityNames(entries) {
+    return entries.filter(isEntityEntry).map(e => e.name);
+}
+/**
+ * Returns true when `entry` is owned by `owner`:
+ *   * For `KcResources`, matches child entries under `owner.ownedPrefixes`
+ *     (the model anchor itself is not a child prefix).
+ *   * For `KcAnchor`, matches both the model anchor entry (`owner.anchorId`)
+ *     and child entries under `owner.ownedPrefixes`.
+ */
+function isEntryOwner(owner, entry) {
+    if ('anchorId' in owner) {
+        if (!owner.anchorId)
+            return false;
+        if ('entryType' in entry && anchorId(entry) === owner.anchorId)
+            return true;
+    }
+    return startsWithAny(entryId(entry), owner.ownedPrefixes);
+}
+/**
+ * Filters `entries` to those owned by `owner` (`KcResources` or `KcAnchor`).
+ */
+function collectOwnedEntries(owner, entries) {
+    return entries.filter(e => isEntryOwner(owner, e));
+}
+const LINK_CONTAINER_RE = /^(projects\/[^/]+\/locations\/[^/]+\/entryGroups\/[^/]+\/)entryLinks\//;
+/**
+ * Returns the endpoint references of `link` that belong to `link`'s own entry
+ * group (when `link.name` carries a full resource container) and are owned by
+ * `owner` (`KcResources` or `KcAnchor`).
+ *
+ * `link.name` and its references must spell the project the same way.
+ */
+function collectOwnedReferences(owner, link) {
+    // A reference `r` in `link.entryReferences` is owned by `owner` when:
+    //   1. Either `link.name` has no container prefix, or `r.name` starts with
+    //      `${m[1]}entries/` (`projects/<project>/locations/<location>/
+    //      entryGroups/<entryGroup>/entries/`). A different prefix means `r`
+    //      points to another entry group or project.
+    //   2. `isEntryOwner(owner, r)` is true (`r`'s entry ID belongs to `owner`).
+    const m = link.name?.match(LINK_CONTAINER_RE);
+    return link.entryReferences.filter(r => (!m || r.name.startsWith(`${m[1]}entries/`)) &&
+        isEntryOwner(owner, r));
+}
+/**
+ * Returns true when both endpoints of `link` are in `link`'s entry group and
+ * owned by `owner` (`KcResources` or `KcAnchor`).
+ */
+function isLinkOwner(owner, link) {
+    return link.entryReferences.length === 2 &&
+        collectOwnedReferences(owner, link).length === 2;
+}
+// ---------------------------------------------------------------------------
+// 4. Aspect Keys & Link-Reference Comparison
+// ---------------------------------------------------------------------------
+/**
+ * Resolves the project and location where built-in system types live.
+ *
+ * Uses `opts` overrides when provided and defaults to `DEFAULT_TYPE_PROJECT`
+ * and `DEFAULT_TYPE_LOCATION`.
+ */
+function systemTypeProjectAndLocation(opts) {
+    return {
+        proj: opts?.systemTypeProject ?? kc_ids_1.DEFAULT_TYPE_PROJECT,
+        loc: opts?.systemTypeLocation ?? kc_ids_1.DEFAULT_TYPE_LOCATION,
+    };
+}
+/**
+ * Returns the set of aspect keys to include when updating `entry`.
+ *
+ * Includes every aspect key present on `entry.aspects` plus the optional
+ * `<proj>.<loc>.guidelines` aspect. When `opts?.v2Aspects` is true:
+ *   * Adds `<proj>.<loc>.semantic-extensions` and `<proj>.<loc>.overview` on
+ *     model, entity, metric and relationship entries, so Dataplex removes the
+ *     aspect when the object no longer has content for it.
+ *   * Adds `<proj>.<loc>.sql-expressions` on entity and metric entries.
+ *   * Adds `<proj>.<loc>.<type>@*` for guidelines, semantic-extensions and
+ *     overview on entity entries, so Dataplex writes each field's instance
+ *     `entry` carries and removes the others. A field's own key is left out.
+ */
+function entryAspectKeys(entry, opts) {
+    const { proj, loc } = systemTypeProjectAndLocation(opts);
+    const keys = new Set([
+        ...Object.keys(entry.aspects ?? {}).filter(key => !key.includes('@')),
+        `${proj}.${loc}.guidelines`,
+    ]);
+    if (!opts?.v2Aspects)
+        return keys;
+    if (isSemanticObjectEntry(entry)) {
+        keys.add(`${proj}.${loc}.semantic-extensions`);
+        keys.add(`${proj}.${loc}.overview`);
+    }
+    if (isEntityEntry(entry) || isMetricEntry(entry)) {
+        keys.add(`${proj}.${loc}.sql-expressions`);
+    }
+    if (isEntityEntry(entry)) {
+        for (const type of ['guidelines', 'semantic-extensions', 'overview']) {
+            keys.add(`${proj}.${loc}.${type}@*`);
+        }
+    }
+    return keys;
+}
+/**
+ * Formats an `EntryReference` into a canonical comparison key combining its
+ * bare entry ID, reference type (defaulting to `'UNSPECIFIED'`), and path
+ * (treating an absent path and `''` as equal).
+ */
+function formatLinkReference(ref) {
+    const id = (0, kc_ids_1.entryIdOf)(ref.name);
+    const type = ref.type ?? 'UNSPECIFIED';
+    return `${id}|${type}|${ref.path ?? ''}`;
+}
+/**
+ * Compares the `entryReferences` of two entry links by bare entry ID, reference
+ * type, and path, independent of reference order.
+ */
+function sameLinkReferences(a, b) {
+    const refsA = a.entryReferences;
+    const refsB = b.entryReferences;
+    if (refsA.length !== refsB.length)
+        return false;
+    const sortedA = refsA.map(formatLinkReference).sort();
+    const sortedB = refsB.map(formatLinkReference).sort();
+    return sortedA.every((ref, i) => ref === sortedB[i]);
+}

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

@@ -0,0 +1,102 @@
+import { Entity, Metric, Relationship, SemanticModel } from './ir';
+export declare const DEFAULT_TYPE_PROJECT = "dataplex-types";
+export declare const DEFAULT_TYPE_LOCATION = "global";
+/** Destination and layout options for constructing Knowledge Catalog names. */
+export interface NamerOptions {
+    project: string;
+    location: string;
+    entryGroup: string;
+    systemTypeProject?: string;
+    systemTypeLocation?: string;
+    v2Aspects?: boolean;
+}
+/**
+ * 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.
+ */
+export declare class Namer {
+    private readonly typeProject;
+    private readonly typeLocation;
+    private readonly container;
+    private readonly v2Aspects;
+    constructor(opts: NamerOptions);
+    /** Full resource name of a system type. `kind` selects the collection. */
+    typeName(kind: 'entry' | 'aspect' | 'entryLink', name: string): string;
+    /**
+     * Aspect-map key: the `project.location.type` reference form the client keys
+     * an entry's aspects by (see dataplex._nameToTypeRef / _fixEntry).
+     */
+    aspectRef(name: string): string;
+    /** Full resource name of an entry in the destination entry group. */
+    entry(entryId: string): string;
+    /** Full resource name of an entry link in the destination entry group. */
+    entryLink(linkId: string): string;
+    /**
+     * 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: SemanticModel): string;
+    /** Bare entry ID for an entity within a semantic model. */
+    entityId(model: SemanticModel, entity: Entity): string;
+    /** Bare entry ID for a metric within a semantic model. */
+    metricId(model: SemanticModel, metric: Metric): string;
+    /** Bare V2 entry ID for a relationship within a semantic model. */
+    relationshipId(model: SemanticModel, rel: Relationship): string;
+    /**
+     * 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: SemanticModel, rel: Relationship): string;
+}
+/** Entry-link ID for a relationship on a model. */
+export declare function relationshipLinkId(modelName: string, relName: string): string;
+/**
+ * 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.
+ */
+export declare function semanticLinkId(kind: 'link' | 'relationship' | 'extends', ...parts: string[]): string;
+/**
+ * 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.
+ */
+export declare function ownedEntryIdPrefixes(modelName: string): string[];
+/**
+ * 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'`).
+ */
+export declare function entryIdOf(resourceName: string): string;
+/**
+ * Entry IDs allow letters, numbers, underscores, hyphens, and periods; maps
+ * anything else to an underscore.
+ */
+export declare function slug(s: string): string;
+/**
+ * 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.
+ */
+export declare function linkSlug(s: string): string;