repo-audit-tool 1.2.3 → 1.3.0

package/BEST-PRACTICES.md

@@ -159,7 +159,7 @@ gh repo edit <org>/dsh-<name> --add-topic deepseek-harness --add-topic dsh-plugi
 2. **peer 同范围复制进 devDependencies**（社区事实标准）：peer 不进自身依赖树 → tsc/测试/CI 找不到类型
 3. **单库化坑（subagent-router 实战）**：单库独立安装不装宿主包的 peer——**运行时可达的宿主 peer 包全部显式进 devDependencies**；判定法：`npm test` 报 `Cannot find package` 逐个补
 4. **devDep 精确 pin 特例**：`dsh-client-ui-slots` 的 module augmentation 要求与 runtime 解析副本一致，caret 会漂移致 SlotMap 双副本 → 该包 pin 精确版本（0.2.0 踩过 TS2664/TS2345）
-5. **版本锁定分工**：范围写 package.json（caret），具体版靠提交入库的 `package-lock.json`；CI `npm ci --legacy-peer-deps`（dsh alpha 生态 peer 链不完整）
+5. **版本锁定分工**：范围写 package.json（caret），具体版靠提交入库的 `package-lock.json`；CI `npm ci --legacy-peer-deps`（dsh alpha 生态 peer 链不完整）。锁文件的核心价值在**被消费**：CI/验证链必须实际安装它（`npm ci` / `pip install -r requirements.lock`）——只入库不安装是装饰性合规；`requirements.lock` 非 pip 原生锁格式，没有默认消费者，CI 须显式安装；零依赖仓（依赖声明为空）无锁对象，可豁免。
 
 ### 5.3 dual ESM/CJS（外部调研结论）
 

package/docs/AGENT-INDEX.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "repo-audit 文档索引",
   "description": "AI Agent 可读的文档索引 — 包含所有文档的元数据、结构、和调用协议",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "updated": "2026-09-06",
   "repo": "NinjaSln-labs/repo-audit",
   "npm": "repo-audit-tool",
@@ -20,7 +20,7 @@
     "name": "repo-audit",
     "description": "仓库标准化审计工具 + 工程脚手架生成器（零依赖）",
     "bin": "repo-audit",
-    "version": "1.2.3",
+    "version": "1.3.0",
     "language": "JavaScript (ESM)",
     "runtime": "Node.js >= 18",
     "dependencies": [],
