taurusdb-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+export { TaurusDBEngine } from "./engine.js";
+export type { EnhancedExplainResult, ConfirmationOutcome, DataSourceInfo, IssueConfirmationInput, TaurusDBEngineCreateOptions, TaurusDBEngineDeps, } from "./engine.js";
+export { createConfigFromEnv, getConfig, redactConfigForLog, resetConfigForTests, } from "./config/index.js";
+export type { Config } from "./config/index.js";
+export { createSqlProfileLoader, RuntimeOverrideProfileLoader, } from "./auth/sql-profile-loader.js";
+export type { DataSourceProfile, DatabaseEngine, ProfileLoader, RuntimeDataSourceTarget, RuntimeTargetProfileLoader, TlsOptions, } from "./auth/sql-profile-loader.js";
+export { DatasourceResolutionError } from "./context/datasource-resolver.js";
+export type { DatasourceResolveInput, DatasourceResolver, RuntimeLimits, SessionContext, } from "./context/session-context.js";
+export { ConnectionPoolError } from "./executor/connection-pool.js";
+export type { CancelResult, ExplainResult, MutationOptions, MutationResult, QueryResult, QueryStatus, ReadonlyOptions, SqlExecutor, } from "./executor/sql-executor.js";
+export { createCapabilityProbe } from "./capability/probe.js";
+export type { CapabilityProbe } from "./capability/probe.js";
+export { UnsupportedFeatureError } from "./capability/types.js";
+export type { CapabilitySnapshot, FeatureMatrix, FeatureStatus, KernelInfo, TaurusFeatureName, } from "./capability/types.js";
+export { createConfirmationStore, InMemoryConfirmationStore, } from "./safety/confirmation-store.js";
+export type { ConfirmationStore, ConfirmationToken, ConfirmationValidationResult, IssueInput, } from "./safety/confirmation-store.js";
+export { createGuardrail } from "./safety/guardrail.js";
+export type { Guardrail, GuardrailDecision, GuardrailRuntimeLimits, InspectInput, } from "./safety/guardrail.js";
+export type { ExplainRiskSummary, RiskLevel, ValidationResult } from "./safety/sql-validator.js";
+export { SchemaIntrospectionError } from "./schema/introspector.js";
+export type { ColumnInfo, DatabaseInfo, IndexInfo, SchemaIntrospector, TableInfo, TableSchema, } from "./schema/introspector.js";
+export { ErrorCode, formatBlocked, formatConfirmationRequired, formatError, formatSuccess, } from "./utils/formatter.js";
+export type { ErrorCode as ErrorCodeValue, ResponseMetadata, StatementType, ToolError, ToolResponse, } from "./utils/formatter.js";
+export { normalizeSql, sqlHash } from "./utils/hash.js";
+export { generateQueryId, generateTaskId } from "./utils/id.js";
+export { logger, withTaskContext } from "./utils/logger.js";
+export { CloudTaurusInstanceClient, createCloudTaurusInstanceClient, } from "./cloud/instances.js";
+export type { CloudTaurusInstanceSummary, ListCloudTaurusInstancesInput, } from "./cloud/instances.js";
+export { canAuthenticateHuaweiCloudRequests, fetchHuaweiCloud, getHuaweiCloudAuthFromConfig, hasHuaweiCloudCredentialAuth, inferHuaweiCloudRegionFromEndpoint, resolveHuaweiCloudProjectId, } from "./cloud/auth.js";
+export type { HuaweiCloudAuthOptions } from "./cloud/auth.js";
+export { FlashbackNoViewError, formatTimestamp as formatFlashbackTimestamp, } from "./taurus/flashback.js";
+export type { FlashbackInput, FlashbackNoViewDetails, } from "./taurus/flashback.js";
+export { buildListRecycleBinSql, buildRestoreRecycleBinTableSql, RECYCLE_BIN_DATABASE, } from "./taurus/recycle-bin.js";
+export type { RecycleBinListResult, RecycleBinRestoreResult, RestoreRecycleBinTableInput, } from "./taurus/recycle-bin.js";
+export { createPlaceholderDiagnosticResult } from "./diagnostics/types.js";
+export { buildResolveSlowSqlInput, createSlowSqlSource, TaurusApiSlowSqlSource, } from "./diagnostics/slow-sql-source.js";
+export { CesMetricsSource, createMetricsSource, } from "./diagnostics/metrics-source.js";
+export type { DbHotspotItem, DbHotspotResult, DiagnosticBaseInput, DiagnosticConfidence, DiagnosticEvidenceItem, DiagnosticEvidenceLevel, DiagnosticNextToolInput, DiagnoseDbHotspotInput, DiagnoseServiceLatencyInput, FindTopSlowSqlInput, FindTopSlowSqlResult, DiagnosticResult, DiagnosticRootCauseCandidate, DiagnosticSeverity, DiagnosticStatus, ServiceLatencyCandidate, ServiceLatencyResult, ServiceLatencySuspectedCategory, DiagnosticSuspiciousEntities, DiagnosticToolName, DiagnosisWindow, DiagnoseConnectionSpikeInput, DiagnoseLockContentionInput, DiagnoseSlowQueryInput, DiagnoseStoragePressureInput, PlaceholderDiagnosticOptions, TopSlowSqlItem, } from "./diagnostics/types.js";
+export type { ExternalSlowSqlSample, ResolveSlowSqlInput, SlowSqlSource, } from "./diagnostics/slow-sql-source.js";
+export type { MetricAlias, MetricPoint, MetricSummary, MetricsSource, QueryMetricsInput, } from "./diagnostics/metrics-source.js";

