repo-audit-tool 1.3.0 → 1.3.2

package/PUBLISHING.md

@@ -1,15 +1,21 @@
 # 发布记录：repo-audit-tool
 
-## 发布状态（2026-09-06 更新）
+## 发布状态（2026-09-07 更新）
 
 | 项 | 状态 |
 |---|---|
-| npm | `repo-audit-tool` v1.2.3（latest，CI 自动发布） |
+| npm | `repo-audit-tool` v1.3.1（latest，CI 自动发布）；v1.3.2 发版中 |
 | GitHub | `NinjaSln-labs/repo-audit` master；发版 tag `v*` |
-| 本地验证 | 自审计 100/A，验证链 4/4，测试 3/3，CI 全绿 |
+| 本地验证 | 自审计 100/A，验证链 4/4，测试 12/12，CI 双平台（ubuntu + windows） |
 
 ## 版本历史
 
+- **1.3.2** — Issue#4 修复：入口守卫 `pathToFileURL` 归一化，修复 Windows 全形态
+  静默不执行（v1.3.1 回归）；守卫 stderr 诊断提示；command 检查器 Git Bash 探测；
+  CI 加 windows-latest 矩阵 + npm 安装 smoke 步骤（2026-09-07）
+- **1.3.1** — 入口守卫 realpath 归一化，修复 npm bin symlink 下主流程不执行（2026-09-06）
+- **1.3.0** — 反馈修复 Issue#1/#2/#3：yaml_field 注释剥离、SEC-004 job 级 fallback、
+  AGENTS 来源声明、QUA-004 消费意图、--update 动线成文（2026-09-06）
 - **1.2.3** — package.json 补充 `repository` 字段，修复 npm provenance E422；
   首次 Trusted Publisher（OIDC）tag 触发自动发布（2026-09-06）
 - **1.2.2** — publish CI 修复：node 20→22 + npm 条件升级，修复 EBADENGINE；

package/docs/AGENT-INDEX.json

@@ -2,8 +2,8 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "repo-audit 文档索引",
   "description": "AI Agent 可读的文档索引 — 包含所有文档的元数据、结构、和调用协议",
-  "version": "1.3.0",
-  "updated": "2026-09-06",
+  "version": "1.3.2",
+  "updated": "2026-09-07",
   "repo": "NinjaSln-labs/repo-audit",
   "npm": "repo-audit-tool",
   "pages": "https://ninjasln-labs.github.io/repo-audit/",
@@ -20,7 +20,7 @@
     "name": "repo-audit",
     "description": "仓库标准化审计工具 + 工程脚手架生成器（零依赖）",
     "bin": "repo-audit",
-    "version": "1.3.0",
+    "version": "1.3.2",
     "language": "JavaScript (ESM)",
     "runtime": "Node.js >= 18",
     "dependencies": [],
