@kaelio/ktx 0.5.0 → 0.6.0

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

@@ -1,206 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { createKtxConnectorCapabilities, } from './types.js';
-describe('KTX scan contract types', () => {
-    it('defaults to structural-only connector capabilities', () => {
-        expect(createKtxConnectorCapabilities()).toEqual({
-            structuralIntrospection: true,
-            tableSampling: false,
-            columnSampling: false,
-            columnStats: false,
-            readOnlySql: false,
-            nestedAnalysis: false,
-            eventStreamDiscovery: false,
-            formalForeignKeys: false,
-            estimatedRowCounts: false,
-        });
-    });
-    it('keeps structural introspection mandatory when optional capabilities are enabled', () => {
-        expect(createKtxConnectorCapabilities({
-            tableSampling: true,
-            readOnlySql: true,
-            eventStreamDiscovery: true,
-            estimatedRowCounts: true,
-        })).toEqual({
-            structuralIntrospection: true,
-            tableSampling: true,
-            columnSampling: false,
-            columnStats: false,
-            readOnlySql: true,
-            nestedAnalysis: false,
-            eventStreamDiscovery: true,
-            formalForeignKeys: false,
-            estimatedRowCounts: true,
-        });
-    });
-    it('describes the connector surface without requiring enrichment methods', async () => {
-        const snapshot = {
-            connectionId: 'warehouse',
-            driver: 'postgres',
-            extractedAt: '2026-04-29T00:00:00.000Z',
-            scope: { schemas: ['public'] },
-            metadata: { source: 'unit-test' },
-            tables: [
-                {
-                    catalog: null,
-                    db: 'public',
-                    name: 'orders',
-                    kind: 'table',
-                    comment: 'Customer orders',
-                    estimatedRows: 42,
-                    columns: [
-                        {
-                            name: 'id',
-                            nativeType: 'integer',
-                            normalizedType: 'integer',
-                            dimensionType: 'number',
-                            nullable: false,
-                            primaryKey: true,
-                            comment: 'Primary key',
-                        },
-                    ],
-                    foreignKeys: [],
-                },
-            ],
-        };
-        const connector = {
-            id: 'test-postgres',
-            driver: 'postgres',
-            capabilities: createKtxConnectorCapabilities({ estimatedRowCounts: true }),
-            async introspect(input, ctx) {
-                expect(input.connectionId).toBe('warehouse');
-                expect(ctx.runId).toBe('scan-run-1');
-                return snapshot;
-            },
-        };
-        await expect(connector.introspect({
-            connectionId: 'warehouse',
-            driver: 'postgres',
-            scope: { schemas: ['public'] },
-            mode: 'structural',
-        }, { runId: 'scan-run-1' })).resolves.toEqual(snapshot);
-    });
-    it('models optional event-stream discovery as a connector capability and port', async () => {
-        const eventTypes = [{ value: '$pageview', count: 42 }];
-        const propertyKeys = [{ key: '$browser', count: 31 }];
-        const propertyValues = { values: ['Chrome', 'Safari'], cardinality: 2 };
-        const discovery = {
-            async listEventTypes(input) {
-                expect(input).toEqual({
-                    connectionId: 'product',
-                    table: { catalog: '157881', db: null, name: 'events' },
-                    eventColumn: 'event',
-                    limit: 2,
-                    minCount: 30,
-                    lookbackDays: 14,
-                });
-                return eventTypes;
-            },
-            async listPropertyKeys(input) {
-                expect(input).toEqual({
-                    connectionId: 'product',
-                    table: { catalog: '157881', db: null, name: 'events' },
-                    jsonColumn: 'properties',
-                    sampleSize: 1000,
-                    limit: 5,
-                    lookbackDays: 7,
-                });
-                return propertyKeys;
-            },
-            async listPropertyValues(input) {
-                expect(input).toEqual({
-                    connectionId: 'product',
-                    table: { catalog: '157881', db: null, name: 'events' },
-                    jsonColumn: 'properties',
-                    propertyKey: '$browser',
-                    limit: 3,
-                    maxCardinality: 1000,
-                    lookbackDays: 30,
-                });
-                return propertyValues;
-            },
-        };
-        const connector = {
-            id: 'clickhouse:product',
-            driver: 'clickhouse',
-            capabilities: createKtxConnectorCapabilities({ eventStreamDiscovery: true }),
-            eventStreamDiscovery: discovery,
-            async introspect() {
-                return {
-                    connectionId: 'product',
-                    driver: 'clickhouse',
-                    extractedAt: '2026-04-29T00:00:00.000Z',
-                    scope: { catalogs: ['157881'] },
-                    metadata: {},
-                    tables: [],
-                };
-            },
-        };
-        await expect(connector.eventStreamDiscovery?.listEventTypes({
-            connectionId: 'product',
-            table: { catalog: '157881', db: null, name: 'events' },
-            eventColumn: 'event',
-            limit: 2,
-            minCount: 30,
-            lookbackDays: 14,
-        }, { runId: 'scan-run-1' })).resolves.toEqual([{ value: '$pageview', count: 42 }]);
-        await expect(connector.eventStreamDiscovery?.listPropertyKeys({
-            connectionId: 'product',
-            table: { catalog: '157881', db: null, name: 'events' },
-            jsonColumn: 'properties',
-            sampleSize: 1000,
-            limit: 5,
-            lookbackDays: 7,
-        }, { runId: 'scan-run-1' })).resolves.toEqual([{ key: '$browser', count: 31 }]);
-        await expect(connector.eventStreamDiscovery?.listPropertyValues({
-            connectionId: 'product',
-            table: { catalog: '157881', db: null, name: 'events' },
-            jsonColumn: 'properties',
-            propertyKey: '$browser',
-            limit: 3,
-            maxCardinality: 1000,
-            lookbackDays: 30,
-        }, { runId: 'scan-run-1' })).resolves.toEqual({ values: ['Chrome', 'Safari'], cardinality: 2 });
-    });
-    it('keeps read-only query results separate from schema snapshots', () => {
-        const result = {
-            headers: ['id', 'amount'],
-            headerTypes: ['integer', 'numeric'],
-            rows: [[1, 10.5]],
-            totalRows: 1,
-            rowCount: 1,
-        };
-        expect(result).toEqual({
-            headers: ['id', 'amount'],
-            headerTypes: ['integer', 'numeric'],
-            rows: [[1, 10.5]],
-            totalRows: 1,
-            rowCount: 1,
-        });
-    });
-    it('models host-provided network tunnel endpoint resolution without app imports', async () => {
-        const endpoint = {
-            host: '127.0.0.1',
-            port: 15432,
-            close: async () => undefined,
-        };
-        const tunnelPort = {
-            async resolveEndpoint(input) {
-                expect(input).toEqual({
-                    connectionId: 'warehouse',
-                    driver: 'postgres',
-                    host: 'db.internal',
-                    port: 5432,
-                    connection: { networkProxy: { type: 'ssh_tunnel' } },
-                });
-                return endpoint;
-            },
-        };
-        await expect(tunnelPort.resolveEndpoint({
-            connectionId: 'warehouse',
-            driver: 'postgres',
-            host: 'db.internal',
-            port: 5432,
-            connection: { networkProxy: { type: 'ssh_tunnel' } },
-        })).resolves.toBe(endpoint);
-    });
-});

