frontend-guardian-core 2.6.0

package/bin/watch-mode.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Watch Mode — 文件变更自动增量扫描
+ *
+ * Usage: fg-core <project-dir> --watch [--module <name>]
+ */
+
+import { watch } from "node:fs";
+import { statSync, existsSync } from "node:fs";
+import { resolve, relative } from "node:path";
+import pc from "picocolors";
+
+/**
+ * 启动 watch 模式
+ * @param {Object} options - CLI 选项
+ * @param {Function} scanFn - 扫描函数 (options, cacheInstance) => Promise<void>
+ * @param {Object} cacheInstance - SmartCache 实例（可选，用于复用缓存）
+ */
+export async function runWatchMode(options, scanFn, cacheInstance) {
+    const projectDir = options.projectDir;
+    const includeExts = new Set([".js", ".ts", ".jsx", ".tsx", ".vue", ".svelte", ".css", ".scss", ".less"]);
+
+    console.log(pc.cyan("👀 Watch 模式已启动"));
+    console.log(pc.gray(`   项目: ${projectDir}`));
+    console.log(pc.gray(`   模块: ${options.module}`));
+    if (cacheInstance && options.cache !== false) {
+        console.log(pc.gray("   缓存: 已启用（Watch 模式复用）"));
+    }
+    console.log(pc.gray("   按 Ctrl+C 退出\n"));
+
+    // 防抖：200ms 内多次变更只扫描一次
+    let debounceTimer = null;
+    const changedFiles = new Set();
+
+    // 首次扫描（复用 cacheInstance）
+    await scanFn({ ...options, watch: false }, cacheInstance);
+    console.log(pc.gray("\n⏳ 等待文件变更...\n"));
+
+    function handleChange(filePath) {
+        const ext = filePath.slice(filePath.lastIndexOf("."));
+        if (!includeExts.has(ext)) return;
+        if (filePath.includes("node_modules")) return;
+        if (filePath.includes(".git")) return;
+
+        changedFiles.add(filePath);
+
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+        }
+
+        debounceTimer = setTimeout(async () => {
+            const files = Array.from(changedFiles);
+            changedFiles.clear();
+
+            console.clear();
+            console.log(pc.cyan(`📝 检测到 ${files.length} 个文件变更`));
+            for (const f of files) {
+                console.log(pc.gray(`   - ${relative(projectDir, f)}`));
+            }
+            console.log("");
+
+            const watchOptions = {
+                ...options,
+                files,
+                watch: false,
+            };
+
+            try {
+                await scanFn(watchOptions, cacheInstance);
+            } catch (err) {
+                console.error(pc.red("扫描失败:"), err.message || err);
+            }
+
+            console.log(pc.gray("\n⏳ 等待文件变更...\n"));
+        }, 300);
+    }
+
+    // 递归监听 src 目录和配置文件
+    const watchDirs = [resolve(projectDir, "src")];
+    if (!existsSync(watchDirs[0])) {
+        watchDirs[0] = projectDir;
+    }
+
+    const watchers = [];
+
+    function addWatcher(dir) {
+        try {
+            const watcher = watch(dir, { recursive: true }, (eventType, filename) => {
+                if (!filename) return;
+                const fullPath = resolve(dir, filename);
+                if (!existsSync(fullPath)) return;
+                try {
+                    const stat = statSync(fullPath);
+                    if (stat.isDirectory()) return;
+                } catch {
+                    return;
+                }
+                handleChange(fullPath);
+            });
+            watchers.push(watcher);
+        } catch {
+            // 某些环境不支持递归 watch
+        }
+    }
+
+    for (const dir of watchDirs) {
+        if (existsSync(dir)) {
+            addWatcher(dir);
+        }
+    }
+
+    // 保持进程运行
+    process.on("SIGINT", () => {
+        console.log(pc.gray("\n👋 Watch 模式已停止"));
+        for (const w of watchers) {
+            w.close();
+        }
+        process.exit(0);
+    });
+
+    // 永不 resolve，保持运行
+    return new Promise(() => {});
+}

package/dist/engine/cache.d.ts