@@ -231,6 +231,7 @@
   },
 
   "changelog": {
+    "1.3.0": "反馈修复：yaml_field 行内注释剥离 + fallback_field 通配（SEC-004 兼容 job 级权限）；AGENTS-core 来源声明二选一；QUA-004 锁文件消费意图；手册补 --update 存量补齐动线",
     "1.2.3": "package.json 补充 repository 字段，修复 npm provenance E422；完成 Trusted Publisher tag 自动发布",
     "1.2.2": "publish CI 改用 node 22 + 条件升级 npm，修复 EBADENGINE（tag 发布因 1.2.1 已存在未出包）",
     "1.2.1": "README 链接改为绝对 URL（修复 npm 页面 404）",

package/docs/repo-audit/AGENT-GUIDE.md

@@ -191,7 +191,29 @@ cat audit-report/report.json | jq '.findings[] | select(.status=="fail") | .id'
 # 5. 如有 Critical 发现，阻断生成流程
 ```
 
-### 4.2 模板升级后校验
+### 4.2 存量仓库补齐缺失文档（Issue#3 动线）
+
+审计 fail 后需要补 AGENTS.md / CONTRIBUTING.md 等模板文档时，**优先用 `scaffold --update` 而不是手写**：
+
+```bash
+# 1. 存量仓首次接入（无 .scaffold/lock/）——adopt 模式，零覆盖保证
+node scaffold.mjs --update <repo> --type <type> --dry-run   # 先看会落位什么
+node scaffold.mjs --update <repo> --type <type>            # 实际执行
+
+# 2. 行为：
+#    - 仓库缺失的文件（如 AGENTS.md）→ ADDED 直拷
+#    - 仓库已有且与模板不同 → .scaffold-merge/ 人工评审区（不覆盖你的内容）
+#    - 工作区必须 clean（先 commit/stash）
+# 3. 补齐后重跑审计确认
+node repo-audit.mjs --repo <repo> --format json
+```
+
+要点：
+- `--update` 对**从未被 scaffold 管理的仓**同样可用（自动 adopt，建立 `.scaffold/lock/`）
+- 手写 AGENTS.md 时，**按来源声明二选一**：无 lock 的仓删除「单源拼装」行、保留「自主维护」行（模板头部已内置两种措辞）
+- `--skip <path>` 可排除不想让模板接管的文件（可多次）
+
+### 4.3 模板升级后校验
 
 ```bash
 # 1. 审计当前状态
@@ -209,7 +231,7 @@ after=$(cat ./audit-after/report.json | jq '.summary')
 # 如果 after.critical > before.critical → 告警：模板升级引入了问题
 ```
 
-### 4.3 CI 门禁集成
+### 4.4 CI 门禁集成
 
 ```yaml
 # GitHub Actions 示例
@@ -219,7 +241,7 @@ after=$(cat ./audit-after/report.json | jq '.summary')
     echo "Score: $(jq '.summary | 100 - (.critical * 25) - (.major * 10) - (.minor * 3)' ./.ci-audit/report.json)"
 ```
 
-### 4.4 增量维度审计
+### 4.5 增量维度审计
 
 ```bash
 # 只审计安全（快速）
@@ -232,7 +254,7 @@ node repo-audit.mjs --dim docs --format json
 node repo-audit.mjs --dim git --dim docs --dim security --dim quality --format json
 ```
 
-### 4.5 自定义规则叠加
+### 4.6 自定义规则叠加
 
 ```bash
 # 创建自定义规则

package/docs/repo-audit/HUMAN-GUIDE.md

@@ -507,10 +507,13 @@ node repo-audit.mjs --repo ./my-repo --type python-app
 | 操作 | 命令序列 |
 |---|---|
 | 新建仓库后验证 | `scaffold.mjs --type xxx --name yyy` → `repo-audit.mjs --repo ./yyy` |
+| **存量仓补齐缺失文档** | `scaffold.mjs --update ./zzz --type xxx --dry-run`（预览）→ `scaffold.mjs --update ./zzz`（执行；adopt 模式零覆盖）→ `repo-audit.mjs --repo ./zzz` 复审 |
 | 模板升级后对比 | `repo-audit.mjs --repo ./zzz --output ./before` → `scaffold.mjs --update ./zzz` → `repo-audit.mjs --repo ./zzz --output ./after` |
 | CI 门禁 | `repo-audit.mjs --repo . --strict --format json` |
 | PR 描述附件 | `repo-audit.mjs --repo . --format md --output ./pr-audit` → 附 `pr-audit/report.md` 到 PR |
 
+> **补 AGENTS.md 提示**（DOC-004 fail 时）：优先 `scaffold --update` 补齐（模板头部自带来源声明二选一）；确需手写时，无 `.scaffold/lock/` 的仓按「自主维护」措辞写头部，勿照抄「单源拼装」行。
+
 ---
 
 ## 十一、操作授权与完成路径

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-audit-tool",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "仓库标准化审计工具 + 工程脚手架生成器（零依赖）",
   "type": "module",
   "main": "repo-audit.mjs",

package/repo-audit.mjs

@@ -202,7 +202,48 @@ function countNonHiddenFiles(path) {
   return count
 }
 
+// Issue#2 fix: 定位指定缩进层级下的具名子键（返回行号与缩进；未找到返回 null）
+function findNestedYamlKey(lines, startIdx, baseIndent, key) {
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const l = lines[i]
+    if (!l.trim() || l.trim().startsWith('#')) continue
+    const ind = l.length - l.trimStart().length
+    if (ind <= baseIndent) return null
+    if (ind !== baseIndent + 2) continue // 只看直接子层（YAML 常规 2 空格缩进）
+    const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
+    if (m && m[1] === key) return { idx: i, indent: ind }
+  }
+  return null
+}
+// Issue#2 fix: 列出指定父键下一层的所有子键名（通配 * 展开用）
+function listChildKeys(lines, startIdx, baseIndent) {
+  const keys = []
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const l = lines[i]
+    if (!l.trim() || l.trim().startsWith('#')) continue
+    const ind = l.length - l.trimStart().length
+    if (ind <= baseIndent) break
+    if (ind !== baseIndent + 2) continue
+    const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
+    if (m) keys.push(m[1])
+  }
+  return keys
+}
+
 // P0-3 fix: 嵌套 YAML 路径下钻查找（替代行级正则）
