@kaelio/ktx 0.10.0 → 0.12.0

package/dist/context/scan/local-structural-artifacts.js

@@ -25,7 +25,7 @@ function parseWarning(rawWarning, path) {
         !scanWarningCodes.has(rawWarning.code) ||
         typeof rawWarning.message !== 'string' ||
         typeof rawWarning.recoverable !== 'boolean') {
-        throw new Error(`Invalid KTX schema warning artifact: ${path}`);
+        throw new Error(`Invalid ktx schema warning artifact: ${path}`);
     }
     return {
         code: rawWarning.code,
@@ -42,7 +42,7 @@ async function readWarnings(input) {
         const warningRaw = await input.project.fileStore.readFile(path);
         const parsed = JSON.parse(warningRaw.content);
         if (!isRecord(parsed) || !Array.isArray(parsed.warnings)) {
-            throw new Error(`Invalid KTX schema warnings artifact: ${path}`);
+            throw new Error(`Invalid ktx schema warnings artifact: ${path}`);
         }
         return parsed.warnings.map((warning) => parseWarning(warning, path));
     }
@@ -68,7 +68,7 @@ function parseColumn(rawColumn, path) {
             rawColumn.dimensionType !== 'string' &&
             rawColumn.dimensionType !== 'number' &&
             rawColumn.dimensionType !== 'boolean')) {
-        throw new Error(`Invalid KTX schema column artifact: ${path}`);
+        throw new Error(`Invalid ktx schema column artifact: ${path}`);
     }
     return {
         name: rawColumn.name,
@@ -85,7 +85,7 @@ function parseForeignKey(rawForeignKey, path) {
         typeof rawForeignKey.fromColumn !== 'string' ||
         typeof rawForeignKey.toTable !== 'string' ||
         typeof rawForeignKey.toColumn !== 'string') {
-        throw new Error(`Invalid KTX schema foreign key artifact: ${path}`);
+        throw new Error(`Invalid ktx schema foreign key artifact: ${path}`);
     }
     return {
         fromColumn: rawForeignKey.fromColumn,
@@ -99,7 +99,7 @@ function parseForeignKey(rawForeignKey, path) {
 function parseTable(raw, path) {
     const parsed = JSON.parse(raw);
     if (!isRecord(parsed) || typeof parsed.name !== 'string' || !Array.isArray(parsed.columns)) {
-        throw new Error(`Invalid KTX schema table artifact: ${path}`);
+        throw new Error(`Invalid ktx schema table artifact: ${path}`);
     }
     return {
         catalog: optionalStringOrNull(parsed.catalog) ?? null,

package/dist/context/scan/relationship-benchmark-report.js

@@ -211,7 +211,7 @@ function compositeSkipBlocks(report) {
 }
 export function formatKtxRelationshipBenchmarkReportMarkdown(report) {
     const lines = [
-        '# KTX Relationship Discovery Benchmark Evidence',
+        '# ktx Relationship Discovery Benchmark Evidence',
         '',
         `Generated: ${report.generatedAt}`,
         '',

package/dist/context/scan/relationship-discovery.js

@@ -87,7 +87,7 @@ async function detectCompositeRelationships(input) {
     catch (error) {
         input.warnings.push({
             code: 'relationship_validation_failed',
-            message: `KTX composite relationship detection failed: ${error instanceof Error ? error.message : String(error)}`,
+            message: `ktx composite relationship detection failed: ${error instanceof Error ? error.message : String(error)}`,
             recoverable: true,
             metadata: { source: 'composite_relationship_detection' },
         });
@@ -110,7 +110,7 @@ function sqlExecutor(input) {
             warnings: [
                 {
                     code: 'connector_capability_missing',
-                    message: 'KTX scan connector cannot run read-only SQL relationship validation',
+                    message: 'ktx scan connector cannot run read-only SQL relationship validation',
                     recoverable: true,
                     metadata: { capability: 'readOnlySql' },
                 },
@@ -123,7 +123,7 @@ function sqlExecutor(input) {
             warnings: [
                 {
                     code: 'relationship_validation_failed',
-                    message: 'KTX scan connector advertises readOnlySql but does not expose executeReadOnly',
+                    message: 'ktx scan connector advertises readOnlySql but does not expose executeReadOnly',
                     recoverable: true,
                     metadata: { capability: 'readOnlySql' },
                 },

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

@@ -116,7 +116,7 @@ function mapValidProposals(schema, output, settings) {
         const fromColumn = fromTable ? findColumn(fromTable, item.fromColumn) : null;
         const toColumn = toTable ? findColumn(toTable, item.toColumn) : null;
         if (!fromTable || !toTable || !fromColumn || !toColumn) {
-            warnings.push(invalidReferenceWarning('KTX relationship LLM proposal referenced a table or column that is not in the schema.', {
+            warnings.push(invalidReferenceWarning('ktx relationship LLM proposal referenced a table or column that is not in the schema.', {
                 proposal: item,
             }));
             continue;
@@ -148,7 +148,7 @@ function generationFailureWarning(error) {
     const message = error instanceof Error ? error.message : String(error);
     return {
         code: 'relationship_llm_proposal_failed',
-        message: `KTX relationship LLM proposal failed: ${message}`,
+        message: `ktx relationship LLM proposal failed: ${message}`,
         recoverable: true,
     };
 }
@@ -159,7 +159,7 @@ export async function proposeKtxRelationshipCandidatesWithLlm(input) {
     const settings = mergeSettings(input.settings);
     const evidence = buildEvidencePacket(input.schema, input.profile, settings);
     const system = [
-        'You are helping KTX review possible SQL relationships before validation.',
+        'You are helping ktx review possible SQL relationships before validation.',
         'Use only the compact schema evidence. Propose likely primary keys and foreign keys for later SQL validation.',
         'Return structured output only; never assume a join is accepted.',
     ].join('\n');

package/dist/context/sl/local-query.js

@@ -1,38 +1,8 @@
+import { sqlAnalysisDialectForDriver } from '../sql-analysis/dialect.js';
 import { loadLocalSlSourceRecords } from './local-sl.js';
 import { toResolvedWire } from './semantic-layer.service.js';
+import { assertSafeConnectionId } from './source-files.js';
 const COMPILE_ONLY_REASON = 'Local semantic-layer query compiled SQL but no data-source execution adapter is configured.';
-function assertSafePathToken(kind, value) {
-    if (value.trim().length === 0 ||
-        value.includes('..') ||
-        value.includes('\\') ||
-        value.startsWith('/') ||
-        value.startsWith('.') ||
-        value.includes('//')) {
-        throw new Error(`Unsafe ${kind}: ${value}`);
-    }
-    return value;
-}
-function assertSafeConnectionId(connectionId) {
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId)) {
-        throw new Error(`Unsafe connection id: ${connectionId}`);
-    }
-    return assertSafePathToken('connection id', connectionId);
-}
-function dialectForDriver(driver) {
-    const normalized = (driver ?? 'postgres').toUpperCase();
-    const map = {
-        POSTGRES: 'postgres',
-        BIGQUERY: 'bigquery',
-        SNOWFLAKE: 'snowflake',
-        MYSQL: 'mysql',
-        SQLSERVER: 'tsql',
-        SQLITE: 'sqlite',
-        DUCKDB: 'duckdb',
-        CLICKHOUSE: 'clickhouse',
-        DATABRICKS: 'databricks',
-    };
-    return map[normalized] ?? 'postgres';
-}
 function resolveLocalConnectionId(project, requested) {
     if (requested) {
         return assertSafeConnectionId(requested);
@@ -56,7 +26,7 @@ function headersFromColumns(columns) {
 export async function compileLocalSlQuery(project, options) {
     await options.onProgress?.({ progress: 0, message: 'Compiling query' });
     const connectionId = resolveLocalConnectionId(project, options.connectionId);
-    const dialect = dialectForDriver(project.config.connections[connectionId]?.driver);
+    const dialect = sqlAnalysisDialectForDriver(project.config.connections[connectionId]?.driver);
     const sources = await loadComputableSources(project, connectionId);
     await options.onProgress?.({ progress: 0.3, message: 'Generating SQL' });
     const response = await options.compute.query({

package/dist/context/sl/local-sl.d.ts

@@ -1,5 +1,4 @@
 import type { KtxEmbeddingPort } from '../../context/core/embedding.js';
-import type { KtxFileWriteResult } from '../../context/core/file-store.js';
 import type { KtxLocalProject } from '../../context/project/project.js';
 import type { PgliteSlSearchPrototypeOwnerOptions } from './pglite-sl-search-prototype.js';
 import type { SemanticLayerSource, SlDictionaryMatch, SlSearchLaneSummary, SlSearchMatchReason } from './types.js';
@@ -56,13 +55,6 @@ export declare function validateLocalSlSource(rawYaml: string, options?: {
     connectionId?: string;
     sourceName?: string;
 }): Promise<LocalSlValidationResult>;
-/** @internal */
-export declare function writeLocalSlSource(project: KtxLocalProject, input: {
-    connectionId: string;
-    sourceName: string;
-    yaml: string;
-}): Promise<KtxFileWriteResult>;
-/** @internal */
 export declare function readLocalSlSource(project: KtxLocalProject, input: {
     connectionId: string;
     sourceName: string;

package/dist/context/sl/local-sl.js

@@ -7,48 +7,12 @@ import { normalizeSemanticLayerDescriptions } from './description-normalization.
 import { sourceDefinitionSchema, sourceOverlaySchema } from './schemas.js';
 import { composeOverlay, projectManifestEntry, SemanticLayerService, toResolvedWire, } from './semantic-layer.service.js';
 import { loadLatestSlDictionaryEntries } from './sl-dictionary-profile.js';
+import { assertSafeConnectionId, isSafeConnectionId, isSlYamlPath, slSourceNameForFile, sourceNameFromPath, } from './source-files.js';
 import { buildSemanticLayerSourceSearchText, SlSearchService } from './sl-search.service.js';
 import { SqliteSlSourcesIndex } from './sqlite-sl-sources-index.js';
-const LOCAL_AUTHOR = 'ktx';
-const LOCAL_AUTHOR_EMAIL = 'ktx@example.com';
-function assertSafePathToken(kind, value) {
-    if (value.trim().length === 0 ||
-        value.includes('..') ||
-        value.includes('\\') ||
-        value.startsWith('/') ||
-        value.startsWith('.') ||
-        value.includes('//')) {
-        throw new Error(`Unsafe ${kind}: ${value}`);
-    }
-    return value;
-}
-function assertSafeConnectionId(connectionId) {
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId)) {
-        throw new Error(`Unsafe connection id: ${connectionId}`);
-    }
-    return assertSafePathToken('connection id', connectionId);
-}
-function isSafeConnectionId(connectionId) {
-    return typeof connectionId === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId);
-}
-function assertSafeSourceName(sourceName) {
-    if (!/^[a-z0-9][a-z0-9_]*$/.test(sourceName)) {
-        throw new Error(`Unsafe semantic-layer source name: ${sourceName}`);
-    }
-    return assertSafePathToken('semantic-layer source name', sourceName);
-}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function slPath(connectionId, sourceName) {
-    return `semantic-layer/${assertSafeConnectionId(connectionId)}/${assertSafeSourceName(sourceName)}.yaml`;
-}
-function sourceNameFromPath(path) {
-    return (path
-        .split('/')
-        .at(-1)
-        ?.replace(/\.ya?ml$/, '') ?? path);
-}
 function parseYamlRecord(raw) {
     const parsed = YAML.parse(raw);
     if (!isRecord(parsed)) {
@@ -126,11 +90,17 @@ export async function loadLocalSlSourceRecords(project, input) {
     const dir = `semantic-layer/${connectionId}`;
     const schemaDir = `${dir}/_schema`;
     const listed = await project.fileStore.listFiles(dir);
-    const paths = listed.files.filter((file) => file.endsWith('.yaml') || file.endsWith('.yml')).sort();
+    const paths = listed.files.filter(isSlYamlPath).sort();
     const sources = new Map();
     for (const path of paths.filter((file) => file.startsWith(`${schemaDir}/`))) {
         const raw = await project.fileStore.readFile(path);
-        const tables = manifestTables(parseYamlRecord(raw.content));
+        let tables;
+        try {
+            tables = manifestTables(parseYamlRecord(raw.content));
+        }
+        catch (error) {
+            throw new Error(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
         if (!tables) {
             continue;
         }
@@ -146,7 +116,30 @@ export async function loadLocalSlSourceRecords(project, input) {
     }
     for (const path of paths.filter((file) => !file.startsWith(`${schemaDir}/`))) {
         const raw = await project.fileStore.readFile(path);
-        const parsed = parseYamlRecord(raw.content);
+        let parsed;
+        try {
+            parsed = parseYamlRecord(raw.content);
+        }
+        catch {
+            // A source mid-edit (e.g. an agent saved half-written YAML) must not take
+            // down reads, listings, or search for its siblings. Key it by the same
+            // name the writer side uses (the intact top-level `name:`, recovered even
+            // when the YAML is broken below it; filename only as a last resort) so a
+            // broken uppercase/hashed/human-renamed source stays reachable under its
+            // real name, and surface the raw content for repair.
+            const brokenName = slSourceNameForFile(path, raw.content);
+            sources.set(brokenName, {
+                connectionId,
+                name: brokenName,
+                path,
+                columnCount: 0,
+                measureCount: 0,
+                joinCount: 0,
+                yaml: raw.content,
+                source: { name: brokenName, grain: [], columns: [], joins: [], measures: [] },
+            });
+            continue;
+        }
         const name = typeof parsed.name === 'string' && parsed.name.length > 0 ? parsed.name : sourceNameFromPath(path);
         if (parsed.table || parsed.sql) {
             const source = parsedStandaloneSource(parsed, name);
@@ -191,36 +184,18 @@ export async function validateLocalSlSource(rawYaml, options) {
         return { valid: false, errors: validationErrors(error) };
     }
 }
-/** @internal */
-export async function writeLocalSlSource(project, input) {
-    const validation = await validateLocalSlSource(input.yaml, { project, connectionId: input.connectionId });
-    if (!validation.valid) {
-        throw new Error(`Invalid semantic-layer source: ${validation.errors.join('; ')}`);
-    }
-    const parsed = parseYamlRecord(input.yaml);
-    if (typeof parsed.name === 'string' && parsed.name !== input.sourceName) {
-        throw new Error(`Semantic-layer source name "${parsed.name}" does not match requested path "${input.sourceName}"`);
-    }
-    const path = slPath(input.connectionId, input.sourceName);
-    return project.fileStore.writeFile(path, input.yaml.endsWith('\n') ? input.yaml : `${input.yaml}\n`, LOCAL_AUTHOR, LOCAL_AUTHOR_EMAIL, `Write semantic-layer source: ${input.connectionId}/${input.sourceName}`);
-}
-/** @internal */
 export async function readLocalSlSource(project, input) {
-    const path = slPath(input.connectionId, input.sourceName);
-    try {
-        const result = await project.fileStore.readFile(path);
-        return {
-            ...summarizeSource({ connectionId: input.connectionId, path, raw: result.content }),
-            yaml: result.content,
-        };
-    }
-    catch {
-        const records = await loadLocalSlSourceRecords(project, {
-            connectionId: input.connectionId,
-        });
-        const record = records.find((source) => source.name === input.sourceName);
-        return record ? { ...record } : null;
-    }
+    // Source identity is the in-file `name:` (mirroring the warehouse identifier
+    // verbatim, e.g. Snowflake's uppercase `WIDGET_SALES`), never the filename. The
+    // record loader resolves standalone files, overlays, manifest-backed sources,
+    // and mid-edit files whose YAML no longer parses — so readers — `ktx sl read`,
+    // `ktx sl validate`, and the `sl_read_source` MCP tool — can surface broken
+    // content for repair instead of failing on it.
+    const records = await loadLocalSlSourceRecords(project, {
+        connectionId: input.connectionId,
+    });
+    const record = records.find((source) => source.name === input.sourceName);
+    return record ? { ...record } : null;
 }
 export async function resolveLocalSlSource(project, input) {
     if (input.connectionId !== undefined) {

package/dist/context/sl/semantic-layer.service.d.ts

@@ -38,17 +38,23 @@ export declare class SemanticLayerService {
         name: string;
         connectionType: string;
     }>>;
-    private sourcePath;
+    private resolveWritePath;
     writeSource(connectionId: string, source: SemanticLayerSource, author: string, authorEmail: string, commitMessage?: string, options?: WriteSourceOptions & {
         skipLock?: boolean;
     }): Promise<{
+        path: string;
         warnings: string[];
         commitHash?: string | null;
     }>;
+    /**
+     * Raw standalone/overlay file for a source, resolved by its in-file `name:`.
+     * Returns null when no file declares the name (the source may still exist as
+     * a manifest entry under `_schema/`).
+     */
     readSourceFile(connectionId: string, sourceName: string): Promise<{
         content: string;
         path: string;
-    }>;
+    } | null>;
     loadSource(connectionId: string, sourceName: string): Promise<SemanticLayerSource | null>;
     loadAllSources(connectionId: string): Promise<LoadAllSourcesResult>;
     /**
@@ -87,14 +93,8 @@ export declare class SemanticLayerService {
     } | null>;
     validatePhysicalTableReferences(connectionId: string, sources: SemanticLayerSource[]): Promise<string[]>;
     getDialectForConnection(connectionId: string): Promise<string>;
-    listSourceNames(connectionId: string): Promise<string[]>;
     listFilesForConnection(connectionId: string): Promise<string[]>;
-    readFileByPath(connectionId: string, relativePath: string): Promise<{
-        content: string;
-        readOnly: boolean;
-    }>;
     deleteSource(connectionId: string, sourceName: string, author: string, authorEmail: string): Promise<import("../../context/core/file-store.js").KtxFileWriteResult | null>;
-    getSourceHistory(connectionId: string, sourceName: string): Promise<unknown>;
     /**
      * Validate the semantic layer state that *would* exist if `proposedSource`
      * were written, without persisting anything. Used by write/edit tools to
@@ -203,6 +203,23 @@ export interface ManifestTableEntry {
     usage?: TableUsageOutput;
 }
 export declare function projectManifestEntry(name: string, entry: ManifestTableEntry): SemanticLayerSource;
+export interface MissingJoinTarget {
+    to: string;
+    /** Source whose name matches only case-insensitively, if any — the usual authoring mistake. */
+    caseMismatch: string | null;
+}
+/**
+ * Join targets that do not exactly match a known source name. The Python
+ * engine resolves `joins[].to` by exact name within one connection's source
+ * set (`engine._collect_orphan_join_target_errors`) and `query()` raises on a
+ * miss, so anything looser here — case-insensitive matches, table refs,
+ * sources in other connections — would pass this gate and then fail
+ * query/validation as an orphan join target.
+ */
+export declare function findMissingJoinTargets(joins: Array<{
+    to: string;
+}> | undefined, knownSourceNames: Iterable<string>): MissingJoinTarget[];
+export declare function formatMissingJoinTarget(missing: MissingJoinTarget): string;
 /**
  * Returns one message per measure-level segment reference that doesn't resolve to
  * a segment defined on the source. Array is empty when every reference checks out.