@causa/workspace-google 1.3.1 → 1.4.0-beta.2

package/dist/graph/rules/terraform/event-topics.js

@@ -0,0 +1,193 @@
+import { GraphOriginKind, } from '@causa/workspace-core';
+import { brokerSubscriptionId, brokerTopicId, databaseId, ModelFact, nodeId, tableId, tableLocator, topicId, } from '@causa/workspace-core/graph';
+import { terraformDeploys } from '@causa/workspace-terraform';
+import { relative } from 'path';
+import { rawEventsTableName } from '../../../functions/google-pubsub/index.js';
+import { BIGQUERY_ENGINE, bigQueryDatasetLocator, rawEventsSubscriptionLocator, } from '../../ids.js';
+import { blockResource, infrastructureModules, argumentOrConfiguration, } from '../../terraform-modules.js';
+/**
+ * The source of the Causa Terraform module creating the Pub/Sub topics, and the raw events BigQuery tables.
+ */
+export const EVENT_TOPICS_MODULE_SOURCE = 'causa-io/event-topics-pubsub/google';
+/**
+ * The configuration defining the raw events BigQuery dataset, when the block does not set it.
+ */
+const RAW_EVENTS_DATASET_CONFIGURATION = 'google.pubSub.bigQueryStorage.rawEventsDatasetId';
+/**
+ * Returns the raw events dataset of an event topics module block: its `bigquery_raw_events_dataset` argument, or the
+ * `google.pubSub.bigQueryStorage.rawEventsDatasetId` configuration.
+ *
+ * @param graph The context of the extraction.
+ * @param module The event topics module block.
+ * @param warnings The warnings of the rule, to which the one about a computed argument is added.
+ * @returns The dataset, or `undefined` if raw events are not stored.
+ */
+async function rawEventsDataset(graph, module, warnings) {
+    const part = argumentOrConfiguration(module.block, 'bigquery_raw_events_dataset', RAW_EVENTS_DATASET_CONFIGURATION, warnings);
+    if (typeof part === 'string') {
+        return {
+            dataset: part,
+            part,
+            locator: bigQueryDatasetLocator(part),
+            sources: [],
+        };
+    }
+    const dataset = module.context
+        .asConfiguration()
+        .get(RAW_EVENTS_DATASET_CONFIGURATION);
+    if (typeof dataset !== 'string') {
+        return undefined;
+    }
+    return {
+        dataset,
+        part,
+        locator: bigQueryDatasetLocator(dataset),
+        sources: [
+            await graph.locator.configurationSource(module.context, RAW_EVENTS_DATASET_CONFIGURATION.split('.')),
+        ],
+    };
+}
+/**
+ * The resources created by the event topics module block.
+ *
+ * - A `brokerTopic` node per event topic, named by the topic ID: the module creates one Pub/Sub topic per topic listed
+ *   by `EventTopicList`. It `realizes` the event topic of the same ID.
+ * - When the block has a raw events dataset (`bigquery_raw_events_dataset`, or
+ *   `google.pubSub.bigQueryStorage.rawEventsDatasetId`), a `database` node for the BigQuery dataset, and for each
+ *   topic:
+ *   - A `table` node, named by the topic ID with `.` and `-` replaced by `_`.
+ *   - A BigQuery `brokerSubscription` node: the module creates one `bq-<topic>` subscription per topic, writing events
+ *     to the topic's raw table. The broker topic `delivers` to it, and it `targets` the table.
+ */
+export const eventTopicsModule = {
+    name: 'eventTopicsModule',
+    kind: GraphOriginKind.Declared,
+    description: 'One `brokerTopic` per event topic for the first event topics module block, realizing the topic. When the block has a raw events BigQuery dataset, one `database` node for the dataset, and for each topic one `table` node, named by the topic ID with `.` and `-` replaced by `_`, and one `brokerSubscription` (`rawEvents/<topic>`) delivered to by the broker topic and targeting the table. Each resource is linked by a `deploys` edge from the projects applying the block.',
+    async run(graph) {
+        const { context } = graph;
+        const [eventTopics, model] = await Promise.all([
+            infrastructureModules(graph, EVENT_TOPICS_MODULE_SOURCE),
+            graph.get(ModelFact),
+        ]);
+        const nodes = [];
+        const edges = [];
+        const warnings = [];
+        const [module, ...skipped] = eventTopics;
+        if (!module) {
+            if (model.topics.size > 0) {
+                warnings.push({
+                    message: 'There is no event topics module block: no broker topics are created for the event topics.',
+                });
+            }
+            return { warnings };
+        }
+        warnings.push(...skipped.map((m) => ({
+            message: 'The event topics module block is skipped: only the first one is processed, as several blocks would create resources with the same IDs.',
+            sources: [m.block.declaration],
+        })));
+        const source = module.block.declaration;
+        const projectPart = argumentOrConfiguration(module.block, 'gcp_project_id', 'google.project', warnings);
+        const rawEvents = await rawEventsDataset(graph, module, warnings);
+        if (rawEvents) {
+            const data = {
+                engine: BIGQUERY_ENGINE,
+                resource: await blockResource(graph, module.block, {
+                    type: 'bigquery.googleapis.com/Dataset',
+                    scope: module.project,
+                    id: ['projects/', projectPart, '/datasets/', rawEvents.part],
+                }, warnings),
+            };
+            nodes.push({
+                layer: 'infrastructure',
+                type: 'database',
+                locator: rawEvents.locator,
+                name: rawEvents.dataset,
+                description: 'Raw events from Pub/Sub, one table per topic.',
+                sources: [source, ...rawEvents.sources],
+                data,
+            });
+            edges.push(...terraformDeploys(module.block, nodeId('database', rawEvents.locator)));
+        }
+        for (const topic of model.topics.values()) {
+            const schemaSource = {
+                path: relative(context.rootPath, topic.schemaFilePath),
+            };
+            nodes.push({
+                layer: 'infrastructure',
+                type: 'brokerTopic',
+                locator: topic.id,
+                name: topic.id,
+                sources: [source, schemaSource],
+                data: {
+                    resource: await blockResource(graph, module.block, {
+                        type: 'pubsub.googleapis.com/Topic',
+                        scope: module.project,
+                        id: ['projects/', projectPart, `/topics/${topic.id}`],
+                    }, warnings),
+                },
+            });
+            edges.push(...terraformDeploys(module.block, nodeId('brokerTopic', topic.id)), {
+                type: 'realizes',
+                from: brokerTopicId(topic.id),
+                to: topicId(topic.id),
+                sources: [source],
+            });
+            if (!rawEvents) {
+                continue;
+            }
+            const tableName = rawEventsTableName(topic.id);
+            const rawTableLocator = tableLocator(rawEvents.locator, tableName);
+            nodes.push({
+                layer: 'infrastructure',
+                type: 'table',
+                locator: rawTableLocator,
+                parent: databaseId(rawEvents.locator),
+                name: tableName,
+                description: `Raw \`${topic.id}\` events.`,
+                sources: [source, schemaSource],
+                data: {
+                    resource: await blockResource(graph, module.block, {
+                        type: 'bigquery.googleapis.com/Table',
+                        scope: module.project,
+                        id: [
+                            'projects/',
+                            projectPart,
+                            '/datasets/',
+                            rawEvents.part,
+                            `/tables/${tableName}`,
+                        ],
+                    }, warnings),
+                },
+            });
+            edges.push(...terraformDeploys(module.block, nodeId('table', rawTableLocator)));
+            const subscriptionLocator = rawEventsSubscriptionLocator(topic.id);
+            const subscription = `bq-${topic.id}`;
+            nodes.push({
+                layer: 'infrastructure',
+                type: 'brokerSubscription',
+                locator: subscriptionLocator,
+                name: subscription,
+                sources: [source, ...rawEvents.sources],
+                data: {
+                    resource: await blockResource(graph, module.block, {
+                        type: 'pubsub.googleapis.com/Subscription',
+                        scope: module.project,
+                        id: ['projects/', projectPart, `/subscriptions/${subscription}`],
+                    }, warnings),
+                },
+            });
+            edges.push(...terraformDeploys(module.block, nodeId('brokerSubscription', subscriptionLocator)), {
+                type: 'delivers',
+                from: brokerTopicId(topic.id),
+                to: brokerSubscriptionId(subscriptionLocator),
+                sources: [source],
+            }, {
+                type: 'targets',
+                from: brokerSubscriptionId(subscriptionLocator),
+                to: tableId(rawEvents.locator, tableName),
+                sources: [source],
+            });
+        }
+        return { nodes, edges, warnings };
+    },
+};

