@kaelio/ktx 0.5.0 → 0.6.0

package/dist/context/scan/relationship-llm-proposal.test.js

@@ -1,197 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { proposeKtxRelationshipCandidatesWithLlm } from './relationship-llm-proposal.js';
-function llmRuntime(output) {
-    return {
-        generateText: vi.fn(),
-        generateObject: vi.fn(async () => output),
-        runAgentLoop: vi.fn(),
-    };
-}
-function column(tableId, name, overrides = {}) {
-    const tableRef = overrides.tableRef ?? { catalog: null, db: null, name: tableId };
-    return {
-        id: `${tableId}.${name}`,
-        tableId,
-        tableRef,
-        name,
-        nativeType: overrides.nativeType ?? 'INTEGER',
-        normalizedType: overrides.normalizedType ?? 'integer',
-        dimensionType: overrides.dimensionType ?? 'number',
-        nullable: overrides.nullable ?? true,
-        primaryKey: overrides.primaryKey ?? false,
-        parentColumnId: null,
-        descriptions: {},
-        embedding: null,
-        sampleValues: null,
-        cardinality: null,
-        ...overrides,
-    };
-}
-function table(name, columns) {
-    const ref = { catalog: null, db: null, name };
-    return {
-        id: name,
-        ref,
-        enabled: true,
-        descriptions: {},
-        columns: columns.map((item) => ({ ...item, tableId: name, tableRef: ref })),
-    };
-}
-function schema() {
-    return {
-        connectionId: 'warehouse',
-        relationships: [],
-        tables: [
-            table('customers', [
-                column('customers', 'id', { nullable: false }),
-                column('customers', 'email', { nativeType: 'TEXT', normalizedType: 'text', dimensionType: 'string' }),
-            ]),
-            table('orders', [
-                column('orders', 'id', { nullable: false }),
-                column('orders', 'buyer_ref'),
-            ]),
-        ],
-    };
-}
-function profile() {
-    return {
-        connectionId: 'warehouse',
-        driver: 'sqlite',
-        sqlAvailable: true,
-        queryCount: 4,
-        warnings: [],
-        tables: [
-            { table: { catalog: null, db: null, name: 'customers' }, rowCount: 2 },
-            { table: { catalog: null, db: null, name: 'orders' }, rowCount: 2 },
-        ],
-        columns: {
-            'customers.id': {
-                table: { catalog: null, db: null, name: 'customers' },
-                column: 'id',
-                nativeType: 'INTEGER',
-                normalizedType: 'integer',
-                rowCount: 2,
-                nullCount: 0,
-                distinctCount: 2,
-                uniquenessRatio: 1,
-                nullRate: 0,
-                sampleValues: ['1', '2'],
-                minTextLength: 1,
-                maxTextLength: 1,
-            },
-            'orders.buyer_ref': {
-                table: { catalog: null, db: null, name: 'orders' },
-                column: 'buyer_ref',
-                nativeType: 'INTEGER',
-                normalizedType: 'integer',
-                rowCount: 2,
-                nullCount: 0,
-                distinctCount: 2,
-                uniquenessRatio: 1,
-                nullRate: 0,
-                sampleValues: ['1', '2'],
-                minTextLength: 1,
-                maxTextLength: 1,
-            },
-        },
-    };
-}
-describe('relationship LLM proposals', () => {
-    it('maps valid structured FK proposals into review candidates with rationale evidence', async () => {
-        const runtime = llmRuntime({
-            pkCandidates: [{ table: 'customers', column: 'id', confidence: 0.94, rationale: 'Unique customer identifier.' }],
-            fkCandidates: [
-                {
-                    fromTable: 'orders',
-                    fromColumn: 'buyer_ref',
-                    toTable: 'customers',
-                    toColumn: 'id',
-                    confidence: 0.88,
-                    rationale: 'Buyer reference values match customer identifiers.',
-                },
-            ],
-        });
-        const result = await proposeKtxRelationshipCandidatesWithLlm({
-            connectionId: 'warehouse',
-            schema: schema(),
-            profile: profile(),
-            llmRuntime: runtime,
-        });
-        expect(result.summary).toBe('completed');
-        expect(result.llmCalls).toBe(1);
-        expect(result.warnings).toEqual([]);
-        expect(result.candidates).toHaveLength(1);
-        expect(result.candidates[0]).toMatchObject({
-            from: { tableId: 'orders', columnIds: ['orders.buyer_ref'], columns: ['buyer_ref'] },
-            to: { tableId: 'customers', columnIds: ['customers.id'], columns: ['id'] },
-            source: 'llm_proposal',
-            status: 'review',
-            evidence: {
-                llmConfidence: 0.88,
-                llmRationale: 'Buyer reference values match customer identifiers.',
-                reasons: ['llm_proposal', 'llm_pk_proposal'],
-            },
-        });
-        expect(runtime.generateObject).toHaveBeenCalledWith(expect.objectContaining({
-            role: 'candidateExtraction',
-            system: expect.stringContaining('You are helping KTX review possible SQL relationships'),
-            prompt: expect.stringContaining('"tables"'),
-        }));
-        const call = vi.mocked(runtime.generateObject).mock.calls[0]?.[0];
-        expect(call?.prompt).not.toContain('You are helping KTX review possible SQL relationships');
-    });
-    it('skips when no runtime is configured', async () => {
-        const result = await proposeKtxRelationshipCandidatesWithLlm({
-            connectionId: 'warehouse',
-            schema: schema(),
-            profile: profile(),
-            llmRuntime: null,
-        });
-        expect(result).toMatchObject({ candidates: [], llmCalls: 0, summary: 'skipped' });
-        expect(result.warnings).toEqual([]);
-    });
-    it('returns recoverable warnings for invalid references and generation failures', async () => {
-        const invalidReference = await proposeKtxRelationshipCandidatesWithLlm({
-            connectionId: 'warehouse',
-            schema: schema(),
-            profile: profile(),
-            llmRuntime: llmRuntime({
-                pkCandidates: [],
-                fkCandidates: [
-                    {
-                        fromTable: 'orders',
-                        fromColumn: 'missing_column',
-                        toTable: 'customers',
-                        toColumn: 'id',
-                        confidence: 0.7,
-                        rationale: 'Invalid source column.',
-                    },
-                ],
-            }),
-        });
-        expect(invalidReference.candidates).toEqual([]);
-        expect(invalidReference.summary).toBe('completed');
-        expect(invalidReference.warnings[0]).toMatchObject({
-            code: 'relationship_llm_invalid_reference',
-            recoverable: true,
-        });
-        const failed = await proposeKtxRelationshipCandidatesWithLlm({
-            connectionId: 'warehouse',
-            schema: schema(),
-            profile: profile(),
-            llmRuntime: {
-                generateText: vi.fn(),
-                generateObject: vi.fn(async () => {
-                    throw new Error('model unavailable');
-                }),
-                runAgentLoop: vi.fn(),
-            },
-        });
-        expect(failed).toMatchObject({ candidates: [], llmCalls: 1, summary: 'failed' });
-        expect(failed.warnings[0]).toMatchObject({
-            code: 'relationship_llm_proposal_failed',
-            message: 'KTX relationship LLM proposal failed: model unavailable',
-            recoverable: true,
-        });
-    });
-});

