canship 0.2.0 → 0.2.1

package/dist/cli.js

@@ -47,13 +47,7 @@ var SECRET_PATTERNS = [
   {
     id: "npm-token",
     name: "npm access token",
-    // Shape only, though npm encodes a CRC32 of the token into its last six
-    // characters and this could verify it. The github-token entry above uses
-    // the same scheme and does not verify it either, for the reason that
-    // settles it: if the algorithm ever changes, a checksum test turns a real
-    // leaked token into a silent pass. A false positive costs a glance. This
-    // particular false negative costs the account, and every account that
-    // installs anything published from it afterwards.
+    // 仅检查令牌形状，不校验其校验码。
     pattern: /\bnpm_[A-Za-z0-9]{36}\b/g,
     impact: "Publishes packages under your account. Anyone who installs one afterwards runs whatever that version contains.",
     rotateAt: "https://docs.npmjs.com/creating-and-viewing-access-tokens"
@@ -64,13 +58,7 @@ var SECRET_PATTERNS = [
     pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g,
     impact: "Depending on its scope, this can be used to run up billed usage on Google Cloud services.",
     rotateAt: "https://console.cloud.google.com/apis/credentials",
-    // Unlike every other pattern in this table, an AIza-format key is not a
-    // bearer credential: it identifies a Firebase project or a Maps Platform
-    // caller, and Google's own docs say it belongs in client code. Flagging
-    // it as "exposed to the browser — rotate this" was a false positive on
-    // every ordinary Firebase or Maps front-end, and the actual protection
-    // (application/API restrictions in the Cloud console) is not something a
-    // static scan of the repository can confirm one way or the other.
+    // Google 项目标识符不直接作为私密凭据报告。
     publicByDesign: true
   },
   {
@@ -91,17 +79,7 @@ var SECRET_PATTERNS = [
     id: "supabase-secret-key",
     name: "Supabase secret key",
     rotateLabel: "Supabase secret key",
-    // Supabase's newer key format. The prefix settles it: sb_secret_ is the
-    // server-side half, sb_publishable_ is the one meant for browsers, and the
-    // two are never confusable.
-    //
-    // framework.ts has recognised this format since the day it was written —
-    // but only for deciding whether a *client-exposed* value is the admin key.
-    // It was never in this table, and this table is what the hardcoded-secret
-    // rule and the output-boundary redaction both walk. So a project with one
-    // of these in its source got a clean report, and a project with one beside
-    // another credential had it printed in full: the redaction pass could not
-    // mask a format it did not know.
+    // 共享新版 Supabase 私密密钥模式，与公开密钥区分。
     pattern: new RegExp(String.raw`\b${SB_SECRET_SOURCE}\b`, "g"),
     impact: "This is the server-side Supabase key. It bypasses every Row Level Security policy \u2014 it is effectively your database root password.",
     rotateAt: "your Supabase dashboard, Project Settings -> API Keys"
@@ -117,22 +95,9 @@ var SECRET_PATTERNS = [
     id: "db-connection-string",
     name: "Database connection string with password",
     pattern: /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp):\/\/[^\s:@/'"`]+:([^\s@/'"`]+)@(\[[^\]\s]+\]|[^\s'"`/:]+)(?::\d+)?(?:[/?#][^\s'"`]*)?/g,
-    // Check only the password group for placeholders, so an "example" or "test"
-    // in the host does not cause a miss.
+    // 仅用密码组判断占位符，避免主机名影响判断。
     secretGroup: 1,
-    // But if the host itself is an example domain or a local address, the
-    // connection string is worthless and not worth reporting.
-    //
-    // The host alternative takes a bracketed form first so IPv6 survives:
-    // `[^\s'"/:]+` stops at the first colon, so `@[::1]:5432` captured a lone
-    // `[`, which matches no entry below — an IPv6 loopback string was reported
-    // P0 while the identical `localhost` one was correctly ignored.
-    //
-    // The backtick is excluded for the same reason. It is the third string
-    // delimiter in JavaScript and the only one this pattern had never heard of,
-    // so a connection string written in a template literal handed the host
-    // group a trailing backtick and defeated the check below. canship found
-    // that one on its own source, in the comment above.
+    // 支持 IPv6，并排除示例和本地地址。
     ignoreIf: (m) => IRRELEVANT_HOSTS.test(m[2] ?? ""),
     rotateLabel: "database password",
     impact: "This contains your database username AND password. Anyone with it can read, modify, or delete your entire database."
@@ -233,6 +198,7 @@ import { execFileSync } from "child_process";
 import { accessSync, constants, existsSync, lstatSync, readFileSync, realpathSync, statSync } from "fs";
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "path";
 var MAX_GIT_OUTPUT = 32 * 1024 * 1024;
+var GIT_TIMEOUT_MS = 3e4;
 function canonical(path) {
   try {
     return realpathSync.native(path);
@@ -437,6 +403,7 @@ function hardeningArgs(root) {
 }
 function execGitSync(executable, root, args, options = {}) {
   return execFileSync(executable, [...hardeningArgs(root), ...args], {
+    timeout: GIT_TIMEOUT_MS,
     cwd: root,
     encoding: "utf8",
     maxBuffer: options.maxBuffer ?? MAX_GIT_OUTPUT,
@@ -447,6 +414,7 @@ function execGitSync(executable, root, args, options = {}) {
 }
 function execGitBatch(executable, root, args, input, options = {}) {
   return execFileSync(executable, [...hardeningArgs(root), ...args], {
+    timeout: GIT_TIMEOUT_MS,
     cwd: root,
     input,
     maxBuffer: options.maxBuffer ?? MAX_GIT_OUTPUT,
@@ -458,6 +426,8 @@ function execGitBatch(executable, root, args, input, options = {}) {
 
 // src/walker.ts
 var MAX_FILE_BYTES = 2 * 1024 * 1024;
+var MAX_SCAN_BYTES = 128 * 1024 * 1024;
+var MAX_SCAN_FILES = 1e4;
 var MAX_WALK_DEPTH = 16;
 var SKIP_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
@@ -476,8 +446,7 @@ var SKIP_DIRS = /* @__PURE__ */ new Set([
   ".venv",
   "venv",
   ".cache",
-  // Build output and tool caches from ecosystems beyond JavaScript. Walking
-  // these to look for credential files is pure cost.
+  // 排除其他生态的构建产物和工具缓存。
   ".dart_tool",
   ".gradle",
   "Pods",
@@ -515,7 +484,7 @@ var SCAN_EXTENSIONS = /* @__PURE__ */ new Set([
   ".yml",
   ".toml",
   ".sql",
-  // Firebase security rules (firestore.rules / storage.rules)
+  // Firebase 规则文件。
   ".rules",
   ".env",
   ".sh",
@@ -810,7 +779,7 @@ function isExampleContext(relPath) {
   if (/\.(test|spec)\.[jt]sx?$/i.test(name)) return true;
   return false;
 }
-function collectFiles(root, isGitRepo, gitExecutable = resolveGitExecutable(root)) {
+function collectFiles(root, isGitRepo, gitExecutable = resolveGitExecutable(root), limits = {}) {
   const skipped = [];
   const ignored = [];
   const fromGit = isGitRepo ? listViaGit(root, gitExecutable) : null;
@@ -839,6 +808,10 @@ function collectFiles(root, isGitRepo, gitExecutable = resolveGitExecutable(root
     forced.add(hidden);
   }
   const files = [];
+  let bytesRead = 0;
+  let filesRead = 0;
+  const maxBytes = limits.maxBytes ?? MAX_SCAN_BYTES;
+  const maxFiles = limits.maxFiles ?? MAX_SCAN_FILES;
   for (const relPath of candidates) {
     if (!forced.has(relPath) && !shouldScan(relPath)) continue;
     const absPath = join2(root, relPath);
@@ -859,7 +832,22 @@ function collectFiles(root, isGitRepo, gitExecutable = resolveGitExecutable(root
         });
         continue;
       }
-      content = decodeText(readFileSync2(absPath));
+      if (filesRead >= maxFiles || bytesRead + size > maxBytes) {
+        skipped.push({
+          path: relPath,
+          reason: "too-large",
+          detail: `scan read budget exceeded (${maxFiles} files, ${maxBytes} bytes); remaining candidates were not read`
+        });
+        break;
+      }
+      const bytes = readFileSync2(absPath);
+      bytesRead += bytes.length;
+      filesRead++;
+      if (bytesRead > maxBytes) {
+        skipped.push({ path: relPath, reason: "too-large", detail: "scan read budget exceeded during file read" });
+        break;
+      }
+      content = decodeText(bytes);
     } catch (err) {
       if (!isMissing(err)) {
         skipped.push({
@@ -1350,6 +1338,20 @@ var secretsRule = {
 // src/rules/exposure.ts
 import { basename as basename3 } from "path";
 var JWT_SHAPED2 = new RegExp(String.raw`\b${JWT_SOURCE}\b`, "g");
+var FindingBuffer = class {
+  items = [];
+  overflow = false;
+  push(finding) {
+    if (this.items.length < MAX_FINDINGS_PER_FILE) {
+      this.items.push(finding);
+      return;
+    }
+    this.overflow = true;
+    if (finding.confidence !== "certain") return;
+    const index = this.items.findIndex((item) => item.confidence === "likely");
+    if (index !== -1) this.items[index] = finding;
+  }
+};
 function parseEnv(file) {
   const entries = [];
   file.lines.forEach((raw, i) => {
@@ -1366,35 +1368,20 @@ var exposureRule = {
     if (isEnvFile(name)) return true;
     return /\.(ts|tsx|js|jsx|mjs|cjs|svelte|vue|astro)$/.test(name);
   },
-  /**
-   * The ceiling, applied here rather than inside each branch.
-   *
-   * This rule was the last one without one. secrets.ts, firebase.ts and
-   * supabase.ts all cap and all say so — the constant was pulled into limits.ts
-   * precisely so the reasoning would not have to be rediscovered — and exposure
-   * never adopted it. A `.env` holding 3,000 public-prefixed credential names
-   * produced 3,000 findings, 2.36 MB of JSON and 48,046 lines of terminal
-   * output, with `partial` false and `errors` empty: the identical shape of the
-   * bug firebase.ts records in its own comment.
-   *
-   * At the entry point because there are two branches and a future third would
-   * have to remember. Truncating after the fact rather than stopping the loop
-   * keeps that single place honest: the input is already bounded by
-   * MAX_FILE_BYTES, so what this protects is the report, not the scan.
-   */
+  /** 使用有界缓冲区保留结果，超限时记录扫描缺口。 */
   check(file, ctx) {
     const name = basename3(file.path);
     const findings = isEnvFile(name) ? checkEnvFile(file) : checkSourceFile(file);
-    if (findings.length <= MAX_FINDINGS_PER_FILE) return findings;
+    if (!findings.overflow) return findings.items;
     ctx.reportIncomplete(
       "exposure/public-env",
       `${file.path} holds more than ${MAX_FINDINGS_PER_FILE} values exposed to the browser; the rest were not reported`
     );
-    return findings.slice(0, MAX_FINDINGS_PER_FILE);
+    return findings.items;
   }
 };
 function checkEnvFile(file) {
-  const findings = [];
+  const findings = new FindingBuffer();
   for (const entry of parseEnv(file)) {
     const prefix = publicPrefixOf(entry.key);
     if (!prefix) continue;
@@ -1473,7 +1460,7 @@ function checkEnvFile(file) {
   return findings;
 }
 function checkSourceFile(file) {
-  const findings = [];
+  const findings = new FindingBuffer();
   const clientSide = isClientCode(file);
   const commentless = commentsMaskedOf(file).split(/\r?\n/);
   file.lines.forEach((line, i) => {
@@ -1654,6 +1641,7 @@ function historicalEvidence(root, gitExecutable, entry) {
     "--no-textconv",
     "--all",
     "--format=%H",
+    `--max-count=${MAX_HISTORY_REVISIONS + 1}`,
     "--",
     entry.localPath
   ]) ?? "").split(/\r?\n/).filter(Boolean);
@@ -1731,9 +1719,7 @@ var gitleakRule = {
       findings.push({
         ruleId: "gitleak/env-tracked",
         severity: "P0",
-        // Only claim certainty when the file actually holds something that is
-        // recognisably a credential. Everything else is a committed env file
-        // that might hold one, which is worth saying quietly.
+        // 只有非示例中的明确凭据使用确定置信度。
         confidence: evidence === "proof" && !scaffolding ? "certain" : "likely",
         title: evidence === "proof" && !scaffolding ? `${path} is committed to git, with a credential in it` : `${path} is committed to git`,
         file: path,
@@ -1760,7 +1746,7 @@ var gitleakRule = {
       if (history && history.unread > 0) {
         ctx.reportIncomplete(
           "gitleak/env-in-history",
-          `only the ${MAX_HISTORY_REVISIONS} most recent versions of ${path} were read; ${history.unread} older ${history.unread === 1 ? "version was" : "versions were"} not checked`
+          `only the ${MAX_HISTORY_REVISIONS} most recent versions of ${path} were read; at least ${history.unread} older ${history.unread === 1 ? "version was" : "versions were"} not checked`
         );
       }
       if (history && history.unreadable > 0) {
@@ -1776,8 +1762,7 @@ var gitleakRule = {
         ruleId: "gitleak/env-in-history",
         ...history?.sourceFingerprint === void 0 ? {} : { sourceFingerprint: history.sourceFingerprint },
         severity: "P0",
-        // Claiming certainty about a file nobody could read would be the same
-        // overreach the tracked branch just stopped making.
+        // 证据或上下文不足时降低置信度。
         confidence: evidence === "proof" && !scaffolding ? "certain" : "likely",
         title: stillTracked ? `${path} is committed to git, and an older version of it held a credential` : `${path} was removed, but it is still in your git history`,
         file: path,
@@ -2251,8 +2236,7 @@ var firebaseRulesRule = {
       findings.push({
         ruleId: "firebase/open-rules",
         severity: "P1",
-        // Open writes are unambiguous. An open read might be intentional
-        // (a public catalogue, announcements), so it stays lower-confidence.
+        // 开放写入为确定结果，公开读取需人工确认。
         confidence: canWrite ? "certain" : "likely",
         title: canWrite ? `Your ${product} rules let anyone ${ops} this data` : `Your ${product} rules make this data publicly readable`,
         file: file.path,
@@ -2290,8 +2274,7 @@ var firebaseRulesRule = {
       findings.push({
         ruleId: "firebase/test-mode-rules",
         severity: "P1",
-        // A hardcoded expiry date is never a deliberate authorisation design,
-        // so this stays certain whether or not writes are involved.
+        // 固定日期测试模式均作为确定配置问题。
         confidence: "certain",
         title: expired ? `Your ${product} rules are in test mode and expired on ${dateStr}` : `Your ${product} rules allow ${ops} to anyone until ${dateStr}`,
         file: file.path,
@@ -2320,7 +2303,10 @@ import { posix } from "path";
 var APP_ROUTER = /(?:^|\/)app\/api\/(?:.+\/)?route\.[mc]?[jt]sx?$/;
 var PAGES_ROUTER = /(?:^|\/)pages\/api\/.+\.[mc]?[jt]sx?$/;
 function isApiRoute(path) {
-  return APP_ROUTER.test(path) || PAGES_ROUTER.test(path);
+  return APP_ROUTER.test(routePathOf(path)) || PAGES_ROUTER.test(path);
+}
+function routePathOf(path) {
+  return path.replace(/(^|\/)\([^/]+\)(?=\/)/g, "$1").replace(/\/{2,}/g, "/");
 }
 var AUTH_ENDPOINT_NAMES = /^\/api\/auth\/(?:sign[-_]?in|sign[-_]?up|sign[-_]?out|log[-_]?in|log[-_]?out|register|session|verify|confirm|reset(?:[-_]password)?|forgot(?:[-_]password)?|magic[-_]?link|otp)$/;
 var AUTH_CALLBACK = /^\/api\/auth\/callback(?:\/[^/]+)?$/;
@@ -2328,7 +2314,7 @@ function isAuthEndpoint(url) {
   return AUTH_ENDPOINT_NAMES.test(url) || AUTH_CALLBACK.test(url);
 }
 function routeUrl(path) {
-  const m = /(?:^|\/)(?:app|pages)\/(api\/.*)$/.exec(path);
+  const m = /(?:^|\/)(?:app|pages)\/(api\/.*)$/.exec(routePathOf(path));
   if (!m) return `/${path}`;
   const url = m[1].replace(/\/route\.[mc]?[jt]sx?$/, "").replace(/\/index\.[mc]?[jt]sx?$/, "").replace(/\.[mc]?[jt]sx?$/, "");
   return `/${url}`;
@@ -2359,17 +2345,37 @@ function controlledStatement(source, afterCondition) {
   return source.slice(start, end);
 }
 function hasConditionalAuthGuard(code) {
-  const starts = code.matchAll(/\bif\s*\(/g);
-  for (const match of starts) {
+  const starts = /\bif\s*\(/g;
+  let match;
+  while ((match = starts.exec(code)) !== null) {
     const open = code.indexOf("(", match.index);
     const close = closingDelimiter(code, open, "(", ")");
     if (close === null) continue;
     const condition = code.slice(open + 1, close);
     const statement = controlledStatement(code, close + 1);
-    const stopsRequest = /\b(?:return|throw|redirect|notFound)\b/.test(statement);
+    const body = statement.startsWith("{") ? statement.slice(1, -1) : statement;
+    const pairs = delimiterPairs(body);
+    let stopsRequest = false;
+    for (let i = 0; i < body.length; i++) {
+      if (/^(?:return|throw|redirect|notFound)\b/.test(body.slice(i, i + 16)) && (i === 0 || !/[\w$]/.test(body[i - 1]))) {
+        stopsRequest = true;
+        break;
+      }
+      if (/^if\s*\(/.test(body.slice(i, i + 16))) break;
+      const end = pairs.get(i);
+      if (end !== void 0) i = end;
+    }
+    let statementStart = close + 1;
+    while (/\s/.test(code[statementStart] ?? "")) statementStart++;
+    starts.lastIndex = statementStart + statement.length;
     if (!stopsRequest) continue;
     const returnsDeniedStatus = /\b(?:return|throw)\b[\s\S]{0,300}\bstatus\s*[:(=]\s*(?:401|403)\b/i.test(statement);
-    if (AUTH_CONDITION.test(condition) || returnsDeniedStatus) return true;
+    const negative = !/&&|\?/.test(condition) && condition.split("||").some((part) => {
+      const term = part.trim();
+      const rejects = /^!\s*[\w$.]+(?:\s*\([^=]*\))?$/.test(term) || /^[\w$.]+\s*={2,3}\s*(?:null|undefined|false)$/.test(term) || /^[\w$.]+\s*!={1,2}\s*(?!(?:null|undefined|false)\b)[\w$.]+$/.test(term);
+      return rejects && (AUTH_CONDITION.test(term) || returnsDeniedStatus);
+    });
+    if (negative) return true;
   }
   return false;
 }
@@ -2462,6 +2468,16 @@ function unguardedOperations(file, ops) {
       }
       const call = AUTH_ENFORCING_CALL.exec(code.slice(i, i + 100));
       if (call?.index === 0 && !/^(?:withAuth|NextAuth)\b/i.test(call[0]) && !/\bfunction\s*$/.test(code.slice(Math.max(owner.start, i - 30), i))) {
+        const prefixStart = Math.max(
+          owner.start + 1,
+          code.lastIndexOf(";", i - 1) + 1,
+          code.lastIndexOf("\n", i - 1) + 1
+        );
+        const prefix = code.slice(prefixStart, i).trim();
+        if (/(?:&&|\|\||\?|:)\s*$/.test(code.slice(owner.start + 1, prefixStart))) continue;
+        const awaited = /^(?:await|(?:const|let|var)\s+[\w${},:\s]+?=\s*await)(?:\s+[\w$.]+\.)?$/.test(prefix);
+        const synchronous = /^(?:assertAuth(?:enticated)?|constructEvent)\b/i.test(call[0]) && /^(?:(?:const|let|var)\s+[\w$]+\s*=\s*)?(?:[\w$]+\.)*$/.test(prefix);
+        if (!awaited && !synchronous) continue;
         const close2 = pairs.get(i + call[0].length - 1);
         if (close2 !== void 0 && close2 < owner.end) return close2 + 1;
       }
@@ -2559,7 +2575,7 @@ function usesSessionClient(route, sessionModules, allFiles) {
   return buildsSessionClient(route) || importsAnyOf(route, sessionModules, allFiles);
 }
 function moduleScopeOf(routePath) {
-  return /^(.*?)(?:src\/)?(?:app|pages)\/api\//.exec(routePath)?.[1] ?? "";
+  return /^(.*?)(?:src\/)?(?:app|pages)\/api\//.exec(routePathOf(routePath))?.[1] ?? "";
 }
 function importedModules(file, allFiles, aliasScope) {
   const found = [];
@@ -2899,9 +2915,7 @@ var apiAuthRule = {
         findings.push({
           ruleId: "api/admin-db-access-without-auth",
           severity: "P0",
-          // Hard evidence: the route runs queries through a key that bypasses
-          // every RLS policy, and nothing in the file or in middleware checks
-          // who sent the request.
+          // 管理员客户端缺少鉴权时使用确定置信度。
           confidence: "certain",
           title: `Anyone can call ${url} and it queries your database as admin`,
           file: route.path,
@@ -2929,9 +2943,7 @@ var apiAuthRule = {
         findings.push({
           ruleId: "api/db-write-without-auth",
           severity: "P1",
-          // Lower confidence on purpose: the write may be legitimately open
-          // (a waitlist, a contact form), and protection can also live in a
-          // deployment-level proxy this scan cannot see.
+          // 公开写入可能是业务设计，保留疑似置信度。
           confidence: "likely",
           title: `${url} writes to your database with no sign-in check`,
           file: route.path,
@@ -3184,8 +3196,7 @@ var corsRule = {
         findings.push({
           ruleId: "cors/reflected-origin-with-credentials",
           severity: "P1",
-          // Both halves are read straight out of the file: the origin is handed
-          // back unchanged, and credentials are allowed. Nothing is inferred.
+          // 明确的来源回显和凭据配置使用确定置信度。
           confidence: "certain",
           title: "Any website can make signed-in requests to your API and read the answer",
           file: file.path,
@@ -3207,8 +3218,7 @@ var corsRule = {
         findings.push({
           ruleId: "cors/wildcard-with-credentials",
           severity: "P2",
-          // Not a judgement call: the specification forbids this pair, so every
-          // browser rejects it.
+          // 通配符与凭据组合违反浏览器跨域约束。
           confidence: "certain",
           title: "This CORS setup is rejected by every browser, so the requests it enables never work",
           file: file.path,
@@ -3247,8 +3257,7 @@ var RULE_IDS = [
   "gitleak/env-in-history",
   "gitleak/env-tracked",
   "supabase/rls-not-enabled",
-  // One per credential format, built the same way secrets.ts builds them, so
-  // adding a pattern cannot leave a finding id this list has never heard of.
+  // 凭据规则 ID 从共享格式表生成。
   ...SECRET_PATTERNS.map((p) => `secrets/hardcoded/${p.id}`)
 ];
 function ruleMatches(selector, ruleId) {
@@ -3257,6 +3266,13 @@ function ruleMatches(selector, ruleId) {
 function isKnownSelector(selector) {
   return RULE_IDS.some((id) => ruleMatches(selector, id));
 }
+function shouldRunRule(id, only, skip) {
+  if (only.length === 0 && skip.length === 0) return true;
+  const namespace = id.split("/")[0];
+  return RULE_IDS.filter((candidate) => candidate.startsWith(`${namespace}/`)).some(
+    (candidate) => (only.length === 0 || only.some((selector) => ruleMatches(selector, candidate))) && !skip.some((selector) => ruleMatches(selector, candidate))
+  );
+}
 
 // src/engine.ts
 import { createHash as createHash2 } from "crypto";
@@ -3299,28 +3315,11 @@ function sanitize(findings, files) {
     // 仅输出摘要；原始行不进入报告，移动行号不改变身份。
     ...sourceIdentity(f),
     title: clean(f.title),
-    // Per paragraph, so the breaks between them survive a cleaner that removes
-    // every newline inside them. See Finding.why.
+    // 按段落清理，保留段落之间的结构。
     why: f.why.map(clean),
-    // The path was left out of this list once, and a filename holding a
-    // credential put it straight back into the JSON, the terminal, the HTML
-    // and the prompt meant for pasting into an assistant.
+    // 文件路径也必须经过输出清理。
     file: f.file === null ? null : clean(f.file),
-    // Redacted first, cut second, and both of them here.
-    //
-    // A rule that trimmed its own excerpt to length before this ran could
-    // defeat the redaction entirely: cutting at 120 characters through the
-    // middle of a key leaves a fragment that matches no pattern, so `clean`
-    // waved it past and nineteen characters of a live OpenAI key reached the
-    // terminal, the JSON, the HTML report and the prompt meant for pasting
-    // into an assistant. The rule was not doing anything unreasonable — it
-    // truncated, which every other rule also does. The order was simply not
-    // its decision to make.
-    //
-    // So rules hand over the whole line and the boundary does both jobs, in
-    // the only order that is safe. Rules that redact per match still may:
-    // masking a known secret before this point is additive, and truncating an
-    // already-truncated string is a no-op.
+    // 先脱敏再截断，避免截断导致凭据特征失效。
     excerpt: f.excerpt === null ? null : truncate(clean(f.excerpt)),
     fix: f.fix.map(clean),
     ...f.humanOnly ? { humanOnly: f.humanOnly.map(clean) } : {}
@@ -3394,19 +3393,15 @@ async function scan(root, options = {}) {
   const { files, skipped, ignored, vendored } = collectFiles(root, git2 === "repo", gitExecutable);
   const findings = [];
   const errors = [];
+  const fileRules = FILE_RULES.filter((rule) => shouldRunRule(rule.id, options.only ?? [], options.skip ?? []));
+  const projectRules = PROJECT_RULES.filter((rule) => shouldRunRule(rule.id, options.only ?? [], options.skip ?? []));
   const incompleteSeen = /* @__PURE__ */ new Set();
   const ctx = {
     root,
     files,
     git: git2,
     gitExecutable,
-    // Deduplicated here rather than by each rule remembering to report once.
-    // A rule that reaches the same ceiling from two loops over the same file —
-    // firebase does, once for open rules and once for test-mode rules — said
-    // the identical sentence twice, in the terminal's incomplete section and in
-    // the JSON. Saying "part of this did not happen" twice does not make it
-    // twice as true, and a once-flag per rule is the kind of bookkeeping every
-    // new rule would have to remember.
+    // 统一记录不完整状态，避免重复提示。
     reportIncomplete: (ruleId, message) => {
       if (incompleteSeen.has(`${ruleId} ${message}`)) return;
       incompleteSeen.add(`${ruleId} ${message}`);
@@ -3414,16 +3409,16 @@ async function scan(root, options = {}) {
     }
   };
   for (const file of files) {
-    for (const rule of FILE_RULES) {
-      if (!rule.appliesTo(file)) continue;
+    for (const rule of fileRules) {
       try {
+        if (!rule.appliesTo(file)) continue;
         findings.push(...rule.check(file, ctx));
       } catch (err) {
         errors.push({ ruleId: rule.id, file: file.path, message: messageOf(err), kind: "crashed" });
       }
     }
   }
-  for (const rule of PROJECT_RULES) {
+  for (const rule of projectRules) {
     try {
       findings.push(...await rule.check(ctx));
     } catch (err) {
@@ -3435,8 +3430,19 @@ async function scan(root, options = {}) {
     files
   );
   const selected = applyRuleSelection(kept, options);
+  const counts = /* @__PURE__ */ new Map();
+  const bounded = sortFindings(selected.kept).filter((finding) => {
+    const count = (counts.get(finding.file) ?? 0) + 1;
+    counts.set(finding.file, count);
+    if (count <= MAX_FINDINGS_PER_FILE) return true;
+    if (count === MAX_FINDINGS_PER_FILE + 1) ctx.reportIncomplete(
+      "engine/findings-limit",
+      `${finding.file ?? "project"} has more than ${MAX_FINDINGS_PER_FILE} findings; remaining findings were not reported`
+    );
+    return false;
+  });
   return {
-    findings: sanitize(sortFindings(selected.kept), files),
+    findings: sanitize(bounded, files),
     filesScanned: files.length,
     durationMs: Date.now() - started,
     errors: errors.map((e) => ({
@@ -3446,29 +3452,16 @@ async function scan(root, options = {}) {
     })),
     skipped: sanitizeSkippedForOutput(skipped),
     ignored: ignored.map(clean),
-    // The path goes through the boundary like every other path that reaches a
-    // reader: a filename is chosen by whoever can add a file to the repository,
-    // and one holding a credential would otherwise print it here in full.
+    // 清理被忽略结果的路径。
     ignoredFindings: ignoredFindings.map((f) => ({ ...f, file: clean(f.file) })),
-    // Selectors come from a config file or the command line, both of which are
-    // text canship prints back, so both go through the boundary.
+    // 选择器来自外部输入，输出前也需清理。
     ruleSelection: selected.selection === null ? null : {
       only: selected.selection.only.map(clean),
       skip: selected.selection.skip.map(clean),
       removed: selected.selection.removed
     },
     vendored,
-    // A deliberate opt-out is not an incomplete scan: the user made that call
-    // knowingly. It is listed in the report, not treated as a failure.
-    //
-    // Examining no files at all, however, is the purest form of an incomplete
-    // scan, and it used to print a green tick and exit 0 — the exact outcome
-    // the README says must never share an exit code with "clean". It is also
-    // the most likely way to be wrong in practice: the headline command is
-    // `npx canship` with no argument, so running it from the wrong directory
-    // is the ordinary user error, and a directory holding nothing but a
-    // build/ folder (every entry of which the walker skips by design) reaches
-    // zero without looking empty to a human.
+    // 主动忽略不影响完整性；错误、跳过或零文件扫描均标记为未完成。
     partial: errors.length > 0 || skipped.length > 0 || files.length === 0
   };
 }
@@ -3543,8 +3536,7 @@ function renderBaseline(opts) {
   }
   if (stale > 0) {
     out.push(
-      // Not plural() — that helper only appends an s, and "entrys" is not a
-      // word. The irregular ones have to be written out.
+      // 不规则复数单独处理。
       `${INDENT}${dim(`${stale} baseline ${stale === 1 ? "entry" : "entries"} no longer ${stale === 1 ? "matches" : "match"} anything \u2014 re-run --baseline-write to prune.`)}`
     );
   }
@@ -3938,22 +3930,17 @@ function renderHtml(result, opts) {
   const baselineStale = opts.baselineStale ?? 0;
   const { blocking: certain, minor, unsure } = verdictOf(findings);
   const verdict = findings.length === 0 ? result.filesScanned === 0 ? (
-    // Examined nothing, so there is nothing to report either way.
+    // 未扫描文件时不显示通过结论。
     `<div class="verdict warn">No files were scanned &mdash; nothing was checked</div>`
   ) : result.partial ? (
-    // Never the green banner on a partial scan: it reads as a guarantee,
-    // and a scan that skipped files cannot make one.
+    // 扫描不完整时不得显示正常通过。
     hiddenLikely > 0 ? `<div class="verdict warn">No certain findings &mdash; ${hiddenLikely} lower-confidence ${plural(hiddenLikely, "finding")} hidden, and not everything was checked</div>` : `<div class="verdict warn">No findings &mdash; but not everything was checked</div>`
   ) : hiddenLikely > 0 ? `<div class="verdict warn">No certain findings &mdash; ${hiddenLikely} lower-confidence ${plural(hiddenLikely, "finding")} hidden</div>` : (
-    // The green banner is a statement about the project. A baseline
-    // makes it a statement about the diff instead, and this document
-    // outlives the run that produced it — whoever opens it later has
-    // only the banner to go on.
+    // 基线抑制结果时明确说明，避免误报为项目无问题。
     baselineSuppressed > 0 ? `<div class="verdict warn">No new findings &mdash; ${baselineSuppressed} ${plural(baselineSuppressed, "finding")} accepted by the baseline</div>` : `<div class="verdict clean">No exposed credentials found</div>`
   ) : certain > 0 ? `<div class="verdict bad">${certain} critical ${plural(certain, "issue")} &mdash; do not deploy</div>` : minor > 0 ? `<div class="verdict warn">${minor} ${plural(minor, "thing")} to fix &mdash; nothing exposed</div>` : `<div class="verdict warn">${unsure} possible ${plural(unsure, "issue")} to review</div>`;
   const body = findings.length === 0 ? result.filesScanned === 0 ? (
-    // The checklist below would be a false statement here: none of those
-    // checks had any input to run against.
+    // 零文件扫描不能显示已完成的检查清单。
     `<div class="clean-note">
            <p>canship found no files it could read at this path, so none of its checks ran.
            <strong>This is not a clean result &mdash; it is an empty one.</strong></p>
@@ -3988,10 +3975,7 @@ function renderHtml(result, opts) {
   const incomplete = result.partial ? `<div class="incomplete">
          <h2>Not everything was checked</h2>
          <ul>
-           ${// Reachable with findings present: a repository whose working
-  // tree is entirely gitignored still has a git history, and the
-  // history rule reads it. The findings are real; the file-based
-  // checks simply never ran.
+           ${// 工作区零文件时仍可能产生 Git 历史结果。
   result.filesScanned === 0 ? `<li>no files could be read at this path, so every file-based check was skipped</li>` : ""}
            ${result.errors.map(
     (e) => `<li>the <code>${esc(e.ruleId)}</code> check ${e.kind === "incomplete" ? "did not finish" : "failed"}${e.file ? ` on <code>${esc(e.file)}</code>` : ""} &mdash; ${esc(e.message)}</li>`
@@ -4276,8 +4260,7 @@ function rulesOf(findings) {
       text: [...f.why, ...f.fix.length > 0 ? ["How to fix:", ...f.fix] : []].join("\n")
     },
     properties: {
-      // Not part of the SARIF vocabulary, so it travels as a property rather
-      // than being mangled into one of the three levels above.
+      // 工具专属严重度和置信度保存在扩展属性中。
       "canship-severity": f.severity,
       "canship-confidence": f.confidence
     },
@@ -4289,15 +4272,12 @@ function resultsOf(findings) {
     ruleId: f.ruleId,
     level: levelOf(f),
     message: { text: f.title },
-    // A finding with no file — git history, an RLS gap spanning migrations —
-    // gets no location rather than a made-up one. SARIF permits that, and
-    // pointing it at an arbitrary file would put an annotation on a line that
-    // has nothing to do with it.
+    // 无可定位文件时不构造虚假位置。
     locations: f.file === null ? [] : [
       {
         physicalLocation: {
-          // Already relative and already slash-separated, on Windows too.
-          artifactLocation: { uri: f.file },
+          // 按路径段进行 URI 编码，保留目录分隔符。
+          artifactLocation: { uri: f.file.split("/").map((part) => encodeURIComponent(part)).join("/") },
           ...f.line === null ? {} : { region: { startLine: f.line } }
         }
       }
@@ -4308,6 +4288,10 @@ function resultsOf(findings) {
 function renderSarif(result, opts) {
   const { findings } = result;
   const notifications = [
+    ...result.skipped.map((item) => ({
+      level: "warning",
+      message: { text: `${item.path}: ${item.reason}${item.detail ? ` \u2014 ${item.detail}` : ""}` }
+    })),
     ...result.errors.map((e) => ({
       level: e.kind === "crashed" ? "error" : "warning",
       message: { text: `${e.ruleId}: ${e.message}` }
@@ -4330,9 +4314,7 @@ function renderSarif(result, opts) {
         results: resultsOf(findings),
         invocations: [
           {
-            // False when a rule crashed or a file could not be read. It is not
-            // about whether findings exist — a scan that finds problems and
-            // completes was a successful invocation.
+            // 该字段表示执行是否完整，与是否发现问题无关。
             executionSuccessful: !result.partial,
             ...notifications.length > 0 ? { toolExecutionNotifications: notifications } : {}
           }
@@ -4435,7 +4417,7 @@ function loadConfig(root) {
 }
 
 // src/cli.ts
-var VERSION = true ? "0.2.0" : "0.0.0-dev";
+var VERSION = true ? "0.2.1" : "0.0.0-dev";
 function argumentError(message) {
   process.stderr.write(`canship: ${cleanForOutput(message)}
 `);
@@ -4600,8 +4582,8 @@ var HELP = `
         --baseline[=F]       Hide findings already recorded in F, so only new
                              ones are reported (default ${DEFAULT_BASELINE_PATH})
         --baseline-write[=F] Record the current findings as a new baseline and exit
-        --only=IDS    Report only these rules (comma-separated, repeatable)
-        --skip=IDS    Report everything except these rules
+        --only=IDS    Run matching rules (comma-separated, repeatable)
+        --skip=IDS    Exclude matching rules
         --sarif[=F]   Write a SARIF 2.1.0 log for CI code scanning
                       (default canship.sarif)
         --no-config   Ignore canship.config.json in the scanned directory
@@ -4760,8 +4742,7 @@ ${cleanForOutput(String(err))}
           root: displayRoot,
           filesScanned: result.filesScanned,
           durationMs: result.durationMs,
-          // Machine consumers need the same distinction humans get: an empty
-          // findings array from a partial scan is not a pass.
+          // 空结果不能掩盖扫描未完成。
           partial: result.partial,
           errors: result.errors,
           skipped: result.skipped,
@@ -4769,13 +4750,9 @@ ${cleanForOutput(String(err))}
           ignoredFindings: result.ignoredFindings,
           ruleSelection: result.ruleSelection,
           vendored: result.vendored,
-          // The default view hides the detail, never the fact. A machine reading this
-          // must not see "no findings" while lower-confidence ones exist.
+          // 隐藏详情时仍披露疑似结果数量。
           hiddenLikely,
-          // Same reason, for the other thing that removes findings from this
-          // array. A CI job reading `findings: []` is entitled to know whether
-          // that means "nothing is wrong" or "a file in your repository says
-          // not to mention it".
+          // 明确披露基线抑制和过期条目数量。
           baselineSuppressed,
           baselineStale,
           findings: shown