@dommaker/harness 0.13.0 → 0.13.2

package/src/spec/__tests__/annotation-checker.test.ts

@@ -0,0 +1,289 @@
+/**
+ * AnnotationChecker 测试
+ */
+
+import { checkFile, checkDirectory, generateReport } from '../annotation-checker';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Mock fs
+jest.mock('fs', () => ({
+  readFileSync: jest.fn(),
+  readdirSync: jest.fn(),
+  statSync: jest.fn(),
+  existsSync: jest.fn(),
+}));
+
+const mockFs = fs as jest.Mocked<typeof fs>;
+
+describe('AnnotationChecker', () => {
+  const tempDir = '/test/project';
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('checkFile', () => {
+    it('应该检查有效的 JSDoc 注释', () => {
+      mockFs.readFileSync.mockReturnValue(`
+/**
+ * @spec AR-001
+ * @implements feature-auth
+ * @acceptance AC-001
+ * @author test
+ * @since 2026-04-28
+ */
+export function auth() {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.annotations.length).toBe(1);
+      expect(result.annotations[0]?.specId).toBe('AR-001');
+      expect(result.annotations[0]?.implements).toContain('feature-auth');
+      expect(result.annotations[0]?.acceptance).toContain('AC-001');
+      expect(result.annotations[0]?.author).toBe('test');
+      expect(result.annotations[0]?.since).toBe('2026-04-28');
+    });
+
+    it('应该检查行内注释', () => {
+      mockFs.readFileSync.mockReturnValue(`
+// @spec AR-002
+const x = 1;
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.annotations.length).toBe(1);
+      expect(result.annotations[0]?.specId).toBe('AR-002');
+      expect(result.annotations[0]?.type).toBe('inline');
+    });
+
+    it('应该检测无效 Spec ID 格式', () => {
+      mockFs.readFileSync.mockReturnValue(`
+/**
+ * @spec INVALID-ID
+ */
+export function test() {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.errors.length).toBeGreaterThan(0);
+      expect(result.errors[0]?.code).toBe('INVALID_SPEC_FORMAT');
+    });
+
+    it('应该警告缺少 @implements', () => {
+      mockFs.readFileSync.mockReturnValue(`
+/**
+ * @spec AR-003
+ */
+class MyClass {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.warnings.length).toBeGreaterThan(0);
+      expect(result.warnings.some(w => w.code === 'MISSING_IMPLEMENTS')).toBe(true);
+    });
+
+    it('应该警告缺少 @acceptance', () => {
+      mockFs.readFileSync.mockReturnValue(`
+/**
+ * @spec AR-004
+ * @implements feat
+ */
+function myFunc() {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.warnings.some(w => w.code === 'MISSING_ACCEPTANCE')).toBe(true);
+    });
+
+    it('应该推断注释类型', () => {
+      mockFs.readFileSync.mockReturnValue(`
+/**
+ * @spec AR-005
+ */
+class MyClass {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.annotations[0]?.type).toBeDefined();
+    });
+
+    it('应该推断 function 类型', () => {
+      mockFs.readFileSync.mockReturnValue(`
+/**
+ * @spec AR-006
+ */
+async function myAsync() {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.annotations[0]?.type).toBeDefined();
+    });
+
+    it('应该推断 method 类型', () => {
+      mockFs.readFileSync.mockReturnValue(`
+/**
+ * @spec AR-007
+ */
+myMethod() {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.annotations[0]?.type).toBeDefined();
+    });
+
+    it('应该检查公共导出缺少 @spec', () => {
+      mockFs.readFileSync.mockReturnValue(`
+export class NoSpecClass {}
+export function noSpecFunc() {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      // 公共导出可能触发 MISSING_SPEC 警告（通过 checkPublicExports）
+      expect(result.warnings.length + result.errors.length).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('checkDirectory', () => {
+    it('应该递归检查目录', () => {
+      // 需要更完整的 mock，简化测试
+      mockFs.readdirSync.mockReturnValue([] as any);
+
+      const results = checkDirectory(tempDir);
+
+      expect(Array.isArray(results)).toBe(true);
+    });
+
+    it('应该跳过 node_modules 和 dist', () => {
+      mockFs.readdirSync.mockReturnValue(['src'] as any);
+
+      const results = checkDirectory(tempDir);
+
+      // 应该跳过 node_modules 和 dist
+      expect(Array.isArray(results)).toBe(true);
+    });
+
+    it('应该处理空目录', () => {
+      mockFs.readdirSync.mockReturnValue([]);
+
+      const results = checkDirectory(tempDir);
+
+      expect(results.length).toBe(0);
+    });
+  });
+
+  describe('generateReport', () => {
+    it('应该生成报告', () => {
+      const results = [
+        {
+          valid: true,
+          file: '/test/file.ts',
+          annotations: [],
+          errors: [],
+          warnings: [],
+        },
+        {
+          valid: false,
+          file: '/test/bad.ts',
+          annotations: [],
+          errors: [{ line: 1, message: 'Error', code: 'INVALID_SPEC_FORMAT' as const }],
+          warnings: [{ line: 2, message: 'Warning', code: 'MISSING_ACCEPTANCE' as const }],
+        },
+      ];
+
+      const report = generateReport(results);
+
+      expect(report).toContain('注释规范检查报告');
+      expect(report).toContain('检查文件: 2');
+      expect(report).toContain('通过: 1');
+      expect(report).toContain('错误: 1');
+      expect(report).toContain('警告: 1');
+    });
+
+    it('应该处理空结果', () => {
+      const report = generateReport([]);
+
+      expect(report).toContain('检查文件: 0');
+      expect(report).toContain('通过: 0');
+    });
+
+    it('应该截断警告显示（最多5条）', () => {
+      const results = [{
+        valid: true,
+        file: '/test/file.ts',
+        annotations: [],
+        errors: [],
+        warnings: Array(10).fill({ line: 1, message: 'Warning', code: 'MISSING_ACCEPTANCE' as const }),
+      }];
+
+      const report = generateReport(results);
+
+      expect(report).toContain('警告');
+    });
+  });
+
+  describe('边缘情况', () => {
+    it('应该处理空文件', () => {
+      mockFs.readFileSync.mockReturnValue('');
+
+      const result = checkFile('/test/empty.ts');
+
+      expect(result.annotations.length).toBe(0);
+      expect(result.errors.length).toBe(0);
+    });
+
+    it('应该处理多行 JSDoc', () => {
+      mockFs.readFileSync.mockReturnValue(`
+/**
+ * First line
+ * Second line
+ * @spec AR-009
+ * Third line
+ */
+export function multi() {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.annotations.length).toBe(1);
+      expect(result.annotations[0]?.specId).toBe('AR-009');
+    });
+
+    it('应该处理多个 @implements', () => {
+      mockFs.readFileSync.mockReturnValue(`
+/**
+ * @spec AR-010
+ * @implements feat1, feat2, feat3
+ */
+export function multiImpl() {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.annotations[0]?.implements?.length).toBeGreaterThanOrEqual(3);
+    });
+
+    it('应该处理 @dependencies', () => {
+      mockFs.readFileSync.mockReturnValue(`
+/**
+ * @spec AR-011
+ * @dependencies lib1, lib2
+ */
+export function withDeps() {}
+`);
+
+      const result = checkFile('/test/file.ts');
+
+      expect(result.annotations[0]?.dependencies?.length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/spec/annotation-checker.ts

@@ -0,0 +1,342 @@
+/**
+ * 代码注释规范检查器
+ *
+ * 检查代码中的 @spec 注释是否规范
+ */
+
+import { readFileSync, readdirSync, statSync } from 'fs';
+import * as path from 'path';
+
+export interface AnnotationCheckResult {
+  valid: boolean;
+  file: string;
+  annotations: SpecAnnotation[];
+  errors: AnnotationError[];
+  warnings: AnnotationWarning[];
+}
+
+export interface SpecAnnotation {
+  specId: string;
+  implements?: string[];
+  acceptance?: string[];
+  dependencies?: string[];
+  author?: string;
+  since?: string;
+  line: number;
+  type: 'class' | 'method' | 'function' | 'inline';
+}
+
+export interface AnnotationError {
+  line: number;
+  message: string;
+  code: 'MISSING_SPEC' | 'INVALID_SPEC_FORMAT' | 'SPEC_NOT_APPROVED' | 'IMPLEMENTS_NOT_FOUND';
+}
+
+export interface AnnotationWarning {
+  line: number;
+  message: string;
+  code: 'MISSING_IMPLEMENTS' | 'MISSING_ACCEPTANCE' | 'MISSING_AUTHOR';
+}
+
+// Spec ID 格式: AR-XXX, WS-XXX, etc.
+const SPEC_ID_REGEX = /^[A-Z]{2,3}-\d{3}$/;
+
+/**
+ * 检查单个文件
+ */
+export function checkFile(filePath: string): AnnotationCheckResult {
+  const content = readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+  
+  const result: AnnotationCheckResult = {
+    valid: true,
+    file: filePath,
+    annotations: [],
+    errors: [],
+    warnings: [],
+  };
+
+  let inJSDoc = false;
+  let currentJSDoc: string[] = [];
+  let currentJSDocStartLine = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    // JSDoc 开始
+    if (line.startsWith('/**')) {
+      inJSDoc = true;
+      currentJSDoc = [line];
+      currentJSDocStartLine = i + 1;
+      continue;
+    }
+
+    // JSDoc 结束
+    if (inJSDoc && line.endsWith('*/')) {
+      inJSDoc = false;
+      currentJSDoc.push(line);
+      
+      const annotation = parseJSDoc(currentJSDoc, currentJSDocStartLine);
+      if (annotation) {
+        result.annotations.push(annotation);
+        validateAnnotation(annotation, result);
+      }
+      
+      currentJSDoc = [];
+      continue;
+    }
+
+    // JSDoc 中间
+    if (inJSDoc) {
+      currentJSDoc.push(line);
+    }
+
+    // 行内注释 // @spec AR-001
+    const inlineMatch = line.match(/\/\/\s*@spec\s+(\S+)/);
+    if (inlineMatch) {
+      const specId = inlineMatch[1];
+      const annotation: SpecAnnotation = {
+        specId,
+        line: i + 1,
+        type: 'inline',
+      };
+      result.annotations.push(annotation);
+      validateAnnotation(annotation, result);
+    }
+  }
+
+  // 检查公共导出是否有注释
+  checkPublicExports(content, result);
+
+  result.valid = result.errors.length === 0;
+  return result;
+}
+
+/**
+ * 解析 JSDoc 注释
+ */
+function parseJSDoc(lines: string[], startLine: number): SpecAnnotation | null {
+  const content = lines.join('\n');
+  
+  // 检查是否有 @spec
+  const specMatch = content.match(/@spec\s+(\S+)/);
+  if (!specMatch) {
+    return null;
+  }
+
+  const specId = specMatch[1];
+  
+  // 解析其他标签
+  const annotation: SpecAnnotation = {
+    specId,
+    line: startLine,
+    type: inferType(content),
+  };
+
+  // @implements
+  const implementsMatch = content.match(/@implements\s+([\w\-_,\s]+)/);
+  if (implementsMatch) {
+    annotation.implements = implementsMatch[1]
+      .split(/[,\s]+/)
+      .map(s => s.trim())
+      .filter(Boolean);
+  }
+
+  // @acceptance
+  const acceptanceMatch = content.match(/@acceptance\s+([\w\-_,\s]+)/);
+  if (acceptanceMatch) {
+    annotation.acceptance = acceptanceMatch[1]
+      .split(/[,\s]+/)
+      .map(s => s.trim())
+      .filter(Boolean);
+  }
+
+  // @dependencies
+  const depsMatch = content.match(/@dependencies\s+([\w\-_,\s\/]+)/);
+  if (depsMatch) {
+    annotation.dependencies = depsMatch[1]
+      .split(/[,\s]+/)
+      .map(s => s.trim())
+      .filter(Boolean);
+  }
+
+  // @author
+  const authorMatch = content.match(/@author\s+(\S+)/);
+  if (authorMatch) {
+    annotation.author = authorMatch[1];
+  }
+
+  // @since
+  const sinceMatch = content.match(/@since\s+(\d{4}-\d{2}-\d{2})/);
+  if (sinceMatch) {
+    annotation.since = sinceMatch[1];
+  }
+
+  return annotation;
+}
+
+/**
+ * 推断注释类型
+ */
+function inferType(content: string): SpecAnnotation['type'] {
+  if (content.includes('class ')) return 'class';
+  if (content.includes('async ') || content.includes('function ')) return 'function';
+  return 'method';
+}
+
+/**
+ * 验证注释
+ */
+function validateAnnotation(
+  annotation: SpecAnnotation,
+  result: AnnotationCheckResult
+): void {
+  // 检查 Spec ID 格式
+  if (!SPEC_ID_REGEX.test(annotation.specId)) {
+    result.errors.push({
+      line: annotation.line,
+      message: `Invalid spec ID format: ${annotation.specId}`,
+      code: 'INVALID_SPEC_FORMAT',
+    });
+  }
+
+  // 警告：建议标记 @implements
+  if (!annotation.implements && annotation.type !== 'inline') {
+    result.warnings.push({
+      line: annotation.line,
+      message: 'Missing @implements tag',
+      code: 'MISSING_IMPLEMENTS',
+    });
+  }
+
+  // 警告：建议标记 @acceptance
+  if (!annotation.acceptance) {
+    result.warnings.push({
+      line: annotation.line,
+      message: 'Missing @acceptance tag',
+      code: 'MISSING_ACCEPTANCE',
+    });
+  }
+}
+
+/**
+ * 检查公共导出是否有注释
+ */
+function checkPublicExports(content: string, result: AnnotationCheckResult): void {
+  // 查找 export class/function 但没有 @spec 的
+  const exportRegex = /^(export\s+(?:abstract\s+)?(?:class|interface|function|const|let|var))\s+(\w+)/gm;
+  let match;
+  
+  while ((match = exportRegex.exec(content)) !== null) {
+    const line = content.substring(0, match.index).split('\n').length;
+    const name = match[2];
+    
+    // 检查前10行是否有 @spec
+    const beforeContent = content.substring(
+      Math.max(0, match.index - 500),
+      match.index
+    );
+    
+    if (!beforeContent.includes('@spec')) {
+      result.warnings.push({
+        line,
+        message: `Public export "${name}" missing @spec annotation`,
+        code: 'MISSING_SPEC' as any,
+      });
+    }
+  }
+}
+
+/**
+ * 递归获取目录下所有文件
+ */
+function getFilesRecursively(dir: string, extensions: string[]): string[] {
+  const files: string[] = [];
+  
+  try {
+    const items = readdirSync(dir);
+    
+    for (const item of items) {
+      const fullPath = path.join(dir, item);
+      const stat = statSync(fullPath);
+      
+      if (stat.isDirectory()) {
+        // 跳过 node_modules 和 dist
+        if (item === 'node_modules' || item === 'dist') {
+          continue;
+        }
+        files.push(...getFilesRecursively(fullPath, extensions));
+      } else if (stat.isFile()) {
+        const ext = path.extname(item);
+        if (extensions.includes(ext) && !item.endsWith('.d.ts')) {
+          files.push(fullPath);
+        }
+      }
+    }
+  } catch {
+    // 目录不存在或无法访问
+  }
+  
+  return files;
+}
+
+/**
+ * 批量检查目录
+ */
+export function checkDirectory(
+  dir: string,
+  options: { extensions?: string[] } = {}
+): AnnotationCheckResult[] {
+  const extensions = options.extensions || ['.ts', '.tsx', '.js', '.jsx'];
+  const files = getFilesRecursively(dir, extensions);
+
+  return files.map(file => checkFile(file));
+}
+
+/**
+ * 生成报告
+ */
+export function generateReport(results: AnnotationCheckResult[]): string {
+  const totalFiles = results.length;
+  const validFiles = results.filter(r => r.valid).length;
+  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+  const totalWarnings = results.reduce((sum, r) => sum + r.warnings.length, 0);
+
+  let report = `## 注释规范检查报告\n\n`;
+  report += `- 检查文件: ${totalFiles}\n`;
+  report += `- 通过: ${validFiles}/${totalFiles}\n`;
+  report += `- 错误: ${totalErrors}\n`;
+  report += `- 警告: ${totalWarnings}\n\n`;
+
+  if (totalErrors > 0) {
+    report += `### ❌ 错误\n\n`;
+    for (const result of results) {
+      for (const error of result.errors) {
+        report += `- ${result.file}:${error.line} - ${error.message}\n`;
+      }
+    }
+    report += '\n';
+  }
+
+  if (totalWarnings > 0) {
+    report += `### ⚠️ 警告\n\n`;
+    for (const result of results) {
+      for (const warning of result.warnings.slice(0, 5)) {
+        report += `- ${result.file}:${warning.line} - ${warning.message}\n`;
+      }
+    }
+  }
+
+  return report;
+}
+
+// CLI 入口
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const dir = args[0] || process.cwd();
+  
+  const results = checkDirectory(dir);
+  console.log(generateReport(results));
+  const hasErrors = results.some(r => r.errors.length > 0);
+  process.exit(hasErrors ? 1 : 0);
+}

package/src/tools/CONTEXT.md

@@ -0,0 +1,25 @@
+# tools/
+
+## 职责
+工具管理：工具类型定义、注册表、核心工具实现、加载器、路径管理。
+
+## 核心导出
+- `types.ts` — 工具类型定义
+- `registry.ts` — 工具注册表
+- `core.ts` — 核心工具实现
+- `loader.ts` — 工具加载器
+- `paths.ts` — 工具路径管理
+
+## 依赖关系
+- 依赖 `src/types/` 公共类型
+- 被 `src/safety/tool-guardrail.ts` 消费
+- 被 Agent 工具调用管线消费
+
+## 约定
+- 工具通过注册表统一管理
+- 工具路径由 paths 模块解析
+- loader 支持动态加载外部工具
+
+## 注意事项
+- 工具注册表与 ToolGuardrail 配合使用
+- 路径管理支持多项目工具目录