package/dist/graph/rules/terraform/index.d.ts

@@ -0,0 +1,5 @@
+import type { GraphRule } from '@causa/workspace-core';
+/**
+ * The Google rules mirroring the Causa Terraform modules, grouped by module.
+ */
+export declare const GOOGLE_TERRAFORM_GRAPH_RULES: readonly GraphRule[];

package/dist/graph/rules/terraform/index.js

@@ -0,0 +1,13 @@
+import { apiRouterModule } from './api-router.js';
+import { cloudRunModule } from './cloud-run-module.js';
+import { eventTopicsModule } from './event-topics.js';
+import { spannerDatabasesModule } from './spanner-databases.js';
+/**
+ * The Google rules mirroring the Causa Terraform modules, grouped by module.
+ */
+export const GOOGLE_TERRAFORM_GRAPH_RULES = [
+    cloudRunModule,
+    apiRouterModule,
+    eventTopicsModule,
+    spannerDatabasesModule,
+];

package/dist/graph/rules/terraform/spanner-databases.d.ts

@@ -0,0 +1,17 @@
+import { type GraphRule } from '@causa/workspace-core';
+/**
+ * The source of the Causa Terraform module creating the Spanner instance and databases.
+ */
+export declare const SPANNER_DATABASES_MODULE_SOURCE = "causa-io/spanner-databases/google";
+/**
+ * The resources created by the blocks of the Spanner databases module:
+ *
+ * - A `google.spanner.instance` node per block, which creates the instance from `google.spanner.instance.name`.
+ * - A `database` node per Spanner database, as `GoogleSpannerListDatabases` lists them. The locator is
+ *   `google.spanner/<instance>.<database>`, and the parent is the instance.
+ * - A `table` node per `CREATE TABLE` statement in the DDL files of each database. Tables no schema declares (e.g. an
+ *   outbox) are still nodes, realizing nothing.
+ * - A `realizes` edge from a table to the entity whose binding names it. The table is the one created by the DDL of a
+ *   database, disambiguated by domain when several databases create a table with the same name.
+ */
+export declare const spannerDatabasesModule: GraphRule;