package/dist/context/scan/relationship-locality.test.d.ts

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

package/dist/context/scan/relationship-locality.test.js

@@ -1,128 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { localCandidateTables } from './relationship-locality.js';
-function column(tableId, id, name, options = {}) {
-    const tableRef = options.tableRef ?? { catalog: null, db: 'public', name: tableId };
-    return {
-        id,
-        tableId,
-        tableRef,
-        name,
-        nativeType: options.nativeType ?? 'INTEGER',
-        normalizedType: options.normalizedType ?? 'integer',
-        dimensionType: options.dimensionType ?? 'number',
-        nullable: options.nullable ?? true,
-        primaryKey: options.primaryKey ?? false,
-        parentColumnId: options.parentColumnId ?? null,
-        descriptions: options.descriptions ?? {},
-        embedding: options.embedding ?? null,
-        sampleValues: options.sampleValues ?? null,
-        cardinality: options.cardinality ?? null,
-    };
-}
-function table(id, name, columns) {
-    const ref = { catalog: null, db: 'public', name };
-    return {
-        id,
-        ref,
-        enabled: true,
-        descriptions: {},
-        columns: columns.map((item) => ({ ...item, tableId: id, tableRef: ref })),
-    };
-}
-describe('relationship locality', () => {
-    it('ranks the referenced parent table ahead of the child table for id-like source columns', () => {
-        const artists = table('artist-id', 'Artist', [column('artist-id', 'artist-pk', 'ArtistId')]);
-        const albums = table('album-id', 'Album', [
-            column('album-id', 'album-pk', 'AlbumId'),
-            column('album-id', 'artist-fk', 'ArtistId'),
-        ]);
-        const unrelated = table('invoice-id', 'Invoice', [column('invoice-id', 'invoice-pk', 'InvoiceId')]);
-        const ranked = localCandidateTables({
-            childTable: albums,
-            childColumn: albums.columns[1],
-            parentTables: [albums, unrelated, artists],
-            maxParentTables: 1,
-        });
-        expect(ranked.map((item) => item.table.ref.name)).toEqual(['Artist']);
-        expect(ranked[0]).toMatchObject({
-            score: expect.any(Number),
-            tokenScore: expect.any(Number),
-            embeddingScore: 0,
-            reasons: expect.arrayContaining(['column_table_token_overlap']),
-        });
-    });
-    it('uses singular and plural variants so plan_code can rank stg_plans', () => {
-        const plans = table('plans-id', 'stg_plans', [column('plans-id', 'plan-code', 'plan_code')]);
-        const segments = table('segments-id', 'mart_account_segments', [
-            column('segments-id', 'current-plan-code', 'current_plan_code', {
-                nativeType: 'TEXT',
-                normalizedType: 'text',
-                dimensionType: 'string',
-            }),
-        ]);
-        const accounts = table('accounts-id', 'accounts', [column('accounts-id', 'account-id', 'id')]);
-        const ranked = localCandidateTables({
-            childTable: segments,
-            childColumn: segments.columns[0],
-            parentTables: [accounts, segments, plans],
-            maxParentTables: 1,
-        });
-        expect(ranked.map((item) => item.table.ref.name)).toEqual(['stg_plans']);
-        expect(ranked[0]?.tokenScore).toBeGreaterThan(0);
-    });
-    it('returns all tables when the schema is smaller than the default locality cap', () => {
-        const accounts = table('accounts-id', 'accounts', [column('accounts-id', 'account-id', 'id')]);
-        const invoices = table('invoices-id', 'invoices', [
-            column('invoices-id', 'invoice-id', 'id'),
-            column('invoices-id', 'account-id', 'account_id'),
-        ]);
-        const ranked = localCandidateTables({
-            childTable: invoices,
-            childColumn: invoices.columns[1],
-            parentTables: [invoices, accounts],
-        });
-        expect(ranked.map((item) => item.table.ref.name).sort()).toEqual(['accounts', 'invoices']);
-    });
-    it('supports an explicit zero cap for deterministic tests', () => {
-        const accounts = table('accounts-id', 'accounts', [column('accounts-id', 'account-id', 'id')]);
-        const invoices = table('invoices-id', 'invoices', [
-            column('invoices-id', 'invoice-id', 'id'),
-            column('invoices-id', 'account-id', 'account_id'),
-        ]);
-        const ranked = localCandidateTables({
-            childTable: invoices,
-            childColumn: invoices.columns[1],
-            parentTables: [invoices, accounts],
-            maxParentTables: 0,
-        });
-        expect(ranked).toEqual([]);
-    });
-    it('uses parent-column embeddings when token locality is weak', () => {
-        const customers = table('customers-id', 'customers', [
-            column('customers-id', 'customers-id-col', 'id', { embedding: [1, 0, 0] }),
-            column('customers-id', 'customers-name-col', 'name', {
-                nativeType: 'TEXT',
-                normalizedType: 'text',
-                dimensionType: 'string',
-                embedding: [0, 1, 0],
-            }),
-        ]);
-        const orders = table('orders-id', 'orders', [
-            column('orders-id', 'orders-id-col', 'id', { embedding: [0, 0, 1] }),
-            column('orders-id', 'buyer-ref-col', 'buyer_ref', { embedding: [0.995, 0.005, 0] }),
-        ]);
-        const invoices = table('invoices-id', 'invoices', [column('invoices-id', 'invoice-id', 'id')]);
-        const ranked = localCandidateTables({
-            childTable: orders,
-            childColumn: orders.columns[1],
-            parentTables: [invoices, customers],
-            maxParentTables: 1,
-        });
-        expect(ranked.map((item) => item.table.ref.name)).toEqual(['customers']);
-        expect(ranked[0]).toMatchObject({
-            embeddingScore: expect.any(Number),
-            reasons: expect.arrayContaining(['embedding_similarity']),
-        });
-        expect(ranked[0].embeddingScore).toBeGreaterThan(0.99);
-    });
-});

