@google-cloud/kcmd 0.0.0-stage → 0.2.0

package/build/ts/kcmd/okf/links.js

@@ -0,0 +1,468 @@
+"use strict";
+// EntryLink serialization and parsing for OKF `bundle/_links.yaml` (SPEC §4).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINKS_FILE = void 0;
+exports.readBundleLinks = readBundleLinks;
+exports.formatLinksYaml = formatLinksYaml;
+exports.entryLinkId = entryLinkId;
+exports.linkDedupKey = linkDedupKey;
+exports.isStaleEntryLink = isStaleEntryLink;
+exports.resolveEntryLinkType = resolveEntryLinkType;
+exports.shortenLinkType = shortenLinkType;
+exports.resolveEntryRefName = resolveEntryRefName;
+exports.shortenEntryName = shortenEntryName;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const yaml = __importStar(require("yaml"));
+const dataplex = __importStar(require("../gcp/dataplex"));
+const concept_1 = require("./concept");
+exports.LINKS_FILE = '_links.yaml';
+const SYSTEM_TYPES_PREFIX = 'projects/dataplex-types/locations/global/entryLinkTypes/';
+const UNDIRECTED_LINK_TYPES = new Set(['related', 'synonym', 'schema-join']);
+// The system link types, which Knowledge Catalog returns under the project
+// number of `dataplex-types` rather than its ID.
+const SYSTEM_LINK_TYPE_NAMES = new Set([
+    'related',
+    'reference',
+    'synonym',
+    'definition',
+    'schema-join',
+]);
+const NUMBERED_SYSTEM_LINK_TYPE = /^projects\/\d+\/locations\/global\/entryLinkTypes\/([a-z0-9-]+)$/;
+/** Reads `bundle/_links.yaml` and any frontmatter `links` from `concepts`. */
+function readBundleLinks(root, entryGroup, concepts = []) {
+    const rawLinks = [];
+    let hasLinksConfig = false;
+    if (fs.existsSync(root)) {
+        for (const linksFile of findLinksFiles(root)) {
+            hasLinksConfig = true;
+            const text = fs.readFileSync(linksFile, 'utf8');
+            let parsed;
+            try {
+                parsed = yaml.parse(text);
+            }
+            catch (err) {
+                throw new Error(`invalid YAML in ${path.relative(root, linksFile)}: ${err.message || err}`);
+            }
+            if (parsed === null || parsed === undefined)
+                continue;
+            for (const item of extractRawLinks(parsed, path.relative(root, linksFile))) {
+                rawLinks.push({ raw: item });
+            }
+        }
+    }
+    for (const concept of concepts) {
+        const fm = concept.frontmatter;
+        const extra = asRecord(fm[concept_1.EXTRA_KEY]);
+        const residue = asRecord(fm[concept_1.RESIDUE_KEY]);
+        const conceptLinks = fm['links'] ?? extra?.['links'] ?? residue?.['links'];
+        if (conceptLinks === undefined)
+            continue;
+        hasLinksConfig = true;
+        for (const item of extractRawLinks(conceptLinks, `${concept.id}.md`)) {
+            rawLinks.push({ raw: item, sourceId: concept.id });
+        }
+    }
+    const byKey = new Map();
+    for (const { raw, sourceId } of rawLinks) {
+        const link = toEntryLink(raw, entryGroup, sourceId);
+        byKey.set(linkDedupKey(link), link);
+    }
+    return { hasLinksConfig, links: [...byKey.values()] };
+}
+/** Formats Dataplex `EntryLink`s into canonical `bundle/_links.yaml` content. */
+function formatLinksYaml(links, entryGroup) {
+    const serialized = links.map((link) => {
+        const shortType = shortenLinkType(link.entryLinkType);
+        const refs = orderedReferences(link.entryReferences ?? [], entryGroup).map((ref) => {
+            const shortName = shortenEntryName(ref.name, entryGroup);
+            const hasPath = typeof ref.path === 'string' && ref.path.length > 0;
+            const hasRole = typeof ref.type === 'string' &&
+                ref.type.length > 0 &&
+                ref.type !== 'UNSPECIFIED';
+            if (!hasPath && !hasRole) {
+                return shortName;
+            }
+            const out = { name: shortName };
+            if (hasPath)
+                out.path = ref.path;
+            if (hasRole)
+                out.type = ref.type;
+            return out;
+        });
+        // The link's own ID, so that pushing a pulled bundle updates the same
+        // link instead of deleting it and creating one under a new ID.
+        const id = entryLinkId(link);
+        const item = {
+            ...(id ? { id } : {}),
+            type: shortType,
+            entries: refs,
+        };
+        if (link.aspects && Object.keys(link.aspects).length > 0) {
+            item.aspects = link.aspects;
+        }
+        return item;
+    });
+    return yaml.stringify({ links: serialized });
+}
+/** Extracts the bare `entryLinkId` from an `EntryLink.name`. */
+function entryLinkId(link) {
+    return link.name?.split('/entryLinks/')[1] ?? link.name ?? '';
+}
+/** Deterministic deduplication key across link type and endpoints. */
+function linkDedupKey(link) {
+    if (link.name)
+        return link.name;
+    const refs = (link.entryReferences ?? [])
+        .map((r) => `${r.type ?? 'UNSPECIFIED'}:${r.name}${r.path ? `@${r.path}` : ''}`)
+        .sort()
+        .join('|');
+    return `${link.entryLinkType}|${refs}`;
+}
+/** True when `existing` differs from `desired` in immutable type or references. */
+function isStaleEntryLink(existing, desired) {
+    if (shortenLinkType(existing.entryLinkType) !==
+        shortenLinkType(desired.entryLinkType)) {
+        return true;
+    }
+    const a = canonicalRefs(existing.entryReferences ?? []);
+    const b = canonicalRefs(desired.entryReferences ?? []);
+    return a !== b;
+}
+function canonicalRefs(refs) {
+    return refs
+        .map((r) => `${r.type ?? 'UNSPECIFIED'}:${normalizeProjectSegment(r.name)}${r.path ? `@${r.path}` : ''}`)
+        .sort()
+        .join('|');
+}
+function normalizeProjectSegment(resourceName) {
+    const idx = resourceName.indexOf('/locations/');
+    return idx === -1 ? resourceName : resourceName.slice(idx);
+}
+function findLinksFiles(dir) {
+    const files = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...findLinksFiles(full));
+        }
+        else if (entry.name === exports.LINKS_FILE) {
+            files.push(full);
+        }
+    }
+    return files.sort();
+}
+function extractRawLinks(parsed, sourceLabel) {
+    if (Array.isArray(parsed)) {
+        return parsed.map((item, i) => {
+            const rec = asRecord(item);
+            if (!rec) {
+                throw new Error(`${sourceLabel}: link #${i + 1} must be an object`);
+            }
+            return rec;
+        });
+    }
+    const obj = asRecord(parsed);
+    if (!obj) {
+        throw new Error(`${sourceLabel}: expected a YAML mapping or sequence`);
+    }
+    const list = obj['links'] ?? obj['entryLinks'] ?? obj['entry_links'];
+    if (list !== undefined) {
+        if (!Array.isArray(list)) {
+            throw new Error(`${sourceLabel}: 'links' must be a list`);
+        }
+        return extractRawLinks(list, sourceLabel);
+    }
+    // Shorthand mapping keyed by link type: `{ related: [...], definition: [...] }`.
+    const out = [];
+    for (const [key, val] of Object.entries(obj)) {
+        if (!Array.isArray(val)) {
+            throw new Error(`${sourceLabel}: unexpected field '${key}' (expected 'links' list)`);
+        }
+        for (const item of extractRawLinks(val, `${sourceLabel}.${key}`)) {
+            out.push({ type: key, ...item });
+        }
+    }
+    return out;
+}
+function toEntryLink(raw, entryGroup, defaultSourceId) {
+    const rawType = asString(raw['type']) ??
+        asString(raw['entryLinkType']) ??
+        asString(raw['entry_link_type']) ??
+        asString(raw['linkType']) ??
+        asString(raw['link_type']);
+    if (!rawType) {
+        throw new Error(`${exports.LINKS_FILE}: link is missing 'type'`);
+    }
+    const entryLinkType = resolveEntryLinkType(rawType);
+    const shortType = shortenLinkType(entryLinkType);
+    const isUndirected = UNDIRECTED_LINK_TYPES.has(shortType);
+    const rawRefs = extractRawRefs(raw, defaultSourceId);
+    if (rawRefs.length < 2) {
+        throw new Error(`${exports.LINKS_FILE}: link of type '${rawType}' must reference at least 2 entries`);
+    }
+    const entryReferences = rawRefs.map((r) => toEntryReference(r, entryGroup, isUndirected));
+    // Directed 2-endpoint links (such as `definition`) default untyped endpoints
+    // to SOURCE -> TARGET in declaration order.
+    if (!isUndirected &&
+        entryReferences.length === 2 &&
+        entryReferences[0].type === 'UNSPECIFIED' &&
+        entryReferences[1].type === 'UNSPECIFIED') {
+        entryReferences[0].type = 'SOURCE';
+        entryReferences[1].type = 'TARGET';
+    }
+    const explicitId = asString(raw['id']) ??
+        asString(raw['entryLinkId']) ??
+        asString(raw['entry_link_id']) ??
+        asString(raw['name']);
+    const linkId = explicitId
+        ? normalizeLinkId(explicitId)
+        : computeDeterministicLinkId(entryLinkType, entryReferences);
+    const link = {
+        name: `${entryGroup}/entryLinks/${linkId}`,
+        entryLinkType,
+        entryReferences,
+    };
+    const rawAspects = asRecord(raw['aspects']);
+    if (rawAspects && Object.keys(rawAspects).length > 0) {
+        const aspects = {};
+        for (const [key, val] of Object.entries(rawAspects)) {
+            const valRec = asRecord(val);
+            if (!valRec)
+                continue;
+            const atIdx = key.indexOf('@');
+            const typeRef = atIdx === -1 ? key : key.slice(0, atIdx);
+            const keyPath = atIdx === -1 ? undefined : key.slice(atIdx + 1);
+            const aspectType = asString(valRec['aspectType']) ??
+                (typeRef.split('.').length === 3
+                    ? dataplex._typeRefToName(typeRef, 'aspect')
+                    : undefined);
+            const data = asRecord(valRec['data']) ?? valRec;
+            aspects[key] = {
+                ...(aspectType ? { aspectType } : {}),
+                ...(keyPath ? { path: keyPath } : {}),
+                data,
+            };
+        }
+        if (Object.keys(aspects).length > 0) {
+            link.aspects = aspects;
+        }
+    }
+    return link;
+}
+function extractRawRefs(raw, defaultSourceId) {
+    const list = raw['entries'] ??
+        raw['entryReferences'] ??
+        raw['entry_references'] ??
+        raw['references'];
+    if (Array.isArray(list)) {
+        if (list.length === 1 && defaultSourceId) {
+            return [{ name: defaultSourceId, type: 'SOURCE' }, list[0]];
+        }
+        return list;
+    }
+    const source = raw['source'] ?? raw['from'] ?? defaultSourceId;
+    const target = raw['target'] ?? raw['to'];
+    if (source !== undefined && target !== undefined) {
+        const srcObj = typeof source === 'string'
+            ? {
+                name: source,
+                path: raw['source_path'] ?? raw['sourcePath'],
+                type: 'SOURCE',
+            }
+            : { ...(asRecord(source) ?? {}), type: 'SOURCE' };
+        const tgtObj = typeof target === 'string'
+            ? {
+                name: target,
+                path: raw['target_path'] ?? raw['targetPath'] ?? raw['path'],
+                type: 'TARGET',
+            }
+            : { ...(asRecord(target) ?? {}), type: 'TARGET' };
+        return [srcObj, tgtObj];
+    }
+    throw new Error(`${exports.LINKS_FILE}: link is missing 'entries' list`);
+}
+function toEntryReference(raw, entryGroup, isUndirected) {
+    if (typeof raw === 'string') {
+        const [rawName, inlinePath] = splitInlinePath(raw);
+        const ref = {
+            name: resolveEntryRefName(rawName, entryGroup),
+            type: 'UNSPECIFIED',
+        };
+        if (inlinePath)
+            ref.path = inlinePath;
+        return ref;
+    }
+    const obj = asRecord(raw);
+    if (!obj) {
+        throw new Error(`${exports.LINKS_FILE}: entry reference must be a string or object`);
+    }
+    const rawName = asString(obj['name']) ??
+        asString(obj['entry']) ??
+        asString(obj['id']) ??
+        asString(obj['target']);
+    if (!rawName) {
+        throw new Error(`${exports.LINKS_FILE}: entry reference is missing 'name'`);
+    }
+    const [baseName, inlinePath] = splitInlinePath(rawName);
+    const pathVal = asString(obj['path']) ??
+        asString(obj['field']) ??
+        asString(obj['column']) ??
+        inlinePath;
+    const rawRole = (asString(obj['type']) ??
+        asString(obj['role']) ??
+        asString(obj['mode']) ??
+        'UNSPECIFIED').toUpperCase();
+    let type = 'UNSPECIFIED';
+    if (!isUndirected) {
+        if (rawRole === 'SOURCE' || rawRole === 'FROM') {
+            type = 'SOURCE';
+        }
+        else if (rawRole === 'TARGET' || rawRole === 'TO') {
+            type = 'TARGET';
+        }
+    }
+    const ref = {
+        name: resolveEntryRefName(baseName, entryGroup),
+        type,
+    };
+    if (pathVal)
+        ref.path = pathVal;
+    return ref;
+}
+function splitInlinePath(raw) {
+    const hashIdx = raw.indexOf('#');
+    if (hashIdx === -1)
+        return [raw, undefined];
+    const base = raw.slice(0, hashIdx);
+    const col = raw.slice(hashIdx + 1);
+    if (!col)
+        return [base, undefined];
+    return [base, col.startsWith('Schema.') ? col : `Schema.${col}`];
+}
+function resolveEntryLinkType(rawType) {
+    const trimmed = rawType.trim();
+    if (trimmed.startsWith('projects/') && trimmed.includes('/entryLinkTypes/')) {
+        return trimmed;
+    }
+    if (trimmed.split('.').length === 3) {
+        return dataplex._typeRefToName(trimmed, 'entryLink');
+    }
+    return `${SYSTEM_TYPES_PREFIX}${trimmed}`;
+}
+function shortenLinkType(entryLinkType) {
+    if (entryLinkType.startsWith(SYSTEM_TYPES_PREFIX)) {
+        return entryLinkType.slice(SYSTEM_TYPES_PREFIX.length);
+    }
+    const numbered = NUMBERED_SYSTEM_LINK_TYPE.exec(entryLinkType)?.[1];
+    if (numbered && SYSTEM_LINK_TYPE_NAMES.has(numbered))
+        return numbered;
+    return entryLinkType;
+}
+function resolveEntryRefName(rawName, entryGroup) {
+    let cleaned = rawName.trim();
+    if (cleaned.startsWith('projects/') && cleaned.includes('/entries/')) {
+        return cleaned;
+    }
+    cleaned = cleaned
+        .replace(/^\.\//, '')
+        .replace(/^(bundle|catalog)\//, '')
+        .replace(/\.md$/, '');
+    return `${entryGroup}/entries/${cleaned}`;
+}
+function shortenEntryName(fullEntryName, entryGroup) {
+    const prefix = `${entryGroup}/entries/`;
+    if (fullEntryName.startsWith(prefix)) {
+        return fullEntryName.slice(prefix.length);
+    }
+    // Handle project-number vs project-id spelling of the same location + entryGroup.
+    const locIdx = entryGroup.indexOf('/locations/');
+    if (locIdx !== -1) {
+        const groupSuffix = `${entryGroup.slice(locIdx)}/entries/`;
+        const matchIdx = fullEntryName.indexOf(groupSuffix);
+        if (matchIdx !== -1 && fullEntryName.startsWith('projects/')) {
+            return fullEntryName.slice(matchIdx + groupSuffix.length);
+        }
+    }
+    return fullEntryName;
+}
+function orderedReferences(refs, entryGroup) {
+    const copy = [...refs];
+    const hasDirected = copy.some((r) => r.type === 'SOURCE' || r.type === 'TARGET');
+    if (hasDirected) {
+        const rank = (t) => t === 'SOURCE' ? 0 : t === 'TARGET' ? 1 : 2;
+        return copy.sort((a, b) => rank(a.type) - rank(b.type));
+    }
+    // For undirected links, list in-group entries before external entries.
+    const isLocal = (r) => shortenEntryName(r.name, entryGroup) !== r.name;
+    return copy.sort((a, b) => Number(isLocal(b)) - Number(isLocal(a)));
+}
+function normalizeLinkId(rawId) {
+    const tail = rawId.includes('/entryLinks/')
+        ? rawId.split('/entryLinks/')[1]
+        : rawId;
+    const slug = tail
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!slug)
+        return 'link-default';
+    const prefixed = /^[a-z]/.test(slug) ? slug : `link-${slug}`;
+    return prefixed.slice(0, 63).replace(/-+$/, '');
+}
+function computeDeterministicLinkId(entryLinkType, refs) {
+    const canonical = `${entryLinkType}|${refs
+        .map((r) => `${r.type}:${r.name}${r.path ? `@${r.path}` : ''}`)
+        .sort()
+        .join('|')}`;
+    const digest = crypto
+        .createHash('sha1')
+        .update(canonical)
+        .digest('hex')
+        .slice(0, 10);
+    return `link-${digest}`;
+}
+function asRecord(val) {
+    return val && typeof val === 'object' && !Array.isArray(val)
+        ? val
+        : undefined;
+}
+function asString(val) {
+    return typeof val === 'string' && val.trim().length > 0
+        ? val.trim()
+        : undefined;
+}

package/build/ts/kcmd/okf/okf_metadata.d.ts

@@ -0,0 +1,12 @@
+import { OKF_METADATA_KEYS } from './concept';
+export { OKF_METADATA_KEYS };
+/** Appends the section. The body is returned unchanged when there is none. */
+export declare function appendOkfMetadata(body: string, frontmatter: Record<string, unknown>): string;
+/**
+ * Splits a trailing section back off the overview body. Only a well-formed
+ * section at the very end counts, so a page that discusses one is left alone.
+ */
+export declare function splitOkfMetadata(content: string): {
+    body: string;
+    metadata: Record<string, unknown>;
+};

package/build/ts/kcmd/okf/okf_metadata.js

@@ -0,0 +1,99 @@
+"use strict";
+// OKF frontmatter keys the catalog has no field for, carried in a trailing
+// section of the overview body so a push does not drop them.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OKF_METADATA_KEYS = void 0;
+exports.appendOkfMetadata = appendOkfMetadata;
+exports.splitOkfMetadata = splitOkfMetadata;
+const yaml = __importStar(require("yaml"));
+const concept_1 = require("./concept");
+Object.defineProperty(exports, "OKF_METADATA_KEYS", { enumerable: true, get: function () { return concept_1.OKF_METADATA_KEYS; } });
+const HEADING = '## OKF Metadata';
+const OPEN = '```yaml';
+const CLOSE = '```';
+const MARKER = `\n\n${HEADING}\n\n${OPEN}\n`;
+// Frontmatter keys stored natively on the catalog entry or in kcmd residue/links,
+// so they are not duplicated into the trailing `## OKF Metadata` block.
+const NON_CARRIED_KEYS = new Set([
+    'type',
+    ...concept_1.ENTRY_SOURCE_KEYS,
+    concept_1.RESIDUE_KEY,
+    concept_1.EXTRA_KEY,
+    'links',
+]);
+/** Appends the section. The body is returned unchanged when there is none. */
+function appendOkfMetadata(body, frontmatter) {
+    const carried = {};
+    for (const key of concept_1.OKF_METADATA_KEYS) {
+        if (frontmatter[key] !== undefined)
+            carried[key] = frontmatter[key];
+    }
+    // Preserve `x-*` producer extensions (SPEC §4.1) and any other unknown OKF
+    // frontmatter keys across push -> pull.
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (value === undefined || key in carried || NON_CARRIED_KEYS.has(key)) {
+            continue;
+        }
+        carried[key] = value;
+    }
+    if (!Object.keys(carried).length)
+        return body;
+    const block = yaml.stringify(carried);
+    return `${body.replace(/\n*$/, '')}${MARKER}${block}${CLOSE}\n`;
+}
+/**
+ * Splits a trailing section back off the overview body. Only a well-formed
+ * section at the very end counts, so a page that discusses one is left alone.
+ */
+function splitOkfMetadata(content) {
+    const at = content.lastIndexOf(MARKER);
+    if (at === -1)
+        return { body: content, metadata: {} };
+    const inner = content.slice(at + MARKER.length);
+    if (!inner.endsWith(`${CLOSE}\n`))
+        return { body: content, metadata: {} };
+    let parsed;
+    try {
+        parsed = yaml.parse(inner.slice(0, -(CLOSE.length + 1)));
+    }
+    catch {
+        return { body: content, metadata: {} };
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { body: content, metadata: {} };
+    }
+    return { body: content.slice(0, at), metadata: parsed };
+}

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

@@ -0,0 +1,22 @@
+import { GenerateResult } from './graph_ddl';
+import { AiContext, Field, SemanticModel } from './ir';
+export interface GenerateOptions {
+    project?: string;
+    dataset?: string;
+    graphName?: string;
+}
+export type { GenerateResult };
+/**
+ * Generates the BigQuery property-graph DDL for a semantic model.
+ *
+ * The generated statement references the entities' existing base tables; it
+ * does not create them. Returns the DDL plus any warnings collected while
+ * mapping the IR (e.g. metrics that could not be placed on a single table).
+ *
+ * Throws when the model yields no valid node table -- it declares no entities,
+ * or every entity lacks a KEY -- since a property graph with an empty NODE
+ * TABLES block is invalid DDL that BigQuery would reject.
+ */
+export declare function generatePropertyGraph(model: SemanticModel, opts?: GenerateOptions): GenerateResult;
+export declare function elementDescription(description?: string, ai?: AiContext): string | undefined;
+export declare function fieldDescription(field: Field): string | undefined;