@dommaker/harness 0.16.0 → 0.16.2

package/src/knowledge/index-generator.ts

@@ -0,0 +1,233 @@
+/**
+ * Knowledge Index Generator
+ *
+ * 扫描知识库目录，生成 grep 友好的单文件索引。
+ * 每行一条，包含 filename/id/type/title/maturity/tags/headings。
+ *
+ * 目标：Agent grep 索引替代 grep 全库，减少 ~96% 输出量。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+
+const EXCLUDED_DIRS = ['.archive', 'archived', '.snapshots', 'resolutions'];
+const INDEX_FILENAME = '_index.md';
+
+interface IndexEntry {
+  filename: string;
+  id: string;
+  type: string;
+  title: string;
+  maturity: string;
+  tags: string[];
+  headings: string[];
+}
+
+export class KnowledgeIndexGenerator {
+  private baseDir: string;
+
+  constructor(baseDir: string) {
+    this.baseDir = baseDir;
+  }
+
+  /**
+   * 生成索引并写入 _index.md
+   */
+  regenerate(): string {
+    const lines = this.generateIndexLines();
+    const output = this.generate();
+    fs.mkdirSync(this.baseDir, { recursive: true });
+    fs.writeFileSync(path.join(this.baseDir, INDEX_FILENAME), output, 'utf-8');
+    return output;
+  }
+
+  /**
+   * 生成完整索引内容（含 header）
+   */
+  generate(): string {
+    const lines = this.generateIndexLines();
+    const byType: Record<string, number> = {};
+    for (const line of lines) {
+      const type = line.split('|')[2];
+      byType[type] = (byType[type] || 0) + 1;
+    }
+
+    const header = [
+      '# Knowledge Base Index',
+      `# Auto-generated — run \`harness knowledge index\` to rebuild`,
+      `# Total: ${lines.length} entries`,
+      `# Types: ${Object.entries(byType).map(([t, n]) => `${t}:${n}`).join(' ')}`,
+      `#`,
+      `# Usage:`,
+      `#   grep "<keyword>" ~/.studio/knowledge/_index.md`,
+      `#   Then Read the matching file for full content.`,
+      `#`,
+      `# filename|id|type|title|maturity|tags|terms`,
+    ].join('\n');
+
+    return header + '\n' + lines.join('\n') + '\n';
+  }
+
+  /**
+   * 扫描目录，返回索引数据行（无 header）
+   */
+  generateIndexLines(): string[] {
+    const files = this.scanFiles(this.baseDir);
+    const entries: IndexEntry[] = [];
+
+    for (const filePath of files) {
+      const entry = this.parseFile(filePath);
+      if (entry) entries.push(entry);
+    }
+
+    // 按 type 分组排序：architecture > decision > guideline > pitfall > process > other
+    const typeOrder: Record<string, number> = {
+      architecture: 0, decision: 1, guideline: 2, pitfall: 3, process: 4, model: 5, pattern: 6, skill: 7,
+    };
+    entries.sort((a, b) => {
+      const oa = typeOrder[a.type] ?? 9;
+      const ob = typeOrder[b.type] ?? 9;
+      if (oa !== ob) return oa - ob;
+      return a.filename.localeCompare(b.filename);
+    });
+
+    return entries.map(e => this.formatLine(e));
+  }
+
+  // ── Internal ───────────────────────────────────────────────────────────────
+
+  private scanFiles(dir: string, relative: string = ''): string[] {
+    const results: string[] = [];
+
+    let items: fs.Dirent[];
+    try {
+      items = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return results;
+    }
+
+    for (const item of items) {
+      const name = item.name;
+      const fullPath = path.join(dir, name);
+      const relPath = relative ? path.join(relative, name) : name;
+
+      if (item.isDirectory()) {
+        if (EXCLUDED_DIRS.includes(name)) continue;
+        if (name.startsWith('.')) continue;
+        results.push(...this.scanFiles(fullPath, relPath));
+      } else if (name.endsWith('.md') && name !== INDEX_FILENAME) {
+        results.push(fullPath);
+      }
+    }
+
+    return results;
+  }
+
+  private parseFile(filePath: string): IndexEntry | null {
+    try {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      const filename = path.relative(this.baseDir, filePath);
+
+      // 跳过 ghost 文件（文件名为 .md）
+      if (path.basename(filename) === '.md') return null;
+
+      // 尝试解析 YAML frontmatter
+      const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+      if (fmMatch) {
+        const meta = yaml.load(fmMatch[1]) as Record<string, unknown>;
+        const body = fmMatch[2];
+        const headings = this.extractHeadings(body);
+
+        // 检测 skill schema（name/description 而非 id/type）
+        const type = meta?.type
+          ? String(meta.type)
+          : meta?.name
+            ? 'skill'
+            : this.inferType(filename);
+
+        return {
+          filename,
+          id: String(meta?.id ?? meta?.name ?? path.basename(filePath, '.md')),
+          type,
+          title: String(meta?.title ?? meta?.description ?? ''),
+          maturity: String(meta?.maturity ?? 'unknown'),
+          tags: Array.isArray(meta?.tags) ? (meta.tags as unknown[]).map(String) : [],
+          headings,
+        };
+      }
+
+      // 无 frontmatter — best effort
+      const headings = this.extractHeadings(raw);
+      const h1Match = raw.match(/^#\s+(.+)$/m);
+
+      return {
+        filename,
+        id: path.basename(filePath, '.md'),
+        type: this.inferType(filename),
+        title: h1Match ? h1Match[1].trim() : '',
+        maturity: 'unknown',
+        tags: [],
+        headings,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 从文件路径推断 type。优先级：目录名 > 特殊前缀 > 文件前缀 > 后缀模式
+   */
+  private inferType(filename: string): string {
+    const base = path.basename(filename);
+    const dir = path.dirname(filename);
+
+    // 1. 目录推断
+    if (dir === 'skills') return 'skill';
+    if (dir === 'arch-patterns') return 'architecture';
+
+    // 2. 特殊复合前缀（必须在通用前缀匹配前检查）
+    if (/^(agent-network|superpowers)-/.test(base)) return 'architecture';
+    if (/^AS-\d+/.test(base)) return 'spec';
+
+    // 3. 文件名前缀（architecture-ARC-011.md → architecture）
+    const prefixMatch = base.match(/^([a-z]+)-/);
+    const knownPrefixes = ['architecture', 'decision', 'guideline', 'pitfall', 'process', 'pattern', 'model', 'skill', 'agent'];
+    if (prefixMatch && knownPrefixes.includes(prefixMatch[1])) {
+      return prefixMatch[1];
+    }
+
+    // 4. 后缀模式（*-pattern.md → pattern）
+    if (/-pattern\.md$/.test(base)) return 'pattern';
+
+    return 'unknown';
+  }
+
+  /**
+   * 提取正文 H2 标题作为搜索词（最多 5 个）
+   */
+  private extractHeadings(body: string): string[] {
+    const matches = body.match(/^##\s+(.+)$/gm);
+    if (!matches) return [];
+
+    return matches
+      .slice(0, 5)
+      .map(h => h.replace(/^##\s+/, '').replace(/[*_`#]/g, '').trim())
+      .filter(h => h.length > 0 && h.length < 60);
+  }
+
+  private formatLine(entry: IndexEntry): string {
+    const sanitize = (s: string) => s.replace(/[\n\r]/g, ' ').replace(/\|/g, '/').replace(/\s+/g, ' ').trim();
+    const tags = entry.tags.join(';');
+    const terms = entry.headings.join(';');
+    return [
+      sanitize(entry.filename),
+      sanitize(entry.id),
+      sanitize(entry.type),
+      sanitize(entry.title),
+      sanitize(entry.maturity),
+      sanitize(tags),
+      sanitize(terms),
+    ].join('|');
+  }
+}

package/src/knowledge/index.ts

@@ -19,3 +19,5 @@ export { KnowledgeLifecycleHooks } from './lifecycle-hooks';
 export { KnowledgeAudit } from './audit';
 export type { AuditRuleName, AuditAction, AuditIssue, AuditReport, AuditOptions } from './audit';
 export { migrateKnowledgeEntries } from './migration';
+export { extractCodeStructure } from './primitives/code-structure';
+export type { CodeStructure, DeclarationInfo, ImportInfo } from './primitives/code-structure';

package/src/knowledge/ingest.ts

@@ -194,7 +194,7 @@ export class KnowledgeIngest {
     const all = this.store.readEntriesFromDisk().filter(e => e.type === type);
 
     // Exact match (case-insensitive)
-    const exact = all.find(e => e.title.toLowerCase() === title.toLowerCase());
+    const exact = all.find(e => (e.title || '').toLowerCase() === title.toLowerCase());
     if (exact) return exact;
 
     // Semantic dedup: content prefix + title substring + keyword overlap
@@ -236,7 +236,7 @@ export class KnowledgeIngest {
 
   /** Strip [prefix] tags and normalize for comparison */
   private normalizeForDedup(title: string): string {
-    const t = title.replace(/^\[.*?\]\s*/g, '').trim();
+    const t = (title || '').replace(/^\[.*?\]\s*/g, '').trim();
     // Keep spaces between character types (Latin/Chinese boundary) for tokenization
     return t.replace(/[，。、：；！？]/g, '').toLowerCase();
   }

package/src/knowledge/lifecycle.ts

@@ -194,9 +194,80 @@ export class KnowledgeLifecycle {
       reason: `Promotion: ${entry.maturity} → ${target}`,
     };
     this.store.update(entryId, { maturity: target });
+
+    // AC-8a: After promotion, check skillCandidate eligibility
+    if (target === 'proven') {
+      this.checkSkillCandidate(entryId);
+    }
+
     return change;
   }
 
+  /**
+   * AC-8a: Check if a proven entry qualifies as a skillCandidate.
+   * Marks with 'skillCandidate' tag and emits event if eligible.
+   * Returns true if newly marked.
+   */
+  checkSkillCandidate(entryId: string): boolean {
+    const entry = this.store.get(entryId);
+    if (!entry) return false;
+    if (!this.isSkillCandidate(entry)) return false;
+
+    // Mark as skillCandidate
+    this.store.update(entryId, {
+      tags: [...entry.tags, 'skillCandidate'],
+    });
+
+    // Emit event for downstream consumers
+    const now = new Date().toISOString();
+    for (const cb of this.onReferenceCallbacks) {
+      try {
+        cb({
+          entryId,
+          contributor: 'lifecycle',
+          timestamp: now,
+          context: 'skillCandidate:marked',
+        });
+      } catch { /* non-blocking */ }
+    }
+
+    return true;
+  }
+
+  /**
+   * AC-8a: Check if an entry meets skillCandidate criteria.
+   */
+  private isSkillCandidate(entry: KnowledgeEntry): boolean {
+    if (entry.maturity !== 'proven') return false;
+    if (entry.tags.includes('skillCandidate')) return false;
+    if (entry.contributors.length < 3) return false;
+    if ((entry.executionResults?.length || 0) < 5) return false;
+    if (entry.content.length < 200) return false;
+
+    const execRate = this.getExecutionSuccessRate(entry.id);
+    if (!execRate || execRate.rate < 0.7) return false;
+
+    return true;
+  }
+
+  /**
+   * AC-8c: Remove skillCandidate tag if success rate drops below 50%.
+   * Called after execution writeback.
+   */
+  checkSkillCandidateRevocation(entryId: string): boolean {
+    const entry = this.store.get(entryId);
+    if (!entry || !entry.tags.includes('skillCandidate')) return false;
+
+    const execRate = this.getExecutionSuccessRate(entryId);
+    if (execRate && execRate.total >= 5 && execRate.rate < 0.5) {
+      this.store.update(entryId, {
+        tags: entry.tags.filter(t => t !== 'skillCandidate'),
+      });
+      return true;
+    }
+    return false;
+  }
+
   /**
    * Check if a source should auto-promote to verified on ingest.
    * Used by KnowledgeBus to decide initial maturity level.

package/src/knowledge/lint.ts

@@ -181,7 +181,7 @@ export class KnowledgeLinter {
       if (entry.maturity === 'archived') continue;
 
       // 基于 title + type 去重（大小写不敏感）
-      const key = `${entry.type}:${entry.title.toLowerCase().trim()}`;
+      const key = `${entry.type}:${(entry.title || '').toLowerCase().trim()}`;
       const existing = seen.get(key) || [];
       existing.push(entry);
       seen.set(key, existing);
@@ -309,8 +309,8 @@ export class KnowledgeLinter {
       const allEntries = this.store.list({ excludeArchived: false });
       for (const existing of allEntries) {
         if (existing.id === entry.title) continue; // not same entry (entry doesn't have id yet)
-        const existingTitle = existing.title.toLowerCase();
-        const newTitle = entry.title.toLowerCase();
+        const existingTitle = (existing.title || '').toLowerCase();
+        const newTitle = (entry.title || '').toLowerCase();
         if (existingTitle === newTitle) {
           issues.push({
             type: 'duplicate',

package/src/knowledge/primitives/__tests__/code-structure.test.ts

@@ -0,0 +1,120 @@
+/**
+ * extractCodeStructure — Layer 1 代码结构提取
+ *
+ * AC:
+ * P5a-1: 从 .ts 文件提取函数/类/接口/类型声明
+ * P5a-2: 从多文件目录提取，包含 import 依赖图
+ * P5a-3: 空目录返回空结构
+ * P5a-4: 非 .ts 文件忽略
+ * P5a-5: JSDoc 注释关联到声明
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { extractCodeStructure } from '../code-structure';
+
+// Use real fs for these tests (no mock) — testing actual TS parsing
+
+describe('extractCodeStructure', () => {
+  const tmpDir = path.join(__dirname, '__tmp__');
+
+  beforeEach(() => {
+    fs.mkdirSync(tmpDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('P5a-1: extracts functions, classes, interfaces, types from .ts file', () => {
+    const code = `
+/** Helper function */
+export function add(a: number, b: number): number { return a + b; }
+
+/** A class */
+export class Calculator {
+  compute(x: number): number { return x * 2; }
+}
+
+export interface Config { debug: boolean; timeout: number; }
+
+export type Result = { ok: boolean; data?: string };
+`;
+    fs.writeFileSync(path.join(tmpDir, 'math.ts'), code);
+
+    const result = extractCodeStructure(tmpDir);
+
+    expect(result.files).toContain('math.ts');
+    expect(result.functions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: 'add' }),
+      ]),
+    );
+    expect(result.classes).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: 'Calculator' }),
+      ]),
+    );
+    expect(result.interfaces).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: 'Config' }),
+      ]),
+    );
+    expect(result.types).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: 'Result' }),
+      ]),
+    );
+  });
+
+  it('P5a-2: extracts imports and builds dependency graph', () => {
+    const codeA = `import { add } from './math'; export const sum = add(1, 2);`;
+    const codeB = `export function add(a: number, b: number): number { return a + b; }`;
+    fs.writeFileSync(path.join(tmpDir, 'app.ts'), codeA);
+    fs.writeFileSync(path.join(tmpDir, 'math.ts'), codeB);
+
+    const result = extractCodeStructure(tmpDir);
+
+    expect(result.imports).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ source: './math' }),
+      ]),
+    );
+  });
+
+  it('P5a-3: empty directory returns empty structure', () => {
+    const emptyDir = path.join(tmpDir, 'empty');
+    fs.mkdirSync(emptyDir);
+
+    const result = extractCodeStructure(emptyDir);
+
+    expect(result.files).toEqual([]);
+    expect(result.functions).toEqual([]);
+    expect(result.classes).toEqual([]);
+    expect(result.interfaces).toEqual([]);
+    expect(result.types).toEqual([]);
+  });
+
+  it('P5a-4: non-.ts files are ignored', () => {
+    fs.writeFileSync(path.join(tmpDir, 'readme.md'), '# Hello');
+    fs.writeFileSync(path.join(tmpDir, 'data.json'), '{}');
+    fs.writeFileSync(path.join(tmpDir, 'code.ts'), 'export const x = 1;');
+
+    const result = extractCodeStructure(tmpDir);
+
+    expect(result.files).toEqual(['code.ts']);
+  });
+
+  it('P5a-5: JSDoc comments are associated with declarations', () => {
+    const code = `
+/** Adds two numbers together */
+export function add(a: number, b: number): number { return a + b; }
+`;
+    fs.writeFileSync(path.join(tmpDir, 'math.ts'), code);
+
+    const result = extractCodeStructure(tmpDir);
+
+    const fn = result.functions.find(f => f.name === 'add');
+    expect(fn?.jsdoc).toContain('Adds two numbers');
+  });
+});

package/src/knowledge/primitives/code-structure.ts

@@ -0,0 +1,161 @@
+/**
+ * extractCodeStructure — Layer 1 代码结构提取（纯代码，零 LLM）
+ *
+ * 使用 TypeScript Compiler API 从 .ts 文件提取：
+ * - 函数声明
+ * - 类声明
+ * - 接口声明
+ * - 类型别名
+ * - import 语句
+ *
+ * 每个声明附带 JSDoc 注释（如果有）。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as ts from 'typescript';
+
+export interface DeclarationInfo {
+  name: string;
+  signature: string;
+  jsdoc?: string;
+}
+
+export interface ImportInfo {
+  source: string;
+  names: string[];
+}
+
+export interface CodeStructure {
+  files: string[];
+  functions: DeclarationInfo[];
+  classes: DeclarationInfo[];
+  interfaces: DeclarationInfo[];
+  types: DeclarationInfo[];
+  imports: ImportInfo[];
+}
+
+/**
+ * 从目录中所有 .ts 文件提取代码结构。
+ *
+ * @param dir 目录路径
+ * @returns CodeStructure JSON
+ */
+export function extractCodeStructure(dir: string): CodeStructure {
+  const result: CodeStructure = {
+    files: [],
+    functions: [],
+    classes: [],
+    interfaces: [],
+    types: [],
+    imports: [],
+  };
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return result;
+  }
+
+  const tsFiles = entries
+    .filter(e => e.isFile() && (e.name.endsWith('.ts') || e.name.endsWith('.tsx')) && !e.name.endsWith('.d.ts'))
+    .map(e => e.name)
+    .sort();
+
+  result.files = tsFiles;
+
+  for (const fileName of tsFiles) {
+    const filePath = path.join(dir, fileName);
+    const sourceText = fs.readFileSync(filePath, 'utf-8');
+    const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true);
+
+    extractFromFile(sourceFile, result);
+  }
+
+  return result;
+}
+
+function extractFromFile(sourceFile: ts.SourceFile, result: CodeStructure): void {
+  ts.forEachChild(sourceFile, node => {
+    if (ts.isFunctionDeclaration(node)) {
+      const info = extractDeclaration(node, sourceFile);
+      if (info) result.functions.push(info);
+    } else if (ts.isClassDeclaration(node)) {
+      const info = extractDeclaration(node, sourceFile);
+      if (info) result.classes.push(info);
+    } else if (ts.isInterfaceDeclaration(node)) {
+      const info = extractDeclaration(node, sourceFile);
+      if (info) result.interfaces.push(info);
+    } else if (ts.isTypeAliasDeclaration(node)) {
+      const info = extractDeclaration(node, sourceFile);
+      if (info) result.types.push(info);
+    } else if (ts.isImportDeclaration(node)) {
+      const importInfo = extractImport(node, sourceFile);
+      if (importInfo) result.imports.push(importInfo);
+    }
+  });
+}
+
+function extractDeclaration(
+  node: ts.FunctionDeclaration | ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration,
+  sourceFile: ts.SourceFile,
+): DeclarationInfo | undefined {
+  const name = node.name?.getText(sourceFile);
+  if (!name) return undefined;
+
+  const signature = node.getText(sourceFile).split('\n')[0].trim();
+  const jsdoc = extractJSDoc(node, sourceFile);
+
+  return { name, signature, jsdoc };
+}
+
+function extractImport(node: ts.ImportDeclaration, sourceFile: ts.SourceFile): ImportInfo | undefined {
+  const moduleSpecifier = node.moduleSpecifier;
+  if (!ts.isStringLiteral(moduleSpecifier)) return undefined;
+
+  const source = moduleSpecifier.text;
+  const names: string[] = [];
+
+  if (node.importClause) {
+    if (node.importClause.name) {
+      names.push(node.importClause.name.getText(sourceFile));
+    }
+    if (node.importClause.namedBindings) {
+      if (ts.isNamedImports(node.importClause.namedBindings)) {
+        for (const element of node.importClause.namedBindings.elements) {
+          names.push(element.name.getText(sourceFile));
+        }
+      }
+    }
+  }
+
+  return { source, names };
+}
+
+function extractJSDoc(node: ts.Node, sourceFile: ts.SourceFile): string | undefined {
+  const jsDocTags = ts.getJSDocTags(node);
+  const fullText = sourceFile.getFullText();
+  const nodeStart = node.getFullStart();
+
+  // Look backwards for JSDoc comment
+  const leadingCommentRanges = ts.getLeadingCommentRanges(fullText, nodeStart);
+  if (!leadingCommentRanges) return undefined;
+
+  for (const range of leadingCommentRanges) {
+    const commentText = fullText.substring(range.pos, range.end);
+    if (commentText.startsWith('/**')) {
+      // Strip /** and */ and clean up
+      return commentText
+        .replace(/^\/\*\*\s*/, '')
+        .replace(/\s*\*\/$/, '')
+        .split('\n')
+        .map(line => line.replace(/^\s*\*\s?/, ''))
+        .filter(line => line.trim().length > 0)
+        .join(' ')
+        .trim();
+    }
+  }
+
+  return undefined;
+}

package/src/knowledge/types.ts

@@ -9,7 +9,10 @@
 
 // ── Dimensions ──────────────────────────────────────────────
 
-export type KnowledgeType = 'model' | 'decision' | 'guideline' | 'pitfall' | 'process' | 'architecture';
+export type KnowledgeSubsystem = 'model' | 'decision' | 'guideline' | 'pitfall' | 'process' | 'architecture';
+
+/** @deprecated Use KnowledgeSubsystem */
+export type KnowledgeType = KnowledgeSubsystem;
 
 export type MaturityLevel = 'draft' | 'verified' | 'proven' | 'archived' | 'active' | 'deprecated';