sillyspec 3.20.3 → 3.20.5

package/templates/workflows/archive-impact.yaml

@@ -0,0 +1,79 @@
+name: archive-impact
+description: 分析变更影响的模块并同步模块文档
+spec_version: 1
+
+roles:
+  - id: impact-analyzer
+    name: "影响分析"
+    task: "分析 git diff，提取变更影响模块"
+    inputs:
+      paths: [".sillyspec/changes/", ".sillyspec/docs/*/modules/"]
+      hints:
+        grep_patterns: ["_module-map", "module-impact", "git diff"]
+    outputs:
+      - path: ".sillyspec/changes/<change-name>/module-impact.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 20
+          - type: contains_sections
+            sections: ["模块影响矩阵", "未匹配文件"]
+    constraints:
+      - "以 git diff 为准（真实 > 声明）"
+      - "影响类型：逻辑变更/数据结构变更/接口变更/调用关系变更/配置变更/新增"
+      - "需要 review 标记不确定的影响"
+
+  - id: doc-syncer
+    name: "文档同步"
+    task: "根据 module-impact.md 同步更新模块索引和卡片"
+    depends_on:
+      - impact-analyzer
+    inputs:
+      from_role: impact-analyzer
+      output: module-impact
+      output_description: "变更影响分析结果，包含模块影响矩阵"
+      paths: [".sillyspec/docs/*/modules/"]
+      hints:
+        grep_patterns: ["_module-map", "module-impact"]
+    outputs:
+      - path: ".sillyspec/docs/sillyspec/modules/_module-map.yaml"
+        required: false
+        checks:
+          - type: file_exists
+      - path: ".sillyspec/docs/sillyspec/modules/<module-id>.md"
+        required: false
+        # checks 跳过：路径含动态 <module-id> 占位符，不适合静态检查
+    constraints:
+      - "结构化事实改 _module-map.yaml，语义解释改模块卡片"
+      - "人工备注区域永远保护，不覆盖"
+      - "更新前展示 diff 摘要，请用户确认"
+
+orchestration:
+  mode: sequential
+  timeout_per_role: 180
+
+checks:
+  role_level:
+    - type: file_exists
+    - type: min_lines
+      min: 10
+  workflow_level:
+    - type: file_exists
+      path: ".sillyspec/changes/<change-name>/module-impact.md"
+
+retry:
+  max_attempts: 1
+  include_failure_context: true
+  retry_scope: failed_role_only
+
+on_check_failure: prompt_retry
+
+permissions:
+  write_mode: patch_only
+  write_scope:
+    - ".sillyspec/docs/"
+    - ".sillyspec/changes/<change-name>/"
+  allow_shell: true
+  allow_network: false
+  allow_git: true

package/templates/workflows/scan-docs.yaml

