sillyspec 3.20.2 → 3.20.3

package/src/endpoint-extractor.js

@@ -1,315 +0,0 @@
-/**
- * endpoint-extractor.js — 从代码中提取 HTTP 端点定义和调用
- *
- * provider 端：扫描 router 文件，提取注册的 API 路径
- * consumer 端：扫描前端文件，提取 apiFetch/request 调用路径
- *
- * 契约对账时：provider 产出 ≠ consumer 消费 → gap
- */
-
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
-import { join, extname, basename, dirname, resolve } from 'path'
-import { execSync } from 'child_process'
-
-// ─── Provider: 扫描后端 router 注册的端点 ───────────────────────────────
-
-/**
- * 从单个文件提取 FastAPI router 端点
- * 支持 APIRouter(prefix=...) 和 @router.get/post/put/delete/patch("/path")
- *
- * @param {string} filePath - 文件绝对路径
- * @returns {Array<{ method: string, path: string, source: string, line: number }>}
- */
-export function extractFastApiEndpoints(filePath) {
-  const content = readFileSync(filePath, 'utf8')
-  const lines = content.split('\n')
-  const endpoints = []
-
-  // 1. 提取 router prefix
-  let routerPrefix = ''
-  for (const line of lines) {
-    const prefixMatch = line.match(/(?:APIRouter|router)\s*\(\s*(?:prefix\s*=\s*)?["'`]([^"'`]+)["'`]/)
-      || line.match(/\.include_router\s*\([^)]*prefix\s*=\s*["'`]([^"'`]+)["'`]/)
-    if (prefixMatch) {
-      routerPrefix = prefixMatch[1]
-    }
-  }
-
-  // 2. 提取 @router.method("/path") 或分散式定义
-  //    FastAPI 支持两种写法：
-  //    a) @router.get("/path", ...) 下一行 def func():
-  //    b) @router.get 下一行 ("/path", ...)
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    const decoratorMatch = line.match(
-      /@(?:router|api_router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/
-    )
-    if (decoratorMatch) {
-      const method = decoratorMatch[1].toUpperCase()
-      const rawPath = decoratorMatch[2]
-      endpoints.push({
-        method,
-        path: routerPrefix + rawPath,
-        source: filePath,
-        line: i + 1,
-      })
-      continue
-    }
-    // 分散式: @router.get\n    ("/path",
-    const splitMatch = line.match(/@(?:router|api_router)\.(get|post|put|delete|patch)\s*$/)
-    if (splitMatch && i + 1 < lines.length) {
-      const nextLine = lines[i + 1]
-      const pathMatch = nextLine.match(/\(\s*["'`]([^"'`]+)["'`]/)
-      if (pathMatch) {
-        endpoints.push({
-          method: splitMatch[1].toUpperCase(),
-          path: routerPrefix + pathMatch[1],
-          source: filePath,
-          line: i + 1,
-        })
-      }
-    }
-  }
-
-  return endpoints
-}
-
-/**
- * 从目录递归扫描所有 Python router 文件的端点
- * @param {string} dir
- * @param {{ filePattern?: RegExp, excludePatterns?: RegExp[] }} opts
- * @returns {Array<{ method: string, path: string, source: string, line: number }>}
- */
-export function scanBackendEndpoints(dir, opts = {}) {
-  const filePattern = opts.filePattern || /(?:router|routes|api|endpoint|controller)\.py$/i
-  const excludePatterns = opts.excludePatterns || [/__pycache__/, /node_modules/, /\.venv/, /test/i]
-
-  const results = []
-  if (!existsSync(dir)) return results
-
-  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() && filePattern.test(entry.name)) {
-        try {
-          results.push(...extractFastApiEndpoints(full))
-        } catch {}
-      }
-    }
-  }
-  walk(dir)
-  return results
-}
-
-// ─── Consumer: 扫描前端 API 调用路径 ─────────────────────────────────────
-
-/**
- * 从前端文件提取 API 调用路径
- * 支持：
- *   apiFetch("/api/xxx")
- *   request("/api/xxx")
- *   axios.get("/api/xxx")
- *   axios.post("/api/xxx")
- *   fetch("/api/xxx")
- *
- * @param {string} filePath
- * @returns {Array<{ method: string, path: string, source: string, line: number, raw: string }>}
- */
-export function extractFrontendApiCalls(filePath) {
-  const content = readFileSync(filePath, 'utf8')
-  const lines = content.split('\n')
-  const results = []
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-
-    // Pattern 1: apiFetch<T>("/path", { method: "POST" }) — default GET
-    const apiFetchMatch = line.match(/apiFetch\s*(?:<[^>]*>)?\s*\(\s*["'`]([^"'`]+)["'`]/)
-    if (apiFetchMatch) {
-      // 检查是否有 method 字段（在后续行或同一行）
-      let method = 'GET'
-      const snippet = lines.slice(i, Math.min(i + 3, lines.length)).join(' ')
-      const methodMatch = snippet.match(/method\s*:\s*["'`](GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)["'`]/i)
-      if (methodMatch) method = methodMatch[1].toUpperCase()
-
-      results.push({
-        method,
-        path: normalizePath(apiFetchMatch[1]),
-        source: filePath,
-        line: i + 1,
-        raw: apiFetchMatch[1],
-      })
-      continue
-    }
-
-    // Pattern 2: axios.get/post/put/delete("/path")
-    const axiosMatch = line.match(/axios\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/i)
-    if (axiosMatch) {
-      results.push({
-        method: axiosMatch[1].toUpperCase(),
-        path: normalizePath(axiosMatch[2]),
-        source: filePath,
-        line: i + 1,
-        raw: axiosMatch[2],
-      })
-      continue
-    }
-
-    // Pattern 3: fetch("/api/xxx", { method: "POST" })
-    const fetchMatch = line.match(/(?:api_?)?fetch\s*\(\s*["'`]([^"'`]+)["'`]/)
-    if (fetchMatch && !apiFetchMatch) {
-      let method = 'GET'
-      const snippet = lines.slice(i, Math.min(i + 3, lines.length)).join(' ')
-      const methodMatch = snippet.match(/method\s*:\s*["'`](GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)["'`]/i)
-      if (methodMatch) method = methodMatch[1].toUpperCase()
-
-      results.push({
-        method,
-        path: normalizePath(fetchMatch[1]),
-        source: filePath,
-        line: i + 1,
-        raw: fetchMatch[1],
-      })
-      continue
-    }
-  }
-
-  return results
-}
-
-/**
- * 递归扫描前端目录的 API 调用
- * @param {string} dir
- * @param {{ filePattern?: RegExp, excludePatterns?: RegExp[] }} opts
- * @returns {Array<{ method: string, path: string, source: string, line: number, raw: string }>}
- */
-export function scanFrontendApiCalls(dir, opts = {}) {
-  const filePattern = opts.filePattern || /\.(ts|tsx|js|jsx)$/
-  const excludePatterns = opts.excludePatterns || [/node_modules/, /\.next/, /dist/, /__tests__/, /\.d\.ts$/]
-
-  const results = []
-  if (!existsSync(dir)) return results
-
-  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() && filePattern.test(entry.name)) {
-        try {
-          results.push(...extractFrontendApiCalls(full))
-        } catch {}
-      }
-    }
-  }
-  walk(dir)
-  return results
-}
-
-// ─── 路径归一化 ─────────────────────────────────────────────────────────
-
-/**
- * 将动态路径归一化为参数占位符
- * /api/ppm/project-plan/${id}/plan-nodes → /api/ppm/project-plan/{param}/plan-nodes
- * /api/ppm/project-plan/:planId/plan-nodes → /api/ppm/project-plan/{param}/plan-nodes
- * @param {string} rawPath
- * @returns {string}
- */
-export function normalizePath(rawPath) {
-  return rawPath
-    .replace(/\$\{[^}]+\}/g, '{param}')
-    .replace(/:\w+/g, '{param}')
-    .replace(/\$\w+/g, '{param}')
-}
-
-// ─── 对账 ───────────────────────────────────────────────────────────────
-
-/**
- * 比较前端调用的路径和后端注册的端点，返回差异
- *
- * @param {Array<{ path: string, method: string, source: string }>} frontendCalls
- * @param {Array<{ path: string, method: string, source: string }>} backendEndpoints
- * @returns {{
- *   missingBackend: Array<{ path: string, method: string, consumerFile: string, consumerLine: number }>,
- *   unusedBackend: Array<{ path: string, method: string, providerFile: string }>
- * }}
- */
-export function diffApiParity(frontendCalls, backendEndpoints) {
-  // 构建 backend 注册表：归一化 path + method → endpoint
-  const backendMap = new Map()
-  for (const ep of backendEndpoints) {
-    const key = `${ep.method}:${normalizePath(ep.path)}`
-    if (!backendMap.has(key)) backendMap.set(key, ep)
-  }
-
-  const missingBackend = []
-  for (const call of frontendCalls) {
-    const key = `${call.method}:${normalizePath(call.path)}`
-    if (!backendMap.has(key)) {
-      missingBackend.push({
-        path: normalizePath(call.path),
-        method: call.method,
-        consumerFile: call.source,
-        consumerLine: call.line,
-      })
-    }
-  }
-
-  // 构建 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)) {
-      unusedBackend.push({
-        path: normalizePath(ep.path),
-        method: ep.method,
-        providerFile: ep.source,
-      })
-    }
-  }
-
-  return { missingBackend, unusedBackend, ok: missingBackend.length === 0 }
-}
-
-// ─── CLI 入口 ────────────────────────────────────────────────────────────
-
-/**
- * CLI 子命令入口：sillyspec contract scan [--backend dir] [--frontend dir]
- * 输出 JSON 格式的端点清单和对账结果
- */
-export async function contractScan(args, cwd) {
-  const backendIdx = args.indexOf('--backend')
-  const frontendIdx = args.indexOf('--frontend')
-  const backendDir = backendIdx !== -1 && args[backendIdx + 1]
-    ? resolve(cwd, args[backendIdx + 1])
-    : resolve(cwd, 'backend')
-  const frontendDir = frontendIdx !== -1 && args[frontendIdx + 1]
-    ? resolve(cwd, args[frontendIdx + 1])
-    : resolve(cwd, 'frontend')
-
-  const backendEndpoints = scanBackendEndpoints(backendDir)
-  const frontendCalls = scanFrontendApiCalls(frontendDir)
-  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, backendEndpoints)
-
-  return {
-    backend: backendEndpoints.map(e => ({ method: e.method, path: normalizePath(e.path), file: e.source })),
-    frontend: frontendCalls.map(c => ({ method: c.method, path: normalizePath(c.path), file: c.source })),
-    missingBackend,
-    unusedBackend,
-    summary: {
-      backendEndpointCount: backendEndpoints.length,
-      frontendCallCount: frontendCalls.length,
-      missingBackendCount: missingBackend.length,
-      unusedBackendCount: unusedBackend.length,
-      ok: missingBackend.length === 0,
-    },
-  }
-}

package/src/hooks/claude-pre-tool-use.cjs

@@ -1,125 +0,0 @@
-#!/usr/bin/env node
-/**
- * Claude Code PreToolUse hook 入口
- *
- * 从 stdin 读取 JSON，调用 worktree-guard 判断是否拦截。
- *
- * Claude Code hooks.json 配置：
- * {
- *   "hooks": {
- *     "PreToolUse": [
- *       {
- *         "matcher": "Edit|Write|MultiEdit|Bash",
- *         "hooks": [
- *           {
- *             "type": "command",
- *             "command": "node /path/to/sillyspec/src/hooks/claude-pre-tool-use.cjs"
- *           }
- *         ]
- *       }
- *     ]
- *   }
- * }
- */
-
-'use strict'
-
-const path = require('path')
-const fs = require('fs')
-
-// 动态 import ESM 模块
-async function main() {
-  // Claude Code hook 通过 stdin 传入 JSON
-  let input = ''
-  try {
-    input = await readStdin()
-  } catch {
-    // 无法读取 stdin → 放行（安全优先于阻断）
-    process.exit(0)
-  }
-
-  let parsed
-  try {
-    parsed = JSON.parse(input)
-  } catch {
-    // 非法 JSON → 放行
-    process.exit(0)
-  }
-
-  // 解析 Claude Code hook 输入格式
-  // 格式：{ tool_name: string, tool_input: { ... } }
-  const toolName = parsed.tool_name || parsed.tool || ''
-  const toolInput = parsed.tool_input || {}
-
-  // 转换为 shouldBlock 的输入格式
-  const toolMap = {
-    'Write': 'Write',
-    'Edit': 'Edit',
-    'MultiEdit': 'MultiEdit',
-    'Bash': 'Bash',
-  }
-
-  const mappedTool = toolMap[toolName]
-  if (!mappedTool) {
-    // 不在拦截范围内的工具 → 放行
-    process.exit(0)
-  }
-
-  // 构造 opts
-  const opts = { tool: mappedTool }
-  if (mappedTool === 'Bash') {
-    opts.command = toolInput.command || ''
-  } else {
-    // Write/Edit/MultiEdit
-    const fp = toolInput.file_path || toolInput.filePath
-    if (fp) opts.filePath = fp
-    // MultiEdit 可能有多个文件
-    if (mappedTool === 'MultiEdit') {
-      const fps = toolInput.edits
-        ? toolInput.edits.map(e => e.file_path || e.filePath).filter(Boolean)
-        : []
-      if (fps.length > 0) opts.filePaths = fps
-    }
-  }
-
-  // 加载 worktree-guard（ESM）
-  let shouldBlock
-  try {
-    const mod = await import('./worktree-guard.js')
-    shouldBlock = mod.shouldBlock
-  } catch (e) {
-    // 模块加载失败 → 放行（不因为 hook 出错阻断工作流）
-    // eslint-disable-next-line no-console
-    console.error(`[sillyspec-hook] 模块加载失败: ${e.message}`)
-    process.exit(0)
-  }
-
-  const result = shouldBlock(opts)
-
-  if (result.blocked) {
-    // 输出错误信息（Claude Code 会显示给 agent）
-    // eslint-disable-next-line no-console
-    console.error(`[sillyspec] ❌ ${result.reason || 'blocked by worktree guard'}`)
-    process.exit(2) // exit code 2 = 阻止工具执行
-  }
-
-  // 放行
-  process.exit(0)
-}
-
-function readStdin() {
-  return new Promise((resolve, reject) => {
-    const chunks = []
-    process.stdin.setEncoding('utf8')
-    process.stdin.on('data', chunk => chunks.push(chunk))
-    process.stdin.on('end', () => resolve(chunks.join('')))
-    process.stdin.on('error', reject)
-    // 超时保护（3秒）
-    setTimeout(() => {
-      process.stdin.destroy()
-      resolve('')
-    }, 3000)
-  })
-}
-
-main().catch(() => process.exit(0))