@kaelio/ktx 0.5.0 → 0.7.0

package/dist/context/scan/embedding-text.test.d.ts

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

package/dist/context/scan/embedding-text.test.js

@@ -1,36 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { buildKtxColumnEmbeddingText } from './embedding-text.js';
-describe('KTX scan embedding text', () => {
-    it('builds column embedding text with table, description, FK, and sample-value context', () => {
-        expect(buildKtxColumnEmbeddingText({
-            tableName: 'orders',
-            columnName: 'status',
-            columnType: 'varchar',
-            resolvedDescription: 'Payment lifecycle state',
-            sampleValues: ['paid', 'refunded', 'pending'],
-            resolvedTableDescription: 'Customer orders',
-            foreignKeys: {
-                outgoing: [{ toTable: 'customers', toColumn: 'id' }],
-                incoming: [{ fromTable: 'refunds', fromColumn: 'order_status' }],
-            },
-            maxSampleValues: 2,
-        })).toBe('orders.status (varchar). Table: Customer orders. Payment lifecycle state. FK -> customers.id. FK <- refunds.order_status. Values: paid, refunded');
-    });
-    it('omits optional sections when the scan has no enrichment context yet', () => {
-        expect(buildKtxColumnEmbeddingText({
-            tableName: 'orders',
-            columnName: 'id',
-            columnType: 'integer',
-            resolvedDescription: null,
-        })).toBe('orders.id (integer)');
-    });
-    it('keeps all available sample values when no explicit max is supplied', () => {
-        expect(buildKtxColumnEmbeddingText({
-            tableName: 'orders',
-            columnName: 'status',
-            columnType: 'varchar',
-            resolvedDescription: null,
-            sampleValues: ['paid', 'refunded'],
-        })).toBe('orders.status (varchar). Values: paid, refunded');
-    });
-});

package/dist/context/scan/enrichment-state.test.d.ts

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

package/dist/context/scan/enrichment-state.test.js