@@ -0,0 +1,132 @@
+name: scan-docs
+description: 并行生成项目的扫描文档（7份）
+spec_version: 1
+
+roles:
+  - id: arch
+    name: "技术架构"
+    task: "生成 ARCHITECTURE.md"
+    inputs:
+      paths:
+        - "src/*.js"
+        - "package.json"
+      hints:
+        grep_patterns: ["class ", "export ", "import ", "schema", "CREATE TABLE"]
+    outputs:
+      - path: "{SPEC_ROOT}/docs/<project>/scan/ARCHITECTURE.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 20
+          - type: contains_sections
+            sections: ["技术栈", "架构概览"]
+    constraints:
+      - "禁止读源码全文，只用 grep/rg 搜索"
+      - "Schema 只记表名+说明+字段数"
+
+  - id: conventions
+    name: "代码约定"
+    task: "生成 CONVENTIONS.md"
+    inputs:
+      paths: ["src/"]
+      hints:
+        grep_patterns: ["function ", "const ", "async ", "try ", "catch "]
+    outputs:
+      - path: "{SPEC_ROOT}/docs/<project>/scan/CONVENTIONS.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+          - type: contains_sections
+            sections: ["框架隐形规则", "代码风格"]
+    constraints:
+      - "禁止读源码全文"
+      - "提取 3-5 个典型模式"
+
+  - id: structure
+    name: "目录结构+外部集成"
+    task: "生成 STRUCTURE.md 和 INTEGRATIONS.md"
+    inputs:
+      paths: ["./"]
+      hints:
+        grep_patterns: ["fetch", "http", "WebSocket", "ws", "chokidar"]
+    outputs:
+      - path: "{SPEC_ROOT}/docs/<project>/scan/STRUCTURE.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+      - path: "{SPEC_ROOT}/docs/<project>/scan/INTEGRATIONS.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+    constraints:
+      - "STRUCTURE: 目录树+模块说明"
+      - "INTEGRATIONS: 按类型分组外部依赖"
+
+  - id: quality
+    name: "测试+债务+概览"
+    task: "生成 TESTING.md、CONCERNS.md、PROJECT.md"
+    inputs:
+      paths: ["src/", "packages/"]
+      hints:
+        grep_patterns: ["TODO", "FIXME", "deprecated", "test", "describe"]
+    outputs:
+      - path: "{SPEC_ROOT}/docs/<project>/scan/TESTING.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 10
+          - type: no_placeholder
+      - path: "{SPEC_ROOT}/docs/<project>/scan/CONCERNS.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 10
+          - type: contains_sections
+            sections: ["代码质量", "依赖风险"]
+      - path: "{SPEC_ROOT}/docs/<project>/scan/PROJECT.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+          - type: contains_sections
+            sections: ["项目简介", "技术栈"]
+    constraints:
+      - "CONCERNS 按严重程度分组（🔴/🟡/🟢）"
+      - "不编造不存在的测试"
+
+orchestration:
+  mode: parallel
+  max_concurrent: 4
+  timeout_per_role: 120
+
+checks:
+  workflow_level:
+    - type: file_count
+      path: "scan/"
+      min: 7
+    - type: no_empty_files
+
+retry:
+  max_attempts: 1
+  include_failure_context: true
+  retry_scope: failed_role_only
+
+on_check_failure: prompt_retry
+
+permissions:
+  write_mode: direct
+  write_scope:
+    - "{SPEC_ROOT}/docs/<project>/scan/"
+  allow_shell: true
+  allow_network: false
+  allow_git: false

package/test/brainstorm-plan-contract.test.mjs

