autosnippet 2.12.0 → 2.13.0

package/lib/injection/ServiceContainer.js

@@ -34,6 +34,8 @@ import { SnippetInstaller } from '../service/snippet/SnippetInstaller.js';
 import { ExclusionManager } from '../service/guard/ExclusionManager.js';
 import { RuleLearner } from '../service/guard/RuleLearner.js';
 import { ViolationsStore } from '../service/guard/ViolationsStore.js';
+import { ComplianceReporter } from '../service/guard/ComplianceReporter.js';
+import { GuardFeedbackLoop } from '../service/guard/GuardFeedbackLoop.js';
 
 // ─── P1: Token Usage Tracking ─────────────────────────
 import { TokenUsageStore } from '../repository/token/TokenUsageStore.js';
@@ -459,6 +461,33 @@ export class ServiceContainer {
       return this.singletons.violationsStore;
     });
 
+    // Guard: ComplianceReporter
+    this.register('complianceReporter', () => {
+      if (!this.singletons.complianceReporter) {
+        const config = this.singletons._config || {};
+        this.singletons.complianceReporter = new ComplianceReporter(
+          this.get('guardCheckEngine'),
+          this.get('violationsStore'),
+          this.get('ruleLearner'),
+          this.get('exclusionManager'),
+          config.qualityGate || {},
+        );
+      }
+      return this.singletons.complianceReporter;
+    });
+
+    // Guard: GuardFeedbackLoop
+    this.register('guardFeedbackLoop', () => {
+      if (!this.singletons.guardFeedbackLoop) {
+        this.singletons.guardFeedbackLoop = new GuardFeedbackLoop(
+          this.get('violationsStore'),
+          this.get('feedbackCollector'),
+          { guardCheckEngine: this.get('guardCheckEngine') },
+        );
+      }
+      return this.singletons.guardFeedbackLoop;
+    });
+
     // Token Usage: 持久化 AI token 消耗
     this.register('tokenUsageStore', () => {
       if (!this.singletons.tokenUsageStore) {

package/lib/service/automation/handlers/GuardHandler.js

@@ -211,9 +211,20 @@ function _auditSingleFile(engine, fullPath, code, detectLanguage, scope = 'file'
     console.log(`  🛡️ ${errors.length} errors, ${warnings.length} warnings`);
     for (const v of errors) {
       console.log(`  ❌ L${v.line} [${v.ruleId}] ${v.message}`);
+      if (v.fixSuggestion) console.log(`     🔧 修复建议: ${v.fixSuggestion}`);
     }
     for (const v of warnings.slice(0, 5)) {
       console.log(`  ⚠️  L${v.line} [${v.ruleId}] ${v.message}`);
+      if (v.fixSuggestion) console.log(`     🔧 修复建议: ${v.fixSuggestion}`);
     }
   }
+
+  // Guard ↔ Recipe 闭环：检测修复并自动确认使用（fire-and-forget）
+  import('../../../injection/ServiceContainer.js').then(({ ServiceContainer }) => {
+    try {
+      const container = ServiceContainer.getInstance();
+      const feedbackLoop = container.get('guardFeedbackLoop');
+      feedbackLoop.processFixDetection({ violations }, fullPath);
+    } catch { /* guardFeedbackLoop not available */ }
+  }).catch(() => { /* ignored */ });
 }

package/lib/service/guard/ComplianceReporter.js

@@ -0,0 +1,335 @@
+/**
+ * ComplianceReporter — 全项目 Guard 合规报告生成
+ *
+ * 依赖:
+ *   - GuardCheckEngine.auditFiles() — 原始 violations 数据
+ *   - ViolationsStore — 历史统计 & 趋势
+ *   - RuleLearner — 规则 P/R/F1
+ *   - ExclusionManager — 排除项（不计入合规分）
+ *   - config.qualityGate — 阈值配置
+ *
+ * 输出:
+ *   ComplianceReport { qualityGate, summary, topViolations, fileHotspots, ruleHealth, trend }
+ */
+
+import Logger from '../../infrastructure/logging/Logger.js';
+import { collectSourceFilesWithContent } from './SourceFileCollector.js';
+
+/**
+ * Quality Gate 评分算法
+ */
+function computeScore(summary, ruleHealth = []) {
+  let score = 100;
+
+  // 扣分：每个 error -5，每个 warning -1，info -0.2
+  score -= summary.errors * 5;
+  score -= summary.warnings * 1;
+  score -= (summary.infos || 0) * 0.2;
+
+  // 加分：规则平均 F1 > 0.8 加 5 分
+  if (ruleHealth.length > 0) {
+    const avgF1 = ruleHealth.reduce((s, r) => s + (r.f1 || 0), 0) / ruleHealth.length;
+    if (avgF1 > 0.8) score += 5;
+  }
+
+  // 扣分：高误报规则每条 -3
+  const problematic = ruleHealth.filter(r => (r.precision || 1) < 0.5);
+  score -= problematic.length * 3;
+
+  return Math.max(0, Math.min(100, Math.round(score)));
+}
+
+/**
+ * 判定 Quality Gate 状态
+ */
+function evaluateGate(summary, score, thresholds) {
+  const { maxErrors = 0, maxWarnings = 20, minScore = 70 } = thresholds;
+
+  if (summary.errors > maxErrors) return 'FAIL';
+  if (score < minScore) return 'FAIL';
+  if (summary.warnings > maxWarnings) return 'WARN';
+  return 'PASS';
+}
+
+export class ComplianceReporter {
+  /**
+   * @param {import('./GuardCheckEngine.js').GuardCheckEngine} guardCheckEngine
+   * @param {import('./ViolationsStore.js').ViolationsStore} violationsStore
+   * @param {import('./RuleLearner.js').RuleLearner} ruleLearner
+   * @param {import('./ExclusionManager.js').ExclusionManager} exclusionManager
+   * @param {object} qualityGateConfig - { maxErrors, maxWarnings, minScore }
+   */
+  constructor(guardCheckEngine, violationsStore, ruleLearner, exclusionManager, qualityGateConfig = {}) {
+    this.engine = guardCheckEngine;
+    this.violationsStore = violationsStore;
+    this.ruleLearner = ruleLearner;
+    this.exclusionManager = exclusionManager;
+    this.qualityGateConfig = {
+      maxErrors: 0,
+      maxWarnings: 20,
+      minScore: 70,
+      ...qualityGateConfig,
+    };
+    this.logger = Logger.getInstance();
+  }
+
+  /**
+   * 生成全项目合规报告
+   * @param {string} projectRoot - 项目根目录
+   * @param {object} options
+   * @param {object} [options.qualityGate] - 覆盖默认的 Quality Gate 阈值
+   * @param {number} [options.maxFiles] - 最大扫描文件数
+   * @returns {Promise<ComplianceReport>}
+   */
+  async generate(projectRoot, options = {}) {
+    const thresholds = { ...this.qualityGateConfig, ...(options.qualityGate || {}) };
+    const maxFiles = options.maxFiles || 500;
+
+    // 1. 收集源文件
+    const files = await collectSourceFilesWithContent(projectRoot, { maxFiles });
+    this.logger.info(`[ComplianceReporter] Collected ${files.length} source files`);
+
+    // 2. 批量审计
+    const auditResult = this.engine.auditFiles(files, { scope: 'project' });
+
+    // 3. 通过 ExclusionManager 过滤被排除的项
+    const filteredFiles = [];
+    for (const fileResult of auditResult.files || []) {
+      if (this.exclusionManager?.isPathExcluded?.(fileResult.filePath)) continue;
+
+      const filteredViolations = fileResult.violations.filter(v => {
+        // isRuleExcluded 内部已检查全局排除
+        if (this.exclusionManager?.isRuleExcluded?.(v.ruleId, fileResult.filePath)) return false;
+        return true;
+      });
+
+      filteredFiles.push({
+        ...fileResult,
+        violations: filteredViolations,
+        summary: {
+          total: filteredViolations.length,
+          errors: filteredViolations.filter(v => v.severity === 'error').length,
+          warnings: filteredViolations.filter(v => v.severity === 'warning').length,
+          infos: filteredViolations.filter(v => v.severity === 'info').length,
+        },
+      });
+    }
+
+    // 4. 汇总
+    const summary = {
+      filesScanned: files.length,
+      totalViolations: filteredFiles.reduce((s, f) => s + f.summary.total, 0),
+      errors: filteredFiles.reduce((s, f) => s + f.summary.errors, 0),
+      warnings: filteredFiles.reduce((s, f) => s + f.summary.warnings, 0),
+      infos: filteredFiles.reduce((s, f) => s + f.summary.infos, 0),
+    };
+
+    // 5. 按规则 ID 聚合 top violations
+    const ruleAgg = new Map();
+    for (const f of filteredFiles) {
+      for (const v of f.violations) {
+        const key = v.ruleId;
+        if (!ruleAgg.has(key)) {
+          ruleAgg.set(key, {
+            ruleId: key,
+            message: v.message,
+            severity: v.severity,
+            fileCount: new Set(),
+            occurrences: 0,
+            fixRecipeId: null,
+            fixRecipeTitle: null,
+          });
+        }
+        const agg = ruleAgg.get(key);
+        agg.fileCount.add(f.filePath);
+        agg.occurrences++;
+        if (v.fixSuggestion && !agg.fixRecipeId) {
+          agg.fixRecipeId = v.fixSuggestion.replace(/^recipe:/, '');
+        }
+      }
+    }
+
+    const topViolations = [...ruleAgg.values()]
+      .map(v => ({ ...v, fileCount: v.fileCount.size }))
+      .sort((a, b) => b.occurrences - a.occurrences)
+      .slice(0, 20);
+
+    // 6. 文件热点
+    const fileHotspots = filteredFiles
+      .filter(f => f.summary.total > 0)
+      .map(f => ({
+        filePath: f.filePath,
+        violationCount: f.summary.total,
+        errorCount: f.summary.errors,
+      }))
+      .sort((a, b) => b.violationCount - a.violationCount)
+      .slice(0, 20);
+
+    // 7. 规则健康度（来自 RuleLearner）
+    let ruleHealth = [];
+    try {
+      if (this.ruleLearner?.getAllStats) {
+        const allStats = this.ruleLearner.getAllStats();
+        ruleHealth = Object.entries(allStats).map(([ruleId, stat]) => ({
+          ruleId,
+          precision: stat.metrics?.precision ?? 1,
+          recall: stat.metrics?.recall ?? 1,
+          f1: stat.metrics?.f1 ?? 1,
+          triggers: stat.triggers || 0,
+          warning: (stat.metrics?.precision ?? 1) < 0.5 ? '高误报' : null,
+        }));
+      }
+    } catch {
+      // RuleLearner not available
+    }
+
+    // 8. 趋势
+    let trend = { errorsChange: 0, warningsChange: 0, hasHistory: false };
+    try {
+      if (this.violationsStore?.getTrend) {
+        trend = this.violationsStore.getTrend();
+      }
+    } catch {
+      // ViolationsStore not available
+    }
+
+    // 9. 评分 + Gate
+    const score = computeScore(summary, ruleHealth);
+    const gateStatus = evaluateGate(summary, score, thresholds);
+
+    // 10. 写入 ViolationsStore（记录本次运行）
+    try {
+      if (this.violationsStore?.appendRun) {
+        const allViolations = filteredFiles.flatMap(f =>
+          f.violations.map(v => ({ ...v, filePath: f.filePath }))
+        );
+        this.violationsStore.appendRun({
+          filePath: projectRoot,
+          violations: allViolations,
+          summary: `Compliance scan: score=${score} ${gateStatus} | ${summary.errors}E ${summary.warnings}W`,
+        });
+      }
+    } catch {
+      // Persist failure — non-critical
+    }
+
+    return {
+      timestamp: new Date().toISOString(),
+      projectRoot,
+      qualityGate: {
+        status: gateStatus,
+        score,
+        thresholds,
+      },
+      summary,
+      topViolations,
+      fileHotspots,
+      ruleHealth,
+      trend,
+    };
+  }
+
+  /**
+   * 终端格式化输出报告
+   * @param {object} report - generate() 产出的报告
+   * @param {object} options - { format: 'text' | 'markdown' | 'json' }
+   */
+  printReport(report, options = {}) {
+    const { format = 'text' } = options;
+
+    if (format === 'json') {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+
+    if (format === 'markdown') {
+      this._printMarkdown(report);
+      return;
+    }
+
+    // text format
+    this._printText(report);
+  }
+
+  _printText(report) {
+    const { qualityGate, summary, topViolations, fileHotspots, trend } = report;
+
+    const gateIcon = qualityGate.status === 'PASS' ? '✅' : qualityGate.status === 'WARN' ? '⚠️' : '❌';
+    console.log(`\n${'═'.repeat(60)}`);
+    console.log(`  🛡️  Guard Compliance Report`);
+    console.log(`${'═'.repeat(60)}`);
+    console.log(`  ${gateIcon} Quality Gate: ${qualityGate.status}  (Score: ${qualityGate.score}/100)`);
+    console.log(`  📁 Files Scanned: ${summary.filesScanned}`);
+    console.log(`  📊 Violations: ${summary.errors} errors, ${summary.warnings} warnings, ${summary.infos || 0} infos`);
+
+    if (trend.hasHistory) {
+      const errTrend = trend.errorsChange > 0 ? `+${trend.errorsChange}` : `${trend.errorsChange}`;
+      const warnTrend = trend.warningsChange > 0 ? `+${trend.warningsChange}` : `${trend.warningsChange}`;
+      console.log(`  📈 Trend: errors ${errTrend}, warnings ${warnTrend}`);
+    }
+
+    if (topViolations.length > 0) {
+      console.log(`\n  Top Violations:`);
+      for (const v of topViolations.slice(0, 10)) {
+        const fix = v.fixRecipeId ? ` → 🔧 recipe:${v.fixRecipeId}` : '';
+        console.log(`    [${v.severity}] ${v.ruleId} — ${v.occurrences} hits in ${v.fileCount} files${fix}`);
+      }
+    }
+
+    if (fileHotspots.length > 0) {
+      console.log(`\n  File Hotspots:`);
+      for (const f of fileHotspots.slice(0, 10)) {
+        console.log(`    📄 ${f.filePath} — ${f.violationCount} violations (${f.errorCount} errors)`);
+      }
+    }
+
+    console.log(`${'═'.repeat(60)}\n`);
+  }
+
+  _printMarkdown(report) {
+    const { qualityGate, summary, topViolations, fileHotspots, trend } = report;
+    const lines = [];
+
+    lines.push('# Guard Compliance Report');
+    lines.push('');
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    lines.push(`| Quality Gate | ${qualityGate.status} (Score: ${qualityGate.score}/100) |`);
+    lines.push(`| Files Scanned | ${summary.filesScanned} |`);
+    lines.push(`| Errors | ${summary.errors} |`);
+    lines.push(`| Warnings | ${summary.warnings} |`);
+    lines.push(`| Infos | ${summary.infos || 0} |`);
+
+    if (trend.hasHistory) {
+      lines.push(`| Errors Trend | ${trend.errorsChange > 0 ? '+' : ''}${trend.errorsChange} |`);
+      lines.push(`| Warnings Trend | ${trend.warningsChange > 0 ? '+' : ''}${trend.warningsChange} |`);
+    }
+
+    if (topViolations.length > 0) {
+      lines.push('');
+      lines.push('## Top Violations');
+      lines.push('');
+      lines.push('| Rule | Severity | Files | Hits | Fix |');
+      lines.push('|------|----------|-------|------|-----|');
+      for (const v of topViolations.slice(0, 20)) {
+        const fix = v.fixRecipeId ? `recipe:${v.fixRecipeId}` : '-';
+        lines.push(`| ${v.ruleId} | ${v.severity} | ${v.fileCount} | ${v.occurrences} | ${fix} |`);
+      }
+    }
+
+    if (fileHotspots.length > 0) {
+      lines.push('');
+      lines.push('## File Hotspots');
+      lines.push('');
+      lines.push('| File | Violations | Errors |');
+      lines.push('|------|-----------|--------|');
+      for (const f of fileHotspots.slice(0, 20)) {
+        lines.push(`| ${f.filePath} | ${f.violationCount} | ${f.errorCount} |`);
+      }
+    }
+
+    console.log(lines.join('\n'));
+  }
+}
+
+export default ComplianceReporter;

package/lib/service/guard/GuardCheckEngine.js

@@ -2,10 +2,11 @@
  * GuardCheckEngine - Guard 规则检查引擎
  * 
  * 从 V1 guard/ios 迁移，适配 V2 架构
- * 支持: 正则模式匹配 + code-level 检查 + 多维度审计
+ * 支持: 正则模式匹配 + AST 语义规则 + code-level 检查 + 多维度审计
  */
 
 import Logger from '../../infrastructure/logging/Logger.js';
+import * as AstAnalyzerModule from '../../core/AstAnalyzer.js';
 
 /**
  * 内置默认规则集（iOS: ObjC + Swift）
@@ -227,6 +228,7 @@ export class GuardCheckEngine {
     this.logger = Logger.getInstance();
     this._builtInRules = BUILT_IN_RULES;
     this._customRulesCache = null;
+    this._astRulesCache = null;
     this._cacheTime = 0;
     this._cacheTTL = options.cacheTTL || 60_000; // 1min
   }
@@ -251,24 +253,40 @@ export class GuardCheckEngine {
                AND lifecycle = 'active'`
           ).all();
         } catch { /* table may not exist */ }
-        this._customRulesCache = rows.map(r => {
+
+        const regexRules = [];
+        const astRules = [];
+
+        for (const r of rows) {
           let guards = [];
           try {
             const constraints = JSON.parse(r.constraints || '{}');
             guards = constraints.guards || [];
           } catch { /* ignore */ }
-          // Each guard entry becomes a rule
-          return guards.map(g => ({
-            id: g.id || r.id,
-            name: g.name || r.title,
-            message: g.message || r.description || r.title,
-            pattern: g.pattern || '',
-            languages: r.language ? [r.language] : [],
-            severity: g.severity || 'warning',
-            dimension: r.scope || 'file',
-            source: 'database',
-          }));
-        }).flat().filter(r => r.pattern);
+
+          for (const g of guards) {
+            const ruleType = g.type || 'regex';
+            const base = {
+              id: g.id || r.id,
+              name: g.name || r.title,
+              message: g.message || r.description || r.title,
+              languages: r.language ? [r.language] : [],
+              severity: g.severity || 'warning',
+              dimension: r.scope || 'file',
+              source: 'database',
+              fixSuggestion: g.fixSuggestion || null,
+            };
+
+            if (ruleType === 'ast' && g.astQuery) {
+              astRules.push({ ...base, type: 'ast', astQuery: g.astQuery });
+            } else if (g.pattern) {
+              regexRules.push({ ...base, type: 'regex', pattern: g.pattern });
+            }
+          }
+        }
+
+        this._customRulesCache = regexRules;
+        this._astRulesCache = astRules;
         this._cacheTime = now;
       }
       rules.push(...this._customRulesCache);
@@ -289,6 +307,8 @@ export class GuardCheckEngine {
           severity: rule.severity,
           dimension: rule.dimension || 'file',
           source: 'built-in',
+          type: 'regex',
+          fixSuggestion: rule.fixSuggestion || null,
         });
       }
     }
