@sofagent/rules 1.3.7 → 1.3.9

package/dist/ast/types.d.ts

@@ -0,0 +1,81 @@
+/** 规则严重级别（与审计规则集对齐） */
+export type AstSeverity = 'FAIL' | 'WARN';
+/** 扫描输入——单个待检文件 */
+export interface AstScanInput {
+    /** 原始文件路径（用于报告定位） */
+    path: string;
+    /** 文件内容（完整内容或 diff 重建内容） */
+    content: string;
+}
+/** 扫描产出——单条规则命中 */
+export interface AstFinding {
+    /** 命中的规则 ID */
+    ruleId: string;
+    /** 文件路径 */
+    file: string;
+    /** 行号（1-based） */
+    line: number;
+    /** 违规描述 */
+    message: string;
+    /** 严重级别 */
+    severity: AstSeverity;
+}
+/** AST 规则的检查上下文——引擎对每个文件调用一次 */
+export interface AstRuleContext {
+    /** 文件原始路径 */
+    path: string;
+    /** 临时文件里的语法树根节点（duck-typed TS RemoteSourceFile） */
+    sourceFile: AstNodeHost;
+    /** 文件全文 */
+    text: string;
+    /** SyntaxKind 名字→数字（如 kind('CallExpression')；未加载 TS 时返回 -1 恒不匹配） */
+    kind(name: string): number;
+    /** 上报一条命中（node 提供 位置信息） */
+    report(node: AstNodeHost, message: string): void;
+    /** 上报一条命中（无节点，直接给行号） */
+    reportLine(line: number, message: string): void;
+}
+/** 文本规则的检查上下文——引擎对每个文件调用一次 */
+export interface AstTextRuleContext {
+    /** 文件原始路径 */
+    path: string;
+    /** 文件全文 */
+    text: string;
+    /** 上报一条命中 */
+    report(line: number, message: string): void;
+}
+/**
+ * TS 语法树节点（duck-typing 最小面）。
+ * TypeScript 7 原生端 RemoteNode 的结构：kind 为数字，
+ * 子属性（expression/arguments 等）按需惰性解码。
+ */
+export interface AstNodeHost {
+    /** 节点种类（数字，经 SyntaxKind 映射取名） */
+    readonly kind: number;
+    /** 标识符/字面量文本（Token 类节点有） */
+    readonly text?: string;
+    /** 语句列表（SourceFile 有） */
+    readonly statements?: readonly AstNodeHost[];
+    /** 遍历直接子节点 */
+    forEachChild(cb: (child: AstNodeHost) => void): void;
+    /** 节点起始位置（不含前导 trivia） */
+    getStart(): number;
+}
+/** 一条 AST 规则的声明 */
+export interface AstRule {
+    /** 规则唯一 ID */
+    id: string;
+    /** 规则显示名 */
+    name: string;
+    /** 严重级别 */
+    severity: AstSeverity;
+    /** 规则说明（写进规则集 JSON） */
+    description: string;
+    /** 适用文件 glob（简化后缀匹配，如 .ts/.js/.md） */
+    filePattern?: RegExp;
+    /** AST 检查钩子（TS/JS 文件） */
+    checkCode?(ctx: AstRuleContext): void;
+    /** 文本检查钩子（markdown/清单文件） */
+    checkText?(ctx: AstTextRuleContext): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/ast/types.js

@@ -0,0 +1,12 @@
+"use strict";
+// ============================================================
+// types.ts · AST 规则引擎类型定义
+// v1.3.9（一）：官方 AST 规则引擎参考实现（sofagent-ruleset-ast）
+//
+// 设计原则：
+// - 规则与引擎解耦——规则只声明 check 钩子，遍历由引擎统一驱动
+// - 两种规则形态：AST 规则（解析 TS/JS 语法树）+ 文本规则（markdown/清单类文件）
+// - 与 v1.2.9 插件接口同构——plugin-adapter 把 PluginContext 转成本包的扫描入参
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/ast/walk.d.ts

@@ -0,0 +1,14 @@
+import type { AstNodeHost, AstRuleContext } from './types';
+/** 深度优先遍历（先序）：visit 返回 false 时剪枝不再下钻 */
+export declare function walk(node: AstNodeHost, visit: (n: AstNodeHost) => boolean | void): void;
+/** 判节点类型：ctx.kind(name) === node.kind */
+export declare function is(ctx: AstRuleContext, node: AstNodeHost | undefined | null, kindName: string): boolean;
+/** 取标识符/字面量文本（Token 节点的 .text 属性） */
+export declare function nodeText(node: AstNodeHost | undefined | null): string | undefined;
+/**
+ * 收集本文件 import 绑定：{ 导入名: 来源模块 }。
+ * 供规则做「符号来自哪个模块」的语法级判断（不需要 checker 语义层）。
+ * 支持：import { x } from 'm' / import * as x from 'm' / import x from 'm'
+ */
+export declare function collectImports(ctx: AstRuleContext): Map<string, string>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/ast/walk.js

@@ -0,0 +1,69 @@
+"use strict";
+// ============================================================
+// walk.ts · 语法树遍历工具
+// v1.3.9（一）：深度优先遍历 + 判型/取文本工具——规则层共用
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.walk = walk;
+exports.is = is;
+exports.nodeText = nodeText;
+exports.collectImports = collectImports;
+/** 深度优先遍历（先序）：visit 返回 false 时剪枝不再下钻 */
+function walk(node, visit) {
+    const keepGoing = visit(node);
+    if (keepGoing === false)
+        return;
+    node.forEachChild((child) => walk(child, visit));
+}
+/** 判节点类型：ctx.kind(name) === node.kind */
+function is(ctx, node, kindName) {
+    return !!node && node.kind === ctx.kind(kindName);
+}
+/** 取标识符/字面量文本（Token 节点的 .text 属性） */
+function nodeText(node) {
+    return node?.text;
+}
+/**
+ * 收集本文件 import 绑定：{ 导入名: 来源模块 }。
+ * 供规则做「符号来自哪个模块」的语法级判断（不需要 checker 语义层）。
+ * 支持：import { x } from 'm' / import * as x from 'm' / import x from 'm'
+ */
+function collectImports(ctx) {
+    const bindings = new Map();
+    const stmts = ctx.sourceFile.statements ?? [];
+    for (const stmt of stmts) {
+        if (!is(ctx, stmt, 'ImportDeclaration'))
+            continue;
+        const moduleSpecifier = nodeText(stmt.moduleSpecifier);
+        if (!moduleSpecifier)
+            continue;
+        const clause = stmt.importClause;
+        if (!clause)
+            continue;
+        // namedBindings：NamedImports { x } / NamespaceImport * as x
+        const named = clause.namedBindings;
+        if (named) {
+            if (is(ctx, named, 'NamespaceImport')) {
+                const name = nodeText(named.name);
+                if (name)
+                    bindings.set(name, moduleSpecifier);
+            }
+            else if (is(ctx, named, 'NamedImports')) {
+                const elements = named.elements ?? [];
+                for (const el of elements) {
+                    // ImportSpecifier：name 是导入名，propertyName 是本地别名（反向）
+                    const imported = nodeText(el.propertyName)
+                        ?? nodeText(el.name);
+                    if (imported)
+                        bindings.set(imported, moduleSpecifier);
+                }
+            }
+        }
+        // default import
+        const def = nodeText(clause.name);
+        if (def)
+            bindings.set(def, moduleSpecifier);
+    }
+    return bindings;
+}
+//# sourceMappingURL=walk.js.map

package/dist/engine.js

@@ -1,7 +1,7 @@
 "use strict";
 // ============================================================
 // engine.ts · RulesEngine 纯函数入口
-// v1.3.7：P3 编排引擎内嵌——规则引擎核心
+// v1.3.9：P3 编排引擎内嵌——规则引擎核心
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RulesEngine = void 0;

package/dist/index.d.ts

@@ -5,4 +5,10 @@ export { shouldAllow } from './should-allow';
 export type { ShouldAllowResult } from './should-allow';
 export { shouldApprove } from './approval-mode';
 export type { ApprovalMode, ApprovalResult } from './approval-mode';
+export { AstRuleEngine } from './ast/engine';
+export type { AstEngineOptions } from './ast/engine';
+export { builtinAstRules, astRuleById } from './ast/rules';
+export { buildSbom } from './ast/rules/asi04-sbom';
+export type { SbomEntry } from './ast/rules/asi04-sbom';
+export type { AstRule, AstFinding, AstScanInput } from './ast/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,18 +1,32 @@
 "use strict";
+// ── API 分级契约（v1.3.9 四）────────────────────────────
+// `/* @public */`：公开 API——semver 锁定，变更必须 bump 版本 + CHANGELOG 记录
+//                 （外部依赖方与跨平台适配器只许 import 这一层）
+// `/* @internal */`：内部 API——不承诺稳定性，破坏性变更无需 bump
+// 未标记的导出视为 @public（保守默认：宁可多承诺不可漏承诺）
+// ────────────────────────────────────────────────────────
 // ============================================================
 // index.ts · @sofagent/rules barrel export
-// v1.3.7：只导出 5 个公开符号，内部实现不外露
+// v1.3.9：只导出 5 个公开符号，内部实现不外露
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.shouldApprove = exports.shouldAllow = exports.defaultToolRules = exports.RulesEngine = void 0;
-var engine_1 = require("./engine");
+exports.buildSbom = exports.astRuleById = exports.builtinAstRules = exports.AstRuleEngine = exports.shouldApprove = exports.shouldAllow = exports.defaultToolRules = exports.RulesEngine = void 0;
+/* @public */ var engine_1 = require("./engine");
 Object.defineProperty(exports, "RulesEngine", { enumerable: true, get: function () { return engine_1.RulesEngine; } });
-var rules_1 = require("./rules");
+/* @public */ var rules_1 = require("./rules");
 Object.defineProperty(exports, "defaultToolRules", { enumerable: true, get: function () { return rules_1.defaultToolRules; } });
 // v1.3.7 (交付 2)：tool-gate 便捷判定 API
-var should_allow_1 = require("./should-allow");
+/* @public */ var should_allow_1 = require("./should-allow");
 Object.defineProperty(exports, "shouldAllow", { enumerable: true, get: function () { return should_allow_1.shouldAllow; } });
 // v1.3.2 (交付 10)：工具审批四模式
-var approval_mode_1 = require("./approval-mode");
+/* @public */ var approval_mode_1 = require("./approval-mode");
 Object.defineProperty(exports, "shouldApprove", { enumerable: true, get: function () { return approval_mode_1.shouldApprove; } });
+// v1.3.9（一）：官方 AST 规则引擎（sofagent-ruleset-ast）——@public 公开面
+/* @public */ var engine_2 = require("./ast/engine");
+Object.defineProperty(exports, "AstRuleEngine", { enumerable: true, get: function () { return engine_2.AstRuleEngine; } });
+/* @public */ var rules_2 = require("./ast/rules");
+Object.defineProperty(exports, "builtinAstRules", { enumerable: true, get: function () { return rules_2.builtinAstRules; } });
+Object.defineProperty(exports, "astRuleById", { enumerable: true, get: function () { return rules_2.astRuleById; } });
+/* @public */ var asi04_sbom_1 = require("./ast/rules/asi04-sbom");
+Object.defineProperty(exports, "buildSbom", { enumerable: true, get: function () { return asi04_sbom_1.buildSbom; } });
 //# sourceMappingURL=index.js.map

package/dist/rules/index.js

@@ -1,7 +1,7 @@
 "use strict";
 // ============================================================
 // rules/index.ts · 默认规则注册表
-// v1.3.7：P3 编排引擎内嵌——默认 tool 规则集合
+// v1.3.9：P3 编排引擎内嵌——默认 tool 规则集合
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultToolRules = void 0;

package/dist/rules/tool-injection.js

@@ -1,7 +1,7 @@
 "use strict";
 // ============================================================
 // tool-injection.ts · 移植 audit rule-a9（prompt injection 检测）
-// v1.3.7：tool 视角——扫 args 里的 prompt injection 模式
+// v1.3.9：tool 视角——扫 args 里的 prompt injection 模式
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toolInjection = void 0;

package/dist/rules/tool-secret-leak.js

@@ -1,8 +1,8 @@
 "use strict";
 // ============================================================
 // tool-secret-leak.ts · 移植 audit rule-a2（密钥泄漏检测）
-// v1.3.7：tool 视角——扫 args 字面量里的密钥模式
-// v1.3.7 SECRET_PATTERNS 抽到 @sofagent/core 共享——此前本文件用严格
+// v1.3.9：tool 视角——扫 args 字面量里的密钥模式
+// v1.3.9 SECRET_PATTERNS 抽到 @sofagent/core 共享——此前本文件用严格
 //   48 位 sk- 模式导致 32-47 位密钥被 ToolGate 放行（与 A2 漂移互补成洞）。
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/rules/tool-sensitive-file.js

@@ -1,7 +1,7 @@
 "use strict";
 // ============================================================
 // tool-sensitive-file.ts · 移植 audit rule-a1（敏感文件保护）
-// v1.3.7：tool 视角——校验 args 里的文件路径
+// v1.3.9：tool 视角——校验 args 里的文件路径
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toolSensitiveFile = void 0;

package/dist/types.js

@@ -1,7 +1,7 @@
 "use strict";
 // ============================================================
 // types.ts · P3 编排引擎内嵌——tool call 拦截器类型定义
-// v1.3.7：从 audit 规则抽出为纯函数，零 fs/git 依赖
+// v1.3.9：从 audit 规则抽出为纯函数，零 fs/git 依赖
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@sofagent/rules",
-  "version": "1.3.7",
-  "description": "sofagent 规则引擎纯函数包——从 audit 抽出，零 fs/git 依赖，供编排引擎 tool call 事前拦截",
+  "version": "1.3.9",
+  "description": "sofagent 规则引擎包——从 audit 抽出，零 git 依赖，供编排引擎 tool call 事前拦截；v1.3.9 起含官方 AST 规则引擎（sofagent-ruleset-ast，经临时文件驱动 TS 编译器，无仓库 fs 依赖）",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./ast": {
+      "types": "./dist/ast/plugin-adapter.d.ts",
+      "default": "./dist/ast/plugin-adapter.js"
+    }
+  },
   "scripts": {
     "build": "npm run clean && tsc",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -12,12 +22,13 @@
   "keywords": [
     "rules-engine",
     "agent-safety",
-    "tool-interceptor"
+    "tool-interceptor",
+    "ast"
   ],
   "author": "孔放勋",
   "license": "MIT",
   "devDependencies": {
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.10"
   },
   "files": [
@@ -28,6 +39,14 @@
     "README.md"
   ],
   "dependencies": {
-    "@sofagent/core": "1.3.7"
+    "@sofagent/core": "1.3.9"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   }
 }