@ultime/codecraft 1.4.0 → 1.6.0

package/scenarios/architecture-report.md

@@ -0,0 +1,88 @@
+# Architecture Report（代码架构分析报告）
+
+> 定位：把代码架构讲清楚，形成一份人能读、能评审、能执行的 Markdown 文档。
+> 范围：只做代码架构；业务能力、角色、业务流程、领域规则不在本 skill 范围。
+> 关系：方法见 `docs/06-architecture.md`；证据门槛见 `docs/08-audit-contract.md`；模板见 `templates/architecture-report.md`。
+
+## 何时用
+
+- 接手老项目，需要一份能读的代码架构说明。
+- 重构 / 迁移 / 拆包前，先固定现状与约束。
+- 新项目立项，需要目标架构、边界与阶段计划。
+- 向人 / 客户汇报代码架构（不含业务架构）。
+
+不适用：业务能力地图、角色与流程、领域建模、UI 设计、运行时性能、渗透测试。
+
+## 输入
+
+- 仓库路径 / 分支 / 目录范围。
+- 模式：老项目 `Audit`；新项目 `Plan`；只出报告 `Audit`。
+- 目标：体检 / 重构 / 迁移 / 新建立 / 汇报。
+- 约束：能否跑命令、时间范围、必须保留的边界。
+- 已知业务背景（可选）：只作为上下文，不写成业务架构结论。
+
+## 先读
+
+1. 项目 `AGENTS.md` / `rules/`
+2. `docs/00-constitution.md`
+3. `docs/06-architecture.md`
+4. 只读相关族卡：`docs/01-family-cards.md`
+5. 审计模式：`docs/08-audit-contract.md`
+6. 输出：`prompts/output.md` + `templates/architecture-report.md`
+
+## 步骤
+
+1. **确认范围**：仓库 / 目录 / 包、只读声明、能否跑命令、本次不覆盖什么。
+2. **盘点**：技术栈、入口、页面 / 路由、模块、包、请求层、状态、类型、生成物、测试与门禁。
+3. **结构**（用表格 / 列表，不画图）：
+   - 系统上下文：外部系统、运行时、部署单元。
+   - 容器 / 模块：职责、边界、依赖方向。
+   - 公共 API：哪些是契约，哪些是内部实现。
+4. **关键链路**：请求链、状态链、错误模型、数据流、生成链；每段给 `file:line`。
+5. **跑静态检查**：`codecraft check / audit`，记录 `files / findings / 覆盖范围`；写明 A17 / A21 盲区。
+6. **逐条判定**：A1–A21，标 `pass` / `pass（静态）` / `warn` / `fail` / `na`，每条带证据与局限。
+7. **风险与技术债**：按 P0–P3 排；区分「已发生」与「可能发生」。
+8. **演进计划**：
+   - 老项目：现状 → 目标 → 分阶段迁移，每阶段可回滚、有验收命令。
+   - 新项目：目标架构 → 边界 → 目录 / 契约 → 阶段计划。
+9. **未知项**：没有证据的角色、规则、运行时行为单列，不猜。
+
+## 输出
+
+- 一份 Markdown 报告，按 `templates/architecture-report.md`。
+- 默认不画图；用表格、列表、缩进表达结构。
+- 如果后续需要图，图只作为视图，源仍写在 Markdown 里，不把图片当唯一真源。
+- 报告落在项目 `docs/` 下；文件名建议 `<主题>-代码架构分析报告.md`，并纳入项目文档索引。
+
+## 证据
+
+- 每条结论给 `path/to/file:line`，或可复现命令。
+- 计数写检索式与统计口径（行 / 处 / 文件）。
+- `0 findings` 只能写「静态检查未命中」，不能写成「架构通过」。
+- 不写密钥、客户名、本机绝对路径；发现即停止并提示轮换。
+
+## 停止条件
+
+- 无法只读访问仓库。
+- 需要改动生产配置或运行服务才能判断。
+- 发现凭证 / 隐私。
+- 业务结论超出代码证据，必须由人确认。
+
+## 验收
+
+- 报告结构与模板一致，结论 / 证据 / 风险 / 计划 / 未知项齐全。
+- A1–A21 全覆盖或写 `na`；每条有证据。
+- 明确写了「只做代码架构，不含业务架构」。
+- Audit / Plan 模式未改任何文件。
+- 计数与命令可复现。
+
+## 与其他场景的区别
+
+| 场景 | 侧重 | 产出 |
+|---|---|---|
+| `audit-existing.md` | A1–A21 体检 | findings、差距、升级计划 |
+| `new-project.md` | 新项目设计 | 目标架构、骨架、阶段计划 |
+| `report-only.md` | 只要 findings | 只读问题清单 |
+| 本场景 | 结构叙事 + 演进 | 一份完整代码架构分析报告 |
+
+本场景可以复用 `audit-existing` 的 findings，但不重复做业务架构。