package/dist/context/scan/warehouse-catalog.test.d.ts

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

package/dist/context/scan/warehouse-catalog.test.js

@@ -1,158 +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 { WarehouseCatalogService } from './warehouse-catalog.js';
-describe('WarehouseCatalogService', () => {
-    let tempDir;
-    let project;
-    beforeEach(async () => {
-        tempDir = await mkdtemp(join(tmpdir(), 'ktx-warehouse-catalog-'));
-        project = await initKtxProject({ projectDir: join(tempDir, 'project') });
-    });
-    afterEach(async () => {
-        await rm(tempDir, { recursive: true, force: true });
-    });
-    async function seedLiveDatabaseScan(connectionId = 'warehouse', syncId = 'sync-2', driver = 'postgres') {
-        const root = `raw-sources/${connectionId}/live-database/${syncId}`;
-        const tableRef = {
-            catalog: driver === 'bigquery' ? 'analytics' : null,
-            db: driver === 'sqlite' ? null : 'public',
-            name: 'orders',
-        };
-        await project.fileStore.writeFile(`${root}/connection.json`, JSON.stringify({ connectionId, driver, extractedAt: '2026-05-12T00:00:00.000Z' }, null, 2), 'ktx', 'ktx@example.com', 'seed connection');
-        await project.fileStore.writeFile(`${root}/tables/orders.json`, JSON.stringify({
-            catalog: tableRef.catalog,
-            db: tableRef.db,
-            name: tableRef.name,
-            kind: 'table',
-            comment: 'Customer orders',
-            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: [],
-        }, null, 2), 'ktx', 'ktx@example.com', 'seed orders');
-        await project.fileStore.writeFile(`${root}/enrichment/relationship-profile.json`, JSON.stringify({
-            connectionId,
-            driver,
-            sqlAvailable: true,
-            queryCount: 3,
-            tables: [{ table: { catalog: tableRef.catalog, db: tableRef.db, name: tableRef.name }, rowCount: 12 }],
-            columns: {
-                'orders.status': {
-                    table: { catalog: tableRef.catalog, db: tableRef.db, name: tableRef.name },
-                    column: 'status',
-                    nativeType: 'text',
-                    normalizedType: 'text',
-                    rowCount: 12,
-                    nullCount: 0,
-                    distinctCount: 2,
-                    uniquenessRatio: 0.1667,
-                    nullRate: 0,
-                    sampleValues: ['paid', 'refunded'],
-                    minTextLength: 4,
-                    maxTextLength: 8,
-                },
-            },
-            warnings: [],
-        }, null, 2), 'ktx', 'ktx@example.com', 'seed profile');
-    }
-    it('finds the latest sync and merges table schema with relationship profile values', async () => {
-        await seedLiveDatabaseScan('warehouse', 'sync-1');
-        await seedLiveDatabaseScan('warehouse', 'sync-2');
-        const catalog = new WarehouseCatalogService({ fileStore: project.fileStore });
-        await expect(catalog.getLatestSyncId('warehouse')).resolves.toBe('sync-2');
-        const detail = await catalog.getTable({ connectionId: 'warehouse', catalog: null, db: 'public', name: 'orders' });
-        expect(detail).toMatchObject({
-            connectionId: 'warehouse',
-            display: 'public.orders',
-            rowCount: 12,
-            columns: [
-                { name: 'id', nativeType: 'integer', primaryKey: true },
-                { name: 'status', nativeType: 'text', sampleValues: ['paid', 'refunded'], distinctCount: 2 },
-            ],
-        });
-        expect(detail).not.toHaveProperty(['connection', 'Name'].join(''));
-        const hits = await catalog.searchByName('warehouse', 'orders', 5);
-        expect(hits[0]).toMatchObject({
-            kind: 'table',
-            connectionId: 'warehouse',
-            display: 'public.orders',
-        });
-        expect(hits[0]).not.toHaveProperty(['connection', 'Name'].join(''));
-    });
-    it('returns scanAvailable=false when no live-database scan exists', async () => {
-        const catalog = new WarehouseCatalogService({ fileStore: project.fileStore });
-        await expect(catalog.getTable({ connectionId: 'missing', catalog: null, db: 'public', name: 'orders' })).resolves.toBeNull();
-        await expect(catalog.hasScan('missing')).resolves.toBe(false);
-    });
-    it('resolves postgres display strings and returns closest candidates for missing tables', async () => {
-        await seedLiveDatabaseScan();
-        const catalog = new WarehouseCatalogService({ fileStore: project.fileStore });
-        await expect(catalog.resolveDisplay('warehouse', 'public.orders')).resolves.toMatchObject({
-            resolved: { catalog: null, db: 'public', name: 'orders' },
-            candidates: [],
-            dialect: 'postgres',
-        });
-        await expect(catalog.resolveDisplay('warehouse', 'public.orderz')).resolves.toMatchObject({
-            resolved: null,
-            candidates: [{ name: 'orders' }],
-        });
-    });
-    it('treats two-part BigQuery identifiers as ambiguous instead of guessing', async () => {
-        await seedLiveDatabaseScan('warehouse', 'sync-bigquery', 'bigquery');
-        const catalog = new WarehouseCatalogService({ fileStore: project.fileStore });
-        await expect(catalog.resolveDisplay('warehouse', 'public.orders')).resolves.toMatchObject({
-            resolved: null,
-            dialect: 'bigquery',
-        });
-    });
-    it('resolves postgres column display strings without treating the column as a table', async () => {
-        await seedLiveDatabaseScan();
-        const catalog = new WarehouseCatalogService({ fileStore: project.fileStore });
-        await expect(catalog.resolveDisplayTarget('warehouse', 'public.orders.status')).resolves.toMatchObject({
-            resolved: { catalog: null, db: 'public', name: 'orders', column: 'status' },
-            candidates: [],
-            dialect: 'postgres',
-        });
-    });
-    it('resolves BigQuery column display strings with four parts', async () => {
-        await seedLiveDatabaseScan('warehouse', 'sync-bigquery', 'bigquery');
-        const catalog = new WarehouseCatalogService({ fileStore: project.fileStore });
-        await expect(catalog.resolveDisplayTarget('warehouse', 'analytics.public.orders.status')).resolves.toMatchObject({
-            resolved: { catalog: 'analytics', db: 'public', name: 'orders', column: 'status' },
-            candidates: [],
-            dialect: 'bigquery',
-        });
-    });
-    it('searches table names, column names, comments, and descriptions', async () => {
-        await seedLiveDatabaseScan();
-        const catalog = new WarehouseCatalogService({ fileStore: project.fileStore });
-        await expect(catalog.searchByName('warehouse', 'status', 10)).resolves.toEqual(expect.arrayContaining([
-            expect.objectContaining({
-                kind: 'column',
-                ref: expect.objectContaining({ db: 'public', name: 'orders', column: 'status' }),
-                matchedOn: 'name',
-            }),
-        ]));
-    });
-});

