@kaelio/ktx 0.5.0 → 0.7.0

package/dist/context/scan/relationship-composite-candidates.test.d.ts

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

package/dist/context/scan/relationship-composite-candidates.test.js

@@ -1,69 +0,0 @@
-import Database from 'better-sqlite3';
-import { join } from 'node:path';
-import { describe, expect, it } from 'vitest';
-import { snapshotToKtxEnrichedSchema } from './local-enrichment.js';
-import { loadKtxRelationshipBenchmarkFixture, maskKtxRelationshipBenchmarkSnapshot } from './relationship-benchmarks.js';
-import { discoverKtxCompositeRelationships } from './relationship-composite-candidates.js';
-import { profileKtxRelationshipSchema } from './relationship-profiling.js';
-class TestSqliteExecutor {
-    db;
-    constructor(dataPath) {
-        this.db = new Database(dataPath, { readonly: true, fileMustExist: true });
-    }
-    async executeReadOnly(input, _ctx) {
-        const rows = this.db.prepare(input.sql).all();
-        const headers = Object.keys(rows[0] ?? {});
-        return {
-            headers,
-            rows: rows.map((row) => headers.map((header) => row[header])),
-            totalRows: rows.length,
-            rowCount: rows.length,
-        };
-    }
-    close() {
-        this.db.close();
-    }
-}
-describe('composite relationship discovery detector', () => {
-    it('infers composite primary keys and validates composite foreign keys from row evidence', async () => {
-        const fixtureRoot = new URL('../../test/fixtures/relationship-benchmarks/', import.meta.url);
-        const fixture = await loadKtxRelationshipBenchmarkFixture(join(fixtureRoot.pathname, 'composite_keys_no_declared_constraints'));
-        const snapshot = maskKtxRelationshipBenchmarkSnapshot(fixture.snapshot, 'declared_pks_and_declared_fks_removed');
-        const schema = snapshotToKtxEnrichedSchema(snapshot, new Map());
-        const executor = new TestSqliteExecutor(fixture.dataPath ?? '');
-        const profiles = await profileKtxRelationshipSchema({
-            connectionId: snapshot.connectionId,
-            driver: snapshot.driver,
-            schema,
-            executor,
-            ctx: { runId: 'test:composite-profile' },
-        });
-        const result = await discoverKtxCompositeRelationships({
-            connectionId: snapshot.connectionId,
-            driver: snapshot.driver,
-            schema,
-            profiles,
-            executor,
-            ctx: { runId: 'test:composite-detect' },
-        });
-        executor.close();
-        expect(result.primaryKeys.map((item) => `${item.table.name}.(${item.columns.join(',')})`)).toEqual([
-            'order_line_allocations.(order_id,line_number,warehouse_code)',
-            'order_lines.(order_id,line_number)',
-        ]);
-        expect(result.relationships.map((item) => `${item.from.table.name}.(${item.from.columns.join(',')})->${item.to.table.name}.(${item.to.columns.join(',')})`)).toEqual(['order_line_allocations.(order_id,line_number)->order_lines.(order_id,line_number)']);
-        expect(result.relationships[0]).toMatchObject({
-            relationshipType: 'many_to_one',
-            status: 'accepted',
-            confidence: 0.95,
-            validation: {
-                targetUniqueness: 1,
-                sourceCoverage: 1,
-                violationCount: 0,
-                violationRatio: 0,
-                reasons: ['composite_validation_passed'],
-            },
-        });
-        expect(result.queryCount).toBeGreaterThan(0);
-    });
-});

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

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

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