@@ -298,6 +318,15 @@ export class GuardCheckEngine {
       rules = rules.filter(r => !r.languages?.length || r.languages.includes(language));
     }
 
+    // 合并 AST 规则（供外部调用者使用，如 GuardFeedbackLoop.查找 fixSuggestion）
+    if (this._astRulesCache?.length) {
+      let astRules = this._astRulesCache;
+      if (language) {
+        astRules = astRules.filter(r => !r.languages?.length || r.languages.includes(language));
+      }
+      rules.push(...astRules);
+    }
+
     return rules;
   }
 
@@ -306,7 +335,7 @@ export class GuardCheckEngine {
    * @param {string} code - 源代码
    * @param {string} language - 'objc'|'swift'|'javascript' 等
    * @param {object} options - {scope, filePath}
-   * @returns {Array<{ruleId, message, severity, line, snippet, dimension?}>}
+   * @returns {Array<{ruleId, message, severity, line, snippet, dimension?, fixSuggestion?}>}
    */
   checkCode(code, language, options = {}) {
     const { scope = null } = options;
@@ -346,6 +375,7 @@ export class GuardCheckEngine {
             line: i + 1,
             snippet: lines[i].trim().slice(0, 120),
             ...(rule.dimension ? { dimension: rule.dimension } : {}),
+            ...(rule.fixSuggestion ? { fixSuggestion: rule.fixSuggestion } : {}),
           });
         }
       }