@@ -231,6 +231,8 @@
   },
 
   "changelog": {
+    "1.3.2": "Issue#4 修复：入口守卫 pathToFileURL 归一化——修复 Windows 全形态静默不执行（v1.3.1 回归）；守卫不命中时 stderr 诊断提示；command 检查器 Git Bash 探测；CI 双平台矩阵 + npm 安装 smoke",
+    "1.3.1": "入口守卫 realpath 归一化——修复 npm bin symlink 下主流程不执行；1.3.0 反馈修复：注释剥离/SEC-004/AGENTS 声明/QUA-004/--update 动线",
     "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 已存在未出包）",

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

@@ -321,6 +321,14 @@ fi
 
 如果自定义规则文件不存在或格式错误，工具会输出警告并继续（只加载成功的规则）。
 
+### 5.5 Windows 调用形态（v1.3.2 起）
+
+v1.3.2 修复了 v1.3.1 在 Windows 上 CLI 全形态静默不执行的回归（Issue#4）。Agent 在 Windows 上的注意事项：
+
+- 入口守卫已跨平台归一化（`pathToFileURL`），`node repo-audit.mjs` / npm bin / shim 全形态可用
+- `command`/`command_result` 检查（GIT-001/GIT-003/QUA-002）自动探测 Git for Windows bash；未装 Git for Windows 时这些项降级 fail，其余规则正常
+- 守卫不命中时 stderr 有 `ℹ 未作为 CLI 入口执行` 诊断提示——若审计"成功"但 0 规则输出，先查 stderr 这一行
+
 ---
 
 ## 六、性能参考
@@ -546,4 +554,4 @@ GitHub Issues                    修复 / 文档 / 不采纳
 3. `minor` — 功能部分受损（1 周内响应）
 4. `info` — 建议改进（排期处理）
 
-*Agent 操作手册 v1.3 · 2026-09-06（新增反馈通道 §10）
+*Agent 操作手册 v1.3.2 · 2026-09-07（§5.5 Windows 调用形态；v1.3.2 修复 Windows 入口回归 Issue#4）*

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

@@ -500,6 +500,20 @@ node repo-audit.mjs --repo ./my-repo --type python-app
 
 或通过 `REPO_AUDIT_TYPES` 环境变量添加自定义分类。
 
+### Windows 上 CLI 无输出（v1.3.1 已修，v1.3.2 起）
+
+v1.3.1 的入口守卫在 Windows 上存在回归：CLI 全形态静默不执行（exit 0 无输出）。v1.3.2 改用 `pathToFileURL` 归一化后修复。升级：
+
+```bash
+npm install -g repo-audit-tool@latest
+```
+
+若仍见 `ℹ 未作为 CLI 入口执行` 提示（stderr），说明调用形态未被守卫识别——请附带该提示行（含两侧 URL/路径形态）提交反馈。
+
+### Windows 无 POSIX shell（command 检查器降级）
+
+`command`/`command_result` 类检查（GIT-001/GIT-003/QUA-002）需 POSIX shell。Windows 上引擎自动探测 Git for Windows 自带的 bash（PATH 中的 `sh` → `Program Files\\Git\\bin\\bash.exe` 等常见位置）。未装 Git for Windows 时这些检查项降级为 fail 并给出提示，不影响其余规则。
+
 ---
 
 ## 十、与 scaffold 的配合
@@ -779,4 +793,13 @@ gh issue view <NUMBER> --repo NinjaSln-labs/repo-audit
 gh issue close <NUMBER> --repo NinjaSln-labs/repo-audit --comment "已处理，感谢反馈"
 ```
 
+### 12.9 Windows 支持（v1.3.2）
+
+v1.3.2 起完整支持 Windows：
+
+- **入口守卫跨平台**：`pathToFileURL` 归一化替代 `file://` 手工拼接，win32 上 CLI 正常执行（v1.3.1 回归修复，见 [Issue #4](https://github.com/NinjaSln-labs/repo-audit/issues/4)）
+- **守卫诊断提示**：调用形态未被识别时 stderr 输出 `ℹ 未作为 CLI 入口执行` 一行提示（不再静默 exit 0）
+- **command 检查器跨平台**：自动探测 Git for Windows bash（PATH `sh` → `Git\bin\bash.exe`），未装时相关检查降级提示
+- **CI 双平台矩阵**：master push/PR 在 ubuntu-latest + windows-latest 上同时跑验证链与 npm 安装 smoke
+
 

package/package.json

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

package/repo-audit.mjs

@@ -18,11 +18,11 @@
  *   REPO_AUDIT_TYPES - 自定义分类列表（JSON 数组）
  */
 
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync, realpathSync } from 'node:fs'
 import { join, resolve, dirname, relative } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { platform } from 'node:os'
 
 const ROOT = dirname(fileURLToPath(import.meta.url))
@@ -332,9 +332,44 @@ function countMdFiles(path) {
 }
 
 // ============================================================
-// Git 工具（跨平台）
+// Shell 工具（跨平台）
 // ============================================================
 
