@lingxiao-office/sdk 1.0.0

package/dist/tools/implementations/ToolDiscoveryTool.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { Tool } from '../Tool.js';
+import { SESSION_KEYS } from '../../core/SessionStateKeys.js';
+import { isOfficeToolName } from '../officeToolContract.js';
+import { BUGHUNT_MODE_TOOL_NAMES } from '../../contracts/constants/toolNames.js';
+import { resolveModeRuntimeProjection } from '../../core/ModeRuntimeProjection.js';
+import { getToolPermissionContextFromToolContext } from '../../core/PermissionSystem.js';
+import { getTeamMemberRegistry } from '../../core/TeamMailbox.js';
+const FindToolsSchema = z.object({
+    query: z.string().optional().describe('按工具名、描述、分类、tier、schema 字段搜索'),
+    category: z.string().optional().describe('只返回指定 category，如 file/browser/office'),
+    tier: z.enum(['read', 'write', 'execute', 'compute']).optional().describe('只返回指定能力层级'),
+    include_schema: z.boolean().optional().default(false).describe('是否返回 JSON schema 和示例参数'),
+    limit: z.number().int().min(1).max(100).optional().default(20).describe('最多返回数量'),
+});
+function scoreTool(query, text, name) {
+    if (!query)
+        return 1;
+    const q = query.toLowerCase();
+    const haystack = text.toLowerCase();
+    let score = 0;
+    if (name.toLowerCase() === q)
+        score += 100;
+    if (name.toLowerCase().includes(q))
+        score += 50;
+    if (haystack.includes(q))
+        score += 20;
+    for (const token of q.split(/\s+/).filter(Boolean)) {
+        if (haystack.includes(token))
+            score += 5;
+    }
+    return score;
+}
+export class ToolDiscoveryTool extends Tool {
+    registry;
+    name = 'find_tools';
+    description = '发现当前可用工具：按名称/描述/category/tier/schema 搜索，返回元数据、风险和示例参数。先用它确认工具名，再调用 tool_preflight 或目标工具。';
+    parameters = FindToolsSchema;
+    constructor(registry) {
+        super();
+        this.registry = registry;
+    }
+    async execute(args, context) {
+        const params = args;
+        const query = (params.query || '').trim();
+        const officeMode = Boolean(context?.sessionId &&
+            context.db?.getSessionState(context.sessionId, SESSION_KEYS.OFFICE_MODE_ACTIVE) === 'true');
+        const bughuntMode = Boolean(context?.sessionId &&
+            context.db?.getSessionState(context.sessionId, SESSION_KEYS.BUGHUNT_MODE_ACTIVE) === 'true');
+        const workflowMode = Boolean(context?.sessionId &&
+            context.db?.getSessionState(context.sessionId, SESSION_KEYS.WORKFLOW_MODE_ACTIVE) === 'true');
+        const blackboardAvailable = Boolean(context?.blackboardGraph);
+        const scope = context?.agentId === 'leader' || context?.agentName === 'leader' || context?.leaderToolsExecutor
+            ? 'all'
+            : 'worker';
+        const modes = (() => {
+            if (!context?.sessionId || !context.db)
+                return undefined;
+            try {
+                return resolveModeRuntimeProjection({
+                    sessionId: context.sessionId,
+                    db: context.db,
+                    permissionContext: getToolPermissionContextFromToolContext(context),
+                    blackboardAvailable,
+                });
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        let callerInTeamRoster = scope === 'all';
+        let callerIsTeamLeader = scope === 'all';
+        if (scope !== 'all' && modes?.collaboration.teamEnabled && context?.agentName && context.sessionId) {
+            try {
+                const member = getTeamMemberRegistry().getByName(context.agentName, context.sessionId);
+                callerInTeamRoster = Boolean(member);
+                callerIsTeamLeader = member?.role === 'leader';
+            }
+            catch {
+                callerInTeamRoster = false;
+                callerIsTeamLeader = false;
+            }
+        }
+        const bughuntTools = new Set(BUGHUNT_MODE_TOOL_NAMES);
+        const all = this.registry.listToolInspections({
+            includeSchema: params.include_schema === true,
+            scope,
+            ...(modes
+                ? {
+                    modePolicy: {
+                        modes,
+                        actor: scope === 'all' ? 'leader' : callerInTeamRoster ? 'team_member' : 'worker',
+                        agentName: typeof context?.agentName === 'string' ? context.agentName : undefined,
+                        callerInTeamRoster,
+                        callerIsTeamLeader,
+                    },
+                }
+                : {}),
+        })
+            .filter((tool) => officeMode || !isOfficeToolName(tool.name))
+            .filter((tool) => bughuntMode || !bughuntTools.has(tool.name))
+            .filter((tool) => workflowMode || tool.name !== 'workflow')
+            .filter((tool) => blackboardAvailable || tool.name !== 'blackboard');
+        const ranked = all
+            .filter((tool) => !params.category || tool.metadata.category === params.category)
+            .filter((tool) => !params.tier || tool.metadata.tier === params.tier)
+            .map((tool) => {
+            const schemaText = params.include_schema && tool.schema ? JSON.stringify(tool.schema) : '';
+            const text = [tool.name, tool.description, tool.metadata.category, tool.metadata.tier, schemaText].join(' ');
+            return { tool, score: scoreTool(query, text, tool.name) };
+        })
+            .filter((item) => !query || item.score > 0)
+            .sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name))
+            .slice(0, params.limit ?? 20)
+            .map(({ tool }) => ({
+            name: tool.name,
+            description: tool.description,
+            loaded: tool.loaded,
+            deferred: tool.deferred,
+            metadata: tool.metadata,
+            schema: tool.schema,
+            example_args: tool.example_args,
+            next_tool_hints: ['tool_preflight', ...(tool.metadata.nextToolHints || [])],
+        }));
+        return {
+            success: true,
+            data: {
+                query,
+                mode: officeMode ? 'office' : bughuntMode ? 'bughunt' : workflowMode ? 'workflow' : 'normal',
+                mode_flags: { office: officeMode, bughunt: bughuntMode, workflow: workflowMode, blackboard: blackboardAvailable },
+                count: ranked.length,
+                tools: ranked,
+            },
+        };
+    }
+}
+export default ToolDiscoveryTool;
+//# sourceMappingURL=ToolDiscoveryTool.js.map

package/dist/tools/implementations/ToolDiscoveryTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolDiscoveryTool.js","sourceRoot":"","sources":["../../../src/tools/implementations/ToolDiscoveryTool.ts"],"names":[],"mappings":"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"}

package/dist/tools/implementations/ToolPreflightTool.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { Tool, type ToolContext, type ToolResult } from '../Tool.js';
+import type { ToolRegistry } from '../Registry.js';
+export declare class ToolPreflightTool extends Tool {
+    private readonly registry;
+    readonly name = "tool_preflight";
+    readonly description = "\u5DE5\u5177\u8C03\u7528\u9884\u68C0\uFF1A\u4E0D\u6267\u884C\u76EE\u6807\u5DE5\u5177\uFF0C\u53EA\u68C0\u67E5\u5DE5\u5177\u662F\u5426\u5B58\u5728\u3001\u53C2\u6570\u662F\u5426\u80FD\u89E3\u6790/\u901A\u8FC7 schema\u3001\u662F\u5426\u7F3A\u5C11\u5148\u8BFB\u6587\u4EF6\u7B49\u524D\u7F6E\u6761\u4EF6\uFF0C\u5E76\u7ED9\u51FA\u4E0B\u4E00\u6B65\u4FEE\u590D\u5EFA\u8BAE\u3002";
+    readonly parameters: z.ZodObject<{
+        tool: z.ZodString;
+        args: z.ZodOptional<z.ZodUnknown>;
+        include_schema: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$strip>;
+    constructor(registry: ToolRegistry);
+    execute(args: unknown, context?: ToolContext): Promise<ToolResult>;
+}
+export default ToolPreflightTool;
+//# sourceMappingURL=ToolPreflightTool.d.ts.map

package/dist/tools/implementations/ToolPreflightTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolPreflightTool.d.ts","sourceRoot":"","sources":["../../../src/tools/implementations/ToolPreflightTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAQnD,qBAAa,iBAAkB,SAAQ,IAAI;IAK7B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJrC,QAAQ,CAAC,IAAI,oBAAoB;IACjC,QAAQ,CAAC,WAAW,sXAA0E;IAC9F,QAAQ,CAAC,UAAU;;;;sBAAuB;gBAEb,QAAQ,EAAE,YAAY;IAI7C,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CAQzE;AAED,eAAe,iBAAiB,CAAC"}

package/dist/tools/implementations/ToolPreflightTool.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { Tool } from '../Tool.js';
+const ToolPreflightSchema = z.object({
+    tool: z.string().describe('要检查的工具名'),
+    args: z.unknown().optional().describe('准备传给工具的参数 object 或 JSON 字符串'),
+    include_schema: z.boolean().optional().default(true).describe('是否返回该工具 schema'),
+});
+export class ToolPreflightTool extends Tool {
+    registry;
+    name = 'tool_preflight';
+    description = '工具调用预检：不执行目标工具，只检查工具是否存在、参数是否能解析/通过 schema、是否缺少先读文件等前置条件，并给出下一步修复建议。';
+    parameters = ToolPreflightSchema;
+    constructor(registry) {
+        super();
+        this.registry = registry;
+    }
+    async execute(args, context) {
+        const params = args;
+        const result = this.registry.preflight(params.tool, params.args ?? {}, context);
+        if (params.include_schema === false) {
+            delete result.schema;
+        }
+        return { success: true, data: result };
+    }
+}
+export default ToolPreflightTool;
+//# sourceMappingURL=ToolPreflightTool.js.map

package/dist/tools/implementations/ToolPreflightTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolPreflightTool.js","sourceRoot":"","sources":["../../../src/tools/implementations/ToolPreflightTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,IAAI,EAAqC,MAAM,YAAY,CAAC;AAGrE,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IACpE,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC;CAChF,CAAC,CAAC;AAEH,MAAM,OAAO,iBAAkB,SAAQ,IAAI;IAKZ;IAJpB,IAAI,GAAG,gBAAgB,CAAC;IACxB,WAAW,GAAG,sEAAsE,CAAC;IACrF,UAAU,GAAG,mBAAmB,CAAC;IAE1C,YAA6B,QAAsB;QACjD,KAAK,EAAE,CAAC;QADmB,aAAQ,GAAR,QAAQ,CAAc;IAEnD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAa,EAAE,OAAqB;QAChD,MAAM,MAAM,GAAG,IAA2C,CAAC;QAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;QAChF,IAAI,MAAM,CAAC,cAAc,KAAK,KAAK,EAAE,CAAC;YACpC,OAAQ,MAA+B,CAAC,MAAM,CAAC;QACjD,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACzC,CAAC;CACF;AAED,eAAe,iBAAiB,CAAC"}

package/dist/tools/implementations/TreeSitterSecurityEngine.d.ts

@@ -0,0 +1,67 @@
+/**
+ * AstGrepSecurityEngine — 基于 @ast-grep/napi 的多语言 AST 安全扫描引擎
+ *
+ * 文件名保留为 TreeSitterSecurityEngine.ts 以兼容历史导入路径，
+ * 实现已迁移到 ast-grep（NAPI 预编译二进制，零编译），不再依赖 node-tree-sitter。
+ *
+ * 支持语言：JavaScript / TypeScript / Python / Go / Java / Rust / C / C++ / Ruby
+ * 能力：
+ *   - 内置 + 动态加载语言（@ast-grep/lang-*）
+ *   - 节点类型 + 文本正则规则匹配（OWASP Top 10 + CWE）
+ *   - 跨平台（Linux/macOS/Windows × x64/arm64，全部预编译，npm install 即用）
+ */
+import type { SupportedLanguage } from './rules/schema.js';
+import { type LoadedRulePack } from './rules/RuleLoader.js';
+export type { LanguageConfig, SecurityRule, SupportedLanguage } from './rules/schema.js';
+export interface AstScanFinding {
+    id: string;
+    severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'INFO';
+    cwe?: string;
+    owasp?: string;
+    rule: string;
+    title: string;
+    message: string;
+    file: string;
+    line: number;
+    column: number;
+    endLine?: number;
+    code: string;
+    language: string;
+    source: 'ast-grep';
+}
+export interface AstScanResult {
+    success: boolean;
+    tool: string;
+    languages: string[];
+    filesScanned: number;
+    findings: AstScanFinding[];
+    summary: string;
+    duration: number;
+    partial?: boolean;
+    filesSkipped?: number;
+    scanErrors?: Array<{
+        file?: string;
+        reason: string;
+    }>;
+    walkErrors?: Array<{
+        dir: string;
+        reason: string;
+    }>;
+}
+export declare class TreeSitterSecurityEngine {
+    /** 检测目录中使用的语言 */
+    detectLanguages(targetPath: string, pack?: LoadedRulePack): Promise<SupportedLanguage[]>;
+    /** 扫描目录 */
+    scan(targetPath: string, options?: {
+        languages?: SupportedLanguage[];
+        maxFiles?: number;
+        maxFileSize?: number;
+        rules?: string[];
+        rulePack?: LoadedRulePack;
+    }): Promise<AstScanResult>;
+    private scanWithRule;
+    private detectFileLanguage;
+    private walkFiles;
+}
+export declare const treeSitterEngine: TreeSitterSecurityEngine;
+//# sourceMappingURL=TreeSitterSecurityEngine.d.ts.map

package/dist/tools/implementations/TreeSitterSecurityEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeSitterSecurityEngine.d.ts","sourceRoot":"","sources":["../../../src/tools/implementations/TreeSitterSecurityEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAgC,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGzE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAqKzF,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAID,qBAAa,wBAAwB;IACnC,iBAAiB;IACX,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAA8B,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA2B7G,WAAW;IACL,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QACvC,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;QAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,QAAQ,CAAC,EAAE,cAAc,CAAC;KAC3B,GAAG,OAAO,CAAC,aAAa,CAAC;IAkG1B,OAAO,CAAC,YAAY;IA2DpB,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,SAAS;CAyBlB;AAED,eAAO,MAAM,gBAAgB,0BAAiC,CAAC"}

package/dist/tools/implementations/TreeSitterSecurityEngine.js

@@ -0,0 +1,355 @@
+/**
+ * AstGrepSecurityEngine — 基于 @ast-grep/napi 的多语言 AST 安全扫描引擎
+ *
+ * 文件名保留为 TreeSitterSecurityEngine.ts 以兼容历史导入路径，
+ * 实现已迁移到 ast-grep（NAPI 预编译二进制，零编译），不再依赖 node-tree-sitter。
+ *
+ * 支持语言：JavaScript / TypeScript / Python / Go / Java / Rust / C / C++ / Ruby
+ * 能力：
+ *   - 内置 + 动态加载语言（@ast-grep/lang-*）
+ *   - 节点类型 + 文本正则规则匹配（OWASP Top 10 + CWE）
+ *   - 跨平台（Linux/macOS/Windows × x64/arm64，全部预编译，npm install 即用）
+ */
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, extname, relative } from 'path';
+import { getRulePack } from './rules/RuleLoader.js';
+// ═══════════════════════════════════════════════════════════════════════════════
+// 语言注册
+// ═══════════════════════════════════════════════════════════════════════════════
+// SupportedLanguage / LanguageConfig 类型从 ./rules/schema.js 导入（见文件顶部）。
+// 语言配置（原 LANGUAGE_CONFIGS）已外部化到 rules/seed.ts，经 RuleLoader.getRulePack().languages
+// 注入；扩展名集合（原 LANGUAGE_EXTENSION_SETS）改为 LoadedRulePack.languageExtensionSets。
+const LANGUAGE_DETECT_SKIP_DIRS = new Set(['node_modules', 'vendor', 'target', 'dist', 'build']);
+const WALK_SKIP_DIRS = new Set([
+    'node_modules',
+    'vendor',
+    'target',
+    'dist',
+    'build',
+    '__pycache__',
+    '.git',
+    'venv',
+    'env',
+]);
+function shouldSkipLanguageDetectEntry(name) {
+    return name[0] === '.' || LANGUAGE_DETECT_SKIP_DIRS.has(name);
+}
+function shouldSkipWalkEntry(name) {
+    return name[0] === '.' || WALK_SKIP_DIRS.has(name);
+}
+// JSX/TSX 单独映射到 ast-grep 的内置 Tsx
+const EXT_OVERRIDE = {
+    '.tsx': { lang: 'typescript', agName: 'Tsx' },
+    '.jsx': { lang: 'javascript', agName: 'JavaScript' }, // ast-grep JavaScript 内置 jsx
+};
+let registered = false;
+let registerError = null;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function readDefaultExport(moduleValue) {
+    return isRecord(moduleValue) && 'default' in moduleValue ? moduleValue.default : moduleValue;
+}
+function isAstGrepApi(value) {
+    if (!isRecord(value) || typeof value.parse !== 'function')
+        return false;
+    return value.registerDynamicLanguage === undefined || typeof value.registerDynamicLanguage === 'function';
+}
+function isAstGrepRoot(value) {
+    return isRecord(value) && typeof value.root === 'function';
+}
+function isAstGrepNode(value) {
+    return (isRecord(value) &&
+        typeof value.findAll === 'function' &&
+        typeof value.range === 'function' &&
+        typeof value.text === 'function');
+}
+function readNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function readAstGrepPosition(value) {
+    if (!isRecord(value))
+        return null;
+    return {
+        line: readNumber(value.line) ?? readNumber(value.row) ?? 0,
+        column: readNumber(value.column) ?? 0,
+    };
+}
+function readAstGrepRange(value) {
+    if (!isRecord(value))
+        return null;
+    const start = readAstGrepPosition(value.start);
+    const end = readAstGrepPosition(value.end);
+    return start && end ? { start, end } : null;
+}
+async function importAstGrepApi() {
+    const moduleValue = await import('@ast-grep/napi').catch((error) => {
+        registerError = error instanceof Error ? error.message : String(error);
+        return null;
+    });
+    return isAstGrepApi(moduleValue) ? moduleValue : null;
+}
+/** 一次性动态注册非内置语言（ast-grep 内置仅 JavaScript/TypeScript/Tsx/Css/Html） */
+async function ensureLanguagesRegistered() {
+    if (registered)
+        return;
+    registered = true;
+    try {
+        const ag = await importAstGrepApi();
+        const dynamicLangs = {};
+        const tryRequire = async (key, mod) => {
+            try {
+                dynamicLangs[key] = readDefaultExport(await import(mod));
+            }
+            catch (e) {
+                // 单语言加载失败仅降级，整体仍可用其他语言
+            }
+        };
+        await Promise.all([
+            tryRequire('python', '@ast-grep/lang-python'),
+            tryRequire('go', '@ast-grep/lang-go'),
+            tryRequire('java', '@ast-grep/lang-java'),
+            tryRequire('rust', '@ast-grep/lang-rust'),
+            tryRequire('c', '@ast-grep/lang-c'),
+            tryRequire('cpp', '@ast-grep/lang-cpp'),
+            tryRequire('ruby', '@ast-grep/lang-ruby'),
+        ]);
+        if (ag && Object.keys(dynamicLangs).length > 0 && ag.registerDynamicLanguage) {
+            ag.registerDynamicLanguage(dynamicLangs);
+        }
+    }
+    catch (e) {
+        registerError = e instanceof Error ? e.message : String(e);
+    }
+}
+const MAX_FINDINGS = 300;
+export class TreeSitterSecurityEngine {
+    /** 检测目录中使用的语言 */
+    async detectLanguages(targetPath, pack = getRulePack()) {
+        await ensureLanguagesRegistered();
+        const detected = new Set();
+        const allExts = new Set();
+        const walk = (dir, depth = 0) => {
+            if (depth > 5)
+                return;
+            try {
+                for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                    if (shouldSkipLanguageDetectEntry(entry.name))
+                        continue;
+                    if (entry.isDirectory())
+                        walk(join(dir, entry.name), depth + 1);
+                    else
+                        allExts.add(extname(entry.name).toLowerCase());
+                }
+            }
+            catch { /* expected: best-effort cleanup */ }
+        };
+        walk(targetPath);
+        for (const [lang, config] of Object.entries(pack.languages)) {
+            if (config.extensions.some(ext => allExts.has(ext))) {
+                detected.add(lang);
+            }
+        }
+        if (allExts.has('.tsx'))
+            detected.add('typescript');
+        if (allExts.has('.jsx'))
+            detected.add('javascript');
+        return [...detected];
+    }
+    /** 扫描目录 */
+    async scan(targetPath, options) {
+        await ensureLanguagesRegistered();
+        const pack = options?.rulePack ?? getRulePack();
+        const startTime = Date.now();
+        const maxFiles = options?.maxFiles ?? 500;
+        const maxFileSize = options?.maxFileSize ?? 500_000;
+        const scanErrors = [];
+        const walkErrors = [];
+        const ag = await importAstGrepApi();
+        if (!ag) {
+            return {
+                success: false,
+                tool: 'ast-grep',
+                languages: [],
+                filesScanned: 0,
+                findings: [],
+                summary: `ast-grep 不可用${registerError ? `: ${registerError}` : ''}`,
+                duration: Date.now() - startTime,
+            };
+        }
+        const languages = options?.languages ?? await this.detectLanguages(targetPath, pack);
+        if (languages.length === 0) {
+            return { success: true, tool: 'ast-grep', languages: [], filesScanned: 0, findings: [], summary: '未检测到支持的语言', duration: 0 };
+        }
+        const wantedExts = new Set();
+        for (const l of languages)
+            for (const e of pack.languages[l].extensions)
+                wantedExts.add(e);
+        const selectedLanguages = new Set(languages);
+        if (selectedLanguages.has('typescript'))
+            wantedExts.add('.tsx');
+        if (selectedLanguages.has('javascript'))
+            wantedExts.add('.jsx');
+        const files = this.walkFiles(targetPath, [...wantedExts], maxFiles, walkErrors);
+        const findings = [];
+        const allowedRuleIds = options?.rules ? new Set(options.rules) : null;
+        for (const file of files) {
+            if (findings.length >= MAX_FINDINGS)
+                break;
+            try {
+                const content = readFileSync(file, 'utf-8');
+                if (content.length > maxFileSize)
+                    continue;
+                const ext = extname(file).toLowerCase();
+                const override = EXT_OVERRIDE[ext];
+                const lang = override?.lang ?? this.detectFileLanguage(file, pack.languageExtensionSets);
+                if (!lang)
+                    continue;
+                const agName = override?.agName ?? pack.languages[lang].agName;
+                let root;
+                try {
+                    const parsed = ag.parse(agName, content);
+                    if (!isAstGrepRoot(parsed)) {
+                        throw new Error('ast-grep parse result is missing root()');
+                    }
+                    const parsedRoot = parsed.root();
+                    if (!isAstGrepNode(parsedRoot)) {
+                        throw new Error('ast-grep root node is missing expected methods');
+                    }
+                    root = parsedRoot;
+                }
+                catch (error) {
+                    scanErrors.push({ file: relative(targetPath, file), reason: `parse failed: ${error instanceof Error ? error.message : String(error)}` });
+                    continue;
+                }
+                const applicableRules = pack.rules.filter(r => (pack.ruleLanguageSets.get(r.id)?.has(lang) ?? false) && (!allowedRuleIds || allowedRuleIds.has(r.id)));
+                for (const rule of applicableRules) {
+                    if (findings.length >= MAX_FINDINGS)
+                        break;
+                    this.scanWithRule(root, rule, file, targetPath, lang, findings);
+                }
+            }
+            catch (error) {
+                scanErrors.push({ file: relative(targetPath, file), reason: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        const duration = Date.now() - startTime;
+        const highCritical = findings.filter(f => f.severity === 'HIGH' || f.severity === 'CRITICAL').length;
+        const partial = scanErrors.length > 0 || walkErrors.length > 0;
+        const errorSuffix = partial ? `，部分失败: scanErrors=${scanErrors.length}, walkErrors=${walkErrors.length}` : '';
+        return {
+            success: true,
+            tool: 'ast-grep',
+            languages,
+            filesScanned: files.length,
+            findings,
+            summary: `ast-grep AST 扫描完成: ${files.length} 文件, ${languages.length} 种语言 (${languages.join('/')}), ${findings.length} 个安全问题 (${highCritical} 高危), 耗时 ${duration}ms${errorSuffix}`,
+            duration,
+            partial,
+            filesSkipped: scanErrors.length,
+            scanErrors: scanErrors.slice(0, 50),
+            walkErrors: walkErrors.slice(0, 50),
+        };
+    }
+    scanWithRule(root, rule, file, basePath, lang, findings) {
+        // 通过 ast-grep 的 kind 选择器一次拿到所有候选节点，再用正则做精确判断
+        const candidates = [];
+        for (const kind of rule.nodeKinds) {
+            try {
+                // findAll(kind: string) 等价于 findAll({ rule: { kind } })
+                const list = root.findAll({ rule: { kind } });
+                if (Array.isArray(list))
+                    candidates.push(...list.filter(isAstGrepNode));
+            }
+            catch {
+                // 该 kind 在当前语言不存在 → 忽略
+            }
+        }
+        if (candidates.length === 0)
+            return;
+        for (const node of candidates) {
+            if (findings.length >= MAX_FINDINGS)
+                return;
+            let text;
+            try {
+                text = node.text();
+            }
+            catch { /* expected: skip invalid entry */
+                continue;
+            }
+            if (!text)
+                continue;
+            const patternHit = rule.patterns.some(p => { p.lastIndex = 0; return p.test(text); });
+            if (!patternHit)
+                continue;
+            if (rule.contextPatterns && rule.contextPatterns.length > 0) {
+                const allCtx = rule.contextPatterns.every(p => { p.lastIndex = 0; return p.test(text); });
+                if (!allCtx)
+                    continue;
+            }
+            let range = null;
+            try {
+                range = readAstGrepRange(node.range());
+            }
+            catch { /* expected: best-effort cleanup */ }
+            findings.push({
+                id: `${rule.id}-${findings.length + 1}`,
+                severity: rule.severity,
+                cwe: rule.cwe,
+                owasp: rule.owasp,
+                rule: rule.id,
+                title: rule.title,
+                message: rule.description,
+                file: relative(basePath, file),
+                line: (range?.start.line ?? 0) + 1,
+                column: (range?.start.column ?? 0) + 1,
+                endLine: range ? range.end.line + 1 : undefined,
+                code: text.slice(0, 200),
+                language: lang,
+                source: 'ast-grep',
+            });
+        }
+    }
+    detectFileLanguage(file, languageExtensionSets) {
+        const ext = extname(file).toLowerCase();
+        for (const [lang, exts] of languageExtensionSets) {
+            if (exts.has(ext))
+                return lang;
+        }
+        return null;
+    }
+    walkFiles(dir, exts, maxFiles, walkErrors) {
+        const results = [];
+        const extSet = new Set(exts);
+        const walk = (d, depth = 0) => {
+            if (results.length >= maxFiles || depth > 8)
+                return;
+            try {
+                for (const entry of readdirSync(d, { withFileTypes: true })) {
+                    if (results.length >= maxFiles)
+                        return;
+                    const name = entry.name;
+                    if (shouldSkipWalkEntry(name))
+                        continue;
+                    const full = join(d, name);
+                    if (entry.isDirectory())
+                        walk(full, depth + 1);
+                    else if (extSet.has(extname(name).toLowerCase())) {
+                        try {
+                            if (statSync(full).size < 500_000)
+                                results.push(full);
+                        }
+                        catch { /* expected: best-effort cleanup */ }
+                    }
+                }
+            }
+            catch (error) {
+                walkErrors?.push({ dir: d, reason: error instanceof Error ? error.message : String(error) });
+            }
+        };
+        walk(dir);
+        return results;
+    }
+}
+export const treeSitterEngine = new TreeSitterSecurityEngine();
+//# sourceMappingURL=TreeSitterSecurityEngine.js.map