package/scenarios/audit-existing.md

@@ -15,17 +15,21 @@
 
 ## 步骤
 
-1. 盘点：技术栈、目录、页面、请求层、状态、类型、测试。
-2. 逐条对照 A1–A21；标 pass / warn / fail。
-3. 找“历史实现”与“环节缺失”：哪些是习惯，哪些是必需。
-4. 出差距清单：影响、成本、优先级。
-5. 出升级计划：分阶段、可回滚、每阶段验收。
-6. 风险：兼容、数据、权限、发布。
+1. 确认范围：仓库 / 分支 / 目录、只读声明、能否跑命令。
+2. 盘点：技术栈、目录、页面、请求层、状态、类型、测试。
+3. 先跑静态检查，记录 `files / findings` 与覆盖范围；写明 A17 / A21 盲区。
+4. 逐条对照 A1–A21；标 `pass` / `pass（静态）` / `warn` / `fail` / `na`，每条带证据。
+5. 做一致性检查：A4 / A8 / A11 / A17 / A21 与证据矛盾时降级。
+6. 找“历史实现”与“环节缺失”：哪些是习惯，哪些是必需。
+7. 出差距清单：影响、成本、优先级（P0–P3）。
+8. 出升级计划：分阶段、可回滚、每阶段验收；不写时间估算。
+9. 风险：兼容、数据、权限、发布。
 
 ## 输出
 
-- 体检报告
-- 差距清单（severity）
+- 体检报告（按 `docs/08-audit-contract.md`）
+- 逐条判定表（A1–A21，含证据与局限）
+- 差距清单（P0–P3）
 - 升级计划
 - 回滚方案
 
@@ -38,4 +42,7 @@
 ## 验收
 
 - 只读；不改代码
+- A1–A21 全覆盖或写明 `na`
 - 每条结论有文件路径 / 命令 / A-ID
+- `0 findings` 已注明“仅静态未命中”，没有写成通过
+- 计数可用文中命令复现

package/scenarios/new-project.md

@@ -17,7 +17,7 @@
 2. `../docs/00-constitution.md`
 3. `../docs/01-family-cards.md`（只读相关族）
 4. `../docs/03-style-map.md`
-5. `../docs/06-architecture.md`（档位 / 七步法 / 边界 / ADR）
+5. `../docs/06-architecture.md`（档位 / 七步法 / 边界）；决策用 ADR
 6. 需要选型时：`../docs/05-patterns.md`
 
 ## 步骤

package/scenarios/refactor-review.md

@@ -6,7 +6,7 @@
 
 ## 模式
 
-Apply（执行）或 Review（只评审）。
+Apply 或 Review（只评审）。
 
 ## 步骤
 