package/dist/context/search/backend-conformance.test-utils.d.ts

@@ -1,39 +0,0 @@
-import type { SearchBackendCapabilities, SearchLaneStatus } from './types.js';
-export interface SearchBackendConformanceLane {
-    lane: string;
-    status: SearchLaneStatus;
-    reason?: string;
-}
-export interface SearchBackendConformanceDictionaryMatch {
-    column: string;
-    values: readonly string[];
-    overflowCount?: number;
-}
-export interface SearchBackendConformanceResult {
-    id: string;
-    score: number;
-    matchReasons: readonly string[];
-    lanes?: readonly SearchBackendConformanceLane[];
-    dictionaryMatches?: readonly SearchBackendConformanceDictionaryMatch[];
-}
-export interface ExpectedSearchBackendConformanceLane {
-    status: SearchLaneStatus;
-    reason?: string;
-}
-export interface AssertSearchBackendConformanceCaseInput {
-    backendName: string;
-    surface: string;
-    caseName: string;
-    results: readonly SearchBackendConformanceResult[];
-    expectedTopIds: readonly string[];
-    expectedReasonsById?: Record<string, readonly string[]>;
-    expectedLanes?: Record<string, ExpectedSearchBackendConformanceLane>;
-    expectedDictionaryMatchesById?: Record<string, readonly SearchBackendConformanceDictionaryMatch[]>;
-}
-export interface AssertSearchBackendCapabilitiesInput {
-    backendName: string;
-    capabilities: SearchBackendCapabilities;
-    expected: Partial<SearchBackendCapabilities>;
-}
-export declare function assertSearchBackendConformanceCase(input: AssertSearchBackendConformanceCaseInput): void;
-export declare function assertSearchBackendCapabilities(input: AssertSearchBackendCapabilitiesInput): void;

