@ultime/codecraft 1.3.0 → 1.5.0

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) {