@@ -1,333 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { buildKtxRelationshipArtifacts, buildKtxRelationshipDiagnostics, emptyKtxRelationshipProfileArtifact, } from './relationship-diagnostics.js';
-function endpoint(table, column) {
-    return {
-        tableId: table,
-        columnIds: [`${table}.${column}`],
-        table: { catalog: null, db: null, name: table },
-        columns: [column],
-    };
-}
-function enrichedRelationship(input) {
-    return {
-        id: input.id,
-        source: 'inferred',
-        from: endpoint(input.fromTable, input.fromColumn),
-        to: endpoint(input.toTable, input.toColumn),
-        relationshipType: 'many_to_one',
-        confidence: input.confidence ?? 0.92,
-        isPrimaryKeyReference: true,
-    };
-}
-function resolvedRelationship(input) {
-    return {
-        id: input.id,
-        from: endpoint('orders', 'customer_id'),
-        to: endpoint('customers', 'id'),
-        relationshipType: 'many_to_one',
-        confidence: 0.88,
-        source: input.source ?? 'normalized_table_match',
-        status: input.status,
-        evidence: input.source === 'llm_proposal'
-            ? {
-                sourceColumnBase: 'buyer',
-                targetTableBase: 'customer',
-                targetColumnBase: 'id',
-                targetKeyScore: 0.88,
-                nameScore: 0.45,
-                reasons: ['llm_proposal', 'llm_pk_proposal'],
-                llmConfidence: 0.89,
-                llmRationale: 'Buyer reference values align with customer identifiers.',
-            }
-            : {
-                sourceColumnBase: 'customer',
-                targetTableBase: 'customer',
-                targetColumnBase: 'id',
-                targetKeyScore: 0.9,
-                nameScore: 0.85,
-                reasons: ['table_name_matches_source_column'],
-            },
-        score: 0.91,
-        validation: {
-            targetUniqueness: 1,
-            sourceCoverage: input.status === 'rejected' ? 0.2 : 1,
-            violationCount: input.status === 'rejected' ? 8 : 0,
-            violationRatio: input.status === 'rejected' ? 0.8 : 0,
-            sourceNullRate: 0,
-            targetNullRate: 0,
-            childDistinct: 10,
-            parentDistinct: 10,
-            overlap: input.status === 'rejected' ? 2 : 10,
-            checkedValues: 10,
-            reasons: input.validationReasons ?? ['validation_passed'],
-        },
-        pkScore: input.pkScore ?? 0.97,
-        fkScore: input.fkScore ?? 0.94,
-        graph: {
-            targetPkScore: input.pkScore ?? 0.97,
-            incomingCandidateCount: 1,
-            conflictRank: 1,
-            reasons: input.graphReasons ?? ['target_pk_score_passed', 'fk_score_passed'],
-        },
-    };
-}
-describe('relationship diagnostics artifacts', () => {
-    it('groups graph-resolved relationships and preserves evidence reasons', () => {
-        const artifacts = buildKtxRelationshipArtifacts({
-            connectionId: 'warehouse',
-            resolvedRelationships: [
-                resolvedRelationship({ id: 'accepted-edge', status: 'accepted', source: 'llm_proposal' }),
-                resolvedRelationship({
-                    id: 'review-edge',
-                    status: 'review',
-                    validationReasons: ['validation_unavailable'],
-                    graphReasons: ['validation_unavailable_review_only', 'fk_score_review'],
-                }),
-                resolvedRelationship({
-                    id: 'rejected-edge',
-                    status: 'rejected',
-                    validationReasons: ['low_source_coverage'],
-                    graphReasons: ['fk_score_rejected'],
-                }),
-            ],
-        });
-        expect(artifacts.accepted).toHaveLength(1);
-        expect(artifacts.accepted[0]).toMatchObject({
-            source: 'llm_proposal',
-            evidence: {
-                llmConfidence: 0.89,
-                llmRationale: 'Buyer reference values align with customer identifiers.',
-            },
-            reasons: expect.arrayContaining(['llm_proposal', 'llm_pk_proposal']),
-        });
-        expect(artifacts.review).toHaveLength(1);
-        expect(artifacts.rejected).toHaveLength(1);
-        expect(artifacts.review[0]).toMatchObject({
-            id: 'review-edge',
-            status: 'review',
-            source: 'normalized_table_match',
-            fkScore: 0.94,
-            reasons: expect.arrayContaining(['validation_unavailable', 'validation_unavailable_review_only']),
-        });
-        expect(artifacts.rejected[0]?.reasons).toEqual(expect.arrayContaining(['table_name_matches_source_column', 'low_source_coverage', 'fk_score_rejected']));
-    });
-    it('adapts relationship updates into the artifact shape', () => {
-        const artifacts = buildKtxRelationshipArtifacts({
-            connectionId: 'warehouse',
-            relationshipUpdate: {
-                connectionId: 'warehouse',
-                accepted: [
-                    enrichedRelationship({
-                        id: 'orders-customer',
-                        fromTable: 'orders',
-                        fromColumn: 'customer_id',
-                        toTable: 'customers',
-                        toColumn: 'id',
-                    }),
-                ],
-                rejected: [
-                    enrichedRelationship({
-                        id: 'orders-account',
-                        fromTable: 'orders',
-                        fromColumn: 'account_id',
-                        toTable: 'accounts',
-                        toColumn: 'id',
-                        confidence: 0.4,
-                    }),
-                ],
-                skipped: [{ relationshipId: 'orders-region', reason: 'validation_port_unavailable' }],
-            },
-        });
-        expect(artifacts.accepted[0]).toMatchObject({
-            id: 'orders-customer',
-            status: 'accepted',
-            source: 'inferred',
-            reasons: ['accepted_relationship_update'],
-        });
-        expect(artifacts.rejected[0]).toMatchObject({
-            id: 'orders-account',
-            status: 'rejected',
-            reasons: ['rejected_relationship_update'],
-        });
-        expect(artifacts.skipped).toEqual([{ relationshipId: 'orders-region', reason: 'validation_port_unavailable' }]);
-    });
-    it('deduplicates resolved and formal relationship update artifacts by edge id', () => {
-        const artifacts = buildKtxRelationshipArtifacts({
-            connectionId: 'warehouse',
-            resolvedRelationships: [
-                {
-                    id: 'orders:orders.account_id->accounts:accounts.id',
-                    from: endpoint('orders', 'account_id'),
-                    to: endpoint('accounts', 'id'),
-                    relationshipType: 'many_to_one',
-                    source: 'normalized_table_match',
-                    status: 'accepted',
-                    confidence: 0.92,
-                    score: 0.9,
-                    pkScore: 0.92,
-                    fkScore: 0.9,
-                    evidence: {
-                        sourceColumnBase: 'account',
-                        targetTableBase: 'account',
-                        targetColumnBase: 'id',
-                        targetKeyScore: 0.92,
-                        nameScore: 0.92,
-                        reasons: ['foreign_key_suffix'],
-                    },
-                    validation: {
-                        targetUniqueness: 1,
-                        sourceCoverage: 1,
-                        violationCount: 0,
-                        violationRatio: 0,
-                        sourceNullRate: 0,
-                        targetNullRate: 0,
-                        childDistinct: 2,
-                        parentDistinct: 2,
-                        overlap: 2,
-                        checkedValues: 2,
-                        reasons: ['validation_passed'],
-                    },
-                    graph: {
-                        targetPkScore: 0.92,
-                        incomingCandidateCount: 1,
-                        conflictRank: 1,
-                        reasons: ['fk_score_passed'],
-                    },
-                },
-            ],
-            relationshipUpdate: {
-                connectionId: 'warehouse',
-                accepted: [
-                    {
-                        id: 'orders:orders.account_id->accounts:accounts.id',
-                        source: 'formal',
-                        from: endpoint('orders', 'account_id'),
-                        to: endpoint('accounts', 'id'),
-                        relationshipType: 'many_to_one',
-                        confidence: 1,
-                        isPrimaryKeyReference: true,
-                    },
-                ],
-                rejected: [],
-                skipped: [],
-            },
-        });
-        expect(artifacts.accepted).toHaveLength(1);
-        expect(artifacts.accepted[0]).toMatchObject({
-            id: 'orders:orders.account_id->accounts:accounts.id',
-            source: 'normalized_table_match',
-            reasons: expect.arrayContaining(['foreign_key_suffix', 'validation_passed', 'fk_score_passed']),
-        });
-    });
-    it('explains validation-unavailable review candidates', () => {
-        const artifacts = buildKtxRelationshipArtifacts({
-            connectionId: 'warehouse',
-            resolvedRelationships: [
-                resolvedRelationship({
-                    id: 'review-edge',
-                    status: 'review',
-                    validationReasons: ['validation_unavailable'],
-                    graphReasons: ['validation_unavailable_review_only'],
-                }),
-            ],
-        });
-        const profile = emptyKtxRelationshipProfileArtifact({
-            connectionId: 'warehouse',
-            driver: 'sqlite',
-            reason: 'read_only_sql_unavailable',
-        });
-        const diagnostics = buildKtxRelationshipDiagnostics({
-            connectionId: 'warehouse',
-            generatedAt: '2026-05-07T12:00:00.000Z',
-            artifacts,
-            profile,
-            warnings: [
-                {
-                    code: 'connector_capability_missing',
-                    message: 'KTX scan connector cannot run standalone statistical relationship validation',
-                    recoverable: true,
-                    metadata: { capability: 'readOnlySql' },
-                },
-            ],
-            thresholds: { acceptThreshold: 0.85, reviewThreshold: 0.55 },
-        });
-        expect(diagnostics.summary).toEqual({ accepted: 0, review: 1, rejected: 0, skipped: 0 });
-        expect(diagnostics.noAcceptedReason).toBe('validation unavailable; review candidates written');
-        expect(diagnostics.candidateCountsBySource).toEqual({ normalized_table_match: 1 });
-        expect(diagnostics.validation).toEqual({
-            available: false,
-            sqlAvailable: false,
-            queryCount: 0,
-        });
-        expect(diagnostics.profileWarnings).toEqual(['read_only_sql_unavailable']);
-        expect(diagnostics.warnings[0]).toMatchObject({ code: 'connector_capability_missing' });
-    });
-    it('explains empty relationship output as a no-candidate outcome', () => {
-        const artifacts = buildKtxRelationshipArtifacts({ connectionId: 'warehouse' });
-        const diagnostics = buildKtxRelationshipDiagnostics({
-            connectionId: 'warehouse',
-            generatedAt: '2026-05-07T12:00:00.000Z',
-            artifacts,
-            profile: emptyKtxRelationshipProfileArtifact({
-                connectionId: 'warehouse',
-                driver: 'sqlite',
-                reason: 'relationship_profiling_not_run',
-            }),
-        });
-        expect(diagnostics.summary).toEqual({ accepted: 0, review: 0, rejected: 0, skipped: 0 });
-        expect(diagnostics.noAcceptedReason).toBe('no candidate pairs passed type compatibility');
-        expect(diagnostics.candidateCountsBySource).toEqual({});
-    });
-    it('records composite relationship endpoints in relationship artifacts', () => {
-        const artifacts = buildKtxRelationshipArtifacts({
-            connectionId: 'warehouse',
-            compositeRelationships: [
-                {
-                    id: 'order_line_allocations.(order_id,line_number)->order_lines.(order_id,line_number)',
-                    source: 'composite_profile_match',
-                    status: 'accepted',
-                    from: {
-                        tableId: 'order_line_allocations',
-                        columnIds: ['order_line_allocations.order_id', 'order_line_allocations.line_number'],
-                        table: { catalog: null, db: null, name: 'order_line_allocations' },
-                        columns: ['order_id', 'line_number'],
-                    },
-                    to: {
-                        tableId: 'order_lines',
-                        columnIds: ['order_lines.order_id', 'order_lines.line_number'],
-                        table: { catalog: null, db: null, name: 'order_lines' },
-                        columns: ['order_id', 'line_number'],
-                    },
-                    relationshipType: 'many_to_one',
-                    confidence: 0.95,
-                    validation: {
-                        targetUniqueness: 1,
-                        sourceCoverage: 1,
-                        violationCount: 0,
-                        violationRatio: 0,
-                        childDistinct: 2,
-                        parentDistinct: 2,
-                        overlap: 2,
-                        reasons: ['composite_validation_passed'],
-                    },
-                },
-            ],
-        });
-        expect(artifacts.accepted).toEqual([
-            expect.objectContaining({
-                id: 'order_line_allocations.(order_id,line_number)->order_lines.(order_id,line_number)',
-                source: 'composite_profile_match',
-                from: expect.objectContaining({
-                    columnIds: ['order_line_allocations.order_id', 'order_line_allocations.line_number'],
-                    columns: ['order_id', 'line_number'],
-                }),
-                to: expect.objectContaining({
-                    columnIds: ['order_lines.order_id', 'order_lines.line_number'],
-                    columns: ['order_id', 'line_number'],
-                }),
-                reasons: ['composite_validation_passed'],
-                validation: expect.objectContaining({ sourceCoverage: 1 }),
-            }),
-        ]);
-    });
-});

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

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