+// Issue#1 fix: 剥离行内注释（# 前须有空白；引号内 # 不算注释——按引号配对状态跳过）
+export function stripYamlComment(s) {
+  let str = s
+  // 整段以 # 开头（允许前导空白）→ 值为空（父级保持嵌套下钻语义）
+  if (/^\s*#/.test(str)) return ''
+  // 引号包裹：取第一个配对引号内的内容，引号后的尾注释丢弃
+  const q = str.match(/^(\s*)(['"])([\s\S]*?)\2(?:\s+#.*)?$/)
+  if (q) return q[3].trim()
+  // 无引号：以「空白+#」为注释分隔，截断尾部
+  const cut = str.search(/\s#/)
+  if (cut !== -1) str = str.slice(0, cut)
+  return str.trim()
+}
 function findNestedYaml(lines, startIdx, baseIndent, segments) {
   let currentIndent = baseIndent
   for (let i = startIdx + 1; i < lines.length; i++) {
@@ -213,7 +254,7 @@ function findNestedYaml(lines, startIdx, baseIndent, segments) {
     const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
     if (m) {
       const key = m[1]
-      const valStr = m[2].trim()
+      const valStr = stripYamlComment(m[2])
       const seg = segments[0]
       if (key === seg) {
         if (valStr && valStr !== '' && valStr !== '{}') {
@@ -650,7 +691,7 @@ function loadRules(type, customPaths = [], repoPath = null) {
     grep:           { pattern: ['string'] },
     json_field:     { path: ['string'], field: ['string'], fallback_field: ['array', 'string'] },
     toml_field:     { path: ['string'], field: ['string'] },
-    yaml_field:     { path: ['string'], field: ['string'] },
+    yaml_field:     { path: ['string'], field: ['string'], fallback_field: ['array', 'string'] },
     directory_exists: { paths: ['array', 'string'] },
     not_exists:     { paths: ['array', 'string'] },
     glob_count:     { pattern: ['string'] },
@@ -1007,7 +1048,7 @@ function runCheck(rule, repoPath, mpj = null) {
           const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
           if (m && m[1] === segments[0]) {
             currentIndent = ind
-            const valStr = m[2].trim()
+            const valStr = stripYamlComment(m[2])
             if (valStr && valStr !== '' && valStr !== '{}') {
               // 标量值（非嵌套）
               val = valStr
@@ -1028,6 +1069,77 @@ function runCheck(rule, repoPath, mpj = null) {
         passed = false
         evidence = '字段不存在或值不匹配'
       }
+      // Issue#2 fix: yaml_field fallback_field——主字段不匹配时逐个尝试备选字段路径（数组形态）。
+      // 用途：同一语义在不同 YAML 形态下的位置差异（如 id-token: write 可在 workflow 顶层
+      // 或 publish job 级——PyPA 最小化权限模式），任一命中即 pass。
+      // 段内 `*` 为通配（如 jobs.*.permissions.id-token）：在该层级所有子键下逐个尝试。
+      if (!passed && params?.fallback_field) {
+        const fbList = Array.isArray(params.fallback_field) ? params.fallback_field : [params.fallback_field]
+        for (const fbField of fbList) {
+          if (!fbField) continue
+          const fbSegments = String(fbField).split('.')
+          const candidates = [] // 每项 {segments} —— 通配展开后的具体路径列表
+          const expandWildcard = (segs) => {
+            const wIdx = segs.indexOf('*')
+            if (wIdx === -1) { candidates.push({ segments: segs }); return }
+            // 找通配段父级的所有子键：先定位父级前缀（逐段下钻收集行号）
+            const lines = content.split('\n')
+            const prefix = segs.slice(0, wIdx)
+            const suffix = segs.slice(wIdx + 1)
+            // 顶层段
+            if (prefix.length === 0) return
+            for (let i = 0; i < lines.length; i++) {
+              const l = lines[i]
+              if (!l.trim() || l.trim().startsWith('#')) continue
+              const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
+              if (!m || m[1] !== prefix[0]) continue
+              // 沿 prefix 下钻
+              let curIdx = i, curIndent = l.length - l.trimStart().length
+              let ok = true
+              for (let d = 1; d < prefix.length; d++) {
+                const sub = findNestedYamlKey(lines, curIdx, curIndent, prefix[d])
+                if (!sub) { ok = false; break }
+                curIdx = sub.idx; curIndent = sub.indent
+              }
+              if (!ok) return
+              // 列出 curIndent 下一层的所有子键
+              const childKeys = listChildKeys(lines, curIdx, curIndent)
+              for (const k of childKeys) expandWildcard([...prefix, k, ...suffix])
+              return
+            }
+          }
+          expandWildcard(fbSegments)
+          for (const cand of candidates) {
+            let fbVal = null
+            let fbFound = false
+            try {
+              const lines = content.split('\n')
+              for (let i = 0; i < lines.length; i++) {
+                const l = lines[i]
+                if (!l.trim() || l.trim().startsWith('#')) continue
+                const ind = l.length - l.trimStart().length
+                const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
+                if (m && m[1] === cand.segments[0]) {
+                  const v = stripYamlComment(m[2])
+                  if (v && v !== '' && v !== '{}') { fbVal = v; fbFound = true }
+                  else {
+                    const sub = findNestedYaml(lines, i, ind, cand.segments.slice(1))
+                    if (sub.found) { fbVal = sub.value; fbFound = true }
+                  }
+                  break
+                }
+              }
+            } catch {}
+            if (fbFound && String(fbVal).trim() === expected) {
+              passed = true
+              const concrete = cand.segments.join('.')
+              evidence = `fallback ${concrete} = ${String(fbVal).trim()}`
+              break
+            }
+          }
+          if (passed) break
+        }
+      }
       break
     }
 
@@ -1539,7 +1651,11 @@ ${message}
   process.exit(hasCritical && strict ? 1 : 0)
 }
 
-main().catch(err => {
-  console.error(`✗ 运行时错误: ${err.message}`)
-  process.exit(2)
-})
+// Issue#1 fix: 入口守卫——仅直接作为 CLI 运行时执行主流程；被 import（测试/编程复用）不跑
+const isDirectRun = import.meta.url === `file://${process.argv[1]}`
+if (isDirectRun) {
+  main().catch(err => {
+    console.error(`✗ 运行时错误: ${err.message}`)
+    process.exit(2)
+  })
+}

package/rules/domains/quality.yaml

@@ -54,8 +54,9 @@ rules:
         - "go.sum"
         - "requirements.lock"
       anyOf: true
-    description: "锁文件应入库以确保可复现构建（BEST-PRACTICES §5.4 验证链）"
-    note: "无包管理的仓库豁免"
+    description: "锁文件应入库以确保可复现构建（BEST-PRACTICES §5.4）——锁文件还须被 CI/验证链实际安装消费（npm ci / pip install -r requirements.lock 等），只入库不安装是装饰性合规；requirements.lock 非 pip 原生锁格式，CI 须显式写明安装它"
+    note: "无包管理的仓库豁免；零依赖仓（依赖声明为空，无锁对象）可用 .auditrc.yaml 豁免并注明原因"
+    fix_hint: "提交锁文件（package-lock.json / poetry.lock / go.sum / requirements.lock 任一）并确认 CI 安装步骤实际使用它（npm ci / pip install -r …）；零依赖仓在 .auditrc.yaml 豁免注明"
 
   - id: QUA-005
     title: "CLAUDE.md 桥接"

package/rules/domains/security.yaml

@@ -72,8 +72,9 @@ rules:
     params:
       path: ".github/workflows/publish.yml"
       field: "permissions.id-token"
+      fallback_field: ["jobs.*.permissions.id-token"]
       expected: "write"
       skip_if_no_file: ".github/workflows/publish.yml"
-    description: "publish workflow 必须请求 id-token: write 权限（OIDC Trusted Publishing）"
+    description: "publish workflow 必须请求 id-token: write 权限（OIDC Trusted Publishing）——工作流顶层或 publish job 级任一即可（job 级为 PyPA 推荐的最小化模式）"
     template_ref: "templates/repo-root/.github/workflows/publish.yml"
-    fix_hint: "在 workflow 顶部添加 permissions: id-token: write"
+    fix_hint: "在 publish workflow 声明 permissions.id-token: write——顶层（permissions: 块内）或仅 publish job（jobs.publish.permissions: 块内）均可；推荐 job 级（最小化，其他 job 不持有 OIDC 权限）"

package/templates/common/AGENTS-core.md

@@ -1,7 +1,10 @@
 # AGENTS（AI 协作与工程纪律）
 
-> 本文件由模板**单源拼装**（`common/AGENTS-core.md` + 分类 append）——重复段不要在仓库里手改；
-> 改规则先改模板源，再重新生成。人工协作者同样适用本文件全部条款。
+> **来源声明（二选一，按实际来源保留其一，删除另一行）**：
+> - 由 scaffold 生成/更新（仓在 `.scaffold/lock/`）：单源拼装（`common/AGENTS-core.md` + 分类 append）——重复段勿手改，改规则先改模板源，再跑 `node scaffold.mjs --update <repo>` 合并。
+> - 手写/移植（无 `.scaffold/lock/`）：本文件归本仓库自主维护，直接在仓库内改，单源约束不适用。
+>
+> 人工协作者同样适用本文件全部条款。
 
 ## 项目概览
 

package/templates/repo-root/.github/workflows/publish.yml

@@ -61,12 +61,17 @@ jobs:
         # smoke/mount/vitest 为探测式：文件存在才跑，接入即自动进链。
         run: node scripts/verify.mjs
       - name: Publish to npm (OIDC trusted publishing)
-        # 升级 npm：trusted publishing 需 npm CLI >= 11.5.1（含 OIDC 支持）。
+        # trusted publishing 需 npm CLI >= 11.5.1（含 OIDC 支持）。
+        # 上游 runner Node 自带的 npm 已满足时直接用——不装 npm@latest：
+        # 其 engine 门槛会随版本漂移（npm@12 要求 node ^22.22.2，曾致本仓 EBADENGINE），
+        # 仅当自带版本过旧时兜底升级到 npm@11（比 latest 门槛低、仍含 OIDC）。
         # prerelease → dist-tag next（忘加 --tag next 是最常见事故：
         # 用户 npm install 会装到 prerelease）；稳定版 → latest。
         run: |
-          npm install -g npm@latest
           echo "npm version: $(npm --version)"
+          if ! npm --version | grep -qE '^(11\.(5\.[1-9]|[6-9]|[0-9]{2})|1[2-9]|2[0-9])'; then
+            npm install -g npm@11
+          fi
           VERSION="$(node -p "require('./package.json').version")"
           if [[ "$VERSION" == *-* ]]; then
             echo "canary prerelease $VERSION → dist-tag next"