covgate 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "covgate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "覆盖率门禁：客户端 100%，服务端至少 95%，安装时自动检测/配置测试框架与 AI 编码代理接入。",
+  "type": "module",
+  "bin": {
+    "covgate": "bin/covgate.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "schema",
+    "templates",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "test": "node --test test",
+    "test:watch": "node --test --watch test",
+    "postinstall": "node bin/covgate-postinstall.js"
+  },
+  "keywords": [
+    "coverage",
+    "code-coverage",
+    "coverage-gate",
+    "ai",
+    "agent",
+    "vitest",
+    "jest",
+    "ci",
+    "quality-gate"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/wxzzhj/covgate.git"
+  },
+  "homepage": "https://gitee.com/wxzzhj/covgate",
+  "bugs": {
+    "url": "https://gitee.com/wxzzhj/covgate/issues"
+  },
+  "author": "wxzzhj"
+}

package/schema/covgate.schema.json

@@ -0,0 +1,295 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://covgate.dev/schema/covgate.config.schema.json",
+  "title": "CovGate 配置",
+  "description": "CovGate 覆盖率门禁配置。客户端 scope 不得低于 100%，服务端 scope 不得低于 95%。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "scopes"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1,
+      "description": "配置格式版本，当前只支持 1。"
+    },
+    "scopes": {
+      "$ref": "#/$defs/scopes"
+    },
+    "waivers": {
+      "$ref": "#/$defs/waivers"
+    },
+    "reports": {
+      "$ref": "#/$defs/reports"
+    }
+  },
+  "$defs": {
+    "stringOrStrings": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      ]
+    },
+    "scopes": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "pattern": "^[A-Za-z0-9_-]+$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/scope"
+      }
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "commands",
+        "coverage",
+        "sources"
+      ],
+      "properties": {
+        "profile": {
+          "enum": [
+            "client",
+            "server"
+          ],
+          "description": "client 底线 100%；server 底线 95%。scope 名为 client/server 时可省略。"
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "commands": {
+          "type": "array",
+          "minItems": 1,
+          "description": "按顺序执行的测试命令；任一命令失败则门禁失败。",
+          "items": {
+            "$ref": "#/$defs/command"
+          }
+        },
+        "coverage": {
+          "$ref": "#/$defs/coverage"
+        },
+        "thresholds": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "每个指标的门槛。只能高于产品底线，不能低于。",
+          "properties": {
+            "lines": {
+              "$ref": "#/$defs/threshold"
+            },
+            "statements": {
+              "$ref": "#/$defs/threshold"
+            },
+            "functions": {
+              "$ref": "#/$defs/threshold"
+            },
+            "branches": {
+              "$ref": "#/$defs/threshold"
+            }
+          }
+        },
+        "sources": {
+          "$ref": "#/$defs/sources"
+        },
+        "exclude": {
+          "type": "array",
+          "description": "文件级排除。每条都必须写 reason；没有匹配到任何源码文件的排除会失效并导致失败。",
+          "items": {
+            "$ref": "#/$defs/exclusion"
+          }
+        }
+      }
+    },
+    "command": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "run"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1
+            },
+            "run": {
+              "type": "string",
+              "minLength": 1
+            },
+            "cwd": {
+              "type": "string",
+              "minLength": 1,
+              "description": "相对配置文件所在目录。"
+            },
+            "timeoutSeconds": {
+              "type": "number",
+              "exclusiveMinimum": 0,
+              "maximum": 86400,
+              "default": 900
+            },
+            "env": {
+              "type": "object",
+              "additionalProperties": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            }
+          }
+        }
+      ]
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "paths"
+      ],
+      "properties": {
+        "format": {
+          "enum": [
+            "auto",
+            "istanbul",
+            "lcov"
+          ],
+          "default": "auto",
+          "description": "auto 根据扩展名和内容推断；同一 scope 只能使用一种格式。"
+        },
+        "paths": {
+          "$ref": "#/$defs/stringOrStrings",
+          "description": "相对配置文件目录的覆盖率报告文件、目录或 glob。"
+        }
+      }
+    },
+    "sources": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "include"
+      ],
+      "properties": {
+        "include": {
+          "$ref": "#/$defs/stringOrStrings",
+          "description": "必须列出全部需要门禁的源码。未被测试加载、也不在报告中的源码会失败。"
+        }
+      }
+    },
+    "threshold": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "百分比，最多两位小数；client 固定 100，server 最低 95。"
+    },
+    "exclusion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "pattern",
+        "reason"
+      ],
+      "properties": {
+        "pattern": {
+          "type": "string",
+          "minLength": 1,
+          "description": "相对配置目录的 glob；没有斜杠时匹配任意层级同名文件。"
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "为什么这些文件不应参与覆盖率统计。占位词和过短说明会被拒绝。"
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "expires": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+        },
+        "ticket": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "waivers": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "minReasonLength": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 500,
+          "default": 8
+        },
+        "requireOwner": {
+          "type": "boolean",
+          "default": false
+        },
+        "stale": {
+          "enum": [
+            "fail",
+            "warn"
+          ],
+          "default": "fail",
+          "description": "豁免区间没有移除任何未覆盖代码时的处理方式。"
+        },
+        "expiry": {
+          "enum": [
+            "fail",
+            "warn"
+          ],
+          "default": "fail",
+          "description": "过期豁免的处理方式。"
+        }
+      }
+    },
+    "reports": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "dir": {
+          "type": "string",
+          "minLength": 1,
+          "default": ".covgate"
+        },
+        "formats": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "json",
+              "markdown"
+            ]
+          },
+          "default": [
+            "json",
+            "markdown"
+          ]
+        }
+      }
+    }
+  }
+}