package/dist/index.js

@@ -0,0 +1,21 @@
+export { TaurusDBEngine } from "./engine.js";
+export { createConfigFromEnv, getConfig, redactConfigForLog, resetConfigForTests, } from "./config/index.js";
+export { createSqlProfileLoader, RuntimeOverrideProfileLoader, } from "./auth/sql-profile-loader.js";
+export { DatasourceResolutionError } from "./context/datasource-resolver.js";
+export { ConnectionPoolError } from "./executor/connection-pool.js";
+export { createCapabilityProbe } from "./capability/probe.js";
+export { UnsupportedFeatureError } from "./capability/types.js";
+export { createConfirmationStore, InMemoryConfirmationStore, } from "./safety/confirmation-store.js";
+export { createGuardrail } from "./safety/guardrail.js";
+export { SchemaIntrospectionError } from "./schema/introspector.js";
+export { ErrorCode, formatBlocked, formatConfirmationRequired, formatError, formatSuccess, } from "./utils/formatter.js";
+export { normalizeSql, sqlHash } from "./utils/hash.js";
+export { generateQueryId, generateTaskId } from "./utils/id.js";
+export { logger, withTaskContext } from "./utils/logger.js";
+export { CloudTaurusInstanceClient, createCloudTaurusInstanceClient, } from "./cloud/instances.js";
+export { canAuthenticateHuaweiCloudRequests, fetchHuaweiCloud, getHuaweiCloudAuthFromConfig, hasHuaweiCloudCredentialAuth, inferHuaweiCloudRegionFromEndpoint, resolveHuaweiCloudProjectId, } from "./cloud/auth.js";
+export { FlashbackNoViewError, formatTimestamp as formatFlashbackTimestamp, } from "./taurus/flashback.js";
+export { buildListRecycleBinSql, buildRestoreRecycleBinTableSql, RECYCLE_BIN_DATABASE, } from "./taurus/recycle-bin.js";
+export { createPlaceholderDiagnosticResult } from "./diagnostics/types.js";
+export { buildResolveSlowSqlInput, createSlowSqlSource, TaurusApiSlowSqlSource, } from "./diagnostics/slow-sql-source.js";
+export { CesMetricsSource, createMetricsSource, } from "./diagnostics/metrics-source.js";

package/dist/safety/confirmation-store.d.ts