@@ -0,0 +1,273 @@
+/**
+ * Brainstorm → Plan Contract v1 测试
+ *
+ * 验证 design.md 到 plan 的输入契约：
+ * 1. 合法 design 通过
+ * 2. 缺关键章节失败
+ * 3. warning 不阻断
+ */
+import { validateDesignForPlan } from '../src/stages/plan.js'
+
+let failed = 0
+const failures = []
+
+function assert(condition, msg) {
+  if (!condition) {
+    failed++
+    failures.push(msg)
+    console.log(`  ❌ FAIL: ${msg}`)
+  } else {
+    console.log(`  ✅ PASS: ${msg}`)
+  }
+}
+
+console.log('=== Brainstorm → Plan Contract v1 测试 ===\n')
+
+// ─────────────────────────────────────────
+// Case 1: valid design 通过
+// ─────────────────────────────────────────
+console.log('--- Case 1: valid design 通过 ---')
+{
+  const design = `# Design: 用户认证系统
+
+## 背景
+需要实现用户认证。
+
+## 设计目标
+- 支持 OAuth2
+- 支持手机号登录
+
+## 非目标
+- 不做 SSO
+
+## 总体方案
+使用 JWT + Refresh Token。
+
+## 决策
+- D-001@v1: 选择 JWT 而非 Session
+
+## 约束
+- 必须兼容现有 API
+
+## 文件变更清单
+| 操作 | 文件路径 | 说明 |
+|------|---------|------|
+| 新增 | src/auth.js | 认证模块 |
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '完整 design 应校验通过')
+  assert(result.errors.length === 0, '不应有 errors')
+  assert(result.warnings.length === 0, '不应有 warnings')
+}
+
+// ─────────────────────────────────────────
+// Case 2: empty design 失败
+// ─────────────────────────────────────────
+console.log('\n--- Case 2: empty design 失败 ---')
+{
+  assert(!validateDesignForPlan('').ok, '空字符串应失败')
+  assert(!validateDesignForPlan(null).ok, 'null 应失败')
+  assert(!validateDesignForPlan('   ').ok, '纯空格应失败')
+}
+
+// ─────────────────────────────────────────
+// Case 3: missing goal 失败
+// ─────────────────────────────────────────
+console.log('\n--- Case 3: missing goal/背景 失败 ---')
+{
+  const design = `# Design
+
+## 总体方案
+用 JWT。
+
+## 决策
+D-001@v1: 选 JWT
+`
+  const result = validateDesignForPlan(design)
+  assert(!result.ok, '缺目标/背景应失败')
+  assert(result.errors.some(e => e.includes('目标') || e.includes('背景')), '错误应提到目标/背景')
+}
+
+// ─────────────────────────────────────────
+// Case 4: missing scope/方案 失败
+// ─────────────────────────────────────────
+console.log('\n--- Case 4: missing scope/方案 失败 ---')
+{
+  const design = `# Design
+
+## 背景
+需要认证。
+
+## 决策
+D-001@v1: 选 JWT
+`
+  const result = validateDesignForPlan(design)
+  assert(!result.ok, '缺范围/方案应失败')
+  assert(result.errors.some(e => e.includes('范围') || e.includes('方案')), '错误应提到范围/方案')
+}
+
+// ─────────────────────────────────────────
+// Case 5: missing decisions 失败
+// ─────────────────────────────────────────
+console.log('\n--- Case 5: missing decisions 失败 ---')
+{
+  const design = `# Design
+
+## 背景
+需要认证。
+
+## 总体方案
+用 JWT。
+`
+  const result = validateDesignForPlan(design)
+  assert(!result.ok, '缺决策应失败')
+  assert(result.errors.some(e => e.includes('决策')), '错误应提到决策')
+}
+
+// ─────────────────────────────────────────
+// Case 6: decisions.md 引用也算决策
+// ─────────────────────────────────────────
+console.log('\n--- Case 6: decisions.md 引用算决策 ---')
+{
+  const design = `# Design
+
+## 背景
+需要认证。
+
+## 总体方案
+用 JWT。详见 decisions.md。
+
+## 文件变更清单
+| 操作 | 文件 | 说明 |
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, 'decisions.md 引用应满足决策检查')
+}
+
+// ─────────────────────────────────────────
+// Case 7: missing non-goals 只有 warning
+// ─────────────────────────────────────────
+console.log('\n--- Case 7: missing non-goals warning ---')
+{
+  const design = `# Design
+
+## 背景
+需要认证。
+
+## 总体方案
+用 JWT。
+
+## 决策
+D-001@v1: 选 JWT
+
+## 约束
+必须兼容现有 API。
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '缺非目标不应阻断')
+  assert(result.warnings.some(w => w.includes('非目标') || w.includes('Non-goals')), '应有非目标 warning')
+}
+
+// ─────────────────────────────────────────
+// Case 8: missing constraints 只有 warning
+// ─────────────────────────────────────────
+console.log('\n--- Case 8: missing constraints warning ---')
+{
+  const design = `# Design
+
+## 目标
+实现认证。
+
+## 设计方案
+用 JWT。
+
+## 决策
+选择 JWT。
+
+## 非目标
+不做 SSO。
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '缺约束不应阻断')
+  assert(result.warnings.some(w => w.includes('约束') || w.includes('风险') || w.includes('Trade-off')), '应有约束/风险 warning')
+}
+
+// ─────────────────────────────────────────
+// Case 9: missing 文件变更清单 warning
+// ─────────────────────────────────────────
+console.log('\n--- Case 9: missing 文件变更清单 warning ---')
+{
+  const design = `# Design
+
+## 背景
+需要认证。
+
+## 总体方案
+用 JWT。
+
+## 决策
+D-001@v1: 选 JWT
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '缺文件变更清单不应阻断')
+  assert(result.warnings.some(w => w.includes('文件变更')), '应有文件变更 warning')
+}
+
+// ─────────────────────────────────────────
+// Case 10: 英文 design 通过
+// ─────────────────────────────────────────
+console.log('\n--- Case 10: 英文 design 通过 ---')
+{
+  const design = `# Design: Auth System
+
+## Background
+We need authentication.
+
+## Solution
+Use JWT + Refresh Token.
+
+## Decision
+D-001@v1: Choose JWT over Session
+
+## Non-goals
+No SSO.
+
+## Constraints
+Must be backwards compatible.
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '英文 design 应校验通过')
+  assert(result.errors.length === 0, '不应有 errors')
+}
+
+// ─────────────────────────────────────────
+// Case 11: 最小合法 design
+// ─────────────────────────────────────────
+console.log('\n--- Case 11: 最小合法 design ---')
+{
+  const design = `# Design
+
+## 目标
+修 bug。
+
+## 方案
+改代码。
+
+## 决策
+D-001@v1: 直接改。
+`
+  const result = validateDesignForPlan(design)
+  assert(result.ok, '最小合法 design 应通过')
+  // 可能有 warning 但 ok
+}
+
+// ── 结果 ──
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${11 - failed}  ❌ 失败: ${failed}`)
+if (failures.length > 0) {
+  console.log(`失败项:`)
+  failures.forEach(f => console.log(`  - ${f}`))
+}
+console.log(`${'='.repeat(50)}`)
+
+if (failed > 0) process.exit(1)

package/test/check-syntax.mjs

@@ -0,0 +1,26 @@
+import { execFileSync } from 'node:child_process'
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const roots = ['src']
+const files = []
+
+function walk(dir) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    const st = statSync(full)
+    if (st.isDirectory()) {
+      walk(full)
+      continue
+    }
+    if (/\.(js|cjs|mjs)$/.test(entry)) files.push(full)
+  }
+}
+
+for (const root of roots) walk(root)
+
+for (const file of files.sort()) {
+  execFileSync(process.execPath, ['--check', file], { stdio: 'inherit' })
+}
+
+console.log(`Checked ${files.length} JavaScript files`)

package/test/cli-top-level-aliases.test.mjs

@@ -0,0 +1,174 @@
+/**
+ * task-10: 顶层命令别名 doctor/scan/status/quick/explore 转发 runCommand
+ *
+ * 设计依据：task-10.md §TDD + §验收标准
+ *   - sillyspec doctor / scan / status / quick / explore 不再落 default 分支报"未知命令"
+ *   - 行为与 sillyspec run <stage> 字节一致
+ *   - sillyspec worktree doctor 仍走 worktree 分支
+ *   - sillyspec foobar 仍报未知命令
+ *
+ * 断言策略：
+ *   stage 在空目录下可能因无 .sillyspec 进度而 exit != 0（这是 stage 自身行为，
+ *   不属于本任务路由范围）。因此测试只验证"路由正确"——即 stderr 不含"未知命令"
+ *   字样（default 分支的特征文案），并且 doctor/scan 两路 stdout 字节一致。
+ */
+
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, rmSync } from 'node:fs'
+import { join, resolve, dirname } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const cliBin = resolve(__dirname, '..', 'bin', 'sillyspec.js')
+
+let passed = 0
+let failed = 0
+
+function assert(cond, msg) {
+  if (cond) {
+    console.log(`  ✅ PASS: ${msg}`)
+    passed++
+  } else {
+    console.log(`  ❌ FAIL: ${msg}`)
+    failed++
+  }
+}
+
+function runCLI(args, cwd) {
+  const res = spawnSync(process.execPath, [cliBin, ...args], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 15000,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  })
+  return {
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+    status: res.status,
+    combined: (res.stdout || '') + (res.stderr || ''),
+  }
+}
+
+function cleanSillySpec(cwd) {
+  // 清掉 sillyspec 写入 cwd 的进度副作用，保证两路字节级环境一致
+  try { rmSync(join(cwd, '.sillyspec'), { recursive: true, force: true }) } catch {}
+  try { rmSync(join(cwd, '.sillyspec-platform.json'), { force: true }) } catch {}
+}
+
+const tmpRoot = join(tmpdir(), `sillyspec-cli-aliases-${Date.now()}`)
+mkdirSync(tmpRoot, { recursive: true })
+
+try {
+  // ── Red/Green: 5 个顶层命令不再报"未知命令" ──
+  const aliases = ['doctor', 'scan', 'status', 'quick', 'explore']
+  console.log('\n=== Test 1: 顶层命令别名不落 default 分支 ===')
+  for (const stage of aliases) {
+    const res = runCLI([stage], tmpRoot)
+    const hitUnknown =
+      res.combined.includes('未知命令') ||
+      /unknown command/i.test(res.combined)
+    assert(
+      !hitUnknown,
+      `sillyspec ${stage} 不报"未知命令" (exit=${res.status})`
+    )
+  }
+
+  // ── Green: doctor 顶层别名 与 sillyspec run doctor 字节一致 ──
+  // 两路必须在字节级相同环境下运行：同 cwd + 每次跑前清空 .sillyspec
+  // （否则 progress 持久化会让第二次跑读到旧数据触发平台同步检查）
+  console.log('\n=== Test 2: sillyspec doctor 与 sillyspec run doctor 等价 ===')
+  {
+    const cwd = join(tmpRoot, 'doctor-cmp')
+    mkdirSync(cwd, { recursive: true })
+    cleanSillySpec(cwd)
+    const top = runCLI(['doctor'], cwd)
+    cleanSillySpec(cwd)
+    const viaRun = runCLI(['run', 'doctor'], cwd)
+    assert(
+      top.status === viaRun.status,
+      `exit code 一致: doctor=${top.status}, run doctor=${viaRun.status}`
+    )
+    assert(
+      top.stdout === viaRun.stdout,
+      `stdout 字节一致 (len=${top.stdout.length})`
+    )
+    assert(
+      top.stderr === viaRun.stderr,
+      `stderr 字节一致 (len=${top.stderr.length})`
+    )
+  }
+
+  // ── Green: scan 顶层别名 与 sillyspec run scan 字节一致 ──
+  console.log('\n=== Test 3: sillyspec scan 与 sillyspec run scan 等价 ===')
+  {
+    const cwd = join(tmpRoot, 'scan-cmp')
+    mkdirSync(cwd, { recursive: true })
+    cleanSillySpec(cwd)
+    const top = runCLI(['scan'], cwd)
+    cleanSillySpec(cwd)
+    const viaRun = runCLI(['run', 'scan'], cwd)
+    assert(
+      top.status === viaRun.status,
+      `exit code 一致: scan=${top.status}, run scan=${viaRun.status}`
+    )
+    assert(
+      top.stdout === viaRun.stdout,
+      `stdout 字节一致 (len=${top.stdout.length})`
+    )
+  }
+
+  // ── 回归: worktree doctor 走 worktree 分支（与顶层 doctor 不同） ──
+  console.log('\n=== Test 4: sillyspec worktree doctor 走 worktree 分支 ===')
+  {
+    const res = runCLI(['worktree', 'doctor'], tmpRoot)
+    // worktree doctor 不应报顶层 default 的"未知命令"，也不应报"未知阶段"
+    const hitUnknownCmd =
+      res.combined.includes('未知命令') && !/worktree/.test(res.combined)
+    assert(!hitUnknownCmd, `worktree doctor 不报顶层未知命令`)
+    // worktree 子命令 default 分支会输出"未知子命令: worktree"，这里 doctor 合法不应出现
+    assert(
+      !res.combined.includes('未知子命令'),
+      `worktree doctor 不是未知子命令`
+    )
+  }
+
+  // ── 回归: foobar 仍落 default 报未知命令 ──
+  console.log('\n=== Test 5: sillyspec foobar 仍报未知命令 ===')
+  {
+    const res = runCLI(['foobar'], tmpRoot)
+    assert(
+      res.combined.includes('未知命令'),
+      `foobar 命中 default 分支，报"未知命令"`
+    )
+    assert(
+      res.status !== 0,
+      `foobar exit code 非 0 (got ${res.status})`
+    )
+  }
+
+  // ── 选项透传: sillyspec doctor --json 与 sillyspec run doctor --json 等价 ──
+  console.log('\n=== Test 6: doctor --json 选项透传正确 ===')
+  {
+    const top = runCLI(['doctor', '--json'], tmpRoot)
+    const viaRun = runCLI(['run', 'doctor', '--json'], tmpRoot)
+    assert(
+      top.stdout === viaRun.stdout,
+      `doctor --json stdout 与 run doctor --json 一致 (len=${top.stdout.length})`
+    )
+    assert(
+      top.status === viaRun.status,
+      `doctor --json exit 与 run doctor --json 一致`
+    )
+  }
+} finally {
+  try {
+    rmSync(tmpRoot, { recursive: true, force: true })
+  } catch {}
+}
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+process.exit(failed > 0 ? 1 : 0)