package/src/annotations.js

@@ -0,0 +1,224 @@
+import { validateReason } from "./reason.js";
+
+const DIRECTIVE_PATTERNS = [
+  { kind: "next-line", regex: /\bcovgate-ignore-next-line\b\s*:\s*(.*)$/i },
+  { kind: "line", regex: /\bcovgate-ignore-line\b\s*:\s*(.*)$/i },
+  { kind: "start", regex: /\bcovgate-ignore-start\b\s*:\s*(.*)$/i },
+  { kind: "end", regex: /\bcovgate-ignore-end\b\s*:?\s*(.*)$/i },
+  { kind: "file", regex: /\bcovgate-ignore-file\b\s*:\s*(.*)$/i }
+];
+
+const NATIVE_IGNORE = /\b(?:istanbul|c8|nyc|v8|node:coverage)\s+(?:ignore|disable)\b/i;
+const ANY_DIRECTIVE = /\bcovgate-ignore\b/i;
+const METADATA_KEYS = new Set(["owner", "expires", "ticket"]);
+
+/**
+ * @param {string} text
+ */
+function cleanCommentTail(text) {
+  return text
+    .replace(/\*\/\s*$/, "")
+    .replace(/-->\s*$/, "")
+    .replace(/#}\s*$/, "")
+    .trim();
+}
+
+/**
+ * @param {string} raw
+ * @param {number} lineNumber
+ * @returns {{ reason: string, metadata: Record<string, string>, errors: string[] }}
+ */
+function parseReasonAndMetadata(raw, lineNumber) {
+  const errors = [];
+  const cleaned = cleanCommentTail(raw);
+  const segments = cleaned.split("|");
+  const reason = segments.shift()?.trim() ?? "";
+  /** @type {Record<string, string>} */
+  const metadata = {};
+  for (const segment of segments) {
+    const match = /^\s*([A-Za-z][A-Za-z0-9_-]*)\s*=\s*(.*?)\s*$/.exec(segment);
+    if (!match) {
+      errors.push(
+        "第 " +
+          lineNumber +
+          " 行：元数据格式错误，应为 owner=...、expires=YYYY-MM-DD 或 ticket=..."
+      );
+      continue;
+    }
+    const key = match[1].toLowerCase();
+    const value = match[2].trim();
+    if (!METADATA_KEYS.has(key)) {
+      errors.push('第 ' + lineNumber + ' 行：未知元数据 "' + key + '"');
+      continue;
+    }
+    if (!value) {
+      errors.push('第 ' + lineNumber + ' 行：元数据 "' + key + '" 不能为空');
+      continue;
+    }
+    if (metadata[key]) {
+      errors.push('第 ' + lineNumber + ' 行：元数据 "' + key + '" 重复');
+      continue;
+    }
+    metadata[key] = value;
+  }
+  return { reason, metadata, errors };
+}
+
+/**
+ * Parse covgate-ignore directives from source text. The parser is line-oriented
+ * so it works for JS/TS, Python, Go, Java and many other comment syntaxes.
+ * Directive text may appear in any comment.
+ *
+ * @param {string} text
+ * @param {string} relativePath
+ * @param {{ minReasonLength: number, requireOwner: boolean }} policy
+ * @param {Date} [now]
+ */
+export function parseAnnotations(text, relativePath, policy, now = new Date()) {
+  const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);
+  /** @type {Array<any>} */
+  const directives = [];
+  /** @type {Array<{ line: number, text: string }>} */
+  const nativeIgnores = [];
+  /** @type {Array<{ line: number, message: string }>} */
+  const errors = [];
+  /** @type {{ line: number, directive: any } | null} */
+  let openBlock = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const lineNumber = index + 1;
+    const line = lines[index];
+    const nativeMatch = NATIVE_IGNORE.exec(line);
+    if (nativeMatch) {
+      nativeIgnores.push({ line: lineNumber, text: line.trim() });
+    }
+    let matched = null;
+    for (const pattern of DIRECTIVE_PATTERNS) {
+      const match = pattern.regex.exec(line);
+      if (match) {
+        matched = { kind: pattern.kind, raw: match[1] ?? "" };
+        break;
+      }
+    }
+    if (!matched) {
+      if (ANY_DIRECTIVE.test(line)) {
+        errors.push({
+          line: lineNumber,
+          message:
+            "covgate 指令格式错误；可用：covgate-ignore-line、next-line、start、end、file，且除 end 外都必须有冒号和原因"
+        });
+      }
+      continue;
+    }
+    if (matched.kind === "end") {
+      if (!openBlock) {
+        errors.push({
+          line: lineNumber,
+          message: "covgate-ignore-end 没有对应的 covgate-ignore-start"
+        });
+        continue;
+      }
+      const startDirective = openBlock.directive;
+      const endLine = lineNumber - 1;
+      const startLine = openBlock.line + 1;
+      if (startLine > endLine) {
+        errors.push({
+          line: lineNumber,
+          message: "covgate-ignore-start/end 之间没有代码行"
+        });
+      } else {
+        startDirective.startLine = startLine;
+        startDirective.endLine = endLine;
+        directives.push(startDirective);
+      }
+      openBlock = null;
+      continue;
+    }
+
+    const parsed = parseReasonAndMetadata(matched.raw, lineNumber);
+    errors.push(
+      ...parsed.errors.map((message) => ({ line: lineNumber, message }))
+    );
+    const validation = validateReason(
+      parsed.reason,
+      policy,
+      parsed.metadata,
+      now
+    );
+    for (const message of validation.errors) {
+      errors.push({ line: lineNumber, message });
+    }
+    const base = {
+      kind: matched.kind,
+      file: relativePath,
+      reason: parsed.reason,
+      owner: parsed.metadata.owner,
+      expires: parsed.metadata.expires,
+      ticket: parsed.metadata.ticket,
+      directiveLine: lineNumber,
+      expired: validation.expired,
+      validationErrors: validation.errors
+    };
+
+    if (matched.kind === "next-line") {
+      const target = lineNumber + 1;
+      if (target > lines.length) {
+        errors.push({
+          line: lineNumber,
+          message: "covgate-ignore-next-line 位于文件末尾，没有可忽略的下一行"
+        });
+        continue;
+      }
+      directives.push({ ...base, startLine: target, endLine: target });
+    } else if (matched.kind === "line") {
+      directives.push({ ...base, startLine: lineNumber, endLine: lineNumber });
+    } else if (matched.kind === "start") {
+      if (openBlock) {
+        errors.push({
+          line: lineNumber,
+          message: "covgate-ignore-start 不能嵌套；请先写 covgate-ignore-end"
+        });
+        continue;
+      }
+      openBlock = { line: lineNumber, directive: base };
+    } else if (matched.kind === "file") {
+      directives.push({
+        ...base,
+        startLine: 1,
+        endLine: lines.length,
+        fileLevel: true
+      });
+    }
+  }
+
+  if (openBlock) {
+    errors.push({
+      line: openBlock.line,
+      message: "covgate-ignore-start 缺少对应的 covgate-ignore-end"
+    });
+  }
+
+  const fileIgnores = directives.filter((directive) => directive.fileLevel);
+  if (fileIgnores.length > 1) {
+    errors.push({
+      line: fileIgnores[1].directiveLine,
+      message: "同一文件只能有一个 covgate-ignore-file"
+    });
+  }
+  if (fileIgnores.length > 0) {
+    const others = directives.filter((directive) => !directive.fileLevel);
+    if (others.length > 0) {
+      errors.push({
+        line: others[0].directiveLine,
+        message: "covgate-ignore-file 不能与行级豁免同时使用"
+      });
+    }
+  }
+
+  return {
+    directives: directives.filter((directive) => !directive.fileLevel),
+    fileIgnore: fileIgnores[0] ?? null,
+    nativeIgnores,
+    errors
+  };
+}