@@ -0,0 +1,44 @@
+import type { SessionContext } from "../context/session-context.js";
+import type { RiskLevel, ValidationResult } from "./sql-validator.js";
+export type IssueInput = {
+    sqlHash: string;
+    normalizedSql: string;
+    context: SessionContext;
+    riskLevel: RiskLevel;
+    ttlSeconds?: number;
+};
+export type ConfirmationToken = {
+    token: string;
+    issuedAt: number;
+    expiresAt: number;
+};
+export type ConfirmationValidationResult = ValidationResult & {
+    valid: boolean;
+    reason?: string;
+};
+export interface ConfirmationStore {
+    issue(input: IssueInput): Promise<ConfirmationToken>;
+    validate(token: string, currentSql: string, ctx: SessionContext): Promise<ConfirmationValidationResult>;
+    revoke(token: string): Promise<void>;
+}
+export type ConfirmationStoreOptions = {
+    ttlSeconds?: number;
+    cleanupIntervalMs?: number;
+    now?: () => number;
+    randomBytesFn?: (size: number) => Buffer;
+};
+export declare class InMemoryConfirmationStore implements ConfirmationStore {
+    private readonly entries;
+    private readonly now;
+    private readonly ttlSeconds;
+    private readonly randomBytesFn;
+    private cleanupTimer?;
+    constructor(options?: ConfirmationStoreOptions);
+    issue(input: IssueInput): Promise<ConfirmationToken>;
+    validate(token: string, currentSql: string, ctx: SessionContext): Promise<ConfirmationValidationResult>;
+    revoke(token: string): Promise<void>;
+    stop(): void;
+    cleanupExpired(now?: number): void;
+    private generateUniqueToken;
+}
+export declare function createConfirmationStore(options?: ConfirmationStoreOptions): ConfirmationStore;

package/dist/safety/confirmation-store.js

@@ -0,0 +1,130 @@
+import { randomBytes } from "node:crypto";
+import { normalizeSql, sqlHash } from "../utils/hash.js";
+const DEFAULT_TTL_SECONDS = 300;
+const DEFAULT_CLEANUP_INTERVAL_MS = 60_000;
+const TOKEN_PREFIX = "ctok_";
+function allowResult() {
+    return {
+        valid: true,
+        action: "allow",
+        riskLevel: "low",
+        reasonCodes: [],
+        riskHints: [],
+    };
+}
+function blockResult(code, message) {
+    return {
+        valid: false,
+        action: "block",
+        riskLevel: "blocked",
+        reason: message,
+        reasonCodes: [code],
+        riskHints: [message],
+    };
+}
+function normalizeDatabase(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function parseTtlSeconds(ttlSeconds, fallback) {
+    const resolved = ttlSeconds ?? fallback;
+    if (!Number.isInteger(resolved) || resolved <= 0) {
+        throw new Error(`Invalid ttlSeconds: ${ttlSeconds}. It must be a positive integer.`);
+    }
+    return resolved;
+}
+export class InMemoryConfirmationStore {
+    entries = new Map();
+    now;
+    ttlSeconds;
+    randomBytesFn;
+    cleanupTimer;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.ttlSeconds = parseTtlSeconds(options.ttlSeconds, DEFAULT_TTL_SECONDS);
+        this.randomBytesFn = options.randomBytesFn ?? randomBytes;
+        const cleanupIntervalMs = options.cleanupIntervalMs ?? DEFAULT_CLEANUP_INTERVAL_MS;
+        if (cleanupIntervalMs > 0) {
+            this.cleanupTimer = setInterval(() => this.cleanupExpired(), cleanupIntervalMs);
+            this.cleanupTimer.unref();
+        }
+    }
+    async issue(input) {
+        this.cleanupExpired();
+        const ttlSeconds = parseTtlSeconds(input.ttlSeconds, this.ttlSeconds);
+        const issuedAt = this.now();
+        const expiresAt = issuedAt + ttlSeconds * 1000;
+        const token = this.generateUniqueToken();
+        this.entries.set(token, {
+            token,
+            sqlHash: input.sqlHash,
+            normalizedSql: input.normalizedSql,
+            datasource: input.context.datasource,
+            database: normalizeDatabase(input.context.database),
+            riskLevel: input.riskLevel,
+            issuedAt,
+            expiresAt,
+        });
+        return {
+            token,
+            issuedAt,
+            expiresAt,
+        };
+    }
+    async validate(token, currentSql, ctx) {
+        const entry = this.entries.get(token);
+        if (!entry) {
+            return blockResult("CF001", "Confirmation token not found.");
+        }
+        const now = this.now();
+        if (entry.expiresAt <= now) {
+            this.entries.delete(token);
+            return blockResult("CF002", "Confirmation token has expired.");
+        }
+        if (entry.usedAt !== undefined) {
+            return blockResult("CF005", "Confirmation token has already been used.");
+        }
+        const normalizedCurrentSql = normalizeSql(currentSql);
+        const currentSqlHash = sqlHash(normalizedCurrentSql);
+        if (currentSqlHash !== entry.sqlHash) {
+            return blockResult("CF003", "SQL hash mismatch for confirmation token.");
+        }
+        const currentDatabase = normalizeDatabase(ctx.database);
+        if (ctx.datasource !== entry.datasource || currentDatabase !== entry.database) {
+            return blockResult("CF004", "Datasource or database mismatch for confirmation token.");
+        }
+        entry.usedAt = now;
+        return allowResult();
+    }
+    async revoke(token) {
+        this.entries.delete(token);
+    }
+    stop() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+    cleanupExpired(now = this.now()) {
+        for (const [token, entry] of this.entries.entries()) {
+            if (entry.expiresAt <= now) {
+                this.entries.delete(token);
+            }
+        }
+    }
+    generateUniqueToken() {
+        for (let i = 0; i < 5; i += 1) {
+            const token = `${TOKEN_PREFIX}${this.randomBytesFn(32).toString("base64url")}`;
+            if (!this.entries.has(token)) {
+                return token;
+            }
+        }
+        throw new Error("Unable to generate unique confirmation token.");
+    }
+}
+export function createConfirmationStore(options = {}) {
+    return new InMemoryConfirmationStore(options);
+}

