@agile-team/mach-report 2.0.0 → 2.2.0

package/dist/sql.d.cts

@@ -1,5 +1,109 @@
-/**
- * 动态 SQL 子路径入口（@agile-team/mach-report/sql）：
- * 动态 SQL 编译、参数化渲染与 AST/词法双层单 SELECT 校验。
- */
-export * from './sql/index';
+/**
+ * 单 SELECT 结构校验（词法层；AST 级校验见 ast-check.ts 双保险）：
+ * - 去注释后必须以 select 或 with 开头
+ * - 语句内除末尾外不允许出现分号
+ * - 顶层禁止 DML/DDL/调用关键字（字符串字面量内容不参与匹配）
+ */
+export declare function assertSingleSelect(sql: string): void;
+
+/**
+ * AST 深度校验（双保险策略）：
+ * 1. node-sql-parser（MySQL 方言，支持 ? 占位符）AST 顶层必须为 SELECT/集合运算
+ * 2. AST 通过后再叠加词法校验（MySQL 方言把 SELECT INTO 解析为别名，AST 层不可见，
+ *    由词法层兜底拦截）
+ * AST 解析失败（方言不兼容）自动降级为纯词法校验，返回 degraded=true。
+ */
+export declare function assertSingleSelectAst(sql: string): AstCheckResult;
+
+export declare interface AstCheckResult {
+    ok: boolean;
+    /** ast 深度校验是否执行（方言不支持时降级词法） */
+    degraded: boolean;
+    message?: string;
+}
+
+export declare interface CompiledSql {
+    original: string;
+    /** 参数名集合（bind 与 subst 并集） */
+    paramNames: string[];
+    render(params: Record<string, unknown>): RenderedSql;
+}
+
+export declare function compileDynamicSql(source: string): CompiledSql;
+
+/**
+ * 求值动态 SQL 条件表达式（用于 {if(cond, a, b)} 的 cond 与操作数）：
+ * - #param 引用（渲染时被替换为参数值；此实现按值求值）
+ * - "..." 字符串字面量（仅双引号）
+ * - isEmpty(x)、isNotEmpty(x)
+ * - == / != 比较
+ * - + 拼接
+ */
+export declare function evalExpr(input: string, ctx: ExprContext): unknown;
+
+export declare interface ExprContext {
+    params: Record<string, unknown>;
+}
+
+export declare class ExprError extends Error {
+    constructor(message: string);
+}
+
+/** {if(cond, whenTrue, whenFalse)} 的参数拆分（2 或 3 段） */
+export declare function parseIfArgs(inner: string): {
+    cond: string;
+    whenTrue: string;
+    whenFalse: string;
+};
+
+/** 便捷入口：编译 + 渲染 + 校验一体 */
+export declare function renderDynamicSql(source: string, params: Record<string, unknown>): RenderedSql;
+
+export declare interface RenderedSql {
+    sql: string;
+    binds: unknown[];
+    warnings: string[];
+}
+
+/** 按顶层逗号拆分（忽略双引号内与括号/花括号内） */
+export declare function splitTopLevel(input: string): string[];
+
+export declare class SqlSyntaxError extends Error {
+    readonly position: number;
+    readonly source: string;
+    constructor(message: string, position: number, source: string);
+}
+
+export declare class SqlValidationError extends Error {
+    readonly sql: string;
+    constructor(message: string, sql: string);
+}
+
+/**
+ * 去注释：-- 行注释、# 行注释（仅行首/空白后，且排除 #{ 绑定占位）、/* 块注释。
+ * 注意：此函数用于校验口径，输出会折叠空白。
+ */
+export declare function stripSqlComments(sql: string): string;
+
+export declare interface Token {
+    type: TokenType;
+    text: string;
+    /** bind/subst 参数名；if 表达式源码 */
+    value?: string;
+    start: number;
+    end: number;
+}
+
+/**
+ * 扫描动态 SQL，产出 token 流：
+ * - literal: 纯 SQL 文本（已反转义 \{ \}）
+ * - bind:    #{name}
+ * - subst:   ${name}
+ * - if:      {if(expr, a, b)} —— value 为去壳后的参数串
+ * - escape:  \{ 或 \}
+ */
+export declare function tokenize(sql: string): Token[];
+
+export declare type TokenType = "literal" | "bind" | "subst" | "if" | "escape";
+
+export { }