@@ -1,147 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { completedKtxScanEnrichmentStateSummary, computeKtxScanEnrichmentInputHash, summarizeKtxScanEnrichmentState, } from './enrichment-state.js';
-import { SqliteLocalScanEnrichmentStateStore } from './sqlite-local-enrichment-state-store.js';
-const snapshot = {
-    connectionId: 'warehouse',
-    driver: 'postgres',
-    extractedAt: '2026-04-29T12:00:00.000Z',
-    scope: { schemas: ['public'] },
-    metadata: {},
-    tables: [
-        {
-            catalog: null,
-            db: 'public',
-            name: 'orders',
-            kind: 'table',
-            comment: null,
-            estimatedRows: 1,
-            foreignKeys: [],
-            columns: [
-                {
-                    name: 'id',
-                    nativeType: 'integer',
-                    normalizedType: 'integer',
-                    dimensionType: 'number',
-                    nullable: false,
-                    primaryKey: true,
-                    comment: null,
-                },
-            ],
-        },
-    ],
-};
-describe('scan enrichment state', () => {
-    let tempDir;
-    let store;
-    beforeEach(async () => {
-        tempDir = await mkdtemp(join(tmpdir(), 'ktx-scan-enrichment-state-'));
-        store = new SqliteLocalScanEnrichmentStateStore({ dbPath: join(tempDir, 'db.sqlite') });
-    });
-    afterEach(async () => {
-        await rm(tempDir, { recursive: true, force: true });
-    });
-    it('computes stable input hashes without depending on object key order', () => {
-        const first = computeKtxScanEnrichmentInputHash({
-            snapshot,
-            mode: 'enriched',
-            detectRelationships: true,
-            providerIdentity: { provider: 'local-heuristic', llmModel: 'a' },
-        });
-        const second = computeKtxScanEnrichmentInputHash({
-            snapshot: { ...snapshot, metadata: {} },
-            mode: 'enriched',
-            detectRelationships: true,
-            providerIdentity: { llmModel: 'a', provider: 'local-heuristic' },
-        });
-        const firstTable = snapshot.tables[0];
-        if (!firstTable) {
-            throw new Error('Expected test snapshot table');
-        }
-        const changed = computeKtxScanEnrichmentInputHash({
-            snapshot: { ...snapshot, tables: [{ ...firstTable, name: 'orders_v2' }] },
-            mode: 'enriched',
-            detectRelationships: true,
-            providerIdentity: { provider: 'local-heuristic', llmModel: 'a' },
-        });
-        expect(first).toMatch(/^[a-f0-9]{64}$/);
-        expect(second).toBe(first);
-        expect(changed).not.toBe(first);
-    });
-    it('persists completed stages and ignores stale hashes', async () => {
-        const inputHash = computeKtxScanEnrichmentInputHash({
-            snapshot,
-            mode: 'enriched',
-            detectRelationships: true,
-            providerIdentity: { provider: 'local-heuristic' },
-        });
-        await store.saveCompletedStage({
-            runId: 'scan-run-1',
-            connectionId: 'warehouse',
-            syncId: 'sync-1',
-            mode: 'enriched',
-            stage: 'descriptions',
-            inputHash,
-            output: [{ table: { catalog: null, db: 'public', name: 'orders' }, tableDescription: 'Orders' }],
-            updatedAt: '2026-04-29T12:01:00.000Z',
-        });
-        await expect(store.findCompletedStage({
-            runId: 'scan-run-1',
-            stage: 'descriptions',
-            inputHash,
-        })).resolves.toMatchObject({
-            runId: 'scan-run-1',
-            stage: 'descriptions',
-            status: 'completed',
-            output: [{ table: { catalog: null, db: 'public', name: 'orders' }, tableDescription: 'Orders' }],
-        });
-        await expect(store.findCompletedStage({
-            runId: 'scan-run-1',
-            stage: 'descriptions',
-            inputHash: 'different-hash',
-        })).resolves.toBeNull();
-    });
-    it('records failed stages without making them reusable', async () => {
-        await store.saveFailedStage({
-            runId: 'scan-run-2',
-            connectionId: 'warehouse',
-            syncId: 'sync-2',
-            mode: 'enriched',
-            stage: 'embeddings',
-            inputHash: 'hash-2',
-            errorMessage: 'embedding service timed out',
-            updatedAt: '2026-04-29T12:02:00.000Z',
-        });
-        await expect(store.findCompletedStage({
-            runId: 'scan-run-2',
-            stage: 'embeddings',
-            inputHash: 'hash-2',
-        })).resolves.toBeNull();
-        await expect(store.listRunStages('scan-run-2')).resolves.toEqual([
-            expect.objectContaining({
-                runId: 'scan-run-2',
-                stage: 'embeddings',
-                status: 'failed',
-                errorMessage: 'embedding service timed out',
-            }),
-        ]);
-    });
-    it('summarizes resumed, completed, and failed stages for reports', () => {
-        expect(summarizeKtxScanEnrichmentState({
-            resumedStages: ['descriptions'],
-            completedStages: ['descriptions', 'embeddings'],
-            failedStages: ['relationships'],
-        })).toEqual({
-            resumedStages: ['descriptions'],
-            completedStages: ['descriptions', 'embeddings'],
-            failedStages: ['relationships'],
-        });
-        expect(completedKtxScanEnrichmentStateSummary()).toEqual({
-            resumedStages: [],
-            completedStages: [],
-            failedStages: [],
-        });
-    });
-});

package/dist/context/scan/enrichment-summary.test.d.ts

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

package/dist/context/scan/enrichment-summary.test.js