package/dist/safety/guardrail.d.ts

@@ -0,0 +1,39 @@
+import type { DatabaseEngine } from "../auth/sql-profile-loader.js";
+import type { SessionContext } from "../context/session-context.js";
+import { type SqlParser } from "./parser/index.js";
+import { type RiskLevel } from "./sql-validator.js";
+export interface GuardrailRuntimeLimits {
+    readonly: boolean;
+    timeoutMs: number;
+    maxRows: number;
+    maxColumns: number;
+    maxFieldChars: number;
+}
+export interface GuardrailDecision {
+    action: "allow" | "confirm" | "block";
+    riskLevel: RiskLevel;
+    reasonCodes: string[];
+    riskHints: string[];
+    normalizedSql: string;
+    sqlHash: string;
+    requiresExplain: boolean;
+    requiresConfirmation: boolean;
+    runtimeLimits: GuardrailRuntimeLimits;
+}
+export interface InspectInput {
+    toolName: string;
+    sql: string;
+    context: SessionContext;
+}
+export interface Guardrail {
+    inspect(input: InspectInput): Promise<GuardrailDecision>;
+}
+export type GuardrailOptions = {
+    parserFactory?: (engine: DatabaseEngine) => SqlParser;
+};
+export declare class GuardrailImpl implements Guardrail {
+    private readonly parserFactory;
+    constructor(options?: GuardrailOptions);
+    inspect(input: InspectInput): Promise<GuardrailDecision>;
+}
+export declare function createGuardrail(options?: GuardrailOptions): Guardrail;

package/dist/safety/guardrail.js

