frontend-guardian-core 2.6.0

package/dist/engine/rule-engine.js

@@ -0,0 +1,716 @@
+"use strict";
+/**
+ * RuleEngine — 可插拔规则引擎核心
+ *
+ * 设计目标：
+ * 1. 支持注册/注销规则（插件化）
+ * 2. 按 severity 过滤
+ * 3. 按 framework/platform/componentLib 条件执行
+ * 4. 并行扫描多文件
+ * 5. 支持增量扫描（git diff）
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuleEngine = void 0;
+exports.createEngine = createEngine;
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const node_readline_1 = require("node:readline");
+const node_path_1 = require("node:path");
+const ast_parser_js_1 = require("../utils/ast-parser.js");
+const project_detector_js_1 = require("../utils/project-detector.js");
+const config_loader_js_1 = require("../utils/config-loader.js");
+const registry_js_1 = require("../rules/registry.js");
+const globby_1 = require("globby");
+const picocolors_1 = __importDefault(require("picocolors"));
+const index_js_1 = require("../integrations/index.js");
+const cache_js_1 = require("./cache.js");
+const history_report_js_1 = require("../utils/history-report.js");
+const formatter_js_1 = require("../integrations/formatter.js");
+const concurrent_js_1 = require("../utils/concurrent.js");
+class RuleEngine {
+    registry;
+    config = {};
+    projectMeta;
+    options;
+    cache;
+    history;
+    constructor(options) {
+        this.options = options;
+        this.config = (0, config_loader_js_1.loadConfig)(options.projectDir, options.configFile);
+        this.projectMeta = (0, project_detector_js_1.detectProjectMeta)(options.projectDir, this.config);
+        this.registry = (0, registry_js_1.createRegistry)();
+        // Phase 3: 从配置加载规则覆盖和自定义规则
+        this.loadConfigRules();
+        // Phase 5: 初始化智能缓存
+        if (options.cache !== false) {
+            this.cache = options.cacheInstance ?? new cache_js_1.SmartCache(options.projectDir, options.cacheTtl);
+        }
+        // Phase 6: 初始化历史报告
+        this.history = new history_report_js_1.HistoryReport(options.projectDir);
+    }
+    /** ── Phase 3: 配置驱动规则加载 ── */
+    loadConfigRules() {
+        // 1. 加载规则配置覆盖（启用/禁用/severity/params）
+        if (this.config.rules && this.config.rules.length > 0) {
+            this.registry.loadFromConfig(this.config.rules);
+        }
+        // 2. 加载自定义规则文件
+        if (this.config.customRules && this.config.customRules.length > 0) {
+            const paths = this.config.customRules.map((c) => c.path);
+            const result = this.registry.loadCustomRules(paths, this.options.projectDir);
+            if (result.loaded.length > 0) {
+                console.log(picocolors_1.default.blue(`🔌 已加载 ${result.loaded.length} 个自定义规则`));
+            }
+            if (result.failed.length > 0) {
+                console.log(picocolors_1.default.yellow(`⚠️  ${result.failed.length} 个自定义规则加载失败`));
+            }
+        }
+    }
+    /** 注册规则 */
+    register(rule) {
+        this.registry.register(rule);
+        return this;
+    }
+    /** 批量注册 */
+    registerAll(rules) {
+        this.registry.registerAll(rules);
+        return this;
+    }
+    /** 注销规则 */
+    unregister(ruleId) {
+        this.registry.unregister(ruleId);
+        return this;
+    }
+    /** 获取所有已注册规则（应用配置覆盖后） */
+    getRules() {
+        return this.registry.getActiveRules();
+    }
+    /** 根据条件过滤规则 */
+    filterRules(options) {
+        return this.registry.filterRules(options);
+    }
+    /** 模块名到规则 category 的映射 */
+    moduleToCategory(module) {
+        const map = {
+            a11y: "accessibility",
+            naming: "style",
+            "cross-file": "architecture",
+        };
+        return map[module] || module;
+    }
+    /** 执行扫描 */
+    async scan(module) {
+        const startTime = Date.now();
+        const issues = {
+            critical: [],
+            warning: [],
+            suggestion: [],
+        };
+        // 先根据 projectMeta 过滤规则，无匹配规则则跳过 glob
+        const category = this.moduleToCategory(module);
+        const activeRules = this.filterRules({
+            category,
+            framework: this.projectMeta.framework,
+            platform: this.projectMeta.platforms[0],
+            componentLib: this.projectMeta.componentLib,
+        });
+        if (activeRules.length === 0) {
+            return {
+                module,
+                total: 0,
+                issues,
+                duration: 0,
+                filesScanned: 0,
+                filesWithIssues: 0,
+            };
+        }
+        // 获取扫描文件列表
+        const files = await this.getScanFiles();
+        let filesWithIssues = 0;
+        console.log(picocolors_1.default.blue(`🔍 [${module}] 扫描 ${files.length} 个文件，${activeRules.length} 条规则...`));
+        // v2.1.0: 受控并发并行扫描
+        const concurrency = this.options.concurrency ?? (0, concurrent_js_1.getDefaultConcurrency)();
+        const fileResults = await (0, concurrent_js_1.concurrentMap)(files, concurrency, (file) => this.scanFile(file, activeRules));
+        let filesSkipped = 0;
+        for (const { issues: fileIssues, skipped } of fileResults) {
+            if (skipped) {
+                filesSkipped++;
+                continue;
+            }
+            if (fileIssues.length > 0) {
+                filesWithIssues++;
+                for (const issue of fileIssues) {
+                    // severity 过滤
+                    const severityOrder = { critical: 3, warning: 2, suggestion: 1 };
+                    const minSev = this.options.minSeverity || "suggestion";
+                    if (severityOrder[issue.severity] >= severityOrder[minSev]) {
+                        issues[issue.severity].push(issue);
+                    }
+                }
+            }
+        }
+        const total = issues.critical.length + issues.warning.length + issues.suggestion.length;
+        const filesScanned = files.length - filesSkipped;
+        // Phase 5: 保存缓存并输出统计
+        if (this.cache) {
+            this.cache.save();
+            const stats = this.cache.getStats();
+            if (stats.total > 0) {
+                console.log(picocolors_1.default.gray(`   💾 缓存: ${stats.valid} 命中 / ${stats.expired} 过期 / ${stats.total} 总计`));
+            }
+        }
+        const result = {
+            module,
+            total,
+            issues,
+            duration: Date.now() - startTime,
+            filesScanned,
+            filesWithIssues,
+        };
+        // Phase 6: 记录扫描历史并输出趋势
+        const allIssues = [...issues.critical, ...issues.warning, ...issues.suggestion];
+        this.history.record(result, allIssues);
+        const trend = this.history.analyze(module, allIssues.map((i) => `${i.file}|${i.ruleId}|${i.line}`));
+        if (trend.totalScans > 1) {
+            if (trend.newIssues.length > 0) {
+                console.log(picocolors_1.default.yellow(`   📈 新增 ${trend.newIssues.length} 个问题（对比上次扫描）`));
+            }
+            if (trend.fixedIssues.length > 0) {
+                console.log(picocolors_1.default.green(`   ✅ 已修复 ${trend.fixedIssues.length} 个问题（对比上次扫描）`));
+            }
+        }
+        return result;
+    }
+    /** 扫描单个文件（带智能缓存 + 大文件跳过） */
+    async scanFile(filePath, rules) {
+        try {
+            // v2.4.0: 大文件智能跳过
+            const threshold = this.options.skipLargeFilesThreshold ?? 512_000;
+            if (threshold > 0) {
+                try {
+                    const stats = (0, node_fs_1.statSync)(filePath);
+                    if (stats.size > threshold) {
+                        console.log(picocolors_1.default.yellow(`   ⚠️ 跳过超大文件: ${filePath} (${(stats.size / 1024).toFixed(1)}KB > ${(threshold / 1024).toFixed(0)}KB)`));
+                        return { issues: [], skipped: true };
+                    }
+                }
+                catch {
+                    // stat 失败继续尝试读取
+                }
+            }
+            const source = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+            // Phase 5: 智能缓存命中检查
+            if (this.cache?.isCached(filePath, source)) {
+                const cached = this.cache.get(filePath);
+                if (cached) {
+                    return { issues: cached };
+                }
+            }
+            const allIssues = [];
+            const utils = this.createUtils(filePath, source);
+            const context = {
+                filePath,
+                source,
+                config: this.config,
+                projectMeta: this.projectMeta,
+                utils,
+                sharedCache: new Map(),
+            };
+            for (const rule of rules) {
+                try {
+                    const result = await rule.execute(context);
+                    // v2.4.0: 为每个 issue 注入 docsUrl
+                    for (const issue of result) {
+                        if (rule.docsUrl && !issue.docsUrl) {
+                            issue.docsUrl = rule.docsUrl;
+                        }
+                    }
+                    allIssues.push(...result);
+                }
+                catch (err) {
+                    console.error(picocolors_1.default.red(`  Rule "${rule.id}" failed on ${filePath}:`), err);
+                }
+            }
+            // Phase 5: 缓存结果
+            this.cache?.set(filePath, source, allIssues);
+            return { issues: allIssues };
+        }
+        catch (err) {
+            // 文件读取失败，静默跳过
+            return { issues: [] };
+        }
+    }
+    /** 获取扫描文件列表 */
+    async getScanFiles() {
+        // 增量扫描：git staged / diff 范围 / auto-scope
+        if (this.options.staged || this.options.diffRange || this.options.autoScope) {
+            const diffFiles = this.options.autoScope
+                ? this.getAutoScopeFiles()
+                : this.getDiffFiles();
+            if (diffFiles.length === 0) {
+                if (this.options.autoScope) {
+                    // auto-scope 无结果时回退到全量扫描
+                    console.log(picocolors_1.default.yellow("⚠️  未检测到修改文件，回退到全量扫描"));
+                }
+                return [];
+            }
+            // 过滤出符合扩展名的文件
+            const include = this.config.scan?.includeExtensions || [".js", ".ts", ".jsx", ".tsx", ".vue"];
+            const filtered = diffFiles.filter((f) => include.some((ext) => f.endsWith(ext)));
+            if (this.options.autoScope && filtered.length > 0) {
+                console.log(picocolors_1.default.cyan(`🔍 智能扫描范围: ${filtered.length} 个文件`));
+            }
+            return filtered;
+        }
+        if (this.options.files && this.options.files.length > 0) {
+            return this.options.files;
+        }
+        const include = this.config.scan?.includeExtensions || [".js", ".ts", ".jsx", ".tsx", ".vue"];
+        const exclude = [
+            "**/node_modules/**",
+            "**/dist/**",
+            "**/build/**",
+            "**/.git/**",
+            "**/coverage/**",
+            ...(this.options.exclude || []),
+            ...(this.config.scan?.excludeDirs?.map((d) => `**/${d}/**`) || []),
+        ];
+        const patterns = include.map((ext) => `**/*${ext}`);
+        return (0, globby_1.globby)(patterns, {
+            cwd: this.options.projectDir,
+            ignore: exclude,
+            absolute: true,
+        });
+    }
+    /** 通过 git 获取变更文件列表 */
+    getDiffFiles() {
+        try {
+            let cmd;
+            if (this.options.staged) {
+                cmd = "git diff --cached --name-only --diff-filter=ACM";
+            }
+            else if (this.options.diffRange) {
+                cmd = `git diff --name-only --diff-filter=ACM ${this.options.diffRange}`;
+            }
+            else {
+                return [];
+            }
+            const output = (0, node_child_process_1.execSync)(cmd, {
+                cwd: this.options.projectDir,
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "ignore"],
+            });
+            return output
+                .trim()
+                .split("\n")
+                .filter(Boolean)
+                .map((f) => (0, node_path_1.resolve)(this.options.projectDir, f));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** 智能推断扫描范围：未提交修改 → 最近 5 次提交 → 全量 */
+    getAutoScopeFiles() {
+        try {
+            const files = new Set();
+            // 1. 未提交的修改（unstaged + staged）
+            for (const cmd of [
+                "git diff --name-only --diff-filter=ACM",
+                "git diff --cached --name-only --diff-filter=ACM",
+            ]) {
+                try {
+                    const output = (0, node_child_process_1.execSync)(cmd, {
+                        cwd: this.options.projectDir,
+                        encoding: "utf-8",
+                        stdio: ["pipe", "pipe", "ignore"],
+                    });
+                    output
+                        .trim()
+                        .split("\n")
+                        .filter(Boolean)
+                        .forEach((f) => files.add((0, node_path_1.resolve)(this.options.projectDir, f)));
+                }
+                catch {
+                    // 忽略单条命令失败
+                }
+            }
+            // 2. 无未提交修改时，回退到最近 5 次提交
+            if (files.size === 0) {
+                try {
+                    const output = (0, node_child_process_1.execSync)("git diff --name-only --diff-filter=ACM HEAD~5...HEAD", {
+                        cwd: this.options.projectDir,
+                        encoding: "utf-8",
+                        stdio: ["pipe", "pipe", "ignore"],
+                    });
+                    output
+                        .trim()
+                        .split("\n")
+                        .filter(Boolean)
+                        .forEach((f) => files.add((0, node_path_1.resolve)(this.options.projectDir, f)));
+                }
+                catch {
+                    // 可能不足 5 次提交，忽略
+                }
+            }
+            return Array.from(files);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** 创建 RuleUtils */
+    createUtils(filePath, source) {
+        const lineOffsets = this.computeLineOffsets(source);
+        const cache = this.cache;
+        return {
+            // v2.1.0: parseAST 注入 AST 缓存，同一文件未变更时跳过重新解析
+            parseAST: (src, options) => {
+                if (cache && src === source) {
+                    const cached = cache.getAst(filePath, source);
+                    if (cached)
+                        return cached;
+                }
+                const ast = (0, ast_parser_js_1.parseAST)(src, options);
+                if (cache && ast && src === source) {
+                    cache.setAst(filePath, source, ast);
+                }
+                return ast;
+            },
+            getImports: (ast) => (0, ast_parser_js_1.getImports)(ast),
+            reportPosition: (offset) => {
+                let line = 1;
+                let column = 1;
+                for (let i = 0; i < lineOffsets.length; i++) {
+                    if (offset < lineOffsets[i]) {
+                        line = i;
+                        column = offset - (lineOffsets[i - 1] || 0) + 1;
+                        break;
+                    }
+                    if (i === lineOffsets.length - 1) {
+                        line = lineOffsets.length;
+                        column = offset - lineOffsets[i] + 1;
+                    }
+                }
+                return { line, column };
+            },
+            getSourceSnippet: (start, end) => {
+                return source.slice(start, end);
+            },
+        };
+    }
+    /** 计算每行起始偏移 */
+    computeLineOffsets(source) {
+        const offsets = [0];
+        for (let i = 0; i < source.length; i++) {
+            if (source[i] === "\n") {
+                offsets.push(i + 1);
+            }
+        }
+        return offsets;
+    }
+    // ---------------------------------------------------------------------------
+    // 自动修复
+    // ---------------------------------------------------------------------------
+    /**
+     * 应用所有可修复的问题
+     * @param issues 包含 fix 字段的 Issue 列表
+     * @returns 修复统计（dryRun 模式下 filesModified 为空，fixedCount 为预览数量）
+     */
+    applyFixes(issues) {
+        const dryRun = this.options.dryRun;
+        const interactive = this.options.interactive;
+        let fixedCount = 0;
+        let skippedByUser = 0;
+        const filesModified = [];
+        const errors = [];
+        const previews = [];
+        // 按文件分组
+        const byFile = new Map();
+        for (const issue of issues) {
+            if (!issue.fix)
+                continue;
+            const list = byFile.get(issue.file) || [];
+            list.push(issue);
+            byFile.set(issue.file, list);
+        }
+        for (const [filePath, fileIssues] of byFile) {
+            try {
+                let source = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+                const originalSource = source;
+                // 按行号倒序排列，从文件末尾开始修复，避免行号偏移
+                const sorted = [...fileIssues].sort((a, b) => {
+                    const lineDiff = (b.fix.start.line || 0) - (a.fix.start.line || 0);
+                    if (lineDiff !== 0)
+                        return lineDiff;
+                    return (b.fix.start.column || 0) - (a.fix.start.column || 0);
+                });
+                for (const issue of sorted) {
+                    const fix = issue.fix;
+                    const confidence = fix.confidence ?? "high";
+                    const patched = this.applySingleFix(source, fix);
+                    if (dryRun) {
+                        // 生成 diff 预览
+                        const diff = this.makeDiffPreview(source, patched, fix);
+                        previews.push({
+                            file: filePath,
+                            ruleId: issue.ruleId,
+                            title: issue.title,
+                            diff,
+                        });
+                        fixedCount++;
+                        source = patched;
+                        continue;
+                    }
+                    if (interactive) {
+                        // v2.4.0: 交互式修复模式 — 逐条确认
+                        const shouldApply = this.promptForFix(issue, confidence, source, patched);
+                        if (shouldApply) {
+                            const before = source;
+                            source = patched;
+                            if (source !== before) {
+                                fixedCount++;
+                            }
+                        }
+                        else {
+                            skippedByUser++;
+                        }
+                    }
+                    else {
+                        // 自动修复：低置信度自动跳过
+                        if (confidence === "low") {
+                            skippedByUser++;
+                            continue;
+                        }
+                        const before = source;
+                        source = patched;
+                        if (source !== before) {
+                            fixedCount++;
+                        }
+                    }
+                }
+                if (source !== originalSource) {
+                    if (!dryRun) {
+                        (0, node_fs_1.writeFileSync)(filePath, source, "utf-8");
+                    }
+                    filesModified.push(filePath);
+                }
+            }
+            catch (err) {
+                errors.push(`修复 ${filePath} 失败: ${err}`);
+            }
+        }
+        const result = { fixedCount, filesModified, errors, skippedByUser };
+        if (dryRun) {
+            result.previews = previews;
+        }
+        return result;
+    }
+    /**
+     * v2.4.0: 交互式修复 — 向用户展示 diff 并询问是否应用
+     * 同步阻塞式输入（基于 readline），适用于 CLI 场景
+     */
+    promptForFix(issue, confidence, original, patched) {
+        const diff = this.makeDiffPreview(original, patched, issue.fix);
+        const confidenceIcon = confidence === "high" ? picocolors_1.default.green("●") : confidence === "medium" ? picocolors_1.default.yellow("●") : picocolors_1.default.red("●");
+        const confidenceLabel = confidence === "high" ? "高置信度" : confidence === "medium" ? "中置信度" : "低置信度";
+        console.log(picocolors_1.default.cyan(`\n  📄 ${issue.file}:${issue.line}`));
+        console.log(picocolors_1.default.yellow(`     [${issue.ruleId}] ${issue.title}`));
+        console.log(picocolors_1.default.gray(`     置信度: ${confidenceIcon} ${confidenceLabel}`));
+        if (issue.fix?.description) {
+            console.log(picocolors_1.default.gray(`     说明: ${issue.fix.description}`));
+        }
+        console.log(diff);
+        console.log(picocolors_1.default.gray("     选项: [y] 应用  [n] 跳过  [a] 全部应用  [q] 退出"));
+        // 使用同步 readline 读取用户输入
+        const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stdout });
+        try {
+            // 简单同步读取（适用于 Node.js CLI）
+            const answer = this.readSyncLine(rl);
+            const trimmed = answer.trim().toLowerCase();
+            if (trimmed === "a") {
+                // 全部应用：关闭交互模式，后续自动应用
+                this.options.interactive = false;
+                return true;
+            }
+            if (trimmed === "q") {
+                console.log(picocolors_1.default.gray("     已退出交互式修复"));
+                process.exit(0);
+            }
+            return trimmed === "y" || trimmed === "yes" || trimmed === "";
+        }
+        finally {
+            rl.close();
+        }
+    }
+    /** 同步读取一行输入 */
+    readSyncLine(rl) {
+        const { stdin, stdout } = process;
+        stdin.setRawMode?.(true);
+        stdin.resume();
+        let result = "";
+        const buf = Buffer.alloc(1);
+        while (true) {
+            const bytesRead = stdin.readSync ? stdin.readSync(buf) : 0;
+            if (bytesRead === 0)
+                continue;
+            const char = buf.toString("utf8");
+            if (char === "\n" || char === "\r")
+                break;
+            if (char === "")
+                process.exit(0); // Ctrl+C
+            result += char;
+            stdout.write(char);
+        }
+        stdout.write("\n");
+        stdin.setRawMode?.(false);
+        stdin.pause();
+        return result;
+    }
+    /** 对单文件应用单个修复 */
+    applySingleFix(source, fix) {
+        const lines = source.split("\n");
+        const { line: startLine, column: startCol } = fix.start;
+        const { line: endLine, column: endCol } = fix.end;
+        // 单行修复
+        if (startLine === endLine) {
+            const idx = startLine - 1;
+            if (idx < 0 || idx >= lines.length)
+                return source;
+            const targetLine = lines[idx];
+            const before = targetLine.slice(0, Math.max(0, startCol - 1));
+            const after = targetLine.slice(Math.max(0, endCol - 1));
+            lines[idx] = before + fix.text + after;
+            return lines.join("\n");
+        }
+        // 多行修复：替换从 start 到 end 的所有内容
+        const startIdx = startLine - 1;
+        const endIdx = endLine - 1;
+        if (startIdx < 0 || endIdx >= lines.length)
+            return source;
+        const before = lines[startIdx].slice(0, Math.max(0, startCol - 1));
+        const after = lines[endIdx].slice(Math.max(0, endCol - 1));
+        const newLines = fix.text.split("\n");
+        // 合并首尾
+        newLines[0] = before + newLines[0];
+        newLines[newLines.length - 1] = newLines[newLines.length - 1] + after;
+        // 替换行范围
+        lines.splice(startIdx, endIdx - startIdx + 1, ...newLines);
+        return lines.join("\n");
+    }
+    /** 生成 diff 预览（dry-run 模式） */
+    makeDiffPreview(original, patched, fix) {
+        const origLines = original.split("\n");
+        const patchedLines = patched.split("\n");
+        const { line: startLine } = fix.start;
+        const { line: endLine } = fix.end;
+        // 展示变更前后的上下文（前后各2行）
+        const contextBefore = Math.max(0, startLine - 3);
+        const contextAfter = Math.min(origLines.length, endLine + 2);
+        const lines = [];
+        for (let i = contextBefore; i < contextAfter; i++) {
+            const orig = origLines[i] || "";
+            const patch = patchedLines[i] || "";
+            if (i >= startLine - 1 && i < endLine) {
+                lines.push(picocolors_1.default.red(`- ${orig}`));
+            }
+            if (i >= startLine - 1 && i < startLine - 1 + fix.text.split("\n").length) {
+                const patchLines = patch.split("\n");
+                const idx = i - (startLine - 1);
+                if (patchLines[idx]) {
+                    lines.push(picocolors_1.default.green(`+ ${patchLines[idx]}`));
+                }
+            }
+            if (i < startLine - 1 || i >= endLine) {
+                lines.push(picocolors_1.default.gray(`  ${orig}`));
+            }
+        }
+        return lines.join("\n");
+    }
+    /** 清理过期缓存 */
+    gcCache() {
+        return this.cache?.gc() ?? 0;
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Phase 5/6: 代码格式化（对被扫描项目）
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * 格式化被扫描项目的代码
+     * 自动检测 Biome / Prettier，使用项目已有配置或生成默认配置
+     * @param files 指定文件列表（undefined 则格式化全部）
+     */
+    format(files) {
+        return (0, formatter_js_1.runFormat)(this.options.projectDir, files);
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Issue 聚类 (Phase 2: 智能化)
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * 将相似 Issue 聚类为聚合 Issue
+     * 按 (file, ruleId) 分组，同一文件同一规则的多个 Issue 合并为一个
+     */
+    clusterIssues(issues) {
+        const groups = new Map();
+        for (const issue of issues) {
+            const key = `${issue.file}|${issue.ruleId}`;
+            const list = groups.get(key) || [];
+            list.push(issue);
+            groups.set(key, list);
+        }
+        const clustered = [];
+        for (const [, groupIssues] of groups) {
+            if (groupIssues.length === 1) {
+                clustered.push(groupIssues[0]);
+                continue;
+            }
+            // 按行号排序，取第一个作为代表
+            const sorted = [...groupIssues].sort((a, b) => a.line - b.line || a.column - b.column);
+            const representative = sorted[0];
+            const allLines = sorted.map((i) => i.line);
+            clustered.push({
+                ...representative,
+                title: `${representative.title} (×${groupIssues.length})`,
+                description: `${representative.description}\n\n聚类详情：在 ${groupIssues.length} 处发现同类问题（行: ${allLines.join(", ")}）`,
+                meta: {
+                    ...representative.meta,
+                    clusterCount: groupIssues.length,
+                    clusteredLines: allLines,
+                    clusteredRuleId: representative.ruleId,
+                },
+            });
+        }
+        return clustered;
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Phase 4: 外部工具集成 (ESLint / TypeScript / Stylelint)
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * 运行外部工具集成检查
+     * 自动检测项目中可用的工具（ESLint / TypeScript / Stylelint）并执行
+     */
+    runExternal(tools) {
+        const targetTools = tools || this.getDefaultExternalTools();
+        if (targetTools.length === 0) {
+            return [];
+        }
+        console.log(picocolors_1.default.cyan("🔌 运行外部工具集成..."));
+        // 获取当前扫描文件列表（用于增量模式）
+        const scanFiles = this.options.staged || this.options.diffRange ? this.getDiffFiles() : undefined;
+        return (0, index_js_1.runAllExternalTools)(this.options.projectDir, targetTools, scanFiles);
+    }
+    /** 获取默认的外部工具列表 */
+    getDefaultExternalTools() {
+        // 动态导入避免循环依赖
+        const { allExternalTools } = require("../integrations/index.js");
+        return allExternalTools;
+    }
+}
+exports.RuleEngine = RuleEngine;
+/** 创建默认引擎实例 */
+function createEngine(options) {
+    return new RuleEngine(options);
+}
+//# sourceMappingURL=rule-engine.js.map