@@ -1,34 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { failedKtxScanEnrichmentSummary, ktxScanErrorMessage, skippedKtxScanEnrichmentSummary, } from './enrichment-summary.js';
-describe('KTX scan enrichment summaries', () => {
-    it('keeps structural scans skipped when no enrichment was requested', () => {
-        expect(failedKtxScanEnrichmentSummary('structural', false)).toEqual(skippedKtxScanEnrichmentSummary);
-    });
-    it('marks relationship stages failed when relationship detection fails', () => {
-        expect(failedKtxScanEnrichmentSummary('relationships', true)).toEqual({
-            dataDictionary: 'skipped',
-            tableDescriptions: 'skipped',
-            columnDescriptions: 'skipped',
-            embeddings: 'skipped',
-            deterministicRelationships: 'failed',
-            llmRelationshipValidation: 'skipped',
-            statisticalValidation: 'failed',
-        });
-    });
-    it('marks every enriched-only stage failed when full enrichment fails', () => {
-        expect(failedKtxScanEnrichmentSummary('enriched', true)).toEqual({
-            dataDictionary: 'failed',
-            tableDescriptions: 'failed',
-            columnDescriptions: 'failed',
-            embeddings: 'failed',
-            deterministicRelationships: 'failed',
-            llmRelationshipValidation: 'failed',
-            statisticalValidation: 'failed',
-        });
-    });
-    it('formats unknown thrown values for scan warnings', () => {
-        expect(ktxScanErrorMessage(new Error('gateway timeout'))).toBe('gateway timeout');
-        expect(ktxScanErrorMessage('plain failure')).toBe('plain failure');
-        expect(ktxScanErrorMessage({ code: 'E_SCAN' })).toBe('{"code":"E_SCAN"}');
-    });
-});

package/dist/context/scan/enrichment-types.test.d.ts

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

package/dist/context/scan/enrichment-types.test.js