package/dist/context/search/backend-conformance.test-utils.js

@@ -1,88 +0,0 @@
-function caseLabel(input) {
-    return `${input.backendName} ${input.surface} conformance case "${input.caseName}"`;
-}
-function fail(label, failures) {
-    throw new Error([`${label} failed:`, ...failures.map((failure) => `- ${failure}`)].join('\n'));
-}
-function dictionaryMatchKey(match) {
-    const values = [...match.values].sort((left, right) => left.localeCompare(right)).join(',');
-    return `${match.column}:${values}:${match.overflowCount ?? 0}`;
-}
-function dictionaryMatchKeys(matches) {
-    return (matches ?? []).map(dictionaryMatchKey).sort((left, right) => left.localeCompare(right));
-}
-export function assertSearchBackendConformanceCase(input) {
-    const label = caseLabel(input);
-    const failures = [];
-    const topResults = input.results.slice(0, input.expectedTopIds.length);
-    input.expectedTopIds.forEach((expectedId, index) => {
-        const actualId = topResults[index]?.id;
-        if (actualId !== expectedId) {
-            failures.push(`expected result ${index + 1} to be ${expectedId}, got ${actualId ?? '<missing>'}`);
-        }
-    });
-    const byId = new Map(input.results.map((result) => [result.id, result]));
-    for (const expectedId of input.expectedTopIds) {
-        const result = byId.get(expectedId);
-        if (!result) {
-            continue;
-        }
-        if (!Number.isFinite(result.score) || result.score <= 0) {
-            failures.push(`expected ${expectedId} to have a positive finite score, got ${result.score}`);
-        }
-    }
-    for (const [id, expectedReasons] of Object.entries(input.expectedReasonsById ?? {})) {
-        const result = byId.get(id);
-        if (!result) {
-            failures.push(`expected reasons for ${id}, but the result was missing`);
-            continue;
-        }
-        for (const reason of expectedReasons) {
-            if (!result.matchReasons.includes(reason)) {
-                failures.push(`expected ${id} to include match reason ${reason}, got [${result.matchReasons.join(', ')}]`);
-            }
-        }
-    }
-    const allLanes = input.results.flatMap((result) => result.lanes ?? []);
-    for (const [lane, expected] of Object.entries(input.expectedLanes ?? {})) {
-        const actual = allLanes.find((entry) => entry.lane === lane);
-        if (!actual) {
-            failures.push(`expected lane ${lane} to be reported`);
-            continue;
-        }
-        if (actual.status !== expected.status) {
-            failures.push(`expected lane ${lane} status ${expected.status}, got ${actual.status}`);
-        }
-        if (expected.reason !== undefined && actual.reason !== expected.reason) {
-            failures.push(`expected lane ${lane} reason ${expected.reason}, got ${actual.reason ?? '<missing>'}`);
-        }
-    }
-    for (const [id, expectedMatches] of Object.entries(input.expectedDictionaryMatchesById ?? {})) {
-        const result = byId.get(id);
-        if (!result) {
-            failures.push(`expected dictionary matches for ${id}, but the result was missing`);
-            continue;
-        }
-        const actualKeys = dictionaryMatchKeys(result.dictionaryMatches);
-        for (const expectedKey of dictionaryMatchKeys(expectedMatches)) {
-            if (!actualKeys.includes(expectedKey)) {
-                failures.push(`expected ${id} dictionary evidence ${expectedKey}, got [${actualKeys.join(', ')}]`);
-            }
-        }
-    }
-    if (failures.length > 0) {
-        fail(label, failures);
-    }
-}
-export function assertSearchBackendCapabilities(input) {
-    const failures = [];
-    for (const [capability, expected] of Object.entries(input.expected)) {
-        const actual = input.capabilities[capability];
-        if (actual !== expected) {
-            failures.push(`expected ${capability}=${expected}, got ${actual}`);
-        }
-    }
-    if (failures.length > 0) {
-        fail(`${input.backendName} search backend capabilities`, failures);
-    }
-}

package/dist/context/search/backend-conformance.test-utils.test.d.ts

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