soloforge 1.1.47 → 1.1.49

package/dist/gate/executors/executors_annotation.d.ts

@@ -1,24 +1,47 @@
 /**
- * ast_annotation_check 执行器 — 检查 Controller/Service 方法上的注解组合是否合规。
+ * ast_annotation_check 执行器 — 检查 Controller 方法上的注解组合是否合规（如 @PostMapping 须配 @PreAuthorize）。
  *
  * 职责边界：
- * - 负责：正则扫描源码，检查注解组合（如 @PostMapping 必须 @Valid + @PreAuthorize）
- * - 不负责：AST 级别的精确分析（用正则近似）
+ * - 负责：正则扫描源码，检查「X 注解必须配 Y 注解」类规则（regex_pattern_scan 的「命中=违规」表达不了「必须有」语义）
+ * - 不负责：AST 级别精确分析（用正则近似）
  *
  * 被谁调用：gate_engine evaluateCheck → gateExecutors.get("ast_annotation_check")
  * 调用谁：fs（读取文件）、git diff（获取扫描目标）
  *
- * 数据流：gate YAML rule_source → 规则文件 → pattern → 正则匹配
- * 持久化：无
- *
- * 复用 regex_pattern_scan 的基础设施，但增加了注解上下文感知。
- * 注解检查需要理解"方法级"上下文：注解必须在方法声明附近（若干行内）。
+ * 关键设计：
+ * 1. 按 check.id 选规则——每条 AnnotationRule 绑定 checkId，executor 只跑 check.id 对应的规则，
+ *    避免「一个 check 跑全部规则」导致语义混乱（API-03 只查权限，不该顺带查 @Valid/Swagger）。
+ * 2. 类级注解识别——方法找 requiredAnnotation 时，先查方法自身注解（向上到类边界），
+ *    再查类级注解（class 声明上方）。支持 Spring @PreAuthorize 类级作用于所有方法
+ *    （固定窗口对「类级注解 + 多方法类」会漏查后面方法——治本）。
+ * 3. requiredAnnotation 只查「注解存在」，不查表达式内容——hasAnyRole/or/hasAuthority 等
+ *    多角色表达式只要 @PreAuthorize 在就算通过（表达式语义由 Spring 运行时保障，引擎不判）。
  */
 import type { GateExecutorFn } from "../gate_executors.js";
+/** 注解检查规则（每条绑定一个 check.id） */
+export interface AnnotationRule {
+    /** 该规则对应的 check id（executor 按 check.id 过滤，只跑匹配规则） */
+    checkId: string;
+    /** 被检查的注解（如 @PostMapping） */
+    targetAnnotation: RegExp;
+    /** 必须同时存在的注解（如 @PreAuthorize） */
+    requiredAnnotation: RegExp;
+    /** 规则说明（违规时展示） */
+    hint: string;
+}
+/** 把全局配置的等效鉴权注解合并进 API-03 的 requiredAnnotation 白名单。
+ *  默认 @(PreAuthorize|Secured|RolesAllowed) + 用户声明 @(RequireRole|...) → 合并正则。
+ *  extraNames 传入时直接用（测试用）；不传则从 ~/.soloforge/annotations.yaml 读取。
+ *  配置缺失/为空 → 返回原规则（fail-safe，用默认白名单）。 */
+export declare function mergeAuthAnnotations(rules: AnnotationRule[], extraNames?: string[]): AnnotationRule[];
+/**
+ * 在 targetAnnotation 行查找 requiredAnnotation：先查方法自身注解（向上到类边界），再查类级注解（class 上方紧贴注解段）。
+ * 覆盖 Spring「类级 @PreAuthorize 作用于所有方法」语义——固定窗口对多方法类会漏查，故显式识别类级。
+ */
+export declare function hasRequiredAnnotation(lines: string[], targetIdx: number, required: RegExp): boolean;
 /**
  * ast_annotation_check 执行器入口。
- *
- * 对 git diff 变更的 Java/Kotlin 文件执行注解组合检查。
+ * 按 check.id 选适用的 AnnotationRule，对 git diff 变更的 Java/Kotlin 文件检查注解组合。
  */
 export declare const executeAnnotationCheck: GateExecutorFn;
 //# sourceMappingURL=executors_annotation.d.ts.map

