sillyspec 3.27.12 → 3.28.2

package/src/endpoint-baseline.js

@@ -0,0 +1,109 @@
+/**
+ * endpoint-baseline.js — 变更级端点 before/after 基线（变更 2026-09-07-endpoint-baseline）
+ *
+ * 背景：contract-matrix 只有 provider 完成后的 endpoints.json 事后快照，无变更前基线——
+ * 端点增删（archify Delta 核心内容之一）无法计算。本模块补齐：
+ *   - captureEndpointBaseline：变更起点拍端点集快照（幂等，已存在不覆盖）
+ *   - diffEndpointSets：基线 × 现算的集合运算纯函数（method+path 粒度）
+ *
+ * 消费链：CLI `endpoints baseline`（task-02）→ endpoint-baselines/<change>.json →
+ * archive-delta 第五源（Wave 2）对比出 delta.md「端点增删」节。
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { scanBackendEndpoints, normalizePath } from './endpoint-extractor.js'
+import { gitQuiet } from './git-helper.js'
+
+/**
+ * diff 键归一：method 大写 + normalizePath 参数归一（endpoint-extractor.js 既有导出，
+ * diffApiParity 同款——`:id/{plan_id}` / `{plan_id}/{id}` 等参数形态统一为 `{param}`）
+ * + 去尾斜杠（`/api/x/` 与 `/api/x` 同键；全斜杠归一为 `/`）。
+ * @param {{ method?: string, path?: string }} ep
+ * @returns {string} 形如 `GET /api/ppm/project-plan/{param}`
+ */
+function endpointKey(ep) {
+  const normalized = normalizePath(ep.path || '').replace(/\/+$/, '') || '/'
+  return `${(ep.method || '').toUpperCase()} ${normalized}`
+}
+
+/**
+ * 拍变更前端点基线：endpoint-extractor 现扫 cwd → 写 <runtimeRoot>/endpoint-baselines/<change>.json。
+ *
+ * - 幂等：目标文件已存在 → {written:false, reason:'exists'}（不读旧内容不覆盖——首次跑
+ *   即变更前状态，重跑保持原快照）；存在性检查先于扫描（已拍过直接跳过，不做无效重扫）。
+ * - fail-soft：扫描异常返回错误对象不抛（调用方降级注记，不阻断流程）。
+ * - cwd 锚定主仓根由调用方保证（task-02 CLI 层职责），本函数不做锚定。
+ *
+ * @param {{ cwd: string, changeName: string, runtimeRoot?: string }} opts
+ *   runtimeRoot 缺省 join(cwd, '.sillyspec', '.runtime')
+ * @returns {{ written: boolean, reason?: 'exists', count?: number, path?: string, error?: string }}
+ */
+export function captureEndpointBaseline({ cwd, changeName, runtimeRoot } = {}) {
+  const root = runtimeRoot || join(cwd, '.sillyspec', '.runtime')
+  const baselineDir = join(root, 'endpoint-baselines')
+  const baselinePath = join(baselineDir, `${changeName}.json`)
+
+  // 幂等守卫在前：已存在直接跳过（不读旧内容不覆盖）
+  if (existsSync(baselinePath)) return { written: false, reason: 'exists' }
+
+  let endpoints
+  try {
+    endpoints = scanBackendEndpoints(cwd)
+  } catch (e) {
+    return { written: false, error: (e && e.message) || String(e) }
+  }
+
+  // git rev-parse fail-soft：非仓库/git 缺失 → null（基线仍可拍，端点集是主体）
+  const baseCommit = gitQuiet(cwd, ['rev-parse', '--short', 'HEAD']) || null
+
+  const payload = {
+    schemaVersion: 1,
+    change: changeName,
+    baseCommit,
+    generatedAt: new Date().toISOString(),
+    endpoints: endpoints.map(e => ({ method: e.method, path: e.path, source: e.source })),
+  }
+
+  mkdirSync(baselineDir, { recursive: true })
+  writeFileSync(baselinePath, JSON.stringify(payload, null, 2) + '\n', 'utf8')
+  return { written: true, count: payload.endpoints.length, path: baselinePath }
+}
+
+/**
+ * 端点集合 diff：baseline × current 按 method+归一 path 做 Map 集合运算。
+ *
+ * - 任一输入为 null/非数组 → null（调用方降级：无基线不比）。
+ * - added：current 有 baseline 无（带 current 的 source）；removed：反向（带 baseline 的 source）。
+ * - changed（同 path 参数改名等）不配对——归一键相同则判同（`:id/{plan_id}` vs
+ *   `{param}/{plan_id}` 同键不假报）；键不同的变更天然呈 removed+added 两条独立行
+ *   （design Gap-3 显式声明，防止实现期发明配对逻辑）。
+ *
+ * @param {Array<{method:string,path:string,source:string}>|null} baselineEndpoints
+ * @param {Array<{method:string,path:string,source:string}>|null} currentEndpoints
+ * @returns {{ added: Array<{method,path,source}>, removed: Array<{method,path,source}> } | null}
+ */
+export function diffEndpointSets(baselineEndpoints, currentEndpoints) {
+  if (!Array.isArray(baselineEndpoints) || !Array.isArray(currentEndpoints)) return null
+
+  const baselineMap = new Map()
+  for (const ep of baselineEndpoints) {
+    const key = endpointKey(ep)
+    if (!baselineMap.has(key)) baselineMap.set(key, ep) // 同键保留首个，防重复行
+  }
+  const currentMap = new Map()
+  for (const ep of currentEndpoints) {
+    const key = endpointKey(ep)
+    if (!currentMap.has(key)) currentMap.set(key, ep)
+  }
+
+  const added = []
+  for (const [key, ep] of currentMap) {
+    if (!baselineMap.has(key)) added.push({ method: ep.method, path: ep.path, source: ep.source })
+  }
+  const removed = []
+  for (const [key, ep] of baselineMap) {
+    if (!currentMap.has(key)) removed.push({ method: ep.method, path: ep.path, source: ep.source })
+  }
+  return { added, removed }
+}