+// Windows 无原生 sh；command 检查器需 POSIX shell 语义。
+// 优先 Git for Windows 自带的 bash（npm/CI/开发者机几乎必装），探测顺序：
+//   1. sh 在 PATH（posix 或 Git Bash 已入 PATH）
+//   2. 常见安装位置的 bash.exe（Git for Windows / scoop / winget）
+//   3. 兜底 null（调用方降级为「检查器不可用」而非崩溃）
+let winShellCache
+function findShell() {
+  if (process.platform !== 'win32') return { cmd: 'sh', args: ['-c'] }
+  if (winShellCache !== undefined) return winShellCache
+  const probe = (exe) => spawnSync(exe, ['-c', 'echo ok'], { encoding: 'utf-8' }).status === 0
+  // 1) PATH 中的 sh（可能已是 Git Bash 的 sh.exe）
+  const pathSh = spawnSync('where', ['sh'], { encoding: 'utf-8' })
+  const candidates = []
+  if (pathSh.status === 0) candidates.push(pathSh.stdout.trim().split('\n')[0].trim())
+  // 2) 常见安装位置
+  const common = [
+    process.env.ProgramFiles && `${process.env.ProgramFiles}\\Git\\bin\\bash.exe`,
+    process.env['ProgramFiles(x86)'] && `${process.env['ProgramFiles(x86)']}\\Git\\bin\\bash.exe`,
+    process.env.LOCALAPPDATA && `${process.env.LOCALAPPDATA}\\Programs\\Git\\bin\\bash.exe`,
+  ].filter(Boolean)
+  for (const p of common) { try { if (existsSync(p)) candidates.push(p) } catch {} }
+  for (const c of candidates) {
+    if (probe(c)) { winShellCache = { cmd: c, args: ['-c'] }; return winShellCache }
+  }
+  winShellCache = null
+  return null
+}
+
+// command 检查器统一入口：跨平台执行 shell 命令
+function runShellCommand(command, cwd) {
+  const shell = findShell()
+  if (!shell) return { status: -1, stdout: '', stderr: 'no POSIX shell found on win32 (Git Bash 未安装?)', error: { code: 'ENOENT' } }
+  return spawnSync(shell.cmd, [...shell.args, command], { cwd, encoding: 'utf-8' })
+}
+
 function git(args, cwd) {
   const r = spawnSync('git', args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] })
   return r.status === 0 ? r.stdout.trim() : null
@@ -847,7 +882,7 @@ function runCheck(rule, repoPath, mpj = null) {
 
     case 'regex': {
       if (params?.command) {
-        const r = spawnSync('sh', ['-c', params.command], { cwd: repoPath, encoding: 'utf-8' })
+        const r = runShellCommand(params.command, repoPath)
         if (r.status !== 0) { passed = false; evidence = `命令失败: ${r.stderr?.trim() || 'exit ' + r.status}`; break }
         const re = new RegExp(params.pattern)
         const lines = r.stdout.split('\n').filter(Boolean)
@@ -912,7 +947,7 @@ function runCheck(rule, repoPath, mpj = null) {
     }
 
     case 'command_result': {
-      const r = spawnSync('sh', ['-c', params?.command], { cwd: repoPath, encoding: 'utf-8' })
+      const r = runShellCommand(params?.command, repoPath)
       if (r.status !== 0) { passed = false; evidence = `命令失败 (exit ${r.status})`; break }
       const val = parseInt(r.stdout.trim())
       // P3: skip_if_zero — 命令结果为 0 时豁免（如零提交仓、空文件等）
@@ -1651,11 +1686,25 @@ ${message}
   process.exit(hasCritical && strict ? 1 : 0)
 }
 
-// Issue#1 fix: 入口守卫——仅直接作为 CLI 运行时执行主流程；被 import（测试/编程复用）不跑
-const isDirectRun = import.meta.url === `file://${process.argv[1]}`
-if (isDirectRun) {
+// Issue#1 fix: 入口守卫——仅直接作为 CLI 运行时执行主流程；被 import（测试/编程复用）不跑。
+// Issue#4 fix: pathToFileURL 归一化（跨平台语义正确）——`file://` 手工拼接在 Windows 上产生
+//   非法 URL 形态（file://C:\... 反斜杠），与 import.meta.url（file:///C:/...）永不相等，
+//   导致 v1.3.1 在 Windows 全形态静默不执行（exit 0 无输出）。
+//   pathToFileURL 在 win32 产出 file:///C:/...（正斜杠三斜杠），posix 行为与手工拼接一致。
+// argv[1] 仍经 realpathSync 归一化（npm bin symlink，P-006）。
+export function isCliEntry(metaUrl, argv1) {
+  if (!argv1) return false
+  let real
+  try { real = realpathSync(argv1) } catch { return false }
+  return metaUrl === pathToFileURL(real).href
+}
+const entryArg = process.argv[1]
+if (isCliEntry(import.meta.url, entryArg)) {
   main().catch(err => {
     console.error(`✗ 运行时错误: ${err.message}`)
     process.exit(2)
   })
+} else if (entryArg && !process.env.NODE_TEST_CONTEXT) {
+  // 守卫不命中且非测试形态：提示而非静默——exit 0 无输出会让入口回归极难发现（Issue#4 教训）
+  console.error(`ℹ 未作为 CLI 入口执行（import.meta.url=${import.meta.url}, argv[1]=${entryArg}）。若您直接运行了本文件，请通过 node <本文件> 或安装后的 bin 调用。`)
 }