@@ -1,141 +0,0 @@
-import { describe, expect, it } from 'vitest';
-describe('KTX scan enrichment contracts', () => {
-    it('models an enriched schema with reusable table, column, and relationship metadata', () => {
-        const schema = {
-            connectionId: 'warehouse',
-            tables: [
-                {
-                    id: 'table-orders',
-                    ref: { catalog: 'analytics', db: 'public', name: 'orders' },
-                    enabled: true,
-                    descriptions: { db: 'Raw orders', ai: 'Customer orders' },
-                    columns: [
-                        {
-                            id: 'column-orders-status',
-                            tableId: 'table-orders',
-                            tableRef: { catalog: 'analytics', db: 'public', name: 'orders' },
-                            name: 'status',
-                            nativeType: 'varchar',
-                            normalizedType: 'string',
-                            dimensionType: 'string',
-                            nullable: false,
-                            primaryKey: false,
-                            parentColumnId: null,
-                            descriptions: { db: 'Status code' },
-                            embedding: [0.1, 0.2],
-                            sampleValues: ['paid', 'refunded'],
-                            cardinality: 2,
-                        },
-                    ],
-                },
-            ],
-            relationships: [
-                {
-                    id: 'rel-orders-customers',
-                    source: 'formal',
-                    from: {
-                        tableId: 'table-orders',
-                        columnIds: ['column-orders-customer-id'],
-                        table: { catalog: 'analytics', db: 'public', name: 'orders' },
-                        columns: ['customer_id'],
-                    },
-                    to: {
-                        tableId: 'table-customers',
-                        columnIds: ['column-customers-id'],
-                        table: { catalog: 'analytics', db: 'public', name: 'customers' },
-                        columns: ['id'],
-                    },
-                    relationshipType: 'many_to_one',
-                    confidence: 1,
-                    isPrimaryKeyReference: true,
-                },
-            ],
-        };
-        expect(schema.tables[0].columns[0].sampleValues).toEqual(['paid', 'refunded']);
-        expect(schema.relationships[0].source).toBe('formal');
-    });
-    it('models metadata-store updates without requiring a concrete store implementation', async () => {
-        const structuralPlan = {
-            connectionId: 'warehouse',
-            snapshotId: 'snapshot-1',
-            operations: [{ kind: 'create_table', table: 'orders' }],
-        };
-        const descriptionUpdate = {
-            connectionId: 'warehouse',
-            table: { catalog: 'analytics', db: 'public', name: 'orders' },
-            source: 'ai',
-            tableDescription: 'Customer orders',
-            columnDescriptions: { status: 'Payment lifecycle state' },
-        };
-        const sampleUpdate = {
-            columnId: 'column-orders-status',
-            sampleValues: ['paid', 'refunded'],
-            cardinality: 2,
-        };
-        const embeddingUpdate = {
-            columnId: 'column-orders-status',
-            text: 'orders.status (varchar). Values: paid, refunded',
-            embedding: [0.25, 0.75],
-        };
-        const relationshipUpdate = {
-            connectionId: 'warehouse',
-            accepted: [],
-            rejected: [],
-            skipped: [{ reason: 'missing parent table', relationshipId: 'candidate-1' }],
-        };
-        const store = {
-            loadSchema: async () => null,
-            applyStructuralPlan: async (plan) => ({
-                connectionId: plan.connectionId,
-                tables: [],
-                relationships: [],
-            }),
-            updateDescriptions: async (input) => {
-                expect(input).toEqual(descriptionUpdate);
-            },
-            updateColumnSamples: async (input) => {
-                expect(input).toEqual([sampleUpdate]);
-            },
-            updateColumnEmbeddings: async (input) => {
-                expect(input).toEqual([embeddingUpdate]);
-            },
-            updateInferredRelationships: async (input) => {
-                expect(input).toEqual(relationshipUpdate);
-            },
-        };
-        await expect(store.loadSchema('warehouse')).resolves.toBeNull();
-        await expect(store.applyStructuralPlan(structuralPlan)).resolves.toEqual({
-            connectionId: 'warehouse',
-            tables: [],
-            relationships: [],
-        });
-        await expect(store.updateDescriptions(descriptionUpdate)).resolves.toBeUndefined();
-        await expect(store.updateColumnSamples([sampleUpdate])).resolves.toBeUndefined();
-        await expect(store.updateColumnEmbeddings([embeddingUpdate])).resolves.toBeUndefined();
-        await expect(store.updateInferredRelationships(relationshipUpdate)).resolves.toBeUndefined();
-    });
-});
-describe('relationship tuple contracts', () => {
-    it('represents relationship endpoints and join updates as ordered column tuples', () => {
-        const endpoint = {
-            tableId: 'public.order_lines',
-            columnIds: ['public.order_lines.order_id', 'public.order_lines.line_number'],
-            table: { catalog: null, db: 'public', name: 'order_lines' },
-            columns: ['order_id', 'line_number'],
-        };
-        const update = {
-            connectionId: 'warehouse',
-            fromTable: 'order_line_allocations',
-            fromColumns: ['order_id', 'line_number'],
-            toTable: 'order_lines',
-            toColumns: ['order_id', 'line_number'],
-            relationship: 'many_to_one',
-            author: 'ktx',
-            authorEmail: 'ktx@example.com',
-        };
-        expect(endpoint.columns).toEqual(['order_id', 'line_number']);
-        expect(endpoint.columnIds).toEqual(['public.order_lines.order_id', 'public.order_lines.line_number']);
-        expect(update.fromColumns).toEqual(['order_id', 'line_number']);
-        expect(update.toColumns).toEqual(['order_id', 'line_number']);
-    });
-});

package/dist/context/scan/entity-details.test.d.ts

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

package/dist/context/scan/entity-details.test.js