package/dist/context/scan/relationship-name-similarity.test.d.ts

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

package/dist/context/scan/relationship-name-similarity.test.js

@@ -1,68 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { normalizeKtxRelationshipName, pluralizeKtxRelationshipToken, singularizeKtxRelationshipToken, tokenSimilarity, tokenizeKtxRelationshipName, } from './relationship-name-similarity.js';
-describe('relationship name similarity', () => {
-    it('tokenizes common warehouse naming styles', () => {
-        expect(normalizeKtxRelationshipName('AlbumId')).toMatchObject({
-            normalized: 'album_id',
-            singular: 'album_id',
-            plural: 'album_ids',
-            tokens: ['album', 'id'],
-        });
-        expect(normalizeKtxRelationshipName('artistID')).toMatchObject({
-            normalized: 'artist_id',
-            tokens: ['artist', 'id'],
-        });
-        expect(normalizeKtxRelationshipName('SalesLT.CustomerID')).toMatchObject({
-            normalized: 'sales_lt_customer_id',
-            singular: 'sales_lt_customer_id',
-            tokens: ['sales', 'lt', 'customer', 'id'],
-        });
-        expect(normalizeKtxRelationshipName('SCREAMING_CUSTOMER_UUID')).toMatchObject({
-            normalized: 'screaming_customer_uuid',
-            tokens: ['screaming', 'customer', 'uuid'],
-        });
-        expect(normalizeKtxRelationshipName('billing-account-key')).toMatchObject({
-            normalized: 'billing_account_key',
-            tokens: ['billing', 'account', 'key'],
-        });
-    });
-    it('removes only leading warehouse layer prefixes', () => {
-        expect(normalizeKtxRelationshipName('mart__Sales_Accounts')).toMatchObject({
-            normalized: 'sales_accounts',
-            singular: 'sales_account',
-            plural: 'sales_accounts',
-            tokens: ['sales', 'accounts'],
-        });
-        expect(normalizeKtxRelationshipName('dim_users')).toMatchObject({
-            normalized: 'users',
-            singular: 'user',
-            plural: 'users',
-            tokens: ['users'],
-        });
-        expect(normalizeKtxRelationshipName('customer_dim_id')).toMatchObject({
-            normalized: 'customer_dim_id',
-            tokens: ['customer', 'dim', 'id'],
-        });
-    });
-    it('folds accents and preserves non-suffix trailing s words', () => {
-        expect(normalizeKtxRelationshipName('KundénID')).toMatchObject({
-            normalized: 'kunden_id',
-            tokens: ['kunden', 'id'],
-        });
-        expect(singularizeKtxRelationshipToken('address')).toBe('address');
-        expect(singularizeKtxRelationshipToken('addresses')).toBe('address');
-        expect(singularizeKtxRelationshipToken('status')).toBe('status');
-        expect(pluralizeKtxRelationshipToken('address')).toBe('addresses');
-        expect(pluralizeKtxRelationshipToken('company')).toBe('companies');
-    });
-    it('returns deterministic tokens for direct tokenization calls', () => {
-        expect(tokenizeKtxRelationshipName('HTTPResponseCode')).toEqual(['http', 'response', 'code']);
-        expect(tokenizeKtxRelationshipName('customer2AddressID')).toEqual(['customer', '2', 'address', 'id']);
-    });
-    it('scores token overlap and ordered suffix similarity', () => {
-        expect(tokenSimilarity('artist_id', 'artist_id')).toBe(1);
-        expect(tokenSimilarity('Album.ArtistId', 'ArtistID')).toBeGreaterThanOrEqual(0.74);
-        expect(tokenSimilarity('customer_account_id', 'account_id')).toBeGreaterThan(tokenSimilarity('customer_account_id', 'invoice_id'));
-        expect(tokenSimilarity('', 'artist')).toBe(0);
-    });
-});

package/dist/context/scan/relationship-profiling.test.d.ts

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