package/src/endpoint-extractor.js

@@ -143,6 +143,69 @@ export function extractSpringEndpoints(filePath) {
   return endpoints
 }
 
+/**
+ * 从单个文件提取路由挂载前缀（挂载点侧，与 router 文件分离）。
+ * - FastAPI：`app.include_router(xxx_router, prefix="/api")`（含多行形态，`[^)]*?` 跨参数/换行）
+ * - Express：`app.use("/api", router)`
+ * 跨文件前缀无法在提取端点时合并（挂载点与 router 文件分离，静态扫描不做导入图关联），
+ * 收集为前缀集合供对账端剥除对齐（坑 endpoints-mount-prefix-gap）。
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {string[]} 挂载前缀列表
+ */
+export function extractMountPrefixes(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const prefixes = []
+  for (const m of content.matchAll(/\.include_router\s*\([^)]*?prefix\s*=\s*["'`]([^"'`]+)["'`]/g)) {
+    prefixes.push(m[1])
+  }
+  for (const m of content.matchAll(/\bapp\.use\s*\(\s*["'`]([^"'`]+)["'`]/g)) {
+    prefixes.push(m[1])
+  }
+  return prefixes
+}
+
+// backend 扫描目录排除清单（端点提取与挂载前缀收集共用）。
+// 对齐 scanFrontendApiCalls（坑 parity-scan-stale-dirs：.claude/worktrees 陈旧检出
+// 与各类 build 产物混入端点扫描全是噪音）——backend 侧另含 __pycache__/.gradle/maven target
+const BACKEND_DIR_EXCLUDE = [
+  /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^venv$/, /^\.git$/, /^\.gradle$/,
+  /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/, /^\.next$/, /^\.nuxt$/,
+  /^\.output$/, /^\.turbo$/, /^\.parcel-cache$/, /^coverage$/,
+  /^\.sillyspec$/, /^\.worktrees$/, /^\.d\.ts$/,
+  /^(dist|build|target|out)$/i,
+  /test/i,
+]
+
+/**
+ * 递归扫描目录收集路由挂载前缀集合（include_router prefix / app.use 路径）。
+ * @param {string} dir
+ * @param {{ excludePatterns?: RegExp[] }} opts
+ * @returns {string[]} 去重后的挂载前缀列表
+ */
+export function scanMountPrefixes(dir, opts = {}) {
+  const excludePatterns = opts.excludePatterns || BACKEND_DIR_EXCLUDE
+  const prefixes = new Set()
+  if (!existsSync(dir)) return [...prefixes]
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name)
+      if (entry.isDirectory()) {
+        if (excludePatterns.some(p => p.test(entry.name))) continue
+        walk(full)
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase()
+        if (ext !== '.py' && ext !== '.js' && ext !== '.ts') continue
+        try {
+          for (const p of extractMountPrefixes(full)) prefixes.add(p)
+        } catch {}
+      }
+    }
+  }
+  walk(dir)
+  return [...prefixes]
+}
+
 /**
  * 从目录递归扫描后端端点（多框架）。
  * 按扩展名分派：.py→FastAPI / .js,.ts→Express / .java→Spring。
@@ -152,16 +215,7 @@ export function extractSpringEndpoints(filePath) {
  * @returns {Array<{ method: string, path: string, source: string, line: number }>}
  */
 export function scanBackendEndpoints(dir, opts = {}) {
-  // 排除清单对齐 scanFrontendApiCalls（坑 parity-scan-stale-dirs：.claude/worktrees 陈旧检出
-  // 与各类 build 产物混入端点扫描全是噪音）——backend 侧另含 __pycache__/.gradle/maven target
-  const excludePatterns = opts.excludePatterns || [
-    /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^venv$/, /^\.git$/, /^\.gradle$/,
-    /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/, /^\.next$/, /^\.nuxt$/,
-    /^\.output$/, /^\.turbo$/, /^\.parcel-cache$/, /^coverage$/,
-    /^\.sillyspec$/, /^\.worktrees$/, /^\.d\.ts$/,
-    /^(dist|build|target|out)$/i,
-    /test/i,
-  ]
+  const excludePatterns = opts.excludePatterns || BACKEND_DIR_EXCLUDE
 
   const results = []
   if (!existsSync(dir)) return results
@@ -326,16 +380,30 @@ export function normalizePath(rawPath) {
 // ─── 对账 ───────────────────────────────────────────────────────────────
 
 /**
- * 比较前端调用的路径和后端注册的端点，返回差异
+ * 比较前端调用的路径和后端注册的端点，返回差异。
+ *
+ * 挂载前缀对齐（坑 endpoints-mount-prefix-gap，2026-08-31 用户实证）：后端提取到的是
+ * 「router 自身前缀 + 装饰器路径」，不含挂载点前缀（main.py 的 include_router(prefix=)/
+ * app.use 与 router 文件分离，静态扫描不做导入图关联）→ 前端全路径调用（/api/xxx）对不上
+ * 欠前缀端点（/xxx）→ probe5 全量假 missing（17 个实证，人工定性成本高）。传入
+ * mountPrefixes 时前端调用路径按前缀集合逐个剥除生成候选，任一候选命中即匹配；原始路径
+ * 恒在候选集首位——装饰器自带全路径的仓（提取路径=真实路径）行为不变。
  *
  * @param {Array<{ path: string, method: string, source: string }>} frontendCalls
  * @param {Array<{ path: string, method: string, source: string }>} backendEndpoints
+ * @param {string[]} [mountPrefixes] 挂载前缀集合（scanMountPrefixes 收集）
  * @returns {{
  *   missingBackend: Array<{ path: string, method: string, consumerFile: string, consumerLine: number }>,
- *   unusedBackend: Array<{ path: string, method: string, providerFile: string }>
+ *   unusedBackend: Array<{ path: string, method: string, providerFile: string }>,
+ *   prefixAlignedCount: number,
+ *   ok: boolean
  * }}
  */
-export function diffApiParity(frontendCalls, backendEndpoints) {
+export function diffApiParity(frontendCalls, backendEndpoints, mountPrefixes = []) {
+  // 前缀降序（长的先剥）：/api/ppm 先于 /api，避免剥短前缀后路径失配
+  const prefixes = [...new Set((mountPrefixes || []).filter(p => p && p !== '/'))]
+    .sort((a, b) => b.length - a.length)
+
   // 构建 backend 注册表：归一化 path + method → endpoint
   const backendMap = new Map()
   for (const ep of backendEndpoints) {
@@ -344,27 +412,32 @@ export function diffApiParity(frontendCalls, backendEndpoints) {
   }
 
   const missingBackend = []
+  const frontendKeySet = new Set()
+  let prefixAlignedCount = 0
   for (const call of frontendCalls) {
-    const key = `${call.method}:${normalizePath(call.path)}`
-    if (!backendMap.has(key)) {
+    const base = normalizePath(call.path)
+    const candidates = [base]
+    for (const p of prefixes) {
+      if (base.startsWith(p + '/')) candidates.push(base.slice(p.length))
+    }
+    for (const c of candidates) frontendKeySet.add(`${call.method}:${c}`)
+    const matched = candidates.find(c => backendMap.has(`${call.method}:${c}`))
+    if (!matched) {
       missingBackend.push({
-        path: normalizePath(call.path),
+        path: base,
         method: call.method,
         consumerFile: call.source,
         consumerLine: call.line,
       })
+    } else if (matched !== base) {
+      prefixAlignedCount++
     }
   }
 
-  // 构建 frontend 调用表
-  const frontendSet = new Set(
-    frontendCalls.map(c => `${c.method}:${normalizePath(c.path)}`)
-  )
-
   const unusedBackend = []
   for (const ep of backendEndpoints) {
     const key = `${ep.method}:${normalizePath(ep.path)}`
-    if (!frontendSet.has(key)) {
+    if (!frontendKeySet.has(key)) {
       unusedBackend.push({
         path: normalizePath(ep.path),
         method: ep.method,
@@ -373,7 +446,7 @@ export function diffApiParity(frontendCalls, backendEndpoints) {
     }
   }
 
-  return { missingBackend, unusedBackend, ok: missingBackend.length === 0 }
+  return { missingBackend, unusedBackend, prefixAlignedCount, ok: missingBackend.length === 0 }
 }
 
 // ─── CLI 入口 ────────────────────────────────────────────────────────────
@@ -394,7 +467,9 @@ export async function contractScan(args, cwd) {
 
   const backendEndpoints = scanBackendEndpoints(backendDir)
   const frontendCalls = scanFrontendApiCalls(frontendDir)
-  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, backendEndpoints)
+  // 挂载前缀收集（坑 endpoints-mount-prefix-gap）：backend 根的挂载点（include_router/app.use）
+  const mountPrefixes = scanMountPrefixes(backendDir)
+  const { missingBackend, unusedBackend, prefixAlignedCount } = diffApiParity(frontendCalls, backendEndpoints, mountPrefixes)
 
   return {
     backend: backendEndpoints.map(e => ({ method: e.method, path: normalizePath(e.path), file: e.source })),
@@ -406,6 +481,7 @@ export async function contractScan(args, cwd) {
       frontendCallCount: frontendCalls.length,
       missingBackendCount: missingBackend.length,
       unusedBackendCount: unusedBackend.length,
+      prefixAlignedCount,
       ok: missingBackend.length === 0,
     },
   }

package/src/git-helper.js

@@ -13,6 +13,8 @@
  * safeGit 额外支持 opts.retryOnTimeout：ETIMEDOUT（机器忙瞬时抖动）时用 2× timeout 重试一次。
  */
 import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
 
 /**
  * git C 风格引号路径解码：`\\` `\"` `\n` `\t` 与 `\NNN` 八进制**原始字节**。
@@ -148,3 +150,32 @@ export function gitQuiet(cwd, args, opts = {}) {
     return null
   }
 }
+
+/**
+ * 归档产物机械暂存（2026-09-05 全流程审计：原 archive 步骤 6 的 3 条 git add agent 指令 CLI 化）。
+ * 固定路径：changes/archive/（归档产物）、knowledge/decisions/（决策提炼）、docs/<project>/modules/
+ * （本次同步的模块文档——按已存在目录枚举，未变的目录 git add 是无害 no-op）。
+ * 只 add 不 commit（统一提交工具处理）；平台模式由调用方跳过（specRoot 在源码仓外）。
+ * @param {string} cwd 源码项目根
+ * @returns {{ staged: string[], skipped: string[] }}
+ */
+export function stageArchiveArtifacts(cwd) {
+  const specBase = join(cwd, '.sillyspec')
+  const candidates = [join(specBase, 'changes', 'archive'), join(specBase, 'knowledge', 'decisions')]
+  const docsRoot = join(specBase, 'docs')
+  try {
+    for (const e of readdirSync(docsRoot, { withFileTypes: true })) {
+      if (e.isDirectory()) candidates.push(join(docsRoot, e.name, 'modules'))
+    }
+  } catch { /* 无 docs 目录 → 跳过 */ }
+  const staged = []
+  const skipped = []
+  const existing = candidates.filter(p => existsSync(p))
+  if (existing.length === 0) return { staged, skipped }
+  const r = safeGit(cwd, ['add', ...existing])
+  if (r && r.error) {
+    console.warn(`  ⚠️ 归档产物 git add 失败（可手动处理）：${String(r.error).slice(0, 120)}`)
+    return { staged, skipped: existing }
+  }
+  return { staged: existing, skipped }
+}