@@ -1,234 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { initKtxProject } from '../../context/project/project.js';
-import { createKtxEntityDetailsService } from './entity-details.js';
-describe('createKtxEntityDetailsService', () => {
-    let tempDir;
-    let project;
-    beforeEach(async () => {
-        tempDir = await mkdtemp(join(tmpdir(), 'ktx-entity-details-service-'));
-        project = await initKtxProject({ projectDir: join(tempDir, 'project') });
-    });
-    afterEach(async () => {
-        await rm(tempDir, { recursive: true, force: true });
-    });
-    function scanReport(input) {
-        const rawSourcesDir = `raw-sources/${input.connectionId}/live-database/${input.syncId}`;
-        return {
-            connectionId: input.connectionId,
-            driver: input.driver ?? 'postgres',
-            syncId: input.syncId,
-            runId: input.runId,
-            trigger: 'mcp',
-            mode: 'structural',
-            dryRun: false,
-            artifactPaths: {
-                rawSourcesDir,
-                reportPath: `${rawSourcesDir}/scan-report.json`,
-                manifestShards: [],
-                enrichmentArtifacts: [],
-            },
-            diffSummary: {
-                tablesAdded: 0,
-                tablesModified: 0,
-                tablesDeleted: 0,
-                tablesUnchanged: 1,
-                columnsAdded: 0,
-                columnsModified: 0,
-                columnsDeleted: 0,
-            },
-            manifestShardsWritten: 0,
-            structuralSyncStats: {
-                tablesCreated: 1,
-                tablesUpdated: 0,
-                tablesDeleted: 0,
-                columnsCreated: 0,
-                columnsUpdated: 0,
-                columnsDeleted: 0,
-            },
-            enrichment: {
-                dataDictionary: 'skipped',
-                tableDescriptions: 'skipped',
-                columnDescriptions: 'skipped',
-                embeddings: 'skipped',
-                deterministicRelationships: 'skipped',
-                llmRelationshipValidation: 'skipped',
-                statisticalValidation: 'skipped',
-            },
-            capabilityGaps: [],
-            warnings: [],
-            relationships: { accepted: 0, review: 0, rejected: 0, skipped: 0 },
-            enrichmentState: { resumedStages: [], completedStages: [], failedStages: [] },
-            createdAt: input.createdAt ?? '2026-05-14T09:00:00.000Z',
-        };
-    }
-    function ordersTable(input = {}) {
-        return {
-            catalog: null,
-            db: input.db ?? 'public',
-            name: 'orders',
-            kind: 'table',
-            comment: 'Customer orders',
-            estimatedRows: input.estimatedRows ?? 12,
-            columns: [
-                {
-                    name: 'id',
-                    nativeType: 'integer',
-                    normalizedType: 'integer',
-                    dimensionType: 'number',
-                    nullable: false,
-                    primaryKey: true,
-                    comment: 'Order id',
-                },
-                {
-                    name: 'status',
-                    nativeType: 'text',
-                    normalizedType: 'text',
-                    dimensionType: 'string',
-                    nullable: false,
-                    primaryKey: false,
-                    comment: 'Order status',
-                },
-            ],
-            foreignKeys: [
-                {
-                    fromColumn: 'customer_id',
-                    toCatalog: null,
-                    toDb: 'public',
-                    toTable: 'customers',
-                    toColumn: 'id',
-                    constraintName: 'orders_customer_id_fkey',
-                },
-            ],
-        };
-    }
-    async function seedScan(input) {
-        const connectionId = input.connectionId ?? 'warehouse';
-        const report = scanReport({
-            connectionId,
-            syncId: input.syncId,
-            runId: input.runId,
-            driver: input.driver,
-            createdAt: input.extractedAt,
-        });
-        const root = report.artifactPaths.rawSourcesDir;
-        await project.fileStore.writeFile(`${root}/connection.json`, JSON.stringify({
-            connectionId,
-            driver: report.driver,
-            extractedAt: input.extractedAt ?? report.createdAt,
-            scope: { schemas: ['public'] },
-        }, null, 2), 'ktx', 'ktx@example.com', 'seed connection');
-        for (const table of input.tables ?? [ordersTable()]) {
-            await project.fileStore.writeFile(`${root}/tables/${table.db ?? 'default'}-${table.name}.json`, JSON.stringify(table, null, 2), 'ktx', 'ktx@example.com', `seed ${table.name}`);
-        }
-        await project.fileStore.writeFile(`${root}/scan-report.json`, JSON.stringify(report, null, 2), 'ktx', 'ktx@example.com', 'seed scan report');
-    }
-    it('returns the latest scan snapshot table details for a display string', async () => {
-        await seedScan({ syncId: 'sync-1', runId: 'scan-old', extractedAt: '2026-05-14T08:00:00.000Z' });
-        await seedScan({
-            syncId: 'sync-2',
-            runId: 'scan-new',
-            extractedAt: '2026-05-14T09:00:00.000Z',
-            tables: [ordersTable({ estimatedRows: 99 })],
-        });
-        const service = createKtxEntityDetailsService(project);
-        const result = await service.read({
-            connectionId: 'warehouse',
-            entities: [{ table: 'public.orders' }],
-        });
-        expect(result.results).toHaveLength(1);
-        expect(result.results[0]).toMatchObject({
-            ok: true,
-            connectionId: 'warehouse',
-            display: 'public.orders',
-            estimatedRows: 99,
-            snapshot: {
-                syncId: 'sync-2',
-                scanRunId: 'scan-new',
-                extractedAt: '2026-05-14T09:00:00.000Z',
-            },
-            columns: [
-                { name: 'id', nativeType: 'integer', primaryKey: true },
-                { name: 'status', nativeType: 'text', nullable: false },
-            ],
-        });
-    });
-    it('filters requested columns while keeping full-table foreign keys', async () => {
-        await seedScan({ syncId: 'sync-1', runId: 'scan-1' });
-        const service = createKtxEntityDetailsService(project);
-        const result = await service.read({
-            connectionId: 'warehouse',
-            entities: [{ table: { catalog: null, db: 'public', name: 'orders' }, columns: ['status'] }],
-        });
-        expect(result.results[0]).toMatchObject({
-            ok: true,
-            columns: [{ name: 'status' }],
-            foreignKeys: [
-                {
-                    fromColumn: 'customer_id',
-                    toDb: 'public',
-                    toTable: 'customers',
-                    toColumn: 'id',
-                },
-            ],
-        });
-    });
-    it('returns a structured missing-scan error', async () => {
-        const service = createKtxEntityDetailsService(project);
-        const result = await service.read({
-            connectionId: 'warehouse',
-            entities: [{ table: 'public.orders' }],
-        });
-        expect(result.results).toEqual([
-            {
-                ok: false,
-                connectionId: 'warehouse',
-                table: 'public.orders',
-                error: {
-                    code: 'scan_missing',
-                    message: 'No live-database scan found for connection "warehouse"; run `ktx ingest warehouse` or `ktx scan warehouse`.',
-                },
-            },
-        ]);
-    });
-    it('reports ambiguous bare table names across schemas', async () => {
-        await seedScan({
-            syncId: 'sync-1',
-            runId: 'scan-1',
-            tables: [ordersTable({ db: 'public' }), ordersTable({ db: 'archive' })],
-        });
-        const service = createKtxEntityDetailsService(project);
-        const result = await service.read({
-            connectionId: 'warehouse',
-            entities: [{ table: 'orders' }],
-        });
-        expect(result.results[0]).toMatchObject({
-            ok: false,
-            error: {
-                code: 'ambiguous_table',
-                candidates: [
-                    { tableRef: { catalog: null, db: 'archive', name: 'orders' }, display: 'archive.orders' },
-                    { tableRef: { catalog: null, db: 'public', name: 'orders' }, display: 'public.orders' },
-                ],
-            },
-        });
-    });
-    it('reports missing requested columns with available column candidates', async () => {
-        await seedScan({ syncId: 'sync-1', runId: 'scan-1' });
-        const service = createKtxEntityDetailsService(project);
-        const result = await service.read({
-            connectionId: 'warehouse',
-            entities: [{ table: 'public.orders', columns: ['status', 'plan_tier'] }],
-        });
-        expect(result.results[0]).toMatchObject({
-            ok: false,
-            error: {
-                code: 'column_not_found',
-                message: 'Column(s) not found on public.orders: plan_tier',
-                candidates: ['id', 'status'],
-            },
-        });
-    });
-});

package/dist/context/scan/local-enrichment-artifacts.test.d.ts

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