@dommaker/harness 1.1.0 → 1.2.0

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

@@ -1,294 +0,0 @@
-/**
- * AnnotationChecker 测试
- */
-
-import { checkFile, checkDirectory, generateReport } from '../annotation-checker';
-import * as fs from 'fs';
-
-// 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.readFileSync.mockReturnValue('');
-      mockFs.readdirSync.mockReturnValue([
-        { name: 'node_modules', isDirectory: () => true, isFile: () => false },
-        { name: 'dist', isDirectory: () => true, isFile: () => false },
-        { name: 'file.ts', isDirectory: () => false, isFile: () => true },
-      ] as any);
-
-      const results = checkDirectory(tempDir);
-
-      // 只收集 file.ts，跳过 node_modules 与 dist 目录
-      expect(results).toHaveLength(1);
-      expect(results[0].file).toBe('/test/project/file.ts');
-    });
-
-    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

@@ -1,320 +0,0 @@
-/**
- * 代码注释规范检查器
- *
- * 检查代码中的 @spec 注释是否规范
- */
-
-import { readFileSync } from 'fs';
-import * as path from 'path';
-import { walkFiles } from '../utils/file-walk';
-
-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,
-      });
-    }
-  }
-}
-
-/**
- * 递归获取目录下所有文件（收敛到 utils/file-walk 的 walkFiles，工单 O3）
- */
-function getFilesRecursively(dir: string, extensions: string[]): string[] {
-  return walkFiles(dir, {
-    skipDirs: ['node_modules', 'dist'],
-    filter: (name) => extensions.includes(path.extname(name)) && !name.endsWith('.d.ts'),
-  });
-}
-
-/**
- * 批量检查目录
- */
-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/types/enforcement.ts

@@ -1,48 +0,0 @@
-/**
- * Enforcement 执行器类型定义
- */
-
-import type { Constraint, ConstraintContext } from './constraint';
-
-export type EnforcementId = string;
-
-export interface EnforcementContext extends ConstraintContext {
-  enforcementId: EnforcementId;
-  constraint: Constraint;
-  params?: Record<string, any>;
-}
-
-export interface EnforcementResult {
-  passed: boolean;
-  evidence?: string;
-  message?: string;
-  error?: string;
-  duration?: number;
-  validatedAt?: Date;
-}
-
-export interface EnforcementExecutor {
-  execute(context: EnforcementContext): Promise<EnforcementResult>;
-  description?: string;
-  supportedParams?: string[];
-}
-
-export interface EnforcementRegistration {
-  id: EnforcementId;
-  executor: EnforcementExecutor;
-  registeredAt: Date;
-  source?: string;
-}
-
-export interface InterceptionResult {
-  passed: boolean;
-  constraints: {
-    constraint: Constraint;
-    enforcementResult?: EnforcementResult;
-    skipped?: boolean;
-    skipReason?: string;
-  }[];
-  violations: Constraint[];
-  message?: string;
-  interceptedAt: Date;
-}