@@ -354,6 +384,9 @@ export class GuardCheckEngine {
     // Code-level 检查（不依赖正则）
     violations.push(...this._runCodeLevelChecks(code, language, lines));
 
+    // AST 语义规则检查
+    violations.push(...this._runAstRuleChecks(code, language));
+
     // 跟踪 Guard 命中次数（回写 Recipe 统计）
     this.trackGuardHits(violations);
 
@@ -363,11 +396,133 @@ export class GuardCheckEngine {
       reasoning: {
         whatViolated: v.ruleId,
         whyItMatters: v.message,
-        suggestedFix: v.suggestedFix || null,
+        suggestedFix: v.fixSuggestion || v.suggestedFix || null,
       },
     }));
   }
 
+  /**
+   * AST 语义规则检查
+   * 支持 3 种查询类型: mustCallThrough, mustNotUseInContext, mustConformToProtocol
+   * 仅在 Tree-sitter 可用且语言为 ObjC/Swift 时执行
+   * @param {string} code - 源代码
+   * @param {string} language - 语言标识
+   * @returns {Array} violations
+   */
+  _runAstRuleChecks(code, language) {
+    // AST 规则仅支持 ObjC + Swift
+    const astLangMap = { objc: 'objectivec', swift: 'swift' };
+    const astLang = astLangMap[language];
+    if (!astLang) return [];
+
+    // 获取缓存中的 AST 规则
+    const astRules = (this._astRulesCache || []).filter(r =>
+      !r.languages?.length || r.languages.includes(language)
+    );
+    if (astRules.length === 0) return [];
+
+    // 延迟加载 AstAnalyzer
+    let AstAnalyzer;
+    try {
+      // 使用 dynamic import 会是 async，这里用 require 风格同步加载
+      // AstAnalyzer 作为 ESM 模块，在 constructor 时已被引入
+      AstAnalyzer = this._getAstAnalyzer();
+      if (!AstAnalyzer || !AstAnalyzer.isAvailable()) return [];
+    } catch {
+      this.logger.debug('AstAnalyzer not available, skipping AST rules');
+      return [];
+    }
+
+    const violations = [];
+
+    for (const rule of astRules) {
+      const { astQuery } = rule;
+      if (!astQuery?.queryType) continue;
+
+      try {
+        switch (astQuery.queryType) {
+          case 'mustCallThrough': {
+            // 检查某 API 是否只在指定 wrapper 类中调用
+            const { targetAPI, wrapperClass } = astQuery.params || {};
+            if (!targetAPI || !wrapperClass) break;
+
+            const calls = AstAnalyzer.findCallExpressions(code, astLang, targetAPI);
+            for (const call of calls) {
+              if (call.enclosingClass !== wrapperClass) {
+                violations.push({
+                  ruleId: rule.id,
+                  message: rule.message,
+                  severity: rule.severity,
+                  line: call.line,
+                  snippet: call.snippet,
+                  dimension: rule.dimension || 'file',
+                  ...(rule.fixSuggestion ? { fixSuggestion: rule.fixSuggestion } : {}),
+                });
+              }
+            }
+            break;
+          }
+
+          case 'mustNotUseInContext': {
+            // 在特定上下文中禁止使用某模式
+            const { pattern: textPattern, forbiddenContext } = astQuery.params || {};
+            if (!textPattern || !forbiddenContext) break;
+
+            const matches = AstAnalyzer.findPatternInContext(code, astLang, textPattern, {
+              forbiddenContext,
+            });
+            for (const match of matches) {
+              violations.push({
+                ruleId: rule.id,
+                message: rule.message,
+                severity: rule.severity,
+                line: match.line,
+                snippet: match.snippet,
+                dimension: rule.dimension || 'file',
+                ...(rule.fixSuggestion ? { fixSuggestion: rule.fixSuggestion } : {}),
+              });
+            }
+            break;
+          }
+
+          case 'mustConformToProtocol': {
+            // 检查类是否实现了指定协议
+            const { className, protocolName } = astQuery.params || {};
+            if (!className || !protocolName) break;
+
+            const result = AstAnalyzer.checkProtocolConformance(code, astLang, className, protocolName);
+            if (result.classFound && !result.conforms) {
+              violations.push({
+                ruleId: rule.id,
+                message: rule.message,
+                severity: rule.severity,
+                line: result.classDeclLine || 1,
+                snippet: `class ${className} — missing ${protocolName} conformance`,
+                dimension: rule.dimension || 'file',
+                ...(rule.fixSuggestion ? { fixSuggestion: rule.fixSuggestion } : {}),
+              });
+            }
+            break;
+          }
+
+          default:
+            this.logger.debug(`Unknown AST query type: ${astQuery.queryType}`);
+        }
+      } catch (err) {
+        this.logger.debug(`AST rule ${rule.id} check failed: ${err.message}`);
+      }
+    }
+
+    return violations;
+  }
+
+  /**
+   * 获取 AstAnalyzer 模块（静态 import，带可用性检测）
+   */
+  _getAstAnalyzer() {
+    return AstAnalyzerModule;
+  }
+
   /**
    * 将 Guard 命中计数回写到对应 Recipe 的 guard_hit_count
    * @param {Array<{ruleId: string}>} violations