package/dist/graph/rules/terraform/spanner-databases.js

@@ -0,0 +1,180 @@
+import { GraphOriginKind, } from '@causa/workspace-core';
+import { databaseId, tableId, tableLocator, DomainsFact, ModelFact, nodeId, } from '@causa/workspace-core/graph';
+import { terraformDeploys } from '@causa/workspace-terraform';
+import { SPANNER_ENGINE, spannerInstanceId } from '../../ids.js';
+import { ddlSource, resolveSpannerTable, SpannerFact } from '../../spanner.js';
+import { blockResource, infrastructureModules, argumentOrConfiguration, } from '../../terraform-modules.js';
+/**
+ * The source of the Causa Terraform module creating the Spanner instance and databases.
+ */
+export const SPANNER_DATABASES_MODULE_SOURCE = 'causa-io/spanner-databases/google';
+/**
+ * Returns the GCP project and instance parts of the resource names created by a Spanner databases module block.
+ */
+function nameParts(module, warnings) {
+    return {
+        project: argumentOrConfiguration(module.block, 'gcp_project_id', 'google.project', warnings),
+        instance: argumentOrConfiguration(module.block, 'instance_name', 'google.spanner.instance.name', warnings),
+    };
+}
+/**
+ * The resources created by the blocks of the Spanner databases module:
+ *
+ * - A `google.spanner.instance` node per block, which creates the instance from `google.spanner.instance.name`.
+ * - A `database` node per Spanner database, as `GoogleSpannerListDatabases` lists them. The locator is
+ *   `google.spanner/<instance>.<database>`, and the parent is the instance.
+ * - A `table` node per `CREATE TABLE` statement in the DDL files of each database. Tables no schema declares (e.g. an
+ *   outbox) are still nodes, realizing nothing.
+ * - A `realizes` edge from a table to the entity whose binding names it. The table is the one created by the DDL of a
+ *   database, disambiguated by domain when several databases create a table with the same name.
+ */
+export const spannerDatabasesModule = {
+    name: 'spannerDatabasesModule',
+    kind: GraphOriginKind.Declared,
+    description: 'One `google.spanner.instance` node per Spanner databases module block, named by `google.spanner.instance.name`. One `database` node per Spanner database listed by `GoogleSpannerListDatabases` from the DDL files, and one `table` node per `CREATE TABLE` in them, realizing the entity whose `googleSpannerTable` binding names it, disambiguated by domain. Each resource is linked by a `deploys` edge from the projects applying the block.',
+    async run(graph) {
+        const { locator, context } = graph;
+        const [domains, model, spanner, spannerDatabases] = await Promise.all([
+            graph.get(DomainsFact),
+            graph.get(ModelFact),
+            graph.get(SpannerFact),
+            infrastructureModules(graph, SPANNER_DATABASES_MODULE_SOURCE),
+        ]);
+        const nodes = [];
+        const edges = [];
+        const warnings = [];
+        for (const module of spannerDatabases) {
+            const source = module.block.declaration;
+            if (!spanner.instance) {
+                warnings.push({
+                    message: "A Spanner databases module block exists, but 'google.spanner.instance.name' is not set.",
+                    sources: [source],
+                });
+                continue;
+            }
+            const { project, instance } = nameParts(module, warnings);
+            if (module.block.arguments['instance_name'] !== undefined) {
+                warnings.push({
+                    message: `The module overrides the instance name. Locators use the configured '${spanner.instance}'.`,
+                    sources: [source],
+                });
+            }
+            nodes.push({
+                layer: 'infrastructure',
+                type: 'google.spanner.instance',
+                locator: spanner.instance,
+                name: spanner.instance,
+                sources: [
+                    await locator.configurationSource(module.context, [
+                        'google',
+                        'spanner',
+                        'instance',
+                        'name',
+                    ]),
+                    source,
+                ],
+                data: {
+                    resource: await blockResource(graph, module.block, {
+                        type: 'spanner.googleapis.com/Instance',
+                        scope: module.project,
+                        id: ['projects/', project, '/instances/', instance],
+                    }, warnings),
+                },
+            });
+            edges.push(...terraformDeploys(module.block, nodeId('google.spanner.instance', spanner.instance)));
+            for (const database of spanner.databases) {
+                const data = {
+                    engine: SPANNER_ENGINE,
+                    resource: await blockResource(graph, module.block, {
+                        type: 'spanner.googleapis.com/Database',
+                        scope: module.project,
+                        id: [
+                            'projects/',
+                            project,
+                            '/instances/',
+                            instance,
+                            `/databases/${database.id}`,
+                        ],
+                    }, warnings),
+                };
+                nodes.push({
+                    layer: 'infrastructure',
+                    type: 'database',
+                    locator: database.locator,
+                    parent: spannerInstanceId(spanner.instance),
+                    name: database.id,
+                    sources: [
+                        { path: database.directory },
+                        await locator.configurationSource(context, [
+                            'google',
+                            'spanner',
+                            'ddls',
+                        ]),
+                        source,
+                    ],
+                    data,
+                });
+                edges.push(...terraformDeploys(module.block, nodeId('database', database.locator)));
+            }
+        }
+        if (spanner.databases.length > 0 && spannerDatabases.length === 0) {
+            warnings.push({
+                message: 'Spanner DDL files exist but no Spanner databases module block creates the databases.',
+            });
+        }
+        if (!spanner.instance || spannerDatabases.length === 0) {
+            return { nodes, edges, warnings };
+        }
+        const blocks = spannerDatabases.map((m) => m.block.declaration);
+        for (const database of spanner.databases) {
+            for (const table of database.tables) {
+                const nodeLocator = tableLocator(database.locator, table.name);
+                nodes.push({
+                    layer: 'infrastructure',
+                    type: 'table',
+                    locator: nodeLocator,
+                    parent: databaseId(database.locator),
+                    name: table.name,
+                    sources: [ddlSource(table), ...blocks],
+                });
+                edges.push(...spannerDatabases.flatMap((module) => terraformDeploys(module.block, nodeId('table', nodeLocator))));
+            }
+        }
+        for (const entity of model.entities.values()) {
+            const resolution = resolveSpannerTable(spanner, entity, domains);
+            if (!resolution) {
+                continue;
+            }
+            const { file, segments, definition } = entity.schema;
+            const binding = await locator.source(file, [
+                ...segments,
+                'causa',
+                'googleSpannerTable',
+            ]);
+            const table = definition.databases.find((d) => d.engine === SPANNER_ENGINE)?.table;
+            if (resolution.kind === 'missing') {
+                warnings.push({
+                    message: `Entity '${definition.name}' binds to Spanner table '${table}', which no DDL creates.`,
+                    sources: [binding],
+                });
+                continue;
+            }
+            if (resolution.kind === 'ambiguous') {
+                warnings.push({
+                    message: `Entity '${definition.name}' binds to Spanner table '${table}', which is created in several databases: ${resolution.candidates
+                        .map((c) => `'${c.id}'`)
+                        .join(', ')}.`,
+                    sources: [binding],
+                });
+                continue;
+            }
+            edges.push({
+                type: 'realizes',
+                from: tableId(resolution.database.locator, resolution.table.name),
+                to: entity.id,
+                sources: [binding, ddlSource(resolution.table)],
+            });
+        }
+        return { nodes, edges, warnings };
+    },
+};

