@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/chunk.js

@@ -0,0 +1,110 @@
+/**
+ * Per-model work units (when the project has more than 25 YAML files) only name `rawFiles` under
+ * `models/**`. Other `.yml` (e.g. some `seeds/` or custom layouts) still appear in `peerFileIndex`
+ * or in the small-project / no-models fallbacks — v1 does not emit one WU per non-models file.
+ */
+const MODELS_PREFIX = 'models/';
+/** `peerFileIndex` is a hint only (agents may not read those paths). Cap to limit prompt size. */
+const MAX_PEER_FILE_INDEX = 200;
+function projectYamlPath(allPaths) {
+    if (allPaths.includes('dbt_project.yml')) {
+        return 'dbt_project.yml';
+    }
+    if (allPaths.includes('dbt_project.yaml')) {
+        return 'dbt_project.yaml';
+    }
+    return undefined;
+}
+function modelRelativePaths(allPaths) {
+    return allPaths.filter((p) => p.replace(/\\/g, '/').startsWith(MODELS_PREFIX)).sort();
+}
+function unitKeyForModelFile(mf) {
+    const base = mf
+        .replace(/\.(ya?ml)$/i, '')
+        .replace(/\\/g, '/')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return `dbt-${base.toLowerCase()}`;
+}
+function emitFirstRunWorkUnits(allPaths, dbtDep) {
+    if (allPaths.length === 0) {
+        return [];
+    }
+    if (allPaths.length <= 25) {
+        return [
+            {
+                unitKey: 'dbt-all',
+                displayLabel: 'dbt project (all yaml)',
+                rawFiles: [...allPaths],
+                peerFileIndex: [],
+                dependencyPaths: [],
+                notes: 'dbt project — all YAML in one WorkUnit (≤25 files)',
+            },
+        ];
+    }
+    const modelFiles = modelRelativePaths(allPaths);
+    if (modelFiles.length === 0) {
+        return [
+            {
+                unitKey: 'dbt-all',
+                displayLabel: 'dbt project (all yaml, no models/**)',
+                rawFiles: [...allPaths],
+                peerFileIndex: [],
+                dependencyPaths: dbtDep ? [dbtDep] : [],
+                notes: 'dbt: no models/**/*.yml — single slice with dbt_project as dependency if present',
+            },
+        ];
+    }
+    return modelFiles.map((mf) => {
+        const allPeers = allPaths.filter((p) => p !== mf).sort();
+        const truncated = allPeers.length > MAX_PEER_FILE_INDEX;
+        const peerFileIndex = truncated ? allPeers.slice(0, MAX_PEER_FILE_INDEX) : allPeers;
+        const dependencyPaths = dbtDep && allPaths.includes(dbtDep) && mf !== dbtDep ? [dbtDep].sort() : [];
+        const notes = truncated
+            ? `dbt model schema slice (peer index capped at ${MAX_PEER_FILE_INDEX} of ${allPeers.length} paths)`
+            : 'dbt model schema slice';
+        return {
+            unitKey: unitKeyForModelFile(mf),
+            displayLabel: `dbt ${mf}`,
+            rawFiles: [mf],
+            peerFileIndex,
+            dependencyPaths: dependencyPaths,
+            notes,
+        };
+    });
+}
+function applyDiffSet(firstRunUnits, diffSet) {
+    const touched = new Set([...diffSet.added, ...diffSet.modified]);
+    const kept = [];
+    for (const wu of firstRunUnits) {
+        const touchedRawFiles = wu.rawFiles.filter((p) => touched.has(p));
+        const touchedDependencies = wu.dependencyPaths.filter((p) => touched.has(p));
+        const touchedPeerFiles = wu.peerFileIndex.filter((p) => touched.has(p));
+        if (touchedRawFiles.length === 0 && touchedDependencies.length === 0 && touchedPeerFiles.length === 0) {
+            continue;
+        }
+        const rawFiles = touchedRawFiles.length > 0 ? touchedRawFiles : wu.rawFiles;
+        const unchangedRaw = touchedRawFiles.length > 0 ? wu.rawFiles.filter((p) => !touched.has(p)) : [];
+        for (const p of wu.rawFiles) {
+            if (!rawFiles.includes(p) && !unchangedRaw.includes(p)) {
+                unchangedRaw.push(p);
+            }
+        }
+        const combinedDeps = new Set([...wu.dependencyPaths, ...unchangedRaw, ...touchedPeerFiles]);
+        kept.push({
+            ...wu,
+            rawFiles: rawFiles.sort(),
+            dependencyPaths: [...combinedDeps].sort(),
+        });
+    }
+    const eviction = diffSet.deleted.length > 0 ? { deletedRawPaths: [...diffSet.deleted].sort() } : undefined;
+    return { workUnits: kept, eviction };
+}
+export function chunkDbtProject(project, opts = {}) {
+    const dbtDep = projectYamlPath(project.allPaths);
+    const firstRun = emitFirstRunWorkUnits(project.allPaths, dbtDep);
+    if (!opts.diffSet) {
+        return { workUnits: firstRun };
+    }
+    return applyDiffSet(firstRun, opts.diffSet);
+}

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/chunk.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/chunk.test.js

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { chunkDbtProject } from './chunk.js';
+describe('chunkDbtProject', () => {
+    const diffSet = (modified) => ({ added: [], modified, deleted: [], unchanged: [] });
+    it('caps peerFileIndex when the project has very many yaml files', () => {
+        const modelPaths = Array.from({ length: 201 }, (_, i) => `models/m${i}.yml`);
+        const allPaths = ['dbt_project.yml', ...modelPaths].sort();
+        const { workUnits } = chunkDbtProject({ allPaths });
+        const [first] = workUnits;
+        expect(first).toBeDefined();
+        expect(first?.peerFileIndex).toHaveLength(200);
+        expect(first?.notes).toMatch(/capped at 200/);
+    });
+    it('keeps large-project model work units when dbt_project.yml changes', () => {
+        const modelPaths = Array.from({ length: 30 }, (_, i) => `models/m${i}.yml`);
+        const allPaths = ['dbt_project.yml', ...modelPaths].sort();
+        const { workUnits } = chunkDbtProject({ allPaths }, { diffSet: diffSet(['dbt_project.yml']) });
+        expect(workUnits).toHaveLength(30);
+        expect(workUnits[0]?.rawFiles).toEqual(['models/m0.yml']);
+        expect(workUnits[0]?.dependencyPaths).toContain('dbt_project.yml');
+    });
+    it('keeps large-project model work units when non-model yaml peers change', () => {
+        const modelPaths = Array.from({ length: 30 }, (_, i) => `models/m${i}.yml`);
+        const allPaths = ['dbt_project.yml', 'seeds/seed_properties.yml', ...modelPaths].sort();
+        const { workUnits } = chunkDbtProject({ allPaths }, { diffSet: diffSet(['seeds/seed_properties.yml']) });
+        expect(workUnits).toHaveLength(30);
+        expect(workUnits[0]?.rawFiles).toEqual(['models/m0.yml']);
+        expect(workUnits[0]?.dependencyPaths).toContain('seeds/seed_properties.yml');
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/dbt.adapter.d.ts

@@ -0,0 +1,16 @@
+import type { ChunkResult, DiffSet, SourceAdapter } from '../../types.js';
+import type { FetchContext } from '../../types.js';
+interface DbtSourceAdapterOptions {
+    homeDir?: string;
+}
+export declare class DbtSourceAdapter implements SourceAdapter {
+    private readonly options;
+    readonly source: "dbt";
+    /** Runner merges: ingest_triage, sl_capture, knowledge_capture (see ingest-bundle.runner.ts) */
+    readonly skillNames: string[];
+    constructor(options?: DbtSourceAdapterOptions);
+    detect(stagedDir: string): Promise<boolean>;
+    fetch(pullConfig: unknown, stagedDir: string, ctx: FetchContext): Promise<void>;
+    chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
+}
+export {};

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/dbt.adapter.js

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+import { loadProjectInfo } from '../../dbt-shared/project-vars.js';
+import { loadDbtSchemaFiles } from '../../dbt-shared/schema-files.js';
+import { parseDbtSchemaFiles } from '../dbt-descriptions/parse-schema.js';
+import { chunkDbtProject } from './chunk.js';
+import { detectDbtStagedDir } from './detect.js';
+import { fetchDbtRepo } from './fetch.js';
+import { parseDbtStagedDir } from './parse.js';
+export class DbtSourceAdapter {
+    options;
+    source = 'dbt';
+    /** Runner merges: ingest_triage, sl_capture, knowledge_capture (see ingest-bundle.runner.ts) */
+    skillNames = ['dbt_ingest'];
+    constructor(options = {}) {
+        this.options = options;
+    }
+    detect(stagedDir) {
+        return detectDbtStagedDir(stagedDir);
+    }
+    async fetch(pullConfig, stagedDir, ctx) {
+        const config = pullConfig;
+        if (!config?.repoUrl) {
+            throw new Error('dbt fetch requires repoUrl');
+        }
+        await fetchDbtRepo({
+            config,
+            cacheDir: join(this.options.homeDir ?? '.ktx/cache', 'dbt', ctx.connectionId),
+            stagedDir,
+        });
+    }
+    async chunk(stagedDir, diffSet) {
+        const project = await parseDbtStagedDir(stagedDir);
+        const projectInfo = await loadProjectInfo(stagedDir);
+        const schemaFiles = await loadDbtSchemaFiles(stagedDir);
+        const parseArtifacts = parseDbtSchemaFiles(schemaFiles, projectInfo.variables, {
+            projectName: projectInfo.projectName,
+        });
+        return { ...chunkDbtProject(project, { diffSet }), parseArtifacts };
+    }
+}

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/dbt.adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/dbt.adapter.test.js

@@ -0,0 +1,39 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { DbtSourceAdapter } from './dbt.adapter.js';
+describe('DbtSourceAdapter', () => {
+    let stagedDir;
+    let adapter;
+    beforeEach(async () => {
+        stagedDir = await mkdtemp(join(tmpdir(), 'dbt-adapter-'));
+        adapter = new DbtSourceAdapter();
+    });
+    afterEach(async () => {
+        await rm(stagedDir, { recursive: true, force: true });
+    });
+    it('declares the expected source key and skill list', () => {
+        expect(adapter.source).toBe('dbt');
+        expect(adapter.skillNames).toEqual(['dbt_ingest']);
+    });
+    it('detects a staged dbt project root (dbt_project.yml)', async () => {
+        await writeFile(join(stagedDir, 'dbt_project.yml'), "name: 'jaffle'\nversion: '1.0.0'\n", 'utf-8');
+        expect(await adapter.detect(stagedDir)).toBe(true);
+    });
+    it('chunk: dbt_project.yml + models/a.yml yields one WU (≤25 files)', async () => {
+        await writeFile(join(stagedDir, 'dbt_project.yml'), "name: 'jaffle'\n", 'utf-8');
+        await mkdir(join(stagedDir, 'models'), { recursive: true });
+        await writeFile(join(stagedDir, 'models/a.yml'), 'version: 2\nmodels:\n  - name: orders\n    description: Orders\n', 'utf-8');
+        const result = await adapter.chunk(stagedDir);
+        expect(result.workUnits).toHaveLength(1);
+        expect(result.workUnits[0].unitKey).toBe('dbt-all');
+        expect(result.parseArtifacts).toMatchObject({
+            projectName: 'jaffle',
+            tables: [{ name: 'orders', description: 'Orders' }],
+        });
+    });
+    it('implements fetch() for git-backed dbt source setup', () => {
+        expect(adapter.fetch).toBeTypeOf('function');
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/detect.d.ts

@@ -0,0 +1 @@
+export declare function detectDbtStagedDir(stagedDir: string): Promise<boolean>;

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/detect.js

@@ -0,0 +1,12 @@
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function detectDbtStagedDir(stagedDir) {
+    for (const name of ['dbt_project.yml', 'dbt_project.yaml']) {
+        try {
+            await access(join(stagedDir, name));
+            return true;
+        }
+        catch { }
+    }
+    return false;
+}

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/fetch.d.ts

@@ -0,0 +1,19 @@
+import { cloneOrPull } from '../../repo-fetch.js';
+export interface DbtPullConfig {
+    repoUrl: string;
+    branch?: string;
+    path?: string;
+    authToken?: string | null;
+}
+export interface FetchDbtRepoParams {
+    config: DbtPullConfig;
+    cacheDir: string;
+    stagedDir: string;
+    deps?: {
+        cloneOrPull?: typeof cloneOrPull;
+    };
+}
+export declare function fetchDbtRepo(params: FetchDbtRepoParams): Promise<{
+    commitHash: string;
+    filesCopied: number;
+}>;

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/fetch.js

@@ -0,0 +1,43 @@
+import { access, copyFile, mkdir, readdir } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { cloneOrPull, sanitizeRepoError } from '../../repo-fetch.js';
+export async function fetchDbtRepo(params) {
+    try {
+        const runCloneOrPull = params.deps?.cloneOrPull ?? cloneOrPull;
+        const { commitHash } = await runCloneOrPull({
+            repoUrl: params.config.repoUrl,
+            authToken: params.config.authToken,
+            cacheDir: params.cacheDir,
+            branch: params.config.branch ?? 'main',
+        });
+        const sourceRoot = params.config.path ? join(params.cacheDir, params.config.path) : params.cacheDir;
+        const filesCopied = await copyYamlFilesRecursive(sourceRoot, params.stagedDir);
+        return { commitHash, filesCopied };
+    }
+    catch (error) {
+        throw new Error(sanitizeRepoError(error, params.config.authToken));
+    }
+}
+async function copyYamlFilesRecursive(sourceRoot, destRoot) {
+    try {
+        await access(sourceRoot);
+    }
+    catch {
+        return 0;
+    }
+    await mkdir(destRoot, { recursive: true });
+    const entries = await readdir(sourceRoot, { withFileTypes: true, recursive: true });
+    let copied = 0;
+    for (const entry of entries) {
+        if (!entry.isFile() || !/\.ya?ml$/i.test(entry.name)) {
+            continue;
+        }
+        const absSrc = join(entry.parentPath, entry.name);
+        const rel = relative(sourceRoot, absSrc);
+        const dest = join(destRoot, rel);
+        await mkdir(dirname(dest), { recursive: true });
+        await copyFile(absSrc, dest);
+        copied += 1;
+    }
+    return copied;
+}

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/fetch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/fetch.test.js

@@ -0,0 +1,30 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fetchDbtRepo } from './fetch.js';
+describe('fetchDbtRepo', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-dbt-fetch-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('copies dbt yaml files from a fetched repo subpath into staged dir', async () => {
+        const cacheDir = join(tempDir, 'cache');
+        const stagedDir = join(tempDir, 'staged');
+        await mkdir(join(cacheDir, 'analytics', 'models'), { recursive: true });
+        await writeFile(join(cacheDir, 'analytics', 'dbt_project.yml'), 'name: analytics\n', 'utf-8');
+        await writeFile(join(cacheDir, 'analytics', 'models', 'orders.yml'), 'models: []\n', 'utf-8');
+        const cloneOrPull = vi.fn(async () => ({ commitHash: 'abc123' }));
+        await expect(fetchDbtRepo({
+            config: { repoUrl: 'https://github.com/acme/dbt.git', path: 'analytics' },
+            cacheDir,
+            stagedDir,
+            deps: { cloneOrPull },
+        })).resolves.toEqual({ commitHash: 'abc123', filesCopied: 2 });
+        await expect(readFile(join(stagedDir, 'dbt_project.yml'), 'utf-8')).resolves.toContain('analytics');
+        await expect(readFile(join(stagedDir, 'models', 'orders.yml'), 'utf-8')).resolves.toContain('models');
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/parse.d.ts

@@ -0,0 +1,6 @@
+export declare function normalizeDbtPath(path: string): string;
+export interface ParsedDbtProject {
+    /** All `.yml` / `.yaml` paths under stagedDir, relative + sorted. */
+    allPaths: string[];
+}
+export declare function parseDbtStagedDir(stagedDir: string): Promise<ParsedDbtProject>;

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/parse.js

@@ -0,0 +1,23 @@
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const YAML_EXT_RE = /\.(ya?ml)$/i;
+export function normalizeDbtPath(path) {
+    return path.replaceAll('\\', '/');
+}
+async function collectYamlFiles(stagedDir) {
+    const entries = await readdir(stagedDir, { withFileTypes: true, recursive: true });
+    const paths = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !YAML_EXT_RE.test(entry.name)) {
+            continue;
+        }
+        const abs = join(entry.parentPath, entry.name);
+        paths.push(normalizeDbtPath(relative(stagedDir, abs)));
+    }
+    paths.sort();
+    return paths;
+}
+export async function parseDbtStagedDir(stagedDir) {
+    const allPaths = await collectYamlFiles(stagedDir);
+    return { allPaths };
+}

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/parse.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/ingest/adapters/dbt/parse.test.js

@@ -0,0 +1,7 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeDbtPath } from './parse.js';
+describe('normalizeDbtPath', () => {
+    it('normalizes Windows separators to POSIX separators', () => {
+        expect(normalizeDbtPath('models\\marts\\orders.yml')).toBe('models/marts/orders.yml');
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/dbt-descriptions/match-tables.d.ts

@@ -0,0 +1,27 @@
+import type { DbtParsedTable } from './parse-schema.js';
+export interface DbtHostTableLite {
+    id: string;
+    name: string;
+    catalog: string | null;
+    db: string | null;
+    columns: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export interface DbtTableMatch {
+    dbtTable: string;
+    dbtSchema: string | null;
+    dbtDatabase: string | null;
+    hostTableId: string | null;
+    hostTableName: string | null;
+    matched: boolean;
+    tableDescriptionAction: 'skip' | 'import';
+    tableDescriptionFound: boolean;
+    columnsToImport: number;
+    columnsMatched: number;
+    columnsTotal: number;
+    columnDescriptionsFound: number;
+}
+export declare function matchDbtTables(dbtTables: DbtParsedTable[], hostTables: DbtHostTableLite[], targetSchema?: string | null): DbtTableMatch[];
+export declare function findMatchingKtxTable(dbtTable: DbtParsedTable, hostTables: DbtHostTableLite[], targetSchema?: string | null): DbtHostTableLite | undefined;

package/node_modules/@ktx/context/dist/ingest/adapters/dbt-descriptions/match-tables.js

@@ -0,0 +1,80 @@
+export function matchDbtTables(dbtTables, hostTables, targetSchema) {
+    return dbtTables.map((dbtTable) => {
+        const hostTable = findMatchingKtxTable(dbtTable, hostTables, targetSchema);
+        if (!hostTable) {
+            return {
+                dbtTable: dbtTable.name,
+                dbtSchema: dbtTable.schema,
+                dbtDatabase: dbtTable.database,
+                hostTableId: null,
+                hostTableName: null,
+                matched: false,
+                tableDescriptionAction: 'skip',
+                tableDescriptionFound: Boolean(dbtTable.description),
+                columnsToImport: 0,
+                columnsMatched: 0,
+                columnsTotal: dbtTable.columns.length,
+                columnDescriptionsFound: dbtTable.columns.filter((column) => Boolean(column.description)).length,
+            };
+        }
+        const analysis = analyzeColumns(dbtTable, hostTable);
+        return {
+            dbtTable: dbtTable.name,
+            dbtSchema: dbtTable.schema,
+            dbtDatabase: dbtTable.database,
+            hostTableId: hostTable.id,
+            hostTableName: hostTable.name,
+            matched: true,
+            tableDescriptionAction: dbtTable.description ? 'import' : 'skip',
+            tableDescriptionFound: Boolean(dbtTable.description),
+            ...analysis,
+        };
+    });
+}
+export function findMatchingKtxTable(dbtTable, hostTables, targetSchema) {
+    const dbtName = dbtTable.name.toLowerCase();
+    const effectiveSchema = dbtTable.schema ?? targetSchema ?? null;
+    if (effectiveSchema) {
+        const strictMatch = hostTables.find((table) => {
+            const nameMatches = table.name.toLowerCase() === dbtName;
+            const schemaMatches = table.db?.toLowerCase() === effectiveSchema.toLowerCase();
+            if (!nameMatches || !schemaMatches) {
+                return false;
+            }
+            if (dbtTable.database && table.catalog) {
+                return table.catalog.toLowerCase() === dbtTable.database.toLowerCase();
+            }
+            return true;
+        });
+        if (strictMatch) {
+            return strictMatch;
+        }
+    }
+    if (dbtTable.resourceType === 'source') {
+        return undefined;
+    }
+    const nameMatches = hostTables.filter((table) => table.name.toLowerCase() === dbtName);
+    return nameMatches.length === 1 ? nameMatches[0] : undefined;
+}
+function analyzeColumns(dbtTable, hostTable) {
+    let columnsToImport = 0;
+    let columnsMatched = 0;
+    let columnDescriptionsFound = 0;
+    for (const dbtColumn of dbtTable.columns) {
+        const hostColumn = hostTable.columns.find((column) => column.name.toLowerCase() === dbtColumn.name.toLowerCase());
+        if (!hostColumn) {
+            continue;
+        }
+        columnsMatched++;
+        if (dbtColumn.description) {
+            columnDescriptionsFound++;
+            columnsToImport++;
+        }
+    }
+    return {
+        columnsToImport,
+        columnsMatched,
+        columnsTotal: dbtTable.columns.length,
+        columnDescriptionsFound,
+    };
+}

package/node_modules/@ktx/context/dist/ingest/adapters/dbt-descriptions/match-tables.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/ingest/adapters/dbt-descriptions/match-tables.test.js

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { findMatchingKtxTable, matchDbtTables } from './match-tables.js';
+const hostTables = [
+    { id: '1', name: 'orders', catalog: 'warehouse', db: 'analytics', columns: [{ id: 'c1', name: 'id' }] },
+    { id: '2', name: 'orders', catalog: 'warehouse', db: 'staging', columns: [{ id: 'c2', name: 'id' }] },
+    { id: '3', name: 'customers', catalog: null, db: null, columns: [{ id: 'c3', name: 'id' }] },
+];
+function table(input) {
+    return {
+        name: 'orders',
+        description: null,
+        database: null,
+        schema: null,
+        columns: [],
+        resourceType: 'model',
+        ...input,
+    };
+}
+describe('dbt descriptions table matching', () => {
+    it('uses schema plus name first and checks catalog when dbt database is present', () => {
+        expect(findMatchingKtxTable(table({ database: 'warehouse', schema: 'analytics' }), hostTables, null)?.id).toBe('1');
+    });
+    it('does not fall back to name-only for source tables', () => {
+        expect(findMatchingKtxTable(table({ resourceType: 'source' }), hostTables, null)).toBeUndefined();
+    });
+    it('uses targetSchema for models and name-only only when unique', () => {
+        expect(findMatchingKtxTable(table({ resourceType: 'model' }), hostTables, 'staging')?.id).toBe('2');
+        expect(findMatchingKtxTable(table({ name: 'customers', resourceType: 'model' }), hostTables, null)?.id).toBe('3');
+        expect(findMatchingKtxTable(table({ resourceType: 'model' }), hostTables, null)).toBeUndefined();
+    });
+    it('summarizes matched columns and descriptions', () => {
+        const matches = matchDbtTables([
+            table({
+                name: 'customers',
+                description: 'Customers',
+                columns: [
+                    { name: 'id', description: 'Primary key', dataType: null },
+                    { name: 'missing', description: 'Missing', dataType: null },
+                ],
+            }),
+        ], hostTables, null);
+        expect(matches).toEqual([
+            {
+                dbtTable: 'customers',
+                dbtSchema: null,
+                dbtDatabase: null,
+                hostTableId: '3',
+                hostTableName: 'customers',
+                matched: true,
+                tableDescriptionAction: 'import',
+                tableDescriptionFound: true,
+                columnsToImport: 1,
+                columnsMatched: 1,
+                columnsTotal: 2,
+                columnDescriptionsFound: 1,
+            },
+        ]);
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/dbt-descriptions/merge-semantic-model-tables.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedSemanticModel } from '../metricflow/deep-parse.js';
+import type { DbtSchemaParseResult } from './parse-schema.js';
+export declare function mergeSemanticModelTables(parseResult: DbtSchemaParseResult, semanticModels: ParsedSemanticModel[]): DbtSchemaParseResult;

package/node_modules/@ktx/context/dist/ingest/adapters/dbt-descriptions/merge-semantic-model-tables.js

@@ -0,0 +1,28 @@
+export function mergeSemanticModelTables(parseResult, semanticModels) {
+    const merged = {
+        ...parseResult,
+        tables: [...parseResult.tables],
+        relationships: [...parseResult.relationships],
+    };
+    const existingTableNames = new Set(merged.tables.map((table) => table.name.toLowerCase()));
+    for (const model of semanticModels) {
+        const tableName = model.modelRef;
+        if (existingTableNames.has(tableName.toLowerCase())) {
+            continue;
+        }
+        merged.tables.push({
+            name: tableName,
+            description: model.description,
+            database: null,
+            schema: null,
+            columns: model.dimensions.map((dimension) => ({
+                name: dimension.column,
+                description: dimension.description ?? null,
+                dataType: dimension.type === 'time' ? 'TIMESTAMP' : null,
+            })),
+            resourceType: 'model',
+        });
+        existingTableNames.add(tableName.toLowerCase());
+    }
+    return merged;
+}

package/node_modules/@ktx/context/dist/ingest/adapters/dbt-descriptions/merge-semantic-model-tables.test.d.ts

@@ -0,0 +1 @@
+export {};