sillyspec 3.18.2 → 3.18.4

package/test/contract-artifacts.test.mjs

@@ -0,0 +1,323 @@
+/**
+ * endpoint-extractor 和 contract-matrix 测试
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { writeFileSync, mkdirSync, rmSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import {
+  extractFastApiEndpoints,
+  extractFrontendApiCalls,
+  normalizePath,
+  diffApiParity,
+} from '../src/endpoint-extractor.js'
+import {
+  classifyTask,
+} from '../src/contract-matrix.js'
+
+// ─── 路径归一化 ─────────────────────────────────────────────────────────
+
+describe('normalizePath', () => {
+  it('模板字符串归一化', () => {
+    assert.equal(normalizePath('/api/ppm/project-plan/${id}/plan-nodes'), '/api/ppm/project-plan/{param}/plan-nodes')
+  })
+
+  it('Express 风格参数归一化', () => {
+    assert.equal(normalizePath('/api/users/:userId/posts'), '/api/users/{param}/posts')
+  })
+
+  it('无参数不改变', () => {
+    assert.equal(normalizePath('/api/ppm/plan-node'), '/api/ppm/plan-node')
+  })
+})
+
+// ─── FastAPI 端点提取 ──────────────────────────────────────────────────
+
+describe('extractFastApiEndpoints', () => {
+  const tmpDir = join(tmpdir(), 'sillyspec-test-fastapi')
+  const routerFile = join(tmpDir, 'router.py')
+
+  it('提取单行装饰器端点', () => {
+    mkdirSync(tmpDir, { recursive: true })
+    writeFileSync(routerFile, [
+      'from fastapi import APIRouter',
+      'router = APIRouter(prefix="/api/ppm")',
+      '',
+      '@router.get("/plan-node")',
+      'async def list_plan_nodes():',
+      '    pass',
+      '',
+      '@router.post("/plan-node")',
+      'async def create_plan_node():',
+      '    pass',
+      '',
+      '@router.get("/project-plan/{plan_id}/plan-nodes")',
+      'async def list_ps_plan_nodes(plan_id: str):',
+      '    pass',
+    ].join('\n'), 'utf8')
+
+    const endpoints = extractFastApiEndpoints(routerFile)
+    assert.equal(endpoints.length, 3)
+    assert.equal(endpoints[0].method, 'GET')
+    assert.equal(endpoints[0].path, '/api/ppm/plan-node')
+    assert.equal(endpoints[1].method, 'POST')
+    assert.equal(endpoints[1].path, '/api/ppm/plan-node')
+    assert.equal(endpoints[2].method, 'GET')
+    assert.equal(endpoints[2].path, '/api/ppm/project-plan/{plan_id}/plan-nodes')
+  })
+
+  it('prefix + 路径正确合并', () => {
+    mkdirSync(tmpDir, { recursive: true })
+    writeFileSync(routerFile, [
+      'router = APIRouter(prefix="/api/v2")',
+      '@router.get("/users")',
+      'async def list_users():',
+      '    pass',
+    ].join('\n'), 'utf8')
+
+    const endpoints = extractFastApiEndpoints(routerFile)
+    assert.equal(endpoints.length, 1)
+    assert.equal(endpoints[0].path, '/api/v2/users')
+  })
+
+  it('空文件返回空', () => {
+    mkdirSync(tmpDir, { recursive: true })
+    writeFileSync(routerFile, '', 'utf8')
+    const endpoints = extractFastApiEndpoints(routerFile)
+    assert.equal(endpoints.length, 0)
+  })
+
+  // cleanup
+  it('cleanup', () => {
+    try { rmSync(tmpDir, { recursive: true, force: true }) } catch {}
+  })
+})
+
+// ─── 前端 API 调用提取 ─────────────────────────────────────────────────
+
+describe('extractFrontendApiCalls', () => {
+  const tmpDir = join(tmpdir(), 'sillyspec-test-frontend')
+  const apiFile = join(tmpDir, 'plan.ts')
+
+  it('提取 apiFetch 调用', () => {
+    mkdirSync(tmpDir, { recursive: true })
+    writeFileSync(apiFile, [
+      'export async function listPlanNodes(params: PageReq): Promise<PlanNode[]> {',
+      '  return apiFetch<PlanNode[]>("/api/ppm/plan-node", { query: params });',
+      '}',
+      '',
+      'export async function getProjectPlan(planId: string): Promise<ProjectPlan> {',
+      '  return apiFetch<ProjectPlan>(`/api/ppm/project-plan/${planId}`);',
+      '}',
+      '',
+      'export async function listPlanNodesByPlan(planId: string): Promise<PsPlanNode[]> {',
+      '  return apiFetch<PsPlanNode[]>(`/api/ppm/project-plan/${planId}/plan-nodes`);',
+      '}',
+      '',
+      'export async function createPlanNode(body: CreateReq): Promise<PlanNode> {',
+      '  return apiFetch<PlanNode>("/api/ppm/plan-node", {',
+      '    method: "POST",',
+      '    json: body,',
+      '  });',
+      '}',
+      '',
+      'export async function deletePlan(id: string): Promise<void> {',
+      '  await apiFetch(`/api/ppm/plan-node/${id}`, { method: "DELETE" });',
+      '}',
+    ].join('\n'), 'utf8')
+
+    const calls = extractFrontendApiCalls(apiFile)
+    assert.ok(calls.length >= 5)
+
+    // GET /api/ppm/plan-node
+    const listCall = calls.find(c => c.raw === '/api/ppm/plan-node' && c.method === 'GET')
+    assert.ok(listCall, 'should find GET /api/ppm/plan-node')
+
+    // GET with template string → 归一化
+    const detailCall = calls.find(c => c.path === '/api/ppm/project-plan/{param}')
+    assert.ok(detailCall, 'should find GET /api/ppm/project-plan/{param}')
+
+    // POST
+    const createCall = calls.find(c => c.method === 'POST')
+    assert.ok(createCall, 'should find POST call')
+
+    // DELETE
+    const deleteCall = calls.find(c => c.method === 'DELETE')
+    assert.ok(deleteCall, 'should find DELETE call')
+  })
+
+  it('模板字符串归一化为 {param}', () => {
+    mkdirSync(tmpDir, { recursive: true })
+    writeFileSync(apiFile, [
+      'const id = "123";',
+      'apiFetch(`/api/users/${id}/profile`);',
+    ].join('\n'), 'utf8')
+
+    const calls = extractFrontendApiCalls(apiFile)
+    assert.equal(calls.length, 1)
+    assert.equal(calls[0].path, '/api/users/{param}/profile')
+  })
+
+  // cleanup
+  it('cleanup', () => {
+    try { rmSync(tmpDir, { recursive: true, force: true }) } catch {}
+  })
+})
+
+// ─── Parity Check ──────────────────────────────────────────────────────
+
+describe('diffApiParity', () => {
+  it('前端调用后端不存在路径时 missingBackend', () => {
+    const frontendCalls = [
+      { method: 'GET', path: '/api/ppm/plan-node', source: 'plan.ts', line: 10 },
+      { method: 'GET', path: '/api/ppm/project-plan/{param}/plan-nodes', source: 'plan.ts', line: 20 },
+    ]
+    const backendEndpoints = [
+      { method: 'GET', path: '/api/ppm/plan-node', source: 'router.py' },
+      // 缺少 /project-plan/{id}/plan-nodes
+    ]
+
+    const result = diffApiParity(frontendCalls, backendEndpoints)
+    assert.equal(result.missingBackend.length, 1)
+    assert.equal(result.missingBackend[0].path, '/api/ppm/project-plan/{param}/plan-nodes')
+    assert.equal(result.unusedBackend.length, 0)
+    assert.equal(result.ok, false)
+  })
+
+  it('全部匹配时 ok', () => {
+    const frontendCalls = [
+      { method: 'GET', path: '/api/ppm/plan-node', source: 'plan.ts', line: 10 },
+    ]
+    const backendEndpoints = [
+      { method: 'GET', path: '/api/ppm/plan-node', source: 'router.py' },
+    ]
+
+    const result = diffApiParity(frontendCalls, backendEndpoints)
+    assert.equal(result.ok, true)
+    assert.equal(result.missingBackend.length, 0)
+  })
+
+  it('后端有但前端未调用的路径在 unusedBackend', () => {
+    const frontendCalls = []
+    const backendEndpoints = [
+      { method: 'GET', path: '/api/ppm/internal/health', source: 'router.py' },
+    ]
+
+    const result = diffApiParity(frontendCalls, backendEndpoints)
+    assert.equal(result.unusedBackend.length, 1)
+    assert.equal(result.unusedBackend[0].path, '/api/ppm/internal/health')
+  })
+})
+
+// ─── Task 分类 ──────────────────────────────────────────────────────────
+
+describe('classifyTask', () => {
+  it('后端 router task 识别为 provider', () => {
+    const content = '## 目标\n实现 plan 子域后端 router，包含 APIRouter 路由注册。'
+    const result = classifyTask(content)
+    assert.ok(result.isProvider)
+  })
+
+  it('前端 API client task 识别为 consumer', () => {
+    const content = '## 目标\n为前端提供统一 API client，使用 apiFetch 封装。'
+    const result = classifyTask(content)
+    assert.ok(result.isConsumer)
+  })
+
+  it('纯文档 task 两者都不是', () => {
+    const content = '## 目标\n更新 README 文档。'
+    const result = classifyTask(content)
+    assert.ok(!result.isProvider || result.confidence < 0.5)
+    assert.ok(!result.isConsumer || result.confidence < 0.5)
+  })
+})
+
+// ─── 集成测试：复现 PPM 真实场景 ───────────────────────────────────────
+
+describe('PPM 真实场景：跨 task 端点漏实现', () => {
+  const tmpDir = join(tmpdir(), 'sillyspec-test-ppm')
+  const routerFile = join(tmpDir, 'router.py')
+  const apiClientFile = join(tmpDir, 'plan.ts')
+
+  it('verify 应该 FAIL：前端调用 /project-plan/{id}/plan-nodes 但后端未实现', () => {
+    mkdirSync(tmpDir, { recursive: true })
+
+    // 模拟 task-04 后端实现：只注册了基础 CRUD，遗漏嵌套端点
+    writeFileSync(routerFile, [
+      'router = APIRouter(prefix="/api/ppm")',
+      '',
+      '@router.get("/plan-node")',
+      'async def list_plan_nodes():',
+      '    pass',
+      '',
+      '@router.post("/plan-node")',
+      'async def create_plan_node():',
+      '    pass',
+      '',
+      '@router.get("/project-plan")',
+      'async def list_project_plans():',
+      '    pass',
+      '',
+      '@router.post("/project-plan")',
+      'async def create_project_plan():',
+      '    pass',
+    ].join('\n'), 'utf8')
+
+    // 模拟 task-09 前端 API client：调用了后端不存在的嵌套端点
+    writeFileSync(apiClientFile, [
+      'export async function listProjectPlans(params: PageReq) {',
+      '  return apiFetch<ProjectPlan[]>("/api/ppm/project-plan", pageQuery(params));',
+      '}',
+      '',
+      'export async function listPlanNodes(planId: string) {',
+      '  // ← 后端没实现这个嵌套端点',
+      '  return apiFetch<PsPlanNode[]>(`/api/ppm/project-plan/${planId}/plan-nodes`);',
+      '}',
+      '',
+      'export async function listPlanNodeDetails(nodeId: string) {',
+      '  // ← 后端也没实现这个',
+      '  return apiFetch<PlanNodeDetail[]>(`/api/ppm/plan-node/${nodeId}/details`);',
+      '}',
+    ].join('\n'), 'utf8')
+
+    // 提取后端端点
+    const backendEndpoints = extractFastApiEndpoints(routerFile)
+    const backendPaths = new Set(backendEndpoints.map(e => normalizePath(e.path)))
+
+    // 提取前端调用
+    const frontendCalls = extractFrontendApiCalls(apiClientFile)
+    const { missingBackend, ok } = diffApiParity(frontendCalls, backendEndpoints)
+
+    // 断言：后端只实现了基础 CRUD
+    assert.ok(backendPaths.has('/api/ppm/plan-node'), '后端应有 GET /plan-node')
+    assert.ok(backendPaths.has('/api/ppm/project-plan'), '后端应有 GET /project-plan')
+
+    // 断言：parity check 失败
+    assert.equal(ok, false, 'verify 应该 FAIL')
+    assert.equal(missingBackend.length, 2, '应发现 2 个缺失端点')
+
+    // 断言：缺失的端点正是 PPM 真实 bug 的那两个
+    const missingPaths = missingBackend.map(m => m.path)
+    assert.ok(
+      missingPaths.includes('/api/ppm/project-plan/{param}/plan-nodes'),
+      '应捕获缺失的 /project-plan/{id}/plan-nodes'
+    )
+    assert.ok(
+      missingPaths.includes('/api/ppm/plan-node/{param}/details'),
+      '应捕获缺失的 /plan-node/{id}/details'
+    )
+
+    // 断言：diff 输出带 source 文件路径
+    const planNodesGap = missingBackend.find(
+      m => m.path === '/api/ppm/project-plan/{param}/plan-nodes'
+    )
+    assert.ok(planNodesGap.consumerFile.includes('plan.ts'), '应带前端文件路径')
+    assert.equal(planNodesGap.consumerLine, 7, '应带行号')
+  })
+
+  it('cleanup', () => {
+    try { rmSync(tmpDir, { recursive: true, force: true }) } catch {}
+  })
+})

package/test/knowledge-match.test.mjs

@@ -0,0 +1,231 @@
+/**
+ * knowledge-match.test.mjs — knowledge 关键词匹配引擎测试
+ */
+
+import { join } from 'path'
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { fileURLToPath, pathToFileURL } from 'url'
+import { tmpdir } from 'os'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = join(__filename, '..') // join(__dirname, '..') to get parent
+const root = join(__dirname, '..')
+
+const { parseKnowledgeIndex, matchKnowledge } = await import(
+  pathToFileURL(join(root, 'src', 'knowledge-match.js')).href
+)
+
+let passed = 0, failed = 0
+
+function assert(cond, msg) {
+  if (cond) { console.log(`  ✅ PASS: ${msg}`); passed++ }
+  else { console.log(`  ❌ FAIL: ${msg}`); failed++ }
+}
+
+function setup(name) {
+  const dir = join(tmpdir(), `kh-test-${name}`)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+function clean(...dirs) {
+  for (const d of dirs) try { rmSync(d, { recursive: true, force: true }) } catch {}
+}
+
+// ── 1: 有匹配条目 → matched=true, entries.length > 0 ──
+console.log('\n=== Test 1: 有匹配条目 → matched=true ===')
+{
+  const dir = setup('t1')
+  try {
+    writeFileSync(join(dir, 'INDEX.md'), [
+      '# Knowledge Index',
+      '',
+      '## Conventions',
+      '- ESM|module|import → [ESM Only](conventions.md#esm-only)',
+      '',
+      '## Patterns',
+      '- 阶段定义|stage|stages → [Stage Pattern](patterns.md#stage-step-pattern)',
+    ].join('\n'))
+
+    const result = matchKnowledge(dir, 'setup ESM module imports')
+    assert(result.matched === true, 'matched is true')
+    assert(result.entries.length === 1, 'one entry matched')
+    assert(result.entries[0].file === 'conventions.md', 'file is conventions.md')
+    assert(result.entries[0].anchor === 'esm-only', 'anchor is esm-only')
+    assert(result.entries[0].keywords.includes('ESM'), 'keywords include ESM')
+  } finally { clean(dir) }
+}
+
+// ── 2: 无匹配条目 → matched=false, report 包含 "no matches" ──
+console.log('\n=== Test 2: 无匹配条目 → matched=false ===')
+{
+  const dir = setup('t2')
+  try {
+    writeFileSync(join(dir, 'INDEX.md'), [
+      '# Knowledge Index',
+      '',
+      '## Patterns',
+      '- 阶段定义|stage → [Stage Pattern](patterns.md#stage-step-pattern)',
+    ].join('\n'))
+
+    const result = matchKnowledge(dir, 'implement authentication flow')
+    assert(result.matched === false, 'matched is false')
+    assert(result.entries.length === 0, 'no entries matched')
+    assert(result.report.includes('no matches'), 'report says no matches')
+  } finally { clean(dir) }
+}
+
+// ── 3: INDEX.md 不存在 → matched=false, report 包含 "not found" ──
+console.log('\n=== Test 3: INDEX.md 不存在 → matched=false ===')
+{
+  const dir = setup('t3')
+  try {
+    const result = matchKnowledge(dir, 'any context')
+    assert(result.matched === false, 'matched is false')
+    assert(result.report.includes('not found'), 'report says not found')
+    assert(result.json.matched === false, 'json.matched is false')
+    assert(result.json.entry_count === 0, 'json.entry_count is 0')
+  } finally { clean(dir) }
+}
+
+// ── 4: INDEX.md 有空锚点引用 → 正常处理（不过度校验）──
+console.log('\n=== Test 4: INDEX.md 有空锚点引用 → 正常处理 ===')
+{
+  const dir = setup('t4')
+  try {
+    writeFileSync(join(dir, 'INDEX.md'), [
+      '# Knowledge Index',
+      '',
+      '## Conventions',
+      '- naming|camelCase → [Naming](conventions.md)',
+    ].join('\n'))
+
+    const result = matchKnowledge(dir, 'naming conventions')
+    assert(result.matched === true, 'matched is true with empty anchor')
+    assert(result.entries[0].anchor === '', 'anchor is empty string')
+    assert(result.entries[0].file === 'conventions.md', 'file is correct')
+  } finally { clean(dir) }
+}
+
+// ── 5: 大小写不敏感匹配 → "STAGE" 匹配 "stage" ──
+console.log('\n=== Test 5: 大小写不敏感匹配 ===')
+{
+  const dir = setup('t5')
+  try {
+    writeFileSync(join(dir, 'INDEX.md'), [
+      '# Knowledge Index',
+      '',
+      '## Patterns',
+      '- stage|stages → [Stage Pattern](patterns.md#stage-step-pattern)',
+    ].join('\n'))
+
+    const result = matchKnowledge(dir, 'implement STAGE definition')
+    assert(result.matched === true, 'STAGE matches stage')
+    assert(result.entries.length === 1, 'one entry matched')
+  } finally { clean(dir) }
+}
+
+// ── 6: report 格式包含 "Knowledge Context" header ──
+console.log('\n=== Test 6: report 格式包含 Knowledge Context header ===')
+{
+  const dir = setup('t6')
+  try {
+    writeFileSync(join(dir, 'INDEX.md'), [
+      '# Knowledge Index',
+      '',
+      '## Patterns',
+      '- 阶段定义|stage → [Stage Pattern](patterns.md#stage-step-pattern)',
+    ].join('\n'))
+
+    const result = matchKnowledge(dir, 'stage configuration')
+    assert(result.report.includes('Knowledge Context'), 'report has Knowledge Context header')
+    assert(result.report.includes('Status: matched'), 'report has Status: matched')
+    assert(result.report.includes('Entries: 1'), 'report has Entries: 1')
+    assert(result.report.includes('patterns.md#stage-step-pattern'), 'report has source')
+  } finally { clean(dir) }
+}
+
+// ── 7: json 结构正确 ──
+console.log('\n=== Test 7: json 结构正确 ===')
+{
+  const dir = setup('t7')
+  try {
+    writeFileSync(join(dir, 'INDEX.md'), [
+      '# Knowledge Index',
+      '',
+      '## Conventions',
+      '- ESM|module → [ESM Only](conventions.md#esm-only)',
+      '',
+      '## Patterns',
+      '- stage|stages → [Stage Pattern](patterns.md#stage-step-pattern)',
+    ].join('\n'))
+
+    const result = matchKnowledge(dir, 'stage module setup')
+    const j = result.json
+    assert(j.matched === true, 'json.matched is true')
+    assert(j.entry_count === 2, 'json.entry_count is 2')
+    assert(Array.isArray(j.entries), 'json.entries is array')
+    assert(j.entries.length === 2, 'json.entries length is 2')
+
+    const stageEntry = j.entries.find(e => e.anchor === 'stage-step-pattern')
+    assert(!!stageEntry, 'stage entry found in json')
+    assert(stageEntry.keywords.includes('stage'), 'stage keywords correct')
+    assert(stageEntry.category === 'Patterns', 'stage category correct')
+    assert(stageEntry.file === 'patterns.md', 'stage file correct')
+  } finally { clean(dir) }
+}
+
+// ── 8: 空目录（目录存在但无 INDEX.md）→ no matches ──
+console.log('\n=== Test 8: 空目录（无 INDEX.md）→ no matches ===')
+{
+  const dir = setup('t8')
+  try {
+    const result = matchKnowledge(dir, 'any task')
+    assert(result.matched === false, 'no INDEX.md → matched false')
+    assert(result.report.includes('not found'), 'report says not found')
+  } finally { clean(dir) }
+}
+
+// ── 9: parseKnowledgeIndex 返回正确分类 ──
+console.log('\n=== Test 9: parseKnowledgeIndex 分类正确 ===')
+{
+  const dir = setup('t9')
+  try {
+    writeFileSync(join(dir, 'INDEX.md'), [
+      '# Knowledge Index',
+      '',
+      '## Known Issues',
+      '- GLM|proxy → [GLM Proxy](known-issues.md#glm-proxy)',
+      '',
+      '## Conventions',
+      '- 命名|naming → [命名规范](conventions.md#naming)',
+    ].join('\n'))
+
+    const entries = parseKnowledgeIndex(dir)
+    assert(entries.length === 2, 'parsed 2 entries')
+    assert(entries[0].category === 'Known Issues', 'first entry category correct')
+    assert(entries[1].category === 'Conventions', 'second entry category correct')
+    assert(entries[0].display === 'GLM Proxy', 'display text correct')
+  } finally { clean(dir) }
+}
+
+// ── 10: taskContext 为空 → no matches ──
+console.log('\n=== Test 10: taskContext 为空 → no matches ===')
+{
+  const dir = setup('t10')
+  try {
+    writeFileSync(join(dir, 'INDEX.md'), [
+      '# Knowledge Index',
+      '',
+      '## Patterns',
+      '- stage → [Stage](patterns.md#stage)',
+    ].join('\n'))
+
+    const result = matchKnowledge(dir, '')
+    assert(result.matched === false, 'empty context → matched false')
+  } finally { clean(dir) }
+}
+
+// ── 汇总 ──
+console.log(`\n${'='.repeat(40)}`)
+console.log(`knowledge-match tests: ${passed} passed, ${failed} failed, ${passed + failed} total`)
+if (failed > 0) process.exit(1)