@@ -0,0 +1,99 @@
+import { createSqlParser } from "./parser/index.js";
+import { classifySql } from "./sql-classifier.js";
+import { validateStaticRules, validateToolScope, } from "./sql-validator.js";
+function dedupeCaseInsensitive(values) {
+    const output = [];
+    const seen = new Set();
+    for (const raw of values) {
+        const value = raw.trim();
+        if (!value) {
+            continue;
+        }
+        const key = value.toLowerCase();
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        output.push(value);
+    }
+    return output;
+}
+function pickHigherRisk(a, b) {
+    const order = {
+        low: 0,
+        medium: 1,
+        high: 2,
+        blocked: 3,
+    };
+    return order[b] > order[a] ? b : a;
+}
+function pickDominantAction(current, next) {
+    if (current === "block" || next === "block") {
+        return "block";
+    }
+    if (current === "confirm" || next === "confirm") {
+        return "confirm";
+    }
+    return "allow";
+}
+function buildBaseDecision(input, normalizedSql, sqlHash, action, riskLevel, reasonCodes, riskHints, requiresExplain) {
+    const readonlyByTool = input.toolName === "execute_readonly_sql" || input.toolName === "explain_sql";
+    const readonly = input.context.limits.readonly || readonlyByTool;
+    return {
+        action,
+        riskLevel,
+        reasonCodes: dedupeCaseInsensitive(reasonCodes),
+        riskHints: dedupeCaseInsensitive(riskHints),
+        normalizedSql,
+        sqlHash,
+        requiresExplain,
+        requiresConfirmation: action === "confirm",
+        runtimeLimits: {
+            readonly,
+            timeoutMs: input.context.limits.timeoutMs,
+            maxRows: input.context.limits.maxRows,
+            maxColumns: input.context.limits.maxColumns,
+            maxFieldChars: input.context.limits.maxFieldChars ?? 2048,
+        },
+    };
+}
+function mergeDecision(input, normalizedSql, sqlHash, validations, requiresExplain) {
+    let action = "allow";
+    let riskLevel = "low";
+    const reasonCodes = [];
+    const riskHints = [];
+    for (const validation of validations) {
+        action = pickDominantAction(action, validation.action);
+        riskLevel = pickHigherRisk(riskLevel, validation.riskLevel);
+        reasonCodes.push(...validation.reasonCodes);
+        riskHints.push(...validation.riskHints);
+    }
+    return buildBaseDecision(input, normalizedSql, sqlHash, action, riskLevel, reasonCodes, riskHints, requiresExplain);
+}
+export class GuardrailImpl {
+    parserFactory;
+    constructor(options = {}) {
+        this.parserFactory = options.parserFactory ?? ((engine) => createSqlParser(engine));
+    }
+    async inspect(input) {
+        const parser = this.parserFactory(input.context.engine);
+        const normalized = parser.normalize(input.sql);
+        const parseResult = parser.parse(normalized.normalizedSql);
+        if (!parseResult.ok) {
+            return buildBaseDecision(input, normalized.normalizedSql, normalized.sqlHash, "block", "blocked", ["G001"], [`SQL parse failed: ${parseResult.error.message}`], false);
+        }
+        const cls = classifySql(parseResult.ast, normalized, input.context.engine);
+        const d1 = validateToolScope(input.toolName, cls);
+        if (d1.action === "block") {
+            return mergeDecision(input, normalized.normalizedSql, normalized.sqlHash, [d1], false);
+        }
+        const d2 = validateStaticRules(cls);
+        if (d2.action === "block") {
+            return mergeDecision(input, normalized.normalizedSql, normalized.sqlHash, [d1, d2], false);
+        }
+        return mergeDecision(input, normalized.normalizedSql, normalized.sqlHash, [d1, d2], false);
+    }
+}
+export function createGuardrail(options = {}) {
+    return new GuardrailImpl(options);
+}

package/dist/safety/parser/adapter.d.ts

@@ -0,0 +1,10 @@
+import type { DatabaseEngine } from "../../auth/sql-profile-loader.js";
+import type { NormalizedSql, ParseResult, SqlParser } from "./types.js";
+export declare class NodeSqlParserAdapter implements SqlParser {
+    private readonly parser;
+    private readonly engine;
+    constructor(engine: DatabaseEngine);
+    normalize(sql: string): NormalizedSql;
+    parse(sql: string): ParseResult;
+}
+export declare function createSqlParser(engine: DatabaseEngine): SqlParser;

package/dist/safety/parser/adapter.js

@@ -0,0 +1,72 @@
+import nodeSqlParser from "node-sql-parser";
+import { normalizeSql, sqlHash } from "../../utils/hash.js";
+import { collectStructuredFeatures, scanAst } from "./features.js";
+import { isObject, mapStatementType, normalizeColumnList, normalizeTableList, toParseError } from "./ast-utils.js";
+const { Parser } = nodeSqlParser;
+export class NodeSqlParserAdapter {
+    parser;
+    engine;
+    constructor(engine) {
+        this.parser = new Parser();
+        this.engine = engine;
+    }
+    normalize(sql) {
+        const normalizedSql = normalizeSql(sql);
+        return {
+            normalizedSql,
+            sqlHash: sqlHash(normalizedSql),
+        };
+    }
+    parse(sql) {
+        try {
+            const rawAst = this.parser.astify(sql, { database: this.engine });
+            const astEntries = Array.isArray(rawAst) ? rawAst : [rawAst];
+            const statements = astEntries
+                .filter((entry) => isObject(entry))
+                .map((entry) => entry);
+            const isMultiStatement = statements.length > 1;
+            const statementKind = statements.length === 1 ? mapStatementType(statements[0].type) : "unknown";
+            const tableList = this.parser.tableList(sql, { database: this.engine });
+            const columnList = this.parser.columnList(sql, { database: this.engine });
+            const scan = scanAst(statements);
+            const structured = collectStructuredFeatures(statements);
+            const ast = {
+                kind: statementKind,
+                tables: normalizeTableList(tableList),
+                columns: normalizeColumnList(columnList),
+                hasAggregate: scan.hasAggregate,
+                hasSubquery: scan.hasSubquery,
+                isMultiStatement,
+            };
+            if (structured.where) {
+                ast.where = structured.where;
+            }
+            if (structured.limit) {
+                ast.limit = structured.limit;
+            }
+            if (structured.joins.length > 0) {
+                ast.joins = structured.joins;
+            }
+            if (structured.orderBy.length > 0) {
+                ast.orderBy = structured.orderBy;
+            }
+            if (structured.groupBy.length > 0) {
+                ast.groupBy = structured.groupBy;
+            }
+            return {
+                ok: true,
+                ast,
+                isMultiStatement,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: toParseError(error),
+            };
+        }
+    }
+}
+export function createSqlParser(engine) {
+    return new NodeSqlParserAdapter(engine);
+}

package/dist/safety/parser/ast-utils.d.ts

@@ -0,0 +1,10 @@
+import type { AstNode, ColumnRef, LimitNode, ParseError, StatementType, TableRef, WhereNode } from "./types.js";
+export declare function isObject(value: unknown): value is AstNode;
+export declare function mapStatementType(value: unknown): StatementType;
+export declare function normalizeTableList(tableList: string[]): TableRef[];
+export declare function normalizeColumnList(columnList: string[]): ColumnRef[];
+export declare function readNumericValue(value: unknown): number | undefined;
+export declare function toWhereNode(raw: unknown): WhereNode;
+export declare function toLimitNode(raw: unknown): LimitNode;
+export declare function getFunctionName(value: unknown): string | undefined;
+export declare function toParseError(error: unknown): ParseError;

package/dist/safety/parser/ast-utils.js

@@ -0,0 +1,167 @@
+export function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function mapStatementType(value) {
+    const type = typeof value === "string" ? value.toLowerCase() : "";
+    switch (type) {
+        case "select":
+            return "select";
+        case "show":
+            return "show";
+        case "explain":
+            return "explain";
+        case "desc":
+        case "describe":
+            return "describe";
+        case "insert":
+        case "replace":
+            return "insert";
+        case "update":
+            return "update";
+        case "delete":
+            return "delete";
+        case "alter":
+            return "alter";
+        case "drop":
+            return "drop";
+        case "create":
+            return "create";
+        case "grant":
+            return "grant";
+        case "revoke":
+            return "revoke";
+        case "truncate":
+            return "truncate";
+        case "set":
+            return "set";
+        case "use":
+            return "use";
+        default:
+            return "unknown";
+    }
+}
+export function normalizeTableList(tableList) {
+    const items = [];
+    const seen = new Set();
+    for (const entry of tableList) {
+        const parts = entry.split("::");
+        if (parts.length < 3) {
+            continue;
+        }
+        const schema = parts[1] && parts[1] !== "null" ? parts[1] : undefined;
+        const name = parts.slice(2).join("::").trim();
+        if (!name) {
+            continue;
+        }
+        const dedupeKey = `${schema ?? ""}.${name}`.toLowerCase();
+        if (seen.has(dedupeKey)) {
+            continue;
+        }
+        seen.add(dedupeKey);
+        items.push({ name, schema });
+    }
+    return items;
+}
+export function normalizeColumnList(columnList) {
+    const items = [];
+    const seen = new Set();
+    for (const entry of columnList) {
+        const parts = entry.split("::");
+        if (parts.length < 3) {
+            continue;
+        }
+        const table = parts[1] && parts[1] !== "null" ? parts[1] : undefined;
+        const name = parts.slice(2).join("::").trim();
+        if (!name) {
+            continue;
+        }
+        const dedupeKey = `${table ?? ""}.${name}`.toLowerCase();
+        if (seen.has(dedupeKey)) {
+            continue;
+        }
+        seen.add(dedupeKey);
+        items.push({ name, table });
+    }
+    return items;
+}
+export function readNumericValue(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+export function toWhereNode(raw) {
+    const type = isObject(raw) && typeof raw.type === "string" ? raw.type.toLowerCase() : "";
+    return {
+        kind: type === "binary_expr" ? "binary" : "expression",
+        raw,
+    };
+}
+export function toLimitNode(raw) {
+    if (!isObject(raw) || !Array.isArray(raw.value)) {
+        return { raw };
+    }
+    const values = raw.value
+        .map((entry) => {
+        if (!isObject(entry)) {
+            return undefined;
+        }
+        return readNumericValue(entry.value);
+    })
+        .filter((value) => value !== undefined);
+    const rowCount = values.length > 0 ? values[values.length - 1] : undefined;
+    const offset = values.length > 1 ? values[0] : undefined;
+    return {
+        raw,
+        rowCount,
+        offset,
+    };
+}
+export function getFunctionName(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const token = value
+            .map((entry) => {
+            if (typeof entry === "string") {
+                return entry;
+            }
+            if (isObject(entry) && typeof entry.value === "string") {
+                return entry.value;
+            }
+            return undefined;
+        })
+            .find((entry) => typeof entry === "string");
+        return token;
+    }
+    if (isObject(value)) {
+        if (typeof value.name === "string") {
+            return value.name;
+        }
+        return getFunctionName(value.name);
+    }
+    return undefined;
+}
+export function toParseError(error) {
+    const typed = error;
+    const message = typed instanceof Error ? typed.message : String(error);
+    const line = typed.location?.start?.line;
+    const column = typed.location?.start?.column;
+    return {
+        code: "SQL_PARSE_ERROR",
+        message,
+        position: typeof line === "number" && typeof column === "number"
+            ? {
+                line,
+                column,
+            }
+            : undefined,
+    };
+}

package/dist/safety/parser/features.d.ts

@@ -0,0 +1,12 @@
+import type { AstNode, GroupByNode, JoinNode, LimitNode, OrderByNode, WhereNode } from "./types.js";
+export declare function scanAst(statements: AstNode[]): {
+    hasAggregate: boolean;
+    hasSubquery: boolean;
+};
+export declare function collectStructuredFeatures(statements: AstNode[]): {
+    where?: WhereNode;
+    limit?: LimitNode;
+    joins: JoinNode[];
+    orderBy: OrderByNode[];
+    groupBy: GroupByNode[];
+};