package/dist/sql.d.ts

@@ -1,5 +1,109 @@
-/**
- * 动态 SQL 子路径入口（@agile-team/mach-report/sql）：
- * 动态 SQL 编译、参数化渲染与 AST/词法双层单 SELECT 校验。
- */
-export * from './sql/index';
+/**
+ * 单 SELECT 结构校验（词法层；AST 级校验见 ast-check.ts 双保险）：
+ * - 去注释后必须以 select 或 with 开头
+ * - 语句内除末尾外不允许出现分号
+ * - 顶层禁止 DML/DDL/调用关键字（字符串字面量内容不参与匹配）
+ */
+export declare function assertSingleSelect(sql: string): void;
+
+/**
+ * AST 深度校验（双保险策略）：
+ * 1. node-sql-parser（MySQL 方言，支持 ? 占位符）AST 顶层必须为 SELECT/集合运算
+ * 2. AST 通过后再叠加词法校验（MySQL 方言把 SELECT INTO 解析为别名，AST 层不可见，
+ *    由词法层兜底拦截）
+ * AST 解析失败（方言不兼容）自动降级为纯词法校验，返回 degraded=true。
+ */
+export declare function assertSingleSelectAst(sql: string): AstCheckResult;
+
+export declare interface AstCheckResult {
+    ok: boolean;
+    /** ast 深度校验是否执行（方言不支持时降级词法） */
+    degraded: boolean;
+    message?: string;
+}
+
+export declare interface CompiledSql {
+    original: string;
+    /** 参数名集合（bind 与 subst 并集） */
+    paramNames: string[];
+    render(params: Record<string, unknown>): RenderedSql;
+}
+
+export declare function compileDynamicSql(source: string): CompiledSql;
+
+/**
+ * 求值动态 SQL 条件表达式（用于 {if(cond, a, b)} 的 cond 与操作数）：
+ * - #param 引用（渲染时被替换为参数值；此实现按值求值）
+ * - "..." 字符串字面量（仅双引号）
+ * - isEmpty(x)、isNotEmpty(x)
+ * - == / != 比较
+ * - + 拼接
+ */
+export declare function evalExpr(input: string, ctx: ExprContext): unknown;
+
+export declare interface ExprContext {
+    params: Record<string, unknown>;
+}
+
+export declare class ExprError extends Error {
+    constructor(message: string);
+}
+
+/** {if(cond, whenTrue, whenFalse)} 的参数拆分（2 或 3 段） */
+export declare function parseIfArgs(inner: string): {
+    cond: string;
+    whenTrue: string;
+    whenFalse: string;
+};
+
+/** 便捷入口：编译 + 渲染 + 校验一体 */
+export declare function renderDynamicSql(source: string, params: Record<string, unknown>): RenderedSql;
+
+export declare interface RenderedSql {
+    sql: string;
+    binds: unknown[];
+    warnings: string[];
+}
+
+/** 按顶层逗号拆分（忽略双引号内与括号/花括号内） */
+export declare function splitTopLevel(input: string): string[];
+
+export declare class SqlSyntaxError extends Error {
+    readonly position: number;
+    readonly source: string;
+    constructor(message: string, position: number, source: string);
+}
+
+export declare class SqlValidationError extends Error {
+    readonly sql: string;
+    constructor(message: string, sql: string);
+}
+
+/**
+ * 去注释：-- 行注释、# 行注释（仅行首/空白后，且排除 #{ 绑定占位）、/* 块注释。
+ * 注意：此函数用于校验口径，输出会折叠空白。
+ */
+export declare function stripSqlComments(sql: string): string;
+
+export declare interface Token {
+    type: TokenType;
+    text: string;
+    /** bind/subst 参数名；if 表达式源码 */
+    value?: string;
+    start: number;
+    end: number;
+}
+
+/**
+ * 扫描动态 SQL，产出 token 流：
+ * - literal: 纯 SQL 文本（已反转义 \{ \}）
+ * - bind:    #{name}
+ * - subst:   ${name}
+ * - if:      {if(expr, a, b)} —— value 为去壳后的参数串
+ * - escape:  \{ 或 \}
+ */
+export declare function tokenize(sql: string): Token[];
+
+export declare type TokenType = "literal" | "bind" | "subst" | "if" | "escape";
+
+export { }