@dommaker/harness 0.16.0 → 0.16.1

package/src/cli/commands/doc-freshness-check.ts

@@ -0,0 +1,397 @@
+/**
+ * harness doc-freshness-check 命令
+ *
+ * 从文档中提取可验证的声明(claims)，与代码/文件系统对照，输出差异。
+ * 纯代码操作，零 LLM 调用。
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface DocFreshnessCheckOptions {
+  /** 输出 JSON 格式 */
+  format?: 'json' | 'table';
+  /** 变更文件列表（逗号分隔），用于聚焦检查 */
+  changedFiles?: string;
+  /** 项目路径 */
+  projectPath?: string;
+}
+
+/** 声明类型 */
+export type ClaimType = 'numeric' | 'list' | 'status' | 'narrative';
+
+/** 单条声明 */
+export interface Claim {
+  /** 原始文本片段 */
+  text: string;
+  /** 声明类型 */
+  type: ClaimType;
+  /** 行号 */
+  line: number;
+}
+
+/** 验证结果 */
+export interface ClaimResult {
+  /** 原始声明 */
+  claim: string;
+  /** 声明类型 */
+  type: ClaimType;
+  /** 文档中的期望值 */
+  expected: string;
+  /** 实际值 */
+  actual: string;
+  /** 来源文件 */
+  file: string;
+  /** 是否匹配 */
+  match: boolean;
+}
+
+// ============================================
+// Claim 提取器
+// ============================================
+
+/** 数字声明：N 个/条/项 + 名词 */
+const NUMERIC_PATTERNS = [
+  /(\d+)\s*个\s*(Agent|角色|能力|子系统|模块|端点|命令|组件|层级|阶段|步骤|断点|问题|维度|门|规则|约束)/g,
+  /(\d+)\s*条\s*(知识|规则|约束|命令|铁律|指南|提示|断点|问题|结果|记录)/g,
+  /(\d+)\s*项\s*(检查|任务|功能|变更|修复|优化|指标|配置)/g,
+  /(\d+)\s*(?:大|层)\s*(能力|约束|架构|层级)/g,
+  /(\d+)\s*个\s*(?:CLI\s*)?subcommand/gi,
+];
+
+/** 列表声明：A, B, C, ... (至少 3 项) */
+const LIST_PATTERN = /[A-Z][a-zA-Z]+(?:[,，、]\s*[A-Z][a-zA-Z]+){2,}/g;
+
+/** 状态标记 */
+const STATUS_PATTERNS = [
+  /✅\s*(已完成|已实现|已修复|已部署|已连通|已验证)/g,
+  /❌\s*(缺失|未实现|未完成|失败)/g,
+  /\bDEPRECATED\b/g,
+  /\bTODO\b/g,
+  /待(开发|实现|修复|完善|验证)/g,
+  /已(废弃|弃用|移除|删除)/g,
+];
+
+/**
+ * 从 markdown 内容提取 claims
+ */
+export function extractClaims(content: string, filePath: string): ClaimResult[] {
+  const lines = content.split('\n');
+  const results: ClaimResult[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // 数字声明
+    for (const pattern of NUMERIC_PATTERNS) {
+      pattern.lastIndex = 0;
+      let match;
+      while ((match = pattern.exec(line)) !== null) {
+        const fullMatch = match[0];
+        const number = match[1];
+        results.push({
+          claim: fullMatch,
+          type: 'numeric',
+          expected: number,
+          actual: '', // 待验证
+          file: filePath,
+          match: false,
+        });
+      }
+    }
+
+    // 列表声明
+    const listMatches = line.match(LIST_PATTERN);
+    if (listMatches) {
+      for (const m of listMatches) {
+        const items = m.split(/[,，、]/).map(s => s.trim()).filter(Boolean);
+        if (items.length >= 3) {
+          results.push({
+            claim: m,
+            type: 'list',
+            expected: items.join(', '),
+            actual: '', // 待验证
+            file: filePath,
+            match: false,
+          });
+        }
+      }
+    }
+
+    // 状态标记
+    for (const pattern of STATUS_PATTERNS) {
+      pattern.lastIndex = 0;
+      let match;
+      while ((match = pattern.exec(line)) !== null) {
+        results.push({
+          claim: match[0],
+          type: 'status',
+          expected: match[0],
+          actual: '', // 待验证
+          file: filePath,
+          match: false,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+// ============================================
+// 验证器
+// ============================================
+
+/**
+ * 在项目目录中 grep 搜索匹配内容，返回匹配行数
+ */
+function countGrepMatches(pattern: string, projectPath: string, fileGlob?: string): number {
+  const searchDir = projectPath || process.cwd();
+  let count = 0;
+
+  function walkDir(dir: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist') continue;
+
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walkDir(fullPath);
+      } else if (entry.isFile()) {
+        if (fileGlob && !matchGlob(entry.name, fileGlob)) continue;
+        try {
+          const content = fs.readFileSync(fullPath, 'utf-8');
+          const regex = new RegExp(pattern, 'gi');
+          const matches = content.match(regex);
+          if (matches) count += matches.length;
+        } catch {
+          // skip unreadable files
+        }
+      }
+    }
+  }
+
+  walkDir(searchDir);
+  return count;
+}
+
+/**
+ * 简单 glob 匹配（支持 *.ext 和 *）
+ */
+function matchGlob(filename: string, glob: string): boolean {
+  if (glob === '*') return true;
+  if (glob.startsWith('*.')) {
+    const ext = glob.slice(1);
+    return filename.endsWith(ext);
+  }
+  return filename === glob;
+}
+
+/**
+ * 验证数字声明：计数相关文件/代码模式
+ */
+function verifyNumericClaim(claim: ClaimResult, projectPath: string): ClaimResult {
+  const expected = parseInt(claim.expected, 10);
+
+  // 从声明文本推断搜索模式
+  let searchPattern = '';
+  let fileGlob = '*.ts';
+
+  if (claim.claim.includes('Agent')) {
+    searchPattern = 'export (class|interface|function) \\w*Agent';
+  } else if (claim.claim.includes('命令') || claim.claim.includes('subcommand')) {
+    fileGlob = '*.ts';
+    searchPattern = "program\\.command\\(";
+  } else if (claim.claim.includes('铁律') || claim.claim.includes('约束') || claim.claim.includes('规则')) {
+    searchPattern = "severity:\\s*['\"]?error";
+    fileGlob = '*.ts';
+  } else if (claim.claim.includes('指南')) {
+    searchPattern = "severity:\\s*['\"]?warning";
+    fileGlob = '*.ts';
+  } else if (claim.claim.includes('端点')) {
+    searchPattern = '(router|app)\\.(get|post|put|delete|patch)\\(';
+    fileGlob = '*.ts';
+  } else {
+    // 无法自动验证的数字声明
+    return { ...claim, actual: 'N/A (cannot auto-verify)', match: true };
+  }
+
+  const actual = countGrepMatches(searchPattern, projectPath, fileGlob);
+
+  return {
+    ...claim,
+    actual: String(actual),
+    match: Math.abs(actual - expected) <= Math.max(1, Math.floor(expected * 0.1)), // 10% tolerance
+  };
+}
+
+/**
+ * 验证列表声明：检查列表中的每一项是否存在于代码中
+ */
+function verifyListClaim(claim: ClaimResult, projectPath: string): ClaimResult {
+  const items = claim.expected.split(',').map(s => s.trim());
+  const found: string[] = [];
+  const missing: string[] = [];
+
+  for (const item of items) {
+    const count = countGrepMatches(item, projectPath);
+    if (count > 0) {
+      found.push(item);
+    } else {
+      missing.push(item);
+    }
+  }
+
+  return {
+    ...claim,
+    actual: missing.length === 0
+      ? `all ${items.length} found`
+      : `missing: ${missing.join(', ')}`,
+    match: missing.length === 0,
+  };
+}
+
+/**
+ * 验证状态声明：检查标记是否与代码/文件一致
+ */
+function verifyStatusClaim(claim: ClaimResult, projectPath: string): ClaimResult {
+  // 状态声明的验证较复杂，标记为需要人工确认
+  return {
+    ...claim,
+    actual: 'needs manual verification',
+    match: true, // 不阻断
+  };
+}
+
+/**
+ * 验证所有 claims
+ */
+export function verifyClaims(
+  claims: ClaimResult[],
+  projectPath: string,
+): ClaimResult[] {
+  return claims.map(claim => {
+    switch (claim.type) {
+      case 'numeric':
+        return verifyNumericClaim(claim, projectPath);
+      case 'list':
+        return verifyListClaim(claim, projectPath);
+      case 'status':
+        return verifyStatusClaim(claim, projectPath);
+      default:
+        return { ...claim, actual: 'N/A', match: true };
+    }
+  });
+}
+
+// ============================================
+// 输出格式化
+// ============================================
+
+function formatTable(results: ClaimResult[]): string {
+  if (results.length === 0) return chalk.yellow('未发现可验证的声明');
+
+  const lines: string[] = [];
+  lines.push(chalk.blue(`文档新鲜度检查 (${results.length} 条声明)\n`));
+
+  // 统计
+  const mismatches = results.filter(r => !r.match);
+  lines.push(chalk.bold(`  匹配: ${results.length - mismatches.length}/${results.length}`));
+  if (mismatches.length > 0) {
+    lines.push(chalk.red(`  不匹配: ${mismatches.length}\n`));
+  } else {
+    lines.push(chalk.green('  全部匹配\n'));
+  }
+
+  // 按类型分组
+  const byType: Record<string, ClaimResult[]> = {};
+  for (const r of results) {
+    if (!byType[r.type]) byType[r.type] = [];
+    byType[r.type].push(r);
+  }
+
+  const typeLabels: Record<string, string> = {
+    numeric: '数字声明',
+    list: '列表声明',
+    status: '状态标记',
+    narrative: '叙述声明',
+  };
+
+  for (const [type, items] of Object.entries(byType)) {
+    lines.push(chalk.bold(`  ${typeLabels[type] || type} (${items.length}):`));
+    for (const item of items) {
+      const icon = item.match ? chalk.green('✓') : chalk.red('✗');
+      lines.push(`    ${icon} ${item.claim}`);
+      if (!item.match) {
+        lines.push(`      期望: ${item.expected}`);
+        lines.push(`      实际: ${chalk.yellow(item.actual)}`);
+      }
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ============================================
+// 主入口
+// ============================================
+
+/**
+ * doc-freshness-check CLI 命令
+ */
+export async function docFreshnessCheck(
+  docPath: string,
+  options: DocFreshnessCheckOptions = {},
+): Promise<void> {
+  // 验证文件存在
+  const resolvedPath = path.resolve(docPath);
+  if (!fs.existsSync(resolvedPath)) {
+    console.error(chalk.red(`文件不存在: ${resolvedPath}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!resolvedPath.endsWith('.md')) {
+    console.error(chalk.yellow(`警告: 文件不是 .md 格式，可能无法正确解析`));
+  }
+
+  const projectPath = options.projectPath || path.dirname(resolvedPath);
+
+  // 读取文档
+  const content = fs.readFileSync(resolvedPath, 'utf-8');
+
+  // 提取声明
+  let claims = extractClaims(content, resolvedPath);
+
+  // 如果指定了变更文件，只验证与变更文件相关的声明
+  if (options.changedFiles) {
+    const changed = options.changedFiles.split(',').map(s => s.trim());
+    // 过滤：保留所有 claims，但只验证与变更文件相关的
+    // 实际实现中可以根据声明内容推断相关文件
+    void changed; // 预留
+  }
+
+  // 验证
+  const results = verifyClaims(claims, projectPath);
+
+  // 输出
+  if (options.format === 'json') {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    console.log(formatTable(results));
+  }
+
+  // 有不匹配时 exit 1
+  const mismatches = results.filter(r => !r.match);
+  if (mismatches.length > 0) {
+    process.exitCode = 1;
+  }
+}

package/src/cli/commands/index.ts

@@ -17,10 +17,13 @@ export { contract, validateSchema, type ContractOptions } from './contract';
 export { review, reviewStatus, type ReviewOptions } from './review';
 export { executeCommand, type CommandCheckOptions } from './command';
 export { syncDocs, type SyncDocsOptions } from './sync-docs';
-export { knowledgeList, knowledgeSearch, knowledgeImport, knowledgeDecay, knowledgeStats, knowledgeUpsert, knowledgeSyncStatus, knowledgeSyncRag, knowledgeAudit, knowledgeSnapshot, knowledgeMigrate, type KnowledgeOptions, type KnowledgeUpsertOptions } from './knowledge';
+export { knowledgeList, knowledgeSearch, knowledgeImport, knowledgeDecay, knowledgeStats, knowledgeUpsert, knowledgeSyncStatus, knowledgeSyncRag, knowledgeAudit, knowledgeSnapshot, knowledgeMigrate, knowledgeHealth, knowledgeIndex, type KnowledgeOptions, type KnowledgeUpsertOptions } from './knowledge';
 export { failureList, failureStats, failureClear, type FailureOptions } from './failure';
 export { postevalPlan, type PostEvalPlanOptions } from './posteval-plan';
 export { release, type ReleaseOptions } from './release';
 export { analyzeSessions, type AnalyzeSessionsOptions } from './analyze-sessions';
 export { updateUserModel, type UpdateUserModelOptions } from './update-user-model';
 export { constraints, getConstraintsMeta, type ConstraintsMeta } from './constraints';
+export { docFreshnessCheck, extractClaims, verifyClaims, type DocFreshnessCheckOptions, type ClaimResult, type ClaimType } from './doc-freshness-check';
+export { specBaselineCheck, extractBaselineSection, type SpecBaselineCheckOptions, type PrerequisiteResult } from './spec-baseline-check';
+export { sddIndex, type SDDOptions } from './sdd';

package/src/cli/commands/knowledge.ts

@@ -14,6 +14,7 @@ import { KnowledgeLifecycle } from '../../knowledge/lifecycle';
 import { ColdStartImporter } from '../../knowledge/import';
 import { KnowledgeAudit } from '../../knowledge/audit';
 import { migrateKnowledgeEntries } from '../../knowledge/migration';
+import { KnowledgeIndexGenerator } from '../../knowledge/index-generator';
 import type { KnowledgeType, MaturityLevel, QueryFilter } from '../../knowledge/types';
 
 export interface KnowledgeOptions {
@@ -413,6 +414,106 @@ export async function knowledgeSyncStatus(options: KnowledgeOptions): Promise<vo
   }
 }
 
+/**
+ * 飞轮健康检查 — 零 token 检测知识飞轮数据流状态
+ */
+export async function knowledgeHealth(options: KnowledgeOptions & { dir?: string }): Promise<void> {
+  const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+  const store = new KnowledgeStore({ baseDir });
+  const entries = store.list({ excludeArchived: true });
+
+  const issues: Array<{ severity: 'error' | 'warn' | 'info'; entry: string; detail: string }> = [];
+
+  // D1: 引用密度检查（低引用 = 可能孤立）
+  let lowRefEntries = 0;
+  for (const entry of entries) {
+    if (entry.referencedBy.length === 0 && entry.maturity === 'verified') {
+      lowRefEntries++;
+      issues.push({ severity: 'info', entry: entry.id, detail: `verified 条目零引用（可能孤立）` });
+    }
+  }
+
+  // D2: 新鲜度检查
+  const now = Date.now();
+  const staleThreshold = 90 * 24 * 60 * 60 * 1000; // 90 days
+  let staleEntries = 0;
+  for (const entry of entries) {
+    const created = new Date(entry.created).getTime();
+    if (now - created > staleThreshold && entry.maturity === 'draft') {
+      staleEntries++;
+      issues.push({ severity: 'warn', entry: entry.id, detail: `draft 超过 90 天未推进` });
+    }
+  }
+
+  // D3: 消费数据检查
+  let consumptionData = false;
+  const statsPath = path.join(baseDir, '.consumption-stats.json');
+  if (fs.existsSync(statsPath)) {
+    consumptionData = true;
+  } else {
+    issues.push({ severity: 'info', entry: '-', detail: `消费追踪数据不存在（${statsPath}）` });
+  }
+
+  // D4: 飞轮指标
+  const withRefs = entries.filter(e => e.referencedBy.length > 0).length;
+  const refCoverage = entries.length > 0 ? Math.round(withRefs / entries.length * 100) : 0;
+  const avgRefs = entries.length > 0
+    ? Math.round(entries.reduce((sum, e) => sum + e.referencedBy.length, 0) / entries.length * 10) / 10
+    : 0;
+
+  // 健康分计算
+  const totalIssues = issues.filter(i => i.severity === 'error').length * 3
+    + issues.filter(i => i.severity === 'warn').length * 1;
+  const healthScore = Math.max(0, 100 - totalIssues);
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      healthScore,
+      summary: {
+        total: entries.length,
+        lowRefEntries,
+        staleEntries,
+        consumptionData,
+        refCoverage,
+        avgRefs,
+      },
+      issues: issues.slice(0, 50),
+    }, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue('🏥 飞轮健康检查\n'));
+  console.log(chalk.bold(`  健康分: ${healthScore >= 80 ? chalk.green(healthScore) : healthScore >= 60 ? chalk.yellow(healthScore) : chalk.red(healthScore)}/100`));
+  console.log(chalk.bold(`  活跃条目: ${entries.length}`));
+  console.log();
+
+  console.log(chalk.bold('  数据流状态:'));
+  console.log(`    引用密度: ${lowRefEntries === 0 ? chalk.green('✓') : chalk.yellow(`⚠ ${lowRefEntries} 个零引用 verified`)}`);
+  console.log(`    新鲜度: ${staleEntries === 0 ? chalk.green('✓') : chalk.yellow(`⚠ ${staleEntries} 个过期 draft`)}`);
+  console.log(`    消费追踪: ${consumptionData ? chalk.green('✓') : chalk.gray('○ 未启用')}`);
+  console.log();
+
+  console.log(chalk.bold('  飞轮指标:'));
+  console.log(`    引用覆盖: ${refCoverage}%`);
+  console.log(`    平均引用: ${avgRefs}`);
+  console.log();
+
+  if (issues.length > 0) {
+    console.log(chalk.bold(`  问题 (前 20):`));
+    for (const issue of issues.slice(0, 20)) {
+      const sevColor = issue.severity === 'error' ? chalk.red
+        : issue.severity === 'warn' ? chalk.yellow
+        : chalk.gray;
+      console.log(`    ${sevColor(`[${issue.severity}]`)} ${issue.entry}: ${issue.detail}`);
+    }
+    if (issues.length > 20) {
+      console.log(chalk.gray(`    ... 还有 ${issues.length - 20} 条`));
+    }
+  } else {
+    console.log(chalk.green('  ✓ 无问题'));
+  }
+}
+
 function getKnowledgeDir(projectPath?: string): string {
   if (projectPath) return `${projectPath}/.harness/knowledge`;
   if (process.env.KNOWLEDGE_BASE_DIR) return process.env.KNOWLEDGE_BASE_DIR;
@@ -482,6 +583,7 @@ export async function knowledgeAudit(options: KnowledgeOptions & {
     'maturity-inflation': '成熟度虚高',
     'title-duplicate': '标题重复',
     'source-refs-bloat': 'sourceReferences 膨胀',
+    'fragment-cluster': '碎片集群',
     'promotion-blocked': 'promotion 受阻',
     'orphan-draft': '孤儿 draft',
     'stale-entry': '过期条目',
@@ -511,6 +613,14 @@ export async function knowledgeAudit(options: KnowledgeOptions & {
   if (!options.fix && report.issues.length > 0) {
     console.log(chalk.yellow(`\n  使用 --fix 自动修复`));
   }
+
+  // Auto-rebuild index after audit (files may have changed)
+  const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+  const idxGen = new KnowledgeIndexGenerator(baseDir);
+  idxGen.regenerate();
+  if (!options.json) {
+    console.log(chalk.gray(`  📇 索引已重建`));
+  }
 }
 
 /**
@@ -560,3 +670,43 @@ export function knowledgeMigrate(options: KnowledgeOptions & { dir?: string }):
     console.log(chalk.green(`\n✅ 迁移完成`));
   }
 }
+
+/**
+ * 知识库索引重建 — 生成 _index.md 供 Agent grep 使用，同时同步 index.json
+ */
+export function knowledgeIndex(options: KnowledgeOptions & { dir?: string }): void {
+  const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+  const gen = new KnowledgeIndexGenerator(baseDir);
+
+  const beforeSize = (() => {
+    const indexPath = path.join(baseDir, '_index.md');
+    return fs.existsSync(indexPath) ? fs.statSync(indexPath).size : 0;
+  })();
+
+  const output = gen.regenerate();
+
+  // Sync index.json from disk files (removes ghost entries from manual mv/rm)
+  const store = new KnowledgeStore({ baseDir });
+  store.rebuildIndex();
+
+  const afterSize = Buffer.byteLength(output, 'utf-8');
+  const lineCount = output.split('\n').filter(l => !l.startsWith('#')).length;
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      path: path.join(baseDir, '_index.md'),
+      entries: lineCount,
+      size: afterSize,
+      previousSize: beforeSize,
+    }));
+    return;
+  }
+
+  console.log(chalk.blue(`📇 索引已重建`));
+  console.log(chalk.gray(`  路径: ${path.join(baseDir, '_index.md')}`));
+  console.log(chalk.green(`  条目: ${lineCount}`));
+  console.log(chalk.green(`  大小: ${(afterSize / 1024).toFixed(1)} KB`));
+  if (beforeSize > 0) {
+    console.log(chalk.gray(`  旧大小: ${(beforeSize / 1024).toFixed(1)} KB`));
+  }
+}