package/dist/graph/spanner.d.ts

@@ -0,0 +1,106 @@
+import type { GraphOriginSource } from '@causa/workspace-core';
+import { GraphExtractionFact, type EntityFacts, type GraphContext, type GraphFactOutput, type WorkspaceDomain } from '@causa/workspace-core/graph';
+/**
+ * A table created by a `CREATE TABLE` statement in a Spanner DDL file.
+ */
+export type SpannerTable = {
+    /**
+     * The name of the table.
+     */
+    readonly name: string;
+    /**
+     * The DDL file declaring the table, relative to the workspace root.
+     */
+    readonly file: string;
+    /**
+     * The line of the statement in the file.
+     */
+    readonly line: number;
+};
+/**
+ * A Spanner database of the workspace, and the tables its DDL files create.
+ */
+export type SpannerDatabaseFacts = {
+    /**
+     * The ID of the database, as `GoogleSpannerListDatabases` returns it.
+     */
+    readonly id: string;
+    /**
+     * The name of the database within its engine, `<instance>.<database>`, as `outputs['google.spanner']` lists it.
+     */
+    readonly name: string;
+    /**
+     * The locator of the `database` node.
+     */
+    readonly locator: string;
+    /**
+     * The directory holding the DDL files, relative to the workspace root.
+     */
+    readonly directory: string;
+    /**
+     * The domain the DDL files belong to.
+     */
+    readonly domain: WorkspaceDomain | undefined;
+    /**
+     * The tables created by the DDL files.
+     */
+    readonly tables: SpannerTable[];
+};
+/**
+ * The Spanner databases of the workspace.
+ */
+export type SpannerFacts = {
+    /**
+     * The Spanner instance, from `google.spanner.instance.name`.
+     */
+    readonly instance: string | undefined;
+    /**
+     * The databases, as `GoogleSpannerListDatabases` lists them.
+     */
+    readonly databases: SpannerDatabaseFacts[];
+};
+/**
+ * The Spanner databases of the workspace, as `GoogleSpannerListDatabases` lists them, and the tables their DDL files
+ * create.
+ */
+export declare class SpannerFact extends GraphExtractionFact<SpannerFacts> {
+    compute(graph: GraphContext): Promise<GraphFactOutput<SpannerFacts>>;
+    /**
+     * Parses the tables created by the `CREATE TABLE` statements of DDL files.
+     *
+     * @param context The workspace context.
+     * @param files The DDL files, relative to the workspace root.
+     * @returns The tables, in the order of the files and statements.
+     */
+    private parseTables;
+}
+/**
+ * The resolution of an entity's Spanner binding to a table.
+ */
+export type SpannerTableResolution = {
+    readonly kind: 'resolved';
+    readonly database: SpannerDatabaseFacts;
+    readonly table: SpannerTable;
+} | {
+    readonly kind: 'ambiguous';
+    readonly candidates: SpannerDatabaseFacts[];
+} | {
+    readonly kind: 'missing';
+};
+/**
+ * Resolves the Spanner binding of an entity to the database whose DDL creates a table of that name. When several
+ * databases declare the name, the one in the entity's domain is chosen.
+ *
+ * @param spanner The Spanner databases.
+ * @param entity The entity.
+ * @param domains The domains of the workspace, in which the domain of the entity is looked up.
+ * @returns The resolution, or `undefined` if the entity is not persisted in Spanner.
+ */
+export declare function resolveSpannerTable(spanner: SpannerFacts, entity: EntityFacts, domains: readonly WorkspaceDomain[]): SpannerTableResolution | undefined;
+/**
+ * Returns the origin source of a `CREATE TABLE` statement.
+ *
+ * @param table The table.
+ * @returns The origin source.
+ */
+export declare function ddlSource(table: SpannerTable): GraphOriginSource;

package/dist/graph/spanner.js

@@ -0,0 +1,118 @@
+import { domainAt, domainOfFile, DomainsFact, GraphExtractionFact, } from '@causa/workspace-core/graph';
+import { readFile } from 'fs/promises';
+import { dirname, join, relative } from 'path';
+import { GoogleSpannerListDatabases } from '../functions/google-spanner/index.js';
+import { SPANNER_ENGINE, spannerDatabaseLocator, spannerDatabaseName, } from './ids.js';
+/**
+ * The Spanner databases of the workspace, as `GoogleSpannerListDatabases` lists them, and the tables their DDL files
+ * create.
+ */
+export class SpannerFact extends GraphExtractionFact {
+    async compute(graph) {
+        const { context } = graph;
+        const instance = context
+            .asConfiguration()
+            .get('google.spanner.instance.name');
+        const [listed, domains] = await Promise.all([
+            context.call(GoogleSpannerListDatabases, {}),
+            graph.get(DomainsFact),
+        ]);
+        const databases = await Promise.all(listed.map(async ({ id, ddlFiles }) => {
+            const files = ddlFiles.map((f) => relative(context.rootPath, f)).sort();
+            const tables = await this.parseTables(context, files);
+            const directory = files[0] ? dirname(files[0]) : '';
+            return {
+                id,
+                name: spannerDatabaseName(instance ?? '', id),
+                locator: spannerDatabaseLocator(instance ?? '', id),
+                directory,
+                domain: directory ? domainAt(domains, directory) : undefined,
+                tables,
+            };
+        }));
+        databases.sort((a, b) => a.id.localeCompare(b.id));
+        const warnings = [];
+        for (const database of databases) {
+            const names = new Set();
+            for (const table of database.tables) {
+                if (names.has(table.name)) {
+                    warnings.push({
+                        message: `Table '${table.name}' is created twice in database '${database.id}'.`,
+                        sources: [ddlSource(table)],
+                    });
+                }
+                names.add(table.name);
+            }
+        }
+        return { value: { instance, databases }, warnings };
+    }
+    /**
+     * Parses the tables created by the `CREATE TABLE` statements of DDL files.
+     *
+     * @param context The workspace context.
+     * @param files The DDL files, relative to the workspace root.
+     * @returns The tables, in the order of the files and statements.
+     */
+    async parseTables(context, files) {
+        const tables = [];
+        for (const file of files) {
+            const content = await readFile(join(context.rootPath, file), 'utf-8');
+            const withoutComments = content.replace(/--.*$/gm, (m) => ' '.repeat(m.length));
+            const statements = withoutComments.matchAll(/\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"']?([A-Za-z_]\w*)[`"']?/gi);
+            for (const match of statements) {
+                tables.push({
+                    name: match[1],
+                    file,
+                    line: withoutComments.slice(0, match.index).split('\n').length,
+                });
+            }
+        }
+        return tables;
+    }
+}
+/**
+ * Resolves the Spanner binding of an entity to the database whose DDL creates a table of that name. When several
+ * databases declare the name, the one in the entity's domain is chosen.
+ *
+ * @param spanner The Spanner databases.
+ * @param entity The entity.
+ * @param domains The domains of the workspace, in which the domain of the entity is looked up.
+ * @returns The resolution, or `undefined` if the entity is not persisted in Spanner.
+ */
+export function resolveSpannerTable(spanner, entity, domains) {
+    const { definition, file } = entity.schema;
+    const table = definition.databases.find((d) => d.engine === SPANNER_ENGINE)?.table;
+    if (!table) {
+        return undefined;
+    }
+    const candidates = spanner.databases.filter((d) => d.tables.some((t) => t.name === table));
+    const pick = (database) => ({
+        kind: 'resolved',
+        database,
+        table: database.tables.find((t) => t.name === table),
+    });
+    if (candidates.length === 1) {
+        return pick(candidates[0]);
+    }
+    if (candidates.length === 0) {
+        return { kind: 'missing' };
+    }
+    const domain = domainOfFile(domains, file);
+    const sameDomain = candidates.filter((d) => domain && d.domain?.directory === domain.directory);
+    return sameDomain.length === 1
+        ? pick(sameDomain[0])
+        : { kind: 'ambiguous', candidates };
+}
+/**
+ * Returns the origin source of a `CREATE TABLE` statement.
+ *
+ * @param table The table.
+ * @returns The origin source.
+ */
+export function ddlSource(table) {
+    return {
+        path: table.file,
+        pointer: `CREATE TABLE ${table.name}`,
+        location: { start: { line: table.line } },
+    };
+}