package/src/check.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
+import { matchPath } from './ignore.mjs'
 
 const SKIP_DIRS = new Set([
   'node_modules',
@@ -16,6 +17,10 @@ const SKIP_DIRS = new Set([
   '.output',
   '.turbo',
   '.cache',
+  '.agents',
+  '.trae',
+  '.claude',
+  '.cursor',
 ])
 
 const GENERATED_SKIP_DIRS = new Set(['node_modules', '.git', 'coverage', '.turbo', '.cache'])
@@ -23,6 +28,9 @@ const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue'
 const GENERATED_EXTENSIONS = new Set(['.ts', '.js', '.css', '.json', '.md'])
 const ALLOWED_SEGMENTS = new Set(['external', 'generated', 'api', 'adapters'])
 const GENERATED_MARKER = /生成物|generated|do not edit|勿手改|auto-generated|派生/i
+/** 只认文件头里的只读声明，避免把正文里的「派生」当成生成物。 */
+const GENERATED_HEADER =
+  /@generated|auto-generated|generated by|do not edit|本文件由.{0,60}生成|此文件由.{0,60}生成|本文件[^\n]{0,20}勿手改|此文件[^\n]{0,20}勿手改|由.{0,60}生成[^\n]{0,10}勿手改/i
 const SECRET_EXTENSIONS = new Set([
   '.ts',
   '.tsx',
@@ -37,6 +45,11 @@ const SECRET_EXTENSIONS = new Set([
   '.sh',
   '.toml',
   '.ini',
+  '.properties',
+  '.xml',
+  '.java',
+  '.kt',
+  '.gradle',
 ])
 const SECRET_SKIP_FILES = new Set(['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'])
 /** 文档里公开的示例值，不当作真实凭据。 */
@@ -44,10 +57,33 @@ const SECRET_ALLOW = new Set(['AKIAIOSFODNN7EXAMPLE'])
 const SECRET_PATTERNS = [
   { id: 'private key', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/ },
   { id: 'AWS access key', re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { id: 'Aliyun access key', re: /\bLTAI[0-9A-Za-z]{12,}\b/ },
   { id: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/ },
   { id: 'Slack token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
   { id: 'API secret key', re: /\bsk-[A-Za-z0-9]{20,}\b/ },
 ]
+/** 只在配置 / 后端源码里找明文赋值，避免把业务代码里的普通字符串当密钥。 */
+const ASSIGNMENT_EXTENSIONS = new Set([
+  '.yml',
+  '.yaml',
+  '.properties',
+  '.ini',
+  '.toml',
+  '.env',
+  '.conf',
+  '.config',
+  '.java',
+  '.kt',
+  '.gradle',
+  '.sh',
+])
+const SECRET_ASSIGN = /(?:^|[\s(])([A-Za-z0-9_.-]+)\s*(:|=)(?!=)\s*(.+?)\s*$/
+const SECRET_KEY = /(?:^|[._-])(password|passwd|pwd|secret|appsecret|api[._-]?key|access[._-]?key|token)(?:$|[._-])/i
+/** 代码里的 token 多数是运行时变量；后端源码只认强口令 / 密钥类字段。 */
+const SECRET_KEY_CODE = /(?:^|[._-])(password|passwd|pwd|secret|appsecret|api[._-]?key|access[._-]?key)(?:$|[._-])/i
+const SECRET_KEY_EXCLUDE = /(url|uri|type|name|expires?|expiry|ttl|header|prefix|suffix|length|count|timeout)$/i
+const SECRET_PLACEHOLDER =
+  /^(?:\$\{.*\}|\$[A-Za-z_][A-Za-z0-9_]*|#\{.*\}|%.*%|<.*>|\*+|-+|null|true|false|none|undefined|todo.*|xxx+|[a-z]*example[a-z]*|placeholder.*|your[-_].*|change[-_]?me|process\.env\..*|os\.environ.*|System\..*|getenv.*)$/i
 /** 只认内部文档特征：向上一级找根 docs，或 Ultime 的内部目录名；包自带的 docs/ 不算。 */
 const DOC_PATH = /(?:^|[\s(`'"])(?:(?:\.\.\/)+docs\/|(?:docs\/)?(?:开发计划|设计系统|工程机制)\/)/
 
@@ -57,48 +93,84 @@ const IMPORT_PATTERNS = [
   /^\s*import\s+['"]([^'"]+)['"]/gm,
 ]
 
+const EMPTY_CATCH = /\bcatch\s*(?:\([^)]*\))?\s*\{([\s\S]*?)\}/g
+
 export function check(root, options = {}) {
   const absRoot = path.resolve(root)
   const pack = options.pack ?? 'app'
-  if (pack === 'library') return checkLibrary(absRoot)
-  if (pack === 'design-system') return checkDesignSystem(absRoot)
-  return checkApp(absRoot)
+  if (pack === 'library') return checkLibrary(absRoot, options)
+  if (pack === 'design-system') return checkDesignSystem(absRoot, options)
+  return checkApp(absRoot, options)
 }
 
-function checkApp(root) {
-  const files = collectAppFiles(root)
+function checkApp(root, options = {}) {
+  const isExcluded = createExcluder(root, options.exclude)
+  const files = collectAppFiles(root).filter((file) => !isExcluded(file) && !isMinified(file))
+  const generated = collectGeneratedFiles(files)
   const findings = []
-  for (const file of files) findings.push(...scanAppFile(file, root))
-  findings.push(...scanSecrets(root))
+  for (const file of files) findings.push(...scanAppFile(file, root, options.boundaries, generated))
+  findings.push(...scanSecrets(root, isExcluded))
   return { root, files: files.length, findings }
 }
 
-function checkLibrary(root) {
-  return checkPackages(root, { docPaths: false })
+function checkLibrary(root, options = {}) {
+  return checkPackages(root, {
+    docPaths: false,
+    boundaries: options.boundaries,
+    exclude: options.exclude,
+  })
 }
 
-function checkDesignSystem(root) {
-  return checkPackages(root, { docPaths: true })
+function checkDesignSystem(root, options = {}) {
+  return checkPackages(root, {
+    docPaths: true,
+    boundaries: options.boundaries,
+    exclude: options.exclude,
+  })
 }
 
 function checkPackages(root, options) {
-  const packages = findPackages(root)
+  const isExcluded = createExcluder(root, options.exclude)
+  const packages = findPackages(root).filter((pkg) => !isExcluded(pkg))
   const manifests = packages.map((pkg) => readJson(path.join(pkg, 'package.json')))
   const workspaceNames = new Set(manifests.map((manifest) => manifest?.name).filter(Boolean))
   const findings = []
   let files = 0
 
   for (let i = 0; i < packages.length; i += 1) {
-    const result = checkPackage(packages[i], manifests[i], workspaceNames)
+    const result = checkPackage(packages[i], manifests[i], workspaceNames, isExcluded)
     files += result.files
     findings.push(...result.findings)
-    if (options.docPaths) findings.push(...scanPackageDocs(packages[i]))
+    if (options.docPaths) findings.push(...scanPackageDocs(packages[i], isExcluded))
   }
 
-  findings.push(...scanSecrets(root))
+  findings.push(...scanSecrets(root, isExcluded))
   return { root, files, findings }
 }
 
+/**
+ * 扫描级排除：在收集文件时就跳过，不产生 findings。
+ * 与 ignore 不同，它不能豁免已发现的问题，只用于不扫描（例如测试 fixture、第三方目录）。
+ */
+function createExcluder(root, patterns = []) {
+  const list = (patterns ?? [])
+    .map((pattern) => String(pattern).replace(/\\/g, '/').replace(/^\.\//, ''))
+    .filter(Boolean)
+  if (!list.length) return () => false
+
+  return (file) => {
+    const relative = path.relative(root, file).split(path.sep).join('/')
+    return list.some((pattern) => matchesExclude(pattern, relative))
+  }
+}
+
+function matchesExclude(pattern, relative) {
+  if (matchPath(pattern, relative)) return true
+  if (/[*?]/.test(pattern)) return false
+  const base = pattern.replace(/\/$/, '')
+  return relative === base || relative.startsWith(`${base}/`)
+}
+
 function findPackages(root) {
   const packagesDir = path.join(root, 'packages')
   if (isDir(packagesDir)) {
@@ -112,7 +184,7 @@ function findPackages(root) {
   return []
 }
 
-function checkPackage(pkg, manifest, workspaceNames) {
+function checkPackage(pkg, manifest, workspaceNames, isExcluded = () => false) {
   const name = manifest?.name ?? ''
   const deps = new Set([
     ...Object.keys(manifest?.dependencies ?? {}),
@@ -120,7 +192,9 @@ function checkPackage(pkg, manifest, workspaceNames) {
     ...Object.keys(manifest?.devDependencies ?? {}),
   ])
   const src = path.join(pkg, 'src')
-  const sourceFiles = isDir(src) ? walkFiles(src) : []
+  const sourceFiles = (isDir(src) ? walkFiles(src) : []).filter(
+    (file) => !isExcluded(file) && !isMinified(file),
+  )
   const findings = []
 
   for (const file of sourceFiles) {
@@ -137,9 +211,10 @@ function checkPackage(pkg, manifest, workspaceNames) {
         message,
       })
     }
+    findings.push(...scanEmptyCatch(text, file, pkg))
   }
 
-  for (const file of collectGeneratedCandidates(pkg)) {
+  for (const file of collectGeneratedCandidates(pkg).filter((file) => !isExcluded(file))) {
     const text = read(file)
     if (text == null || hasGeneratedMarker(text)) continue
     findings.push({
@@ -180,6 +255,21 @@ function collectAppFiles(root) {
   return files
 }
 
+function collectGeneratedFiles(files) {
+  const generated = new Map()
+  for (const file of files) {
+    const text = read(file)
+    if (text == null || !hasGeneratedHeader(text)) continue
+    generated.set(path.resolve(file), { types: exportsTypes(text) })
+  }
+  return generated
+}
+
+/** A17 只关心外部类型契约；生成的数据 / 资源模块不算。 */
+function exportsTypes(text) {
+  return /\bexport\s+(?:declare\s+)?(?:interface|type|enum)\b/.test(text)
+}
+
 function collectAppRoots(root) {
   const roots = []
   const apps = path.join(root, 'apps')
@@ -264,21 +354,42 @@ function walkGenerated(dir, files, seen) {
   }
 }
 
-function scanAppFile(file, root) {
-  if (isAllowedImporter(file, root)) return []
-
+function scanAppFile(file, root, boundaries, generated) {
   const text = read(file)
   if (text == null) return []
+  if (generated?.has(path.resolve(file))) return []
 
   const findings = []
-  for (const { spec, line } of collectImports(stripComments(text))) {
-    if (!isExternalSpec(spec)) continue
+  if (!isAllowedImporter(file, root)) {
+    for (const { spec, line } of collectImports(stripComments(text))) {
+      const generatedImport = generated?.size ? resolveGeneratedImport(spec, file, root, generated) : false
+      if (!generatedImport && !isExternalSpec(spec, boundaries)) continue
+      findings.push({
+        rule: 'A17',
+        severity: 'warn',
+        file: path.relative(root, file),
+        line,
+        message: generatedImport
+          ? `imports generated type "${spec}"; access it through Wrapper/API (A17)`
+          : `imports external type "${spec}"; only Wrapper/API may import external/generated (A17)`,
+      })
+    }
+  }
+  findings.push(...scanEmptyCatch(text, file, root))
+  return findings
+}
+
+function scanEmptyCatch(text, file, root) {
+  const findings = []
+  const source = stripComments(text)
+  for (const match of source.matchAll(EMPTY_CATCH)) {
+    if (match[1].trim()) continue
     findings.push({
-      rule: 'A17',
+      rule: 'A6',
       severity: 'warn',
       file: path.relative(root, file),
-      line,
-      message: `imports external type "${spec}"; only Wrapper/API may import external/generated (A17)`,
+      line: lineAt(source, match.index ?? 0),
+      message: 'empty catch swallows failures; return a Result or handle the error (A6)',
     })
   }
   return findings
@@ -315,41 +426,174 @@ function hasGeneratedMarker(text) {
   return GENERATED_MARKER.test(text.split('\n').slice(0, 20).join('\n'))
 }
 
+function hasGeneratedHeader(text) {
+  return GENERATED_HEADER.test(text.split('\n').slice(0, 3).join('\n'))
+}
+
+function resolveGeneratedImport(spec, importer, root, generated) {
+  const target = resolveImportFile(spec, importer, root)
+  if (!target) return false
+  return generated.get(path.resolve(target))?.types === true
+}
+
+function resolveImportFile(spec, importer, root) {
+  const bases = []
+  if (spec.startsWith('.')) {
+    bases.push(path.resolve(path.dirname(importer), spec))
+  } else if (/^[@~#]{1,2}\//.test(spec)) {
+    const rest = spec.replace(/^[@~#]{1,2}\//, '')
+    const srcRoot = findSrcRoot(importer)
+    if (srcRoot) bases.push(path.resolve(srcRoot, rest))
+    bases.push(path.resolve(root, rest), path.resolve(root, 'src', rest))
+  } else {
+    return null
+  }
+
+  const extensions = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte', '.d.ts']
+  for (const base of bases) {
+    for (const extension of extensions) {
+      if (isFile(`${base}${extension}`)) return `${base}${extension}`
+    }
+    for (const extension of extensions) {
+      const index = path.join(base, `index${extension}`)
+      if (isFile(index)) return index
+    }
+  }
+  return null
+}
+
+function findSrcRoot(file) {
+  const parts = path.dirname(file).split(path.sep)
+  const index = parts.lastIndexOf('src')
+  return index === -1 ? null : parts.slice(0, index + 1).join(path.sep) || path.sep
+}
+
+function isFile(target) {
+  try {
+    return fs.statSync(target).isFile()
+  } catch {
+    return false
+  }
+}
+
 function isAllowedImporter(file, root) {
   const segments = path.relative(root, file).split(path.sep)
   return segments.some((segment) => ALLOWED_SEGMENTS.has(segment))
 }
 
-function isExternalSpec(spec) {
-  return /(^|[/@])(external|generated)([/]|$)/.test(spec)
+function isExternalSpec(spec, boundaries) {
+  if (/(^|[/@])(external|generated)([/]|$)/.test(spec)) return true
+  const patterns = [...(boundaries?.external ?? []), ...(boundaries?.generated ?? [])]
+  return patterns.some((pattern) => matchesBoundary(spec, pattern))
+}
+
+function matchesBoundary(spec, pattern) {
+  if (!pattern) return false
+  if (spec === pattern || spec.startsWith(`${pattern.replace(/\/$/, '')}/`)) return true
+  return /[*?]/.test(pattern) && matchPath(pattern, spec)
 }
 
 function isTestFile(file) {
   return /(^|[/\\])(__tests__|tests?)[/\\]/.test(file) || /\.(test|spec)\.[^.]+$/.test(file)
 }
 
-function scanSecrets(root) {
+/** 压缩 / 构建产物：结构规则跳过（A21 仍扫描），避免与源码重复报同一问题。 */
+function isMinified(file) {
+  const text = read(file)
+  if (text == null) return false
+  const lines = text.split('\n')
+  if (lines.length > 3) return false
+  return lines.some((line) => line.length > 1000)
+}
+
+function scanSecrets(root, isExcluded = () => false) {
   const findings = []
+  const seen = new Set()
   for (const file of collectScanFiles(root)) {
+    if (isExcluded(file)) continue
     if (SECRET_SKIP_FILES.has(path.basename(file))) continue
+    if (isTestFile(file)) continue
     const text = read(file)
     if (text == null) continue
+
     for (const pattern of SECRET_PATTERNS) {
-      const match = pattern.re.exec(text)
-      if (!match) continue
-      if (SECRET_ALLOW.has(match[0])) continue
-      findings.push({
+      for (const match of text.matchAll(globalize(pattern.re))) {
+        if (SECRET_ALLOW.has(match[0])) continue
+        pushSecret(findings, seen, {
+          rule: 'A21',
+          severity: 'warn',
+          file: path.relative(root, file),
+          line: lineAt(text, match.index ?? 0),
+          message: `possible ${pattern.id}; remove it and rotate the credential (A21)`,
+        })
+      }
+    }
+
+    const kind = assignmentKind(file)
+    if (!kind) continue
+    text.split('\n').forEach((line, index) => {
+      const assignment = parseSecretAssignment(line, kind)
+      if (!assignment) return
+      pushSecret(findings, seen, {
         rule: 'A21',
         severity: 'warn',
         file: path.relative(root, file),
-        line: lineAt(text, match.index ?? 0),
-        message: `possible ${pattern.id}; remove it and rotate the credential (A21)`,
+        line: index + 1,
+        message: `plaintext ${assignment.key}; move it to env / config center and rotate (A21)`,
       })
-    }
+    })
   }
   return findings
 }
 
+function globalize(re) {
+  return new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`)
+}
+
+function pushSecret(findings, seen, finding) {
+  const key = `${finding.file}:${finding.line}`
+  if (seen.has(key)) return
+  seen.add(key)
+  findings.push(finding)
+}
+
+function parseSecretAssignment(line, kind) {
+  const trimmed = line.trim()
+  if (!trimmed || /^(#|\/\/|\*|<!--)/.test(trimmed)) return null
+  const match = SECRET_ASSIGN.exec(line)
+  if (!match) return null
+  const key = match[1]
+  const keyPattern = kind === 'code' ? SECRET_KEY_CODE : SECRET_KEY
+  if (!keyPattern.test(key) || SECRET_KEY_EXCLUDE.test(key)) return null
+  if (kind === 'code' && !/^["']/.test(match[3].trim())) return null
+  const value = cleanSecretValue(match[3])
+  if (value.length < 6 || SECRET_PLACEHOLDER.test(value)) return null
+  return { key }
+}
+
+function cleanSecretValue(raw) {
+  const trimmed = raw.trim()
+  const quoted = /^(["'`])([\s\S]*?)\1/.exec(trimmed)
+  const value = quoted ? quoted[2] : trimmed.split(/\s+/)[0]
+  return value
+    .replace(/\s+#.*$/, '')
+    .replace(/[;,]\s*$/, '')
+    .trim()
+}
+
+function assignmentKind(file) {
+  const base = path.basename(file)
+  if (base === '.env' || base.startsWith('.env.')) return 'config'
+  const extension = path.extname(base)
+  if (extension === '.java' || extension === '.kt') return 'code'
+  return ASSIGNMENT_EXTENSIONS.has(extension) ? 'config' : null
+}
+
+function isSecretFile(name) {
+  if (name === '.env' || name.startsWith('.env.')) return true
+  return SECRET_EXTENSIONS.has(path.extname(name))
+}
+
 function collectScanFiles(root) {
   const files = []
   walkScan(root, files, new Set())
@@ -374,11 +618,11 @@ function walkScan(dir, files, seen) {
       continue
     }
     if (!entry.isFile()) continue
-    if (SECRET_EXTENSIONS.has(path.extname(entry.name))) files.push(full)
+    if (isSecretFile(entry.name)) files.push(full)
   }
 }
 
-function scanPackageDocs(pkg) {
+function scanPackageDocs(pkg, isExcluded = () => false) {
   const findings = []
   const files = ['README.md', 'USAGE.md', 'CHANGELOG.md', 'compat.md']
     .map((name) => path.join(pkg, name))
@@ -392,6 +636,7 @@ function scanPackageDocs(pkg) {
   }
 
   for (const file of files) {
+    if (isExcluded(file)) continue
     const text = read(file)
     if (text == null) continue
     text.split('\n').forEach((line, index) => {
@@ -411,11 +656,16 @@ function scanPackageDocs(pkg) {
 
 function stripComments(text) {
   return text
-    .replace(/<!--[\s\S]*?-->/g, '')
-    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/<!--[\s\S]*?-->/g, maskComment)
+    .replace(/\/\*[\s\S]*?\*\//g, maskComment)
     .replace(/(^|[^:])\/\/[^\n]*/g, '$1')
 }
 
+/** 用等长空白替换注释，保留换行，避免行号漂移。 */
+function maskComment(match) {
+  return match.replace(/[^\n]/g, ' ')
+}
+
 function lineAt(text, index) {
   let line = 1
   for (let i = 0; i < index; i += 1) {