@mseep/core 3.0.0

package/lib/engine/scanner.js

@@ -0,0 +1,151 @@
+import fs from 'fs';
+import path from 'path';
+import { resolveBookLibPaths } from '../paths.js';
+
+/**
+ * Handles project-wide compliance scanning against the entire BookLib library.
+ * Uses audit.json rule sets for fast, accurate static analysis.
+ * Falls back to skipping files whose skill has no audit.json.
+ */
+export class BookLibScanner {
+  constructor() {}
+
+  /**
+   * Scans a directory and generates a 'Wisdom Compliance' heatmap.
+   *
+   * @param {string} dirPath - The project directory to scan.
+   * @param {object} opts
+   * @param {string} opts.mode - 'code' (default) or 'docs' (scans .md/.txt files)
+   * @returns {string} - A comprehensive project health report.
+   */
+  scan(dirPath, { mode = 'code' } = {}) {
+    const files = this.getFiles(dirPath);
+    const reports = [];
+    const stats = {
+      filesScanned: files.length,
+      filesMatched: 0,
+      filesAudited: 0,
+      violations: 0,
+      healthyFiles: 0,
+      debtBySkill: {},
+      noRulesSkills: new Set(),
+    };
+
+    console.log(`Starting deep scan of ${files.length} files...`);
+
+    for (const file of files) {
+      const skillName = this.detectSkill(file, mode);
+      if (!skillName) continue;
+
+      stats.filesMatched++;
+      const auditJsonPath = this._findAuditJson(skillName);
+      if (!auditJsonPath) {
+        stats.noRulesSkills.add(skillName);
+        continue; // skill has no static rules — skip
+      }
+
+      let rules;
+      try {
+        ({ rules } = JSON.parse(fs.readFileSync(auditJsonPath, 'utf8')));
+      } catch { continue; }
+
+      const lines = fs.readFileSync(file, 'utf8').split('\n');
+      let violationCount = 0;
+      for (const rule of rules) {
+        const regex = new RegExp(rule.pattern, 'g');
+        for (const line of lines) {
+          if (regex.test(line)) violationCount++;
+        }
+      }
+
+      stats.filesAudited++;
+      stats.violations += violationCount;
+      if (violationCount === 0) stats.healthyFiles++;
+      stats.debtBySkill[skillName] = (stats.debtBySkill[skillName] || 0) + violationCount;
+      if (violationCount > 0) {
+        reports.push({ file, skill: skillName, violationCount });
+      }
+    }
+
+    return this.formatDashboard(stats, reports);
+  }
+
+  /**
+   * Detects which BookLib skill is most relevant to a file extension.
+   */
+  detectSkill(filePath, mode = 'code') {
+    const ext = path.extname(filePath);
+    if (mode === 'docs') {
+      if (ext === '.md' || ext === '.mdx' || ext === '.mdc') return 'writing-plans';
+      if (ext === '.txt') return 'writing-plans';
+      return null;
+    }
+    if (ext === '.kt' || ext === '.kts') return 'effective-kotlin';
+    if (ext === '.ts' || ext === '.tsx') return 'effective-typescript';
+    if (ext === '.java') return 'effective-java';
+    if (ext === '.py') return 'effective-python';
+    if (ext === '.js' || ext === '.mjs' || ext === '.cjs') return 'clean-code-reviewer';
+    return null;
+  }
+
+  /**
+   * Finds audit.json for a skill — checks bundled skills first, then community cache.
+   */
+  _findAuditJson(skillName) {
+    const { skillsPath, cachePath } = resolveBookLibPaths();
+    const bundled = path.join(skillsPath, skillName, 'audit.json');
+    if (fs.existsSync(bundled)) return bundled;
+    const community = path.join(cachePath, 'skills', skillName, 'audit.json');
+    if (fs.existsSync(community)) return community;
+    return null;
+  }
+
+  /**
+   * Helper to recursively list files, excluding common noise directories.
+   */
+  getFiles(dir) {
+    let results = [];
+    const list = fs.readdirSync(dir);
+    const ignore = ['.git', 'node_modules', '.booklib', '.claude', '.idea', 'dist', 'build', 'coverage', '.cache'];
+
+    list.forEach(file => {
+      if (ignore.includes(file)) return;
+
+      const fullPath = path.join(dir, file);
+      const stat = fs.statSync(fullPath);
+      if (stat && stat.isDirectory()) {
+        results = results.concat(this.getFiles(fullPath));
+      } else {
+        results.push(fullPath);
+      }
+    });
+    return results;
+  }
+
+  formatDashboard(stats, reports) {
+    const sortedReports = reports.sort((a, b) => b.violationCount - a.violationCount);
+    const topDebt = sortedReports.slice(0, 5);
+
+    return `
+# 📊 BookLib Wisdom Heatmap
+**Project Health Dashboard**
+
+## 📈 Executive Summary
+- **Files Scanned**: ${stats.filesScanned} (${stats.filesMatched} matched a skill lens, ${stats.filesAudited} audited)
+- **Healthy Files**: ${stats.healthyFiles} / ${stats.filesAudited} audited
+- **Total Violations**: ${stats.violations}
+- **Compliance**: ${((stats.healthyFiles / (stats.filesAudited || 1)) * 100).toFixed(1)}% of audited files violation-free
+
+## 🛠 Architectural Debt by Skill
+${Object.entries(stats.debtBySkill).map(([skill, count]) => `- **${skill}**: ${count} violations`).join('\n')}
+
+## 🚨 Top 5 Refactoring Priorities (High Debt)
+${topDebt.map(r => `- \`${path.relative(process.cwd(), r.file)}\` (${r.violationCount} violations | Lens: ${r.skill})`).join('\n')}
+
+---
+> **Note**: This heatmap is based on 'Light Audits' (Static Pattern Detection).
+> Use \`booklib audit <skill> <file>\` for a deep-reasoning review of high-priority files.
+${stats.noRulesSkills.size > 0 ? `> **No static rules loaded for:** ${[...stats.noRulesSkills].join(', ')} — add an \`audit.json\` to enable pattern checks.` : ''}
+`;
+  }
+}

package/lib/engine/searcher.js

@@ -0,0 +1,223 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { LocalIndex } from 'vectra';
+import { createEmbeddingPipeline } from './embedding-provider.js';
+import { resolveBookLibPaths } from '../paths.js';
+import { BM25Index } from './bm25-index.js';
+import { reciprocalRankFusion } from './rrf.js';
+import { expandQuery } from './query-expander.js';
+import { Reranker } from './reranker.js';
+import { loadEdges, traverseEdges } from './graph.js';
+
+const RRF_ORIGINAL_WEIGHT = 2;
+const RRF_EXPANDED_WEIGHT = 1;
+const RERANK_CANDIDATES = 20;
+
+export class BookLibSearcher {
+  constructor(indexPath) {
+    const paths = resolveBookLibPaths();
+    this.indexPath = indexPath ?? paths.readIndexPath;
+    this.index = new LocalIndex(this.indexPath);
+    this.extractor = null;
+    this.reranker = new Reranker();
+  }
+
+  async loadModel() {
+    if (!this.extractor) {
+      const { extractor } = await createEmbeddingPipeline({ quiet: true });
+      this.extractor = extractor;
+    }
+  }
+
+  async getEmbedding(text) {
+    await this.loadModel();
+    const output = await this.extractor(text, { pooling: 'mean', normalize: true });
+    return Array.from(output.data);
+  }
+
+  get bm25Path() {
+    return path.join(path.dirname(this.indexPath), 'bm25.json');
+  }
+
+  get graphFile() {
+    return path.join(path.dirname(this.indexPath), 'knowledge', 'graph.jsonl');
+  }
+
+  async _vectorSearch(query, topK) {
+    const vector = await this.getEmbedding(query);
+    const results = await this.index.queryItems(vector, '', topK);
+    return results.map(r => ({
+      score: r.score,
+      text: r.item.metadata.text,
+      metadata: { ...r.item.metadata, text: undefined },
+    }));
+  }
+
+  async search(query, limit = 5, minScore = 0.5, options = {}) {
+    const { useGraph = false } = options;
+    if (!(await this.index.isIndexCreated())) {
+      throw new Error('Index not found. Please run "booklib index" first.');
+    }
+
+    // Fallback: no BM25 index present — use pure vector search (backwards compatible)
+    if (!fs.existsSync(this.bm25Path)) {
+      const vector = await this.getEmbedding(query);
+      const results = await this.index.queryItems(vector, '', limit);
+      const filtered = results
+        .filter(r => r.score >= minScore)
+        .map(r => ({
+          score: r.score,
+          text: r.item.metadata.text,
+          metadata: { ...r.item.metadata, text: undefined },
+        }));
+      return addDisplayScores(useGraph ? this._appendGraphResults(filtered) : filtered);
+    }
+
+    const bm25 = BM25Index.load(this.bm25Path);
+    const { expanded } = expandQuery(query);
+    const allQueries = [query, ...expanded];
+
+    const resultLists = [];
+    const weights = [];
+
+    for (let i = 0; i < allQueries.length; i++) {
+      const q = allQueries[i];
+      const w = i === 0 ? RRF_ORIGINAL_WEIGHT : RRF_EXPANDED_WEIGHT;
+
+      const [vecResults, bm25Results] = await Promise.all([
+        this._vectorSearch(q, RERANK_CANDIDATES),
+        Promise.resolve(bm25.search(q, RERANK_CANDIDATES)),
+      ]);
+
+      resultLists.push(vecResults, bm25Results);
+      weights.push(w, w);
+    }
+
+    const merged = reciprocalRankFusion(resultLists, { weights });
+    const candidates = merged.slice(0, RERANK_CANDIDATES);
+    const reranked = await this.reranker.rerank(query, candidates);
+
+    const filtered = reranked.filter(r => r.score >= minScore);
+
+    // Sibling expansion: when ≥50% of a section's chunks match, pull in the rest.
+    // This prevents fragmented results — if the search finds "import createClient",
+    // expansion pulls in the full config block and services list from the same section.
+    let withSiblings;
+    try {
+      withSiblings = this._expandSiblings(filtered, bm25);
+    } catch {
+      withSiblings = filtered;
+    }
+    const results = withSiblings.slice(0, limit);
+
+    return addDisplayScores(useGraph ? this._appendGraphResults(results) : results);
+  }
+
+  /**
+   * Expands search results by pulling in missing sibling chunks when ≥50%
+   * of a parent section's chunks already appear in results.
+   * @param {Array} results - search results with metadata.parentId, siblingIndex, siblingCount
+   * @param {BM25Index} bm25 - BM25 index to find sibling chunks
+   * @returns {Array} expanded results with siblings inserted after the first match
+   */
+  _expandSiblings(results, bm25) {
+    // Group results by parentId
+    const byParent = new Map();
+    for (const r of results) {
+      const pid = r.metadata?.parentId;
+      if (!pid) continue;
+      if (!byParent.has(pid)) byParent.set(pid, []);
+      byParent.get(pid).push(r);
+    }
+
+    // Find parents where ≥50% of siblings are in results
+    const expandIds = new Set();
+    for (const [pid, hits] of byParent) {
+      const total = hits[0].metadata?.siblingCount ?? 1;
+      if (total <= 1) continue;
+      if (hits.length / total >= 0.5) expandIds.add(pid);
+    }
+
+    if (expandIds.size === 0) return results;
+
+    // Find missing siblings from BM25 index's internal document store
+    const allDocs = bm25._docs ?? [];
+    const siblingPool = new Map(); // parentId -> [docs sorted by siblingIndex]
+    for (const doc of allDocs) {
+      const pid = doc.metadata?.parentId;
+      if (!pid || !expandIds.has(pid)) continue;
+      if (!siblingPool.has(pid)) siblingPool.set(pid, []);
+      siblingPool.get(pid).push(doc);
+    }
+
+    // Sort siblings by siblingIndex
+    for (const [, siblings] of siblingPool) {
+      siblings.sort((a, b) => (a.metadata?.siblingIndex ?? 0) - (b.metadata?.siblingIndex ?? 0));
+    }
+
+    // Build expanded results: insert missing siblings after the first match
+    const seenTexts = new Set(results.map(r => r.text));
+    const expanded = [];
+    const insertedParents = new Set();
+
+    for (const r of results) {
+      expanded.push(r);
+      const pid = r.metadata?.parentId;
+      if (pid && expandIds.has(pid) && !insertedParents.has(pid)) {
+        insertedParents.add(pid);
+        const siblings = siblingPool.get(pid) ?? [];
+        for (const sib of siblings) {
+          if (!seenTexts.has(sib.text)) {
+            expanded.push({
+              text: sib.text,
+              score: r.score * 0.95, // slightly lower than the matched sibling
+              metadata: sib.metadata,
+              _expanded: true,
+            });
+            seenTexts.add(sib.text);
+          }
+        }
+      }
+    }
+
+    return expanded;
+  }
+
+  _appendGraphResults(results) {
+    const GRAPH_EDGE_TYPES = new Set(['see-also', 'applies-to', 'extends']);
+    let edges;
+    try {
+      edges = loadEdges({ graphFile: this.graphFile });
+    } catch {
+      return results;
+    }
+    if (edges.length === 0) return results;
+
+    const seenIds = new Set(
+      results.map(r => r.metadata?.name ?? r.metadata?.id).filter(Boolean)
+    );
+    const graphLinked = [];
+
+    for (const result of results) {
+      const nodeId = result.metadata?.name ?? result.metadata?.id;
+      if (!nodeId) continue;
+
+      for (const { id: neighborId, edge } of traverseEdges(nodeId, edges, 1)) {
+        if (!GRAPH_EDGE_TYPES.has(edge.type)) continue;
+        if (seenIds.has(neighborId)) continue;
+        seenIds.add(neighborId);
+        graphLinked.push({
+          score: 0,
+          text: '',
+          metadata: { name: neighborId, source: 'graph', edgeType: edge.type },
+        });
+      }
+    }
+
+    return [...results, ...graphLinked];
+  }
+}
+
+function addDisplayScores(results) {
+  return results.map((r, i) => ({ ...r, displayScore: r.displayScore ?? Math.round(100 / (i + 1)) }));
+}

package/lib/engine/session-coordinator.js

@@ -0,0 +1,291 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Coordinates handoff sessions across multiple agents.
+ * Enables session merging, lineage tracking, and cross-agent insights.
+ */
+export class BookLibSessionCoordinator {
+  constructor(handoffDir = path.join(process.cwd(), '.booklib', 'sessions')) {
+    this.handoffDir = handoffDir;
+  }
+
+  /**
+   * Lists all available sessions with metadata.
+   */
+  listAllSessions() {
+    if (!fs.existsSync(this.handoffDir)) return [];
+    
+    const sessions = fs.readdirSync(this.handoffDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => {
+        const sessionName = f.replace('.md', '');
+        const filePath = path.join(this.handoffDir, f);
+        const stats = fs.statSync(filePath);
+        const content = fs.readFileSync(filePath, 'utf8');
+        
+        // Extract key info without full XML parsing (faster)
+        const goalMatch = content.match(/<goal>(.*?)<\/goal>/);
+        const progressMatch = content.match(/<progress>(.*?)<\/progress>/);
+        const branchMatch = content.match(/<branch>(.*?)<\/branch>/);
+        
+        return {
+          id: sessionName,
+          goal: goalMatch ? goalMatch[1] : 'Unknown',
+          progress: progressMatch ? progressMatch[1] : 'Unknown',
+          branch: branchMatch ? branchMatch[1] : 'Unknown',
+          timestamp: stats.mtime,
+          size: stats.size
+        };
+      });
+
+    return sessions.sort((a, b) => b.timestamp - a.timestamp);
+  }
+
+  /**
+   * Merges multiple sessions into a combined session.
+   * Useful for: combining work from parallel agents, multi-agent reviews, etc.
+   * 
+   * Usage:
+   *   coordinator.mergeSessions(['agent-python', 'agent-kotlin'], 'combined-review')
+   *   → Creates combined-review.md with insights from both
+   */
+  mergeSessions(sessionIds, outputSessionId) {
+    const sessions = sessionIds.map(id => {
+      const filePath = path.join(this.handoffDir, `${id}.md`);
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`Session not found: ${id}`);
+      }
+      return {
+        id,
+        content: fs.readFileSync(filePath, 'utf8')
+      };
+    });
+
+    // Extract metadata from all sessions
+    const merged = {
+      metadata: {
+        timestamp: new Date().toISOString(),
+        session_id: outputSessionId,
+        parent_sessions: sessionIds.join(', '),
+        merge_type: 'multi-agent-combined'
+      }
+    };
+
+    const outputPath = path.join(this.handoffDir, `${outputSessionId}.md`);
+    const content = `
+<session_handoff>
+  <metadata>
+    <timestamp>${merged.metadata.timestamp}</timestamp>
+    <session_id>${merged.metadata.session_id}</session_id>
+    <parent_sessions>${merged.metadata.parent_sessions}</parent_sessions>
+    <merge_type>${merged.metadata.merge_type}</merge_type>
+  </metadata>
+
+  <context>
+    <goal>Combined context from multiple agents</goal>
+    <progress>Merged from: ${sessionIds.join(', ')}</progress>
+    <pending_tasks>Review merged insights below</pending_tasks>
+    <note>This session combines work from multiple agents. See merged_agent_contexts below.</note>
+  </context>
+
+  <merged_agent_contexts>
+${sessions.map(s => {
+  const goal = s.content.match(/<goal>(.*?)<\/goal>/)?.[1] || 'Unknown';
+  const progress = s.content.match(/<progress>(.*?)<\/progress>/)?.[1] || 'Unknown';
+  const branch = s.content.match(/<branch>(.*?)<\/branch>/)?.[1] || 'Unknown';
+  return `    <agent id="${s.id}">
+      <goal>${goal}</goal>
+      <progress>${progress}</progress>
+      <branch>${branch}</branch>
+    </agent>`;
+}).join('\n')}
+  </merged_agent_contexts>
+
+  <cross_agent_insights>
+    <note>Each agent contributed unique insights. Review their branches below:</note>
+${sessions.map(s => {
+  const commits = s.content.match(/<recent_commit_history>([\s\S]*?)<\/recent_commit_history>/)?.[1] || '';
+  return `    <agent_work id="${s.id}">
+${commits.trim()}
+    </agent_work>`;
+}).join('\n')}
+  </cross_agent_insights>
+
+  <recovery_instructions>
+    <step1>This is a merged session combining: ${sessionIds.join(', ')}</step1>
+    <step2>Review merged_agent_contexts above to see what each agent accomplished</step2>
+    <step3>Review cross_agent_insights for commits from each agent</step3>
+    <step4>Decide: continue on one branch or synthesize both?</step4>
+    <step5>If synthesizing: git merge the branches with appropriate strategy</step5>
+  </recovery_instructions>
+</session_handoff>
+`;
+
+    fs.writeFileSync(outputPath, content.trim());
+    return outputPath;
+  }
+
+  /**
+   * Tracks session lineage (parent-child relationships).
+   * For example: agent-1 creates "main" session, agent-2 branches to "feature-x"
+   * 
+   * Usage:
+   *   coordinator.trackLineage('main', 'feature-x', 'Agent 2 branched from main')
+   *   → Records parent-child relationship
+   */
+  trackLineage(parentSessionId, childSessionId, reason = '') {
+    const lineageFile = path.join(this.handoffDir, '_lineage.json');
+    
+    let lineage = {};
+    if (fs.existsSync(lineageFile)) {
+      lineage = JSON.parse(fs.readFileSync(lineageFile, 'utf8'));
+    }
+
+    if (!lineage[childSessionId]) {
+      lineage[childSessionId] = {
+        parent: parentSessionId,
+        reason,
+        createdAt: new Date().toISOString(),
+        children: []
+      };
+    }
+
+    if (!lineage[parentSessionId]) {
+      lineage[parentSessionId] = { children: [] };
+    }
+    
+    if (!lineage[parentSessionId].children) {
+      lineage[parentSessionId].children = [];
+    }
+    lineage[parentSessionId].children.push(childSessionId);
+
+    fs.writeFileSync(lineageFile, JSON.stringify(lineage, null, 2));
+    return lineage;
+  }
+
+  /**
+   * Displays session lineage as a tree.
+   * Shows parent-child relationships visually.
+   */
+  displayLineageTree() {
+    const lineageFile = path.join(this.handoffDir, '_lineage.json');
+    if (!fs.existsSync(lineageFile)) {
+      return 'No session lineage tracked yet. Start with trackLineage().';
+    }
+
+    const lineage = JSON.parse(fs.readFileSync(lineageFile, 'utf8'));
+    const roots = Object.entries(lineage)
+      .filter(([_, info]) => !info.parent)
+      .map(([id]) => id);
+
+    let output = 'SESSION LINEAGE TREE\n═══════════════════\n\n';
+    
+    const drawTree = (sessionId, depth = 0) => {
+      const info = lineage[sessionId];
+      const indent = '  '.repeat(depth);
+      const prefix = depth === 0 ? '📍' : '└─';
+      
+      output += `${indent}${prefix} ${sessionId}\n`;
+      if (info.reason) output += `${indent}   (${info.reason})\n`;
+      
+      if (info.children && info.children.length > 0) {
+        info.children.forEach(child => {
+          drawTree(child, depth + 1);
+        });
+      }
+    };
+
+    roots.forEach(root => drawTree(root));
+    return output;
+  }
+
+  /**
+   * Gets the full lineage path of a session (all ancestors).
+   * 
+   * Usage:
+   *   coordinator.getLineagePath('feature-x')
+   *   → Returns: ['main', 'feature-base', 'feature-x']
+   */
+  getLineagePath(sessionId) {
+    const lineageFile = path.join(this.handoffDir, '_lineage.json');
+    if (!fs.existsSync(lineageFile)) return [sessionId];
+
+    const lineage = JSON.parse(fs.readFileSync(lineageFile, 'utf8'));
+    const path = [sessionId];
+    
+    let current = sessionId;
+    while (lineage[current] && lineage[current].parent) {
+      path.unshift(lineage[current].parent);
+      current = lineage[current].parent;
+    }
+
+    return path;
+  }
+
+  /**
+   * Creates a session comparing multiple agents' audits.
+   * Useful for: "Compare Python audit vs Kotlin audit of same file"
+   */
+  compareAudits(auditSessionIds, targetFile, outputSessionId) {
+    const audits = auditSessionIds.map(id => {
+      const filePath = path.join(this.handoffDir, `${id}.md`);
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`Audit session not found: ${id}`);
+      }
+      return {
+        id,
+        content: fs.readFileSync(filePath, 'utf8')
+      };
+    });
+
+    const content = `
+<session_handoff>
+  <metadata>
+    <timestamp>${new Date().toISOString()}</timestamp>
+    <session_id>${outputSessionId}</session_id>
+    <type>audit-comparison</type>
+    <target_file>${targetFile}</target_file>
+  </metadata>
+
+  <context>
+    <goal>Compare audit findings from multiple agents for ${targetFile}</goal>
+    <progress>Aggregated ${auditSessionIds.length} audits</progress>
+    <pending_tasks>Review and prioritize findings, decide which issues to fix first</pending_tasks>
+  </context>
+
+  <audit_comparison>
+    <note>Each agent audited ${targetFile} against their own skill framework</note>
+${audits.map(a => `    <agent_audit id="${a.id}">
+${this._extractContext(a.content)}
+    </agent_audit>`).join('\n')}
+  </audit_comparison>
+
+  <recovery_instructions>
+    <step1>This session compares audits from: ${auditSessionIds.join(', ')}</step1>
+    <step2>Review each agent's findings in audit_comparison above</step2>
+    <step3>Note overlapping issues (high priority)</step3>
+    <step4>Note unique issues per agent (domain-specific)</step4>
+    <step5>Prioritize fixes: overlapping first, then unique critical ones</step5>
+  </recovery_instructions>
+</session_handoff>
+`;
+
+    const outputPath = path.join(this.handoffDir, `${outputSessionId}.md`);
+    fs.writeFileSync(outputPath, content.trim());
+    return outputPath;
+  }
+
+  // ─── HELPER METHODS ───
+
+  /**
+   * Extracts context snippet from session.
+   */
+  _extractContext(content) {
+    const goal = content.match(/<goal>(.*?)<\/goal>/)?.[1] || 'Unknown';
+    const progress = content.match(/<progress>(.*?)<\/progress>/)?.[1] || 'Unknown';
+    const tasks = content.match(/<pending_tasks>(.*?)<\/pending_tasks>/)?.[1] || 'None specified';
+    return `Goal: ${goal}\nProgress: ${progress}\nNext: ${tasks}`;
+  }
+}