@@ -0,0 +1,68 @@
+/**
+ * SmartCache — 智能增量扫描缓存引擎
+ *
+ * 设计目标：
+ * 1. 基于文件内容 SHA-256 哈希，只扫描变更文件
+ * 2. 缓存持久化到 .frontend-guardian/cache.json
+ * 3. 自动过期策略（默认 7 天）
+ * 4. 兼容 --staged / --diff 增量模式
+ */
+import type { Issue } from "../types.js";
+export interface CacheEntry {
+    /** 文件内容 SHA-256 */
+    hash: string;
+    /** 扫描结果 */
+    issues: Issue[];
+    /** 缓存时间戳 */
+    timestamp: number;
+    /** 规则版本（规则变更时缓存失效） */
+    ruleVersion: string;
+}
+export interface CacheManifest {
+    /** 引擎版本 */
+    version: string;
+    /** 项目目录 */
+    projectDir: string;
+    /** 文件到缓存条目的映射 */
+    entries: Record<string, CacheEntry>;
+    /** 上次全量扫描时间 */
+    lastFullScan: number;
+}
+export declare class SmartCache {
+    private manifest;
+    private cacheDir;
+    private cacheFile;
+    private ttl;
+    /** v2.1.0: 内存级 AST 缓存（无需持久化，进程内复用） */
+    private astCache;
+    constructor(projectDir: string, ttl?: number);
+    /** 计算文件内容哈希 */
+    static computeHash(content: string): string;
+    /** 检查文件是否已缓存且未过期 */
+    isCached(filePath: string, content: string): boolean;
+    /** 从缓存获取文件扫描结果 */
+    get(filePath: string): Issue[] | undefined;
+    /** 缓存文件扫描结果 */
+    set(filePath: string, content: string, issues: Issue[]): void;
+    /** 删除缓存条目 */
+    invalidate(filePath: string): void;
+    /** 批量使缓存失效（glob 模式） */
+    invalidatePattern(pattern: string): void;
+    /** 保存缓存到磁盘 */
+    save(): void;
+    /** 获取缓存统计 */
+    getStats(): {
+        total: number;
+        valid: number;
+        expired: number;
+    };
+    /** 获取缓存的 AST（内存级，不持久化） */
+    getAst(filePath: string, content: string): unknown | undefined;
+    /** 缓存 AST 解析结果 */
+    setAst(filePath: string, content: string, ast: unknown): void;
+    /** 清理过期缓存 */
+    gc(): number;
+    /** 加载缓存 manifest */
+    private loadManifest;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/engine/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/engine/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,WAAW,UAAU;IACvB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC1B,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACpC,eAAe;IACf,YAAY,EAAE,MAAM,CAAC;CACxB;AAOD,qBAAa,UAAU;IACnB,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,GAAG,CAAS;IACpB,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAqD;gBAEzD,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,MAAoB;IAOzD,eAAe;IACf,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI3C,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAkBpD,kBAAkB;IAClB,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,SAAS;IAK1C,eAAe;IACf,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI;IAS7D,aAAa;IACb,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIlC,uBAAuB;IACvB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IASxC,cAAc;IACd,IAAI,IAAI,IAAI;IAWZ,aAAa;IACb,QAAQ,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAkB7D,0BAA0B;IAC1B,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAW9D,kBAAkB;IAClB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI;IAO7D,aAAa;IACb,EAAE,IAAI,MAAM;IAcZ,oBAAoB;IACpB,OAAO,CAAC,YAAY;CAoBvB"}

package/dist/engine/cache.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * SmartCache — 智能增量扫描缓存引擎
+ *
+ * 设计目标：
+ * 1. 基于文件内容 SHA-256 哈希，只扫描变更文件
+ * 2. 缓存持久化到 .frontend-guardian/cache.json
+ * 3. 自动过期策略（默认 7 天）
+ * 4. 兼容 --staged / --diff 增量模式
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SmartCache = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** 缓存默认存活时间（7 天） */
+const DEFAULT_TTL = 7 * 24 * 60 * 60 * 1000;
+/** 引擎版本，规则变更时递增使缓存失效 */
+const ENGINE_VERSION = "2.0.0";
+class SmartCache {
+    manifest;
+    cacheDir;
+    cacheFile;
+    ttl;
+    /** v2.1.0: 内存级 AST 缓存（无需持久化，进程内复用） */
+    astCache = new Map();
+    constructor(projectDir, ttl = DEFAULT_TTL) {
+        this.cacheDir = (0, node_path_1.resolve)(projectDir, ".frontend-guardian");
+        this.cacheFile = (0, node_path_1.resolve)(this.cacheDir, "cache.json");
+        this.ttl = ttl;
+        this.manifest = this.loadManifest();
+    }
+    /** 计算文件内容哈希 */
+    static computeHash(content) {
+        return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex").slice(0, 16);
+    }
+    /** 检查文件是否已缓存且未过期 */
+    isCached(filePath, content) {
+        const entry = this.manifest.entries[filePath];
+        if (!entry)
+            return false;
+        // 内容变更
+        const hash = SmartCache.computeHash(content);
+        if (entry.hash !== hash)
+            return false;
+        // 规则版本变更
+        if (entry.ruleVersion !== ENGINE_VERSION)
+            return false;
+        // 缓存过期
+        const now = Date.now();
+        if (now - entry.timestamp > this.ttl)
+            return false;
+        return true;
+    }
+    /** 从缓存获取文件扫描结果 */
+    get(filePath) {
+        const entry = this.manifest.entries[filePath];
+        return entry?.issues;
+    }
+    /** 缓存文件扫描结果 */
+    set(filePath, content, issues) {
+        this.manifest.entries[filePath] = {
+            hash: SmartCache.computeHash(content),
+            issues,
+            timestamp: Date.now(),
+            ruleVersion: ENGINE_VERSION,
+        };
+    }
+    /** 删除缓存条目 */
+    invalidate(filePath) {
+        delete this.manifest.entries[filePath];
+    }
+    /** 批量使缓存失效（glob 模式） */
+    invalidatePattern(pattern) {
+        const regex = new RegExp(pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*"));
+        for (const key of Object.keys(this.manifest.entries)) {
+            if (regex.test(key)) {
+                delete this.manifest.entries[key];
+            }
+        }
+    }
+    /** 保存缓存到磁盘 */
+    save() {
+        try {
+            if (!(0, node_fs_1.existsSync)(this.cacheDir)) {
+                (0, node_fs_1.mkdirSync)(this.cacheDir, { recursive: true });
+            }
+            (0, node_fs_1.writeFileSync)(this.cacheFile, JSON.stringify(this.manifest, null, 2), "utf-8");
+        }
+        catch {
+            // 缓存写入失败静默处理
+        }
+    }
+    /** 获取缓存统计 */
+    getStats() {
+        const now = Date.now();
+        let valid = 0;
+        let expired = 0;
+        for (const entry of Object.values(this.manifest.entries)) {
+            if (now - entry.timestamp > this.ttl || entry.ruleVersion !== ENGINE_VERSION) {
+                expired++;
+            }
+            else {
+                valid++;
+            }
+        }
+        return { total: Object.keys(this.manifest.entries).length, valid, expired };
+    }
+    // ── v2.1.0: AST 内存缓存 ──────────────────────────────────────────────
+    /** 获取缓存的 AST（内存级，不持久化） */
+    getAst(filePath, content) {
+        const cached = this.astCache.get(filePath);
+        if (!cached)
+            return undefined;
+        const hash = SmartCache.computeHash(content);
+        if (cached.hash !== hash) {
+            this.astCache.delete(filePath);
+            return undefined;
+        }
+        return cached.ast;
+    }
+    /** 缓存 AST 解析结果 */
+    setAst(filePath, content, ast) {
+        this.astCache.set(filePath, {
+            hash: SmartCache.computeHash(content),
+            ast,
+        });
+    }
+    /** 清理过期缓存 */
+    gc() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [key, entry] of Object.entries(this.manifest.entries)) {
+            if (now - entry.timestamp > this.ttl || entry.ruleVersion !== ENGINE_VERSION) {
+                delete this.manifest.entries[key];
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /** 加载缓存 manifest */
+    loadManifest() {
+        try {
+            if ((0, node_fs_1.existsSync)(this.cacheFile)) {
+                const raw = (0, node_fs_1.readFileSync)(this.cacheFile, "utf-8");
+                const manifest = JSON.parse(raw);
+                if (manifest.version === ENGINE_VERSION && manifest.projectDir === this.cacheDir) {
+                    return manifest;
+                }
+            }
+        }
+        catch {
+            // 缓存读取失败，返回空 manifest
+        }
+        return {
+            version: ENGINE_VERSION,
+            projectDir: this.cacheDir,
+            entries: {},
+            lastFullScan: 0,
+        };
+    }
+}
+exports.SmartCache = SmartCache;
+//# sourceMappingURL=cache.js.map

package/dist/engine/cache.js.map

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

package/dist/engine/rule-engine.d.ts

@@ -0,0 +1,135 @@
+/**
+ * RuleEngine — 可插拔规则引擎核心
+ *
+ * 设计目标：
+ * 1. 支持注册/注销规则（插件化）
+ * 2. 按 severity 过滤
+ * 3. 按 framework/platform/componentLib 条件执行
+ * 4. 并行扫描多文件
+ * 5. 支持增量扫描（git diff）
+ */
+import type { Rule, Issue, Severity, ScanResult, FixPreview } from "../types.js";
+import type { ExternalTool, ExternalToolResult } from "../integrations/index.js";
+import { SmartCache } from "./cache.js";
+export interface EngineOptions {
+    /** 项目根目录 */
+    projectDir: string;
+    /** 最低 severity */
+    minSeverity?: Severity;
+    /** 仅检查这些文件 */
+    files?: string[];
+    /** 排除模式 */
+    exclude?: string[];
+    /** 并行度 */
+    concurrency?: number;
+    /** 配置文件路径 */
+    configFile?: string;
+    /** 仅扫描 git staged 文件 */
+    staged?: boolean;
+    /** git diff 范围，如 main...feature */
+    diffRange?: string;
+    /** 智能扫描范围：自动检测未提交/最近修改的文件 */
+    autoScope?: boolean;
+    /** 是否运行外部工具集成（ESLint / TypeScript / Stylelint） */
+    external?: boolean;
+    /** 是否启用智能缓存 */
+    cache?: boolean;
+    /** 缓存 TTL（毫秒，默认 7 天） */
+    cacheTtl?: number;
+    /** 修复预览模式（只展示不写入） */
+    dryRun?: boolean;
+    /** 交互式修复模式（逐条确认） */
+    interactive?: boolean;
+    /** 大文件跳过阈值（字节，默认 500KB = 512000） */
+    skipLargeFilesThreshold?: number;
+    /** v2.6.0: 外部传入的 SmartCache 实例（用于 Watch 模式复用缓存） */
+    cacheInstance?: SmartCache;
+}
+export declare class RuleEngine {
+    private registry;
+    private config;
+    private projectMeta;
+    private options;
+    private cache?;
+    private history;
+    constructor(options: EngineOptions);
+    /** ── Phase 3: 配置驱动规则加载 ── */
+    private loadConfigRules;
+    /** 注册规则 */
+    register(rule: Rule): this;
+    /** 批量注册 */
+    registerAll(rules: Rule[]): this;
+    /** 注销规则 */
+    unregister(ruleId: string): this;
+    /** 获取所有已注册规则（应用配置覆盖后） */
+    getRules(): Rule[];
+    /** 根据条件过滤规则 */
+    filterRules(options?: {
+        category?: string;
+        framework?: string;
+        platform?: string;
+        componentLib?: string;
+    }): Rule[];
+    /** 模块名到规则 category 的映射 */
+    private moduleToCategory;
+    /** 执行扫描 */
+    scan(module: string): Promise<ScanResult>;
+    /** 扫描单个文件（带智能缓存 + 大文件跳过） */
+    private scanFile;
+    /** 获取扫描文件列表 */
+    private getScanFiles;
+    /** 通过 git 获取变更文件列表 */
+    private getDiffFiles;
+    /** 智能推断扫描范围：未提交修改 → 最近 5 次提交 → 全量 */
+    private getAutoScopeFiles;
+    /** 创建 RuleUtils */
+    private createUtils;
+    /** 计算每行起始偏移 */
+    private computeLineOffsets;
+    /**
+     * 应用所有可修复的问题
+     * @param issues 包含 fix 字段的 Issue 列表
+     * @returns 修复统计（dryRun 模式下 filesModified 为空，fixedCount 为预览数量）
+     */
+    applyFixes(issues: Issue[]): {
+        fixedCount: number;
+        filesModified: string[];
+        errors: string[];
+        previews?: FixPreview[];
+        skippedByUser?: number;
+    };
+    /**
+     * v2.4.0: 交互式修复 — 向用户展示 diff 并询问是否应用
+     * 同步阻塞式输入（基于 readline），适用于 CLI 场景
+     */
+    private promptForFix;
+    /** 同步读取一行输入 */
+    private readSyncLine;
+    /** 对单文件应用单个修复 */
+    private applySingleFix;
+    /** 生成 diff 预览（dry-run 模式） */
+    private makeDiffPreview;
+    /** 清理过期缓存 */
+    gcCache(): number;
+    /**
+     * 格式化被扫描项目的代码
+     * 自动检测 Biome / Prettier，使用项目已有配置或生成默认配置
+     * @param files 指定文件列表（undefined 则格式化全部）
+     */
+    format(files?: string[]): import("../integrations/formatter.js").FormatResult;
+    /**
+     * 将相似 Issue 聚类为聚合 Issue
+     * 按 (file, ruleId) 分组，同一文件同一规则的多个 Issue 合并为一个
+     */
+    clusterIssues(issues: Issue[]): Issue[];
+    /**
+     * 运行外部工具集成检查
+     * 自动检测项目中可用的工具（ESLint / TypeScript / Stylelint）并执行
+     */
+    runExternal(tools?: ExternalTool[]): ExternalToolResult[];
+    /** 获取默认的外部工具列表 */
+    private getDefaultExternalTools;
+}
+/** 创建默认引擎实例 */
+export declare function createEngine(options: EngineOptions): RuleEngine;
+//# sourceMappingURL=rule-engine.d.ts.map

package/dist/engine/rule-engine.d.ts.map

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