package/dist/gate/executors/executors_annotation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executors_annotation.d.ts","sourceRoot":"","sources":["../../../src/gate/executors/executors_annotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAiG3D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,cAuDpC,CAAC"}
+{"version":3,"file":"executors_annotation.d.ts","sourceRoot":"","sources":["../../../src/gate/executors/executors_annotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAgDD;;;yCAGyC;AACzC,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAarG;AAmBD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAgBnG;AA8BD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,cAiDpC,CAAC"}

package/dist/gate/executors/executors_annotation.js

@@ -1,50 +1,90 @@
 /**
- * ast_annotation_check 执行器 — 检查 Controller/Service 方法上的注解组合是否合规。
+ * ast_annotation_check 执行器 — 检查 Controller 方法上的注解组合是否合规（如 @PostMapping 须配 @PreAuthorize）。
  *
  * 职责边界：
- * - 负责：正则扫描源码，检查注解组合（如 @PostMapping 必须 @Valid + @PreAuthorize）
- * - 不负责：AST 级别的精确分析（用正则近似）
+ * - 负责：正则扫描源码，检查「X 注解必须配 Y 注解」类规则（regex_pattern_scan 的「命中=违规」表达不了「必须有」语义）
+ * - 不负责：AST 级别精确分析（用正则近似）
  *
  * 被谁调用：gate_engine evaluateCheck → gateExecutors.get("ast_annotation_check")
  * 调用谁：fs（读取文件）、git diff（获取扫描目标）
  *
- * 数据流：gate YAML rule_source → 规则文件 → pattern → 正则匹配
- * 持久化：无
- *
- * 复用 regex_pattern_scan 的基础设施，但增加了注解上下文感知。
- * 注解检查需要理解"方法级"上下文：注解必须在方法声明附近（若干行内）。
+ * 关键设计：
+ * 1. 按 check.id 选规则——每条 AnnotationRule 绑定 checkId，executor 只跑 check.id 对应的规则，
+ *    避免「一个 check 跑全部规则」导致语义混乱（API-03 只查权限，不该顺带查 @Valid/Swagger）。
+ * 2. 类级注解识别——方法找 requiredAnnotation 时，先查方法自身注解（向上到类边界），
+ *    再查类级注解（class 声明上方）。支持 Spring @PreAuthorize 类级作用于所有方法
+ *    （固定窗口对「类级注解 + 多方法类」会漏查后面方法——治本）。
+ * 3. requiredAnnotation 只查「注解存在」，不查表达式内容——hasAnyRole/or/hasAuthority 等
+ *    多角色表达式只要 @PreAuthorize 在就算通过（表达式语义由 Spring 运行时保障，引擎不判）。
  */
 import fs from "node:fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
-/** 内置注解检查规则 */
+import YAML from "yaml";
+import { getGlobalAnnotationsPath } from "../../shared/paths.js";
+/** 内置注解检查规则（按 checkId 绑定，executor 按 check.id 选）。
+ *  注：原 @Transactional 规则已删——Controller 层强制事务语义错误（事务归 Service），会误报。 */
 const ANNOTATION_RULES = [
     {
-        targetAnnotation: /@(PostMapping|PutMapping|PatchMapping)/,
-        requiredAnnotation: /@(Valid|Validated)/,
-        windowLines: 5,
-    },
-    {
+        checkId: "API-03",
         targetAnnotation: /@(PostMapping|PutMapping|DeleteMapping|PatchMapping)/,
         requiredAnnotation: /@(PreAuthorize|Secured|RolesAllowed)/,
-        windowLines: 8,
-    },
-    {
-        targetAnnotation: /@(PostMapping|PutMapping|DeleteMapping|PatchMapping)/,
-        requiredAnnotation: /@Transactional/,
-        windowLines: 15,
-    },
-    {
-        targetAnnotation: /@(GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping)/,
-        requiredAnnotation: /@(Operation|Api|Tag)/,
-        windowLines: 5,
-    },
-    {
-        targetAnnotation: /@RequestBody/,
-        requiredAnnotation: /@(Valid|Validated)/,
-        windowLines: 3,
+        hint: "写接口（POST/PUT/DELETE/PATCH）须配权限注解（@PreAuthorize/@Secured/@RolesAllowed），类级或方法级皆可",
     },
 ];
+// ═══════════════════════════════════════════
+// 全局等效鉴权注解配置（~/.soloforge/annotations.yaml）
+// 项目用自定义鉴权注解（如 @RequireRole，配 AuthInterceptor，明确不引入 Spring Security）时，
+// 默认只认 @PreAuthorize/@Secured/@RolesAllowed 的 API-03 会误报。用户可在全局配置声明等效注解合并进白名单。
+// ═══════════════════════════════════════════
+/** 全局等效鉴权注解缓存（按文件 mtime 失效，避免每次 verify 重读文件） */
+let authAnnotationsCache = null;
+/** 读取 ~/.soloforge/annotations.yaml 的 equivalent_auth_annotations 列表（注解简单名，不带 @）。
+ *  文件不存在/解析失败 → 空数组（fail-safe，executor 用内置默认白名单）。 */
+function loadEquivalentAuthAnnotations() {
+    const filePath = getGlobalAnnotationsPath();
+    try {
+        const stat = fs.statSync(filePath);
+        if (authAnnotationsCache &&
+            authAnnotationsCache.path === filePath &&
+            authAnnotationsCache.mtimeMs === stat.mtimeMs) {
+            return authAnnotationsCache.names;
+        }
+        const content = fs.readFileSync(filePath, "utf-8");
+        const doc = YAML.parse(content);
+        const raw = Array.isArray(doc?.equivalent_auth_annotations) ? doc.equivalent_auth_annotations : [];
+        const names = raw
+            .filter((n) => typeof n === "string" && n.trim().length > 0)
+            .map((n) => n.trim());
+        authAnnotationsCache = { names, mtimeMs: stat.mtimeMs, path: filePath };
+        return names;
+    }
+    catch {
+        return [];
+    }
+}
+/** 把全局配置的等效鉴权注解合并进 API-03 的 requiredAnnotation 白名单。
+ *  默认 @(PreAuthorize|Secured|RolesAllowed) + 用户声明 @(RequireRole|...) → 合并正则。
+ *  extraNames 传入时直接用（测试用）；不传则从 ~/.soloforge/annotations.yaml 读取。
+ *  配置缺失/为空 → 返回原规则（fail-safe，用默认白名单）。 */
+export function mergeAuthAnnotations(rules, extraNames) {
+    const extra = extraNames ?? loadEquivalentAuthAnnotations();
+    if (extra.length === 0)
+        return rules;
+    return rules.map((r) => {
+        if (r.checkId !== "API-03")
+            return r;
+        const builtins = ["PreAuthorize", "Secured", "RolesAllowed"];
+        const all = Array.from(new Set([...builtins, ...extra]));
+        return {
+            ...r,
+            requiredAnnotation: new RegExp(`@(${all.join("|")})`),
+            hint: `${r.hint}；或项目自定义等效注解：@(${extra.join("|")})`,
+        };
+    });
+}
+/** 类声明行（class/interface/enum/record）— 方法级查找的上界、类级查找的起点 */
+const CLASS_DECL_RE = /^\s*(public\s+|abstract\s+|final\s+)*(class|interface|enum|record)\s/;
 /** 获取 git diff 变更文件列表 */
 function getGitDiffFiles(projectRoot) {
     try {
@@ -59,12 +99,39 @@ function getGitDiffFiles(projectRoot) {
         return [];
     }
 }
-/** 对单个文件执行注解检查 */
-function checkAnnotations(projectRoot, relativePath) {
+/**
+ * 在 targetAnnotation 行查找 requiredAnnotation：先查方法自身注解（向上到类边界），再查类级注解（class 上方紧贴注解段）。
+ * 覆盖 Spring「类级 @PreAuthorize 作用于所有方法」语义——固定窗口对多方法类会漏查，故显式识别类级。
+ */
+export function hasRequiredAnnotation(lines, targetIdx, required) {
+    // 1. 方法自身注解：从 targetIdx 向上查，到类声明边界停（方法注解紧贴方法上方）
+    let classIdx = -1;
+    for (let j = targetIdx - 1; j >= 0; j--) {
+        if (CLASS_DECL_RE.test(lines[j])) {
+            classIdx = j;
+            break;
+        }
+        if (required.test(lines[j]))
+            return true;
+    }
+    if (classIdx < 0)
+        return false;
+    // 2. 类级注解：从 class 声明行向上查紧贴的注解段（@xxx 行，遇非注解非注释停）
+    for (let j = classIdx - 1; j >= 0; j--) {
+        const ln = lines[j].trim();
+        if (required.test(lines[j]))
+            return true;
+        // 注解段结束：遇非注解、非注释、非空行（package/import/字段/Javadoc 收尾等）则停
+        if (ln && !ln.startsWith("@") && !ln.startsWith("*") && !ln.startsWith("//") && !ln.startsWith("/*"))
+            break;
+    }
+    return false;
+}
+/** 对单个文件执行注解检查（只跑 applicableRules） */
+function checkAnnotations(projectRoot, relativePath, applicableRules) {
     const fullPath = path.join(projectRoot, relativePath);
     if (!fs.existsSync(fullPath))
         return [];
-    // 防御 EISDIR：relativePath 来自 git diff，偶发为目录路径（existsSync 对目录也返回 true）
     let content;
     try {
         content = fs.readFileSync(fullPath, "utf-8");
@@ -75,24 +142,14 @@ function checkAnnotations(projectRoot, relativePath) {
     const lines = content.split("\n");
     const violations = [];
     for (let i = 0; i < lines.length; i++) {
-        for (const rule of ANNOTATION_RULES) {
+        for (const rule of applicableRules) {
             if (!rule.targetAnnotation.test(lines[i]))
                 continue;
-            // 在窗口范围内查找 required 注解
-            const windowStart = Math.max(0, i - rule.windowLines);
-            const windowEnd = Math.min(lines.length - 1, i + rule.windowLines);
-            let found = false;
-            for (let j = windowStart; j <= windowEnd; j++) {
-                if (rule.requiredAnnotation.test(lines[j])) {
-                    found = true;
-                    break;
-                }
-            }
-            if (!found) {
+            if (!hasRequiredAnnotation(lines, i, rule.requiredAnnotation)) {
                 violations.push({
                     file: relativePath,
                     line: i + 1,
-                    rule: `${lines[i].trim()} 缺少 ${rule.requiredAnnotation.source}`,
+                    rule: `${lines[i].trim()} 缺少 ${rule.requiredAnnotation.source}（${rule.hint}）`,
                 });
             }
         }
@@ -101,46 +158,44 @@ function checkAnnotations(projectRoot, relativePath) {
 }
 /**
  * ast_annotation_check 执行器入口。
- *
- * 对 git diff 变更的 Java/Kotlin 文件执行注解组合检查。
+ * 按 check.id 选适用的 AnnotationRule，对 git diff 变更的 Java/Kotlin 文件检查注解组合。
  */
 export const executeAnnotationCheck = async (check, ctx) => {
     const projectRoot = ctx.projectRoot;
-    const diffFiles = getGitDiffFiles(projectRoot);
-    if (diffFiles.length === 0) {
+    // 按 check.id 过滤规则（一个 check 只跑它绑定的规则）
+    const baseRules = ANNOTATION_RULES.filter((r) => r.checkId === check.id);
+    if (baseRules.length === 0) {
         return {
             check_id: check.id,
             executed_by: "code",
             passed: true,
-            evidence: "无变更文件，跳过注解检查",
+            evidence: `check ${check.id} 无绑定的注解规则，跳过`,
         };
     }
-    // 只扫描 Java/Kotlin 文件
+    // 合并全局配置的等效鉴权注解（~/.soloforge/annotations.yaml）进白名单。
+    // 默认只认 Spring Security 三注解，项目用自定义 @RequireRole 等会被误报；用户可在全局配置声明等效注解。
+    const applicableRules = mergeAuthAnnotations(baseRules);
+    const diffFiles = getGitDiffFiles(projectRoot);
+    if (diffFiles.length === 0) {
+        return { check_id: check.id, executed_by: "code", passed: true, evidence: "无变更文件，跳过注解检查" };
+    }
     const codeFiles = diffFiles.filter((f) => f.endsWith(".java") || f.endsWith(".kt"));
     if (codeFiles.length === 0) {
-        return {
-            check_id: check.id,
-            executed_by: "code",
-            passed: true,
-            evidence: "无 Java/Kotlin 变更文件，跳过注解检查",
-        };
+        return { check_id: check.id, executed_by: "code", passed: true, evidence: "无 Java/Kotlin 变更文件，跳过注解检查" };
     }
     const allViolations = [];
     for (const file of codeFiles) {
-        allViolations.push(...checkAnnotations(projectRoot, file));
+        allViolations.push(...checkAnnotations(projectRoot, file, applicableRules));
     }
     if (allViolations.length === 0) {
         return {
             check_id: check.id,
             executed_by: "code",
             passed: true,
-            evidence: `扫描 ${codeFiles.length} 个文件，注解组合全部合规`,
+            evidence: `扫描 ${codeFiles.length} 个文件，注解组合全部合规（check ${check.id}）`,
         };
     }
-    const evidenceLines = allViolations
-        .slice(0, 20)
-        .map((v) => `${v.file}:${v.line}: ${v.rule}`)
-        .join("\n");
+    const evidenceLines = allViolations.slice(0, 20).map((v) => `${v.file}:${v.line}: ${v.rule}`).join("\n");
     return {
         check_id: check.id,
         executed_by: "code",

package/dist/gate/executors/executors_annotation.js.map

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

package/dist/gate/executors/executors_artifact.d.ts

@@ -2,7 +2,7 @@
  * 产物类执行器 — 文件证据、报告结构、文档结构、YAML 切片完成度、切片可验证性校验。
  *
  * 职责边界：
- * - 负责：file_evidence、report_structure、document_structure、yaml_slice_completion、slice_verifiability_check
+ * - 负责：file_evidence、report_structure、document_structure、slice_verifiability_check
  * - 不负责：不涉及部署/构建/追踪/范围/前置条件类 executor
  *
  * 被谁调用：index.ts（registerAllExecutors）
@@ -11,6 +11,25 @@
  * 数据流：GateCheck + EvaluationContext → 读取产物文件 → 结构化验证 → CheckResult
  * 持久化：读取本地文件（.soloforge/evidence/、docs/）
  */
+import type { BlockCheckConfig } from "../../domain/asset_registry/derived_types.js";
 /** 注册产物类执行器 */
 export declare function registerArtifactExecutors(): void;
+/**
+ * 条目块完整性校验（block_check，反退化硬兜底）。
+ * 按 item_pattern 把文档切成多个条目块，逐块校验：
+ * - required_marks：每块必须包含的文本标记（子章节名/关键字），缺任一判失败
+ * - require_table：每块必须含 ≥ min_table_rows 个表格数据行（排除表头分隔行 |---|）
+ * 任一块缺标记或表格行不足 → 精确报「块 X 缺 Y」。
+ * 防退化模式：前详后废、表格退化为一行文字、（同上格式）占位。
+ */
+export declare function checkBlockIntegrity(content: string, cfg: BlockCheckConfig): {
+    passed: boolean;
+    error?: string;
+};
+/**
+ * 解析产物名/模版名到真实文件路径（document_structure 专用）。
+ * 候选 1：CROSS_VALIDATION_ARTIFACT_PATHS 模版名映射（含 glob 多端聚合，取首个命中）；
+ * 候选 2：docs/ 下字面查找；候选 3：项目根相对路径。
+ */
+export declare function resolveArtifactPath(artifact: string | undefined, projectRoot: string): string | undefined;
 //# sourceMappingURL=executors_artifact.d.ts.map

package/dist/gate/executors/executors_artifact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executors_artifact.d.ts","sourceRoot":"","sources":["../../../src/gate/executors/executors_artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,eAAe;AACf,wBAAgB,yBAAyB,IAAI,IAAI,CAgZhD"}
+{"version":3,"file":"executors_artifact.d.ts","sourceRoot":"","sources":["../../../src/gate/executors/executors_artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAErF,eAAe;AACf,wBAAgB,yBAAyB,IAAI,IAAI,CAgWhD;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,gBAAgB,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA+C/G;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAmBzG"}