trellis 2.0.13 → 2.1.2

package/src/garden/cluster.ts

@@ -1,330 +0,0 @@
-/**
- * Idea Garden — Cluster Detection
- *
- * DESIGN.md §7.2–7.4 — Identifies "idea clusters": contiguous sequences
- * of ops that were never incorporated into a milestone and were later
- * diverged from.
- *
- * Three detection heuristics:
- *   1. Context-switch detection (file-set shift)
- *   2. Branch abandonment (stale un-milestoned ops)
- *   3. Revert detection (ops undone by later ops)
- */
-
-import type { VcsOp } from '../vcs/types.js';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface IdeaCluster {
-  id: string;
-  ops: VcsOp[];
-  firstOp: string;
-  lastOp: string;
-  affectedFiles: string[];
-  affectedSymbols: string[]; // Tier 2 — empty for now
-  estimatedIntent: string;
-  createdAt: string;
-  abandonedAt: string;
-  status: 'abandoned' | 'draft' | 'revived';
-  /** Which heuristic detected this cluster. */
-  detectedBy: string;
-}
-
-export interface ClusterDetector {
-  name: string;
-  detect(ops: VcsOp[], milestonedOpHashes: Set<string>): IdeaCluster[];
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** VcsOp kinds that represent file-level work (not control ops). */
-const FILE_OP_KINDS = new Set([
-  'vcs:fileAdd',
-  'vcs:fileModify',
-  'vcs:fileDelete',
-  'vcs:fileRename',
-]);
-
-function isFileOp(op: VcsOp): boolean {
-  return FILE_OP_KINDS.has(op.kind);
-}
-
-function extractFiles(ops: VcsOp[]): string[] {
-  const files = new Set<string>();
-  for (const op of ops) {
-    if (op.vcs?.filePath) files.add(op.vcs.filePath);
-    if (op.vcs?.oldFilePath) files.add(op.vcs.oldFilePath);
-  }
-  return [...files];
-}
-
-function generateClusterId(prefix: string, ops: VcsOp[]): string {
-  const hash = ops[0]?.hash?.slice(0, 8) ?? 'unknown';
-  return `cluster:${prefix}-${hash}`;
-}
-
-// ---------------------------------------------------------------------------
-// 1. Context-switch detector
-// ---------------------------------------------------------------------------
-
-/**
- * Detects clusters when the set of files being modified shifts abruptly.
- * Groups consecutive un-milestoned file ops by "file affinity" — when
- * the overlap between the current working set and the next op drops to zero,
- * a new group starts. Groups that are followed by a different group become
- * candidate clusters.
- */
-export const contextSwitchDetector: ClusterDetector = {
-  name: 'context-switch',
-
-  detect(ops: VcsOp[], milestonedOpHashes: Set<string>): IdeaCluster[] {
-    // Filter to un-milestoned file ops
-    const fileOps = ops.filter(
-      (o) => isFileOp(o) && !milestonedOpHashes.has(o.hash),
-    );
-
-    if (fileOps.length < 2) return [];
-
-    // Group by file affinity windows
-    const groups: VcsOp[][] = [];
-    let currentGroup: VcsOp[] = [];
-    let currentFiles = new Set<string>();
-
-    for (const op of fileOps) {
-      const opFile = op.vcs?.filePath;
-      if (!opFile) continue;
-
-      // Get directory prefix for affinity comparison
-      const opDir = opFile.split('/').slice(0, -1).join('/') || '.';
-
-      if (currentGroup.length === 0) {
-        currentGroup.push(op);
-        currentFiles.add(opDir);
-        continue;
-      }
-
-      // Check if this op's directory overlaps with the current working set
-      const currentDirs = [...currentFiles];
-      const hasOverlap = currentDirs.some(
-        (d) => opDir.startsWith(d) || d.startsWith(opDir) || d === opDir,
-      );
-
-      if (hasOverlap) {
-        currentGroup.push(op);
-        currentFiles.add(opDir);
-      } else {
-        // Context switch — close current group and start new
-        if (currentGroup.length > 0) {
-          groups.push(currentGroup);
-        }
-        currentGroup = [op];
-        currentFiles = new Set([opDir]);
-      }
-    }
-
-    if (currentGroup.length > 0) {
-      groups.push(currentGroup);
-    }
-
-    // All groups except the last (most recent) are candidates
-    const clusters: IdeaCluster[] = [];
-    for (let i = 0; i < groups.length - 1; i++) {
-      const group = groups[i];
-      if (group.length < 2) continue; // Skip trivially small groups
-
-      clusters.push({
-        id: generateClusterId('ctx', group),
-        ops: group,
-        firstOp: group[0].hash,
-        lastOp: group[group.length - 1].hash,
-        affectedFiles: extractFiles(group),
-        affectedSymbols: [],
-        estimatedIntent: '',
-        createdAt: group[0].timestamp,
-        abandonedAt: group[group.length - 1].timestamp,
-        status: 'abandoned',
-        detectedBy: 'context-switch',
-      });
-    }
-
-    return clusters;
-  },
-};
-
-// ---------------------------------------------------------------------------
-// 2. Revert detector
-// ---------------------------------------------------------------------------
-
-/**
- * Detects clusters where a file's content hash returns to a prior value,
- * indicating the intermediate ops were "reverted."
- */
-export const revertDetector: ClusterDetector = {
-  name: 'revert',
-
-  detect(ops: VcsOp[], milestonedOpHashes: Set<string>): IdeaCluster[] {
-    const clusters: IdeaCluster[] = [];
-
-    // Track content hash history per file
-    const hashHistory = new Map<string, { hash: string; opIdx: number }[]>();
-
-    for (let i = 0; i < ops.length; i++) {
-      const op = ops[i];
-      if (!isFileOp(op) || !op.vcs?.filePath || !op.vcs?.contentHash) continue;
-
-      const filePath = op.vcs.filePath;
-      if (!hashHistory.has(filePath)) {
-        hashHistory.set(filePath, []);
-      }
-
-      const history = hashHistory.get(filePath)!;
-      const currentHash = op.vcs.contentHash;
-
-      // Check if this hash appeared before (revert)
-      const priorIdx = history.findIndex((h) => h.hash === currentHash);
-      if (priorIdx >= 0 && priorIdx < history.length - 1) {
-        // Ops between priorIdx+1 and the current position were "reverted"
-        const revertedStartIdx = history[priorIdx + 1].opIdx;
-        const revertedEndIdx = history[history.length - 1].opIdx;
-        const revertedOps = ops
-          .slice(revertedStartIdx, revertedEndIdx + 1)
-          .filter(
-            (o) =>
-              isFileOp(o) &&
-              o.vcs?.filePath === filePath &&
-              !milestonedOpHashes.has(o.hash),
-          );
-
-        if (revertedOps.length >= 2) {
-          clusters.push({
-            id: generateClusterId('rev', revertedOps),
-            ops: revertedOps,
-            firstOp: revertedOps[0].hash,
-            lastOp: revertedOps[revertedOps.length - 1].hash,
-            affectedFiles: [filePath],
-            affectedSymbols: [],
-            estimatedIntent: '',
-            createdAt: revertedOps[0].timestamp,
-            abandonedAt: op.timestamp,
-            status: 'abandoned',
-            detectedBy: 'revert',
-          });
-        }
-      }
-
-      history.push({ hash: currentHash, opIdx: i });
-    }
-
-    return clusters;
-  },
-};
-
-// ---------------------------------------------------------------------------
-// 3. Stale-branch detector
-// ---------------------------------------------------------------------------
-
-/**
- * Detects un-milestoned ops on branches that haven't seen activity recently.
- * Since we operate on a linear op stream for now, this looks for gaps
- * where file ops stop and then resume on different files.
- */
-export const staleBranchDetector: ClusterDetector = {
-  name: 'stale-branch',
-
-  detect(ops: VcsOp[], milestonedOpHashes: Set<string>): IdeaCluster[] {
-    const clusters: IdeaCluster[] = [];
-
-    // Find branch create ops and their un-milestoned file ops
-    const branchOps = new Map<string, VcsOp[]>();
-
-    let currentBranch = 'main';
-    for (const op of ops) {
-      if (op.kind === 'vcs:branchCreate' && op.vcs?.branchName) {
-        currentBranch = op.vcs.branchName;
-        if (!branchOps.has(currentBranch)) {
-          branchOps.set(currentBranch, []);
-        }
-      }
-
-      if (isFileOp(op) && !milestonedOpHashes.has(op.hash)) {
-        if (!branchOps.has(currentBranch)) {
-          branchOps.set(currentBranch, []);
-        }
-        branchOps.get(currentBranch)!.push(op);
-      }
-    }
-
-    // Check each branch for stale un-milestoned work
-    for (const [branchName, fileOps] of branchOps) {
-      if (branchName === 'main') continue; // Don't flag main
-      if (fileOps.length < 2) continue;
-
-      const lastOpTime = new Date(fileOps[fileOps.length - 1].timestamp).getTime();
-      const now = Date.now();
-      const daysSinceLastOp = (now - lastOpTime) / (1000 * 60 * 60 * 24);
-
-      // Flag if no activity for > 7 days (configurable later)
-      if (daysSinceLastOp > 7) {
-        clusters.push({
-          id: generateClusterId('stale', fileOps),
-          ops: fileOps,
-          firstOp: fileOps[0].hash,
-          lastOp: fileOps[fileOps.length - 1].hash,
-          affectedFiles: extractFiles(fileOps),
-          affectedSymbols: [],
-          estimatedIntent: '',
-          createdAt: fileOps[0].timestamp,
-          abandonedAt: fileOps[fileOps.length - 1].timestamp,
-          status: 'abandoned',
-          detectedBy: 'stale-branch',
-        });
-      }
-    }
-
-    return clusters;
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Composite detector
-// ---------------------------------------------------------------------------
-
-/** All built-in detectors. */
-export const defaultDetectors: ClusterDetector[] = [
-  contextSwitchDetector,
-  revertDetector,
-  staleBranchDetector,
-];
-
-/**
- * Run all detectors and merge results (dedup by cluster ID).
- */
-export function detectClusters(
-  ops: VcsOp[],
-  milestonedOpHashes: Set<string>,
-  detectors: ClusterDetector[] = defaultDetectors,
-): IdeaCluster[] {
-  const seen = new Set<string>();
-  const results: IdeaCluster[] = [];
-
-  for (const detector of detectors) {
-    const clusters = detector.detect(ops, milestonedOpHashes);
-    for (const cluster of clusters) {
-      if (!seen.has(cluster.id)) {
-        seen.add(cluster.id);
-        results.push(cluster);
-      }
-    }
-  }
-
-  // Sort by creation time (oldest first)
-  results.sort(
-    (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
-  );
-
-  return results;
-}

package/src/garden/garden.ts

@@ -1,306 +0,0 @@
-/**
- * Idea Garden — Query Layer + Revive
- *
- * DESIGN.md §7.4–7.5 — Search and revive idea clusters.
- *
- * The Garden is a query layer over the causal stream that surfaces
- * abandoned work as searchable idea clusters. It also provides the
- * ability to revive clusters into new branches.
- */
-
-import type { VcsOp } from '../vcs/types.js';
-import {
-  detectClusters,
-  defaultDetectors,
-  type IdeaCluster,
-  type ClusterDetector,
-} from './cluster.js';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface ScoredCluster {
-  cluster: IdeaCluster;
-  score: number;
-}
-
-export interface GardenSearchOpts {
-  /** Filter by affected file path (substring match). */
-  file?: string;
-  /** Filter by keyword in affected files or estimated intent. */
-  keyword?: string;
-  /** Filter by cluster status. */
-  status?: IdeaCluster['status'];
-  /** Maximum results to return. */
-  limit?: number;
-  /** Use vector similarity when an EmbeddingManager is available (default: true). */
-  semantic?: boolean;
-}
-
-/**
- * Optional embedding manager interface for vector-enhanced search.
- * Avoids hard dependency on the embeddings module.
- */
-export interface GardenEmbedder {
-  search(
-    query: string,
-    opts?: { limit?: number; filePrefix?: string },
-  ): Promise<
-    Array<{ chunk: { filePath?: string; content: string }; score: number }>
-  >;
-}
-
-export interface GardenContext {
-  /** All ops in the stream. */
-  readAllOps(): VcsOp[];
-  /** Set of op hashes that belong to a milestone range. */
-  getMilestonedOpHashes(): Set<string>;
-}
-
-// ---------------------------------------------------------------------------
-// Garden
-// ---------------------------------------------------------------------------
-
-export class IdeaGarden {
-  private ctx: GardenContext;
-  private detectors: ClusterDetector[];
-  private _cache: IdeaCluster[] | null = null;
-  private _revivedIds = new Set<string>();
-  private _embedder: GardenEmbedder | null = null;
-
-  constructor(ctx: GardenContext, detectors?: ClusterDetector[]) {
-    this.ctx = ctx;
-    this.detectors = detectors ?? defaultDetectors;
-  }
-
-  /**
-   * Attach an embedding manager for vector-enhanced search.
-   */
-  setEmbedder(embedder: GardenEmbedder | null): void {
-    this._embedder = embedder;
-  }
-
-  /**
-   * Invalidate the cluster cache (call after new ops are added).
-   */
-  invalidate(): void {
-    this._cache = null;
-  }
-
-  /**
-   * Detect and return all idea clusters.
-   */
-  listClusters(): IdeaCluster[] {
-    if (!this._cache) {
-      const ops = this.ctx.readAllOps();
-      const milestoned = this.ctx.getMilestonedOpHashes();
-      this._cache = detectClusters(ops, milestoned, this.detectors);
-
-      // Apply revived status
-      for (const cluster of this._cache) {
-        if (this._revivedIds.has(cluster.id)) {
-          cluster.status = 'revived';
-        }
-      }
-    }
-    return this._cache;
-  }
-
-  /**
-   * Get a single cluster by ID.
-   */
-  getCluster(clusterId: string): IdeaCluster | null {
-    return this.listClusters().find((c) => c.id === clusterId) ?? null;
-  }
-
-  /**
-   * Search clusters with filters (synchronous keyword search).
-   */
-  search(opts: GardenSearchOpts = {}): IdeaCluster[] {
-    let clusters = this.listClusters();
-
-    if (opts.status) {
-      clusters = clusters.filter((c) => c.status === opts.status);
-    }
-
-    if (opts.file) {
-      const fileTerm = opts.file.toLowerCase();
-      clusters = clusters.filter((c) =>
-        c.affectedFiles.some((f) => f.toLowerCase().includes(fileTerm)),
-      );
-    }
-
-    if (opts.keyword) {
-      const kw = opts.keyword.toLowerCase();
-      clusters = clusters.filter((c) => {
-        // Search in file paths
-        if (c.affectedFiles.some((f) => f.toLowerCase().includes(kw)))
-          return true;
-        // Search in estimated intent
-        if (c.estimatedIntent.toLowerCase().includes(kw)) return true;
-        // Search in op kinds
-        if (c.ops.some((o) => o.kind.toLowerCase().includes(kw))) return true;
-        return false;
-      });
-    }
-
-    if (opts.limit && opts.limit > 0) {
-      clusters = clusters.slice(0, opts.limit);
-    }
-
-    return clusters;
-  }
-
-  /**
-   * Vector-enhanced search: uses embeddings to find clusters whose affected
-   * files are semantically similar to the query. Falls back to keyword search
-   * if no embedder is attached.
-   */
-  async semanticSearch(opts: GardenSearchOpts = {}): Promise<ScoredCluster[]> {
-    // Start with keyword-filtered clusters
-    const keywordResults = this.search({ ...opts, limit: undefined });
-
-    // If no embedder or semantic explicitly disabled, wrap as scored
-    if (!this._embedder || opts.semantic === false) {
-      const scored = keywordResults.map((c) => ({ cluster: c, score: 1.0 }));
-      if (opts.limit && opts.limit > 0) return scored.slice(0, opts.limit);
-      return scored;
-    }
-
-    // Use embeddings to score clusters by file similarity
-    const query = opts.keyword ?? opts.file ?? '';
-    if (!query) {
-      const scored = keywordResults.map((c) => ({ cluster: c, score: 1.0 }));
-      if (opts.limit && opts.limit > 0) return scored.slice(0, opts.limit);
-      return scored;
-    }
-
-    const allClusters = this.listClusters();
-    const embeddingResults = await this._embedder.search(query, { limit: 50 });
-
-    // Build file → score map from embedding results
-    const fileScores = new Map<string, number>();
-    for (const r of embeddingResults) {
-      if (r.chunk.filePath) {
-        const existing = fileScores.get(r.chunk.filePath) ?? 0;
-        fileScores.set(r.chunk.filePath, Math.max(existing, r.score));
-      }
-    }
-
-    // Score each cluster by max file similarity
-    const scored: ScoredCluster[] = [];
-    const keywordIds = new Set(keywordResults.map((c) => c.id));
-
-    for (const cluster of allClusters) {
-      // Apply status and file filters
-      if (opts.status && cluster.status !== opts.status) continue;
-      if (opts.file) {
-        const fileTerm = opts.file.toLowerCase();
-        if (
-          !cluster.affectedFiles.some((f) => f.toLowerCase().includes(fileTerm))
-        )
-          continue;
-      }
-
-      let maxScore = 0;
-      for (const file of cluster.affectedFiles) {
-        const s = fileScores.get(file) ?? 0;
-        if (s > maxScore) maxScore = s;
-      }
-
-      // Boost keyword matches
-      if (keywordIds.has(cluster.id)) {
-        maxScore = Math.max(maxScore, 0.5);
-      }
-
-      if (maxScore > 0) {
-        scored.push({ cluster, score: maxScore });
-      }
-    }
-
-    // Sort by score descending
-    scored.sort((a, b) => b.score - a.score);
-
-    if (opts.limit && opts.limit > 0) return scored.slice(0, opts.limit);
-    return scored;
-  }
-
-  /**
-   * Mark a cluster as revived. Returns the ops to replay.
-   */
-  revive(clusterId: string): VcsOp[] | null {
-    const cluster = this.getCluster(clusterId);
-    if (!cluster) return null;
-
-    cluster.status = 'revived';
-    this._revivedIds.add(clusterId);
-    this.invalidate();
-
-    return cluster.ops;
-  }
-
-  /**
-   * Get summary statistics for the garden.
-   */
-  stats(): {
-    total: number;
-    abandoned: number;
-    draft: number;
-    revived: number;
-    totalOps: number;
-    totalFiles: number;
-  } {
-    const clusters = this.listClusters();
-    const allFiles = new Set<string>();
-    let totalOps = 0;
-
-    for (const c of clusters) {
-      totalOps += c.ops.length;
-      for (const f of c.affectedFiles) allFiles.add(f);
-    }
-
-    return {
-      total: clusters.length,
-      abandoned: clusters.filter((c) => c.status === 'abandoned').length,
-      draft: clusters.filter((c) => c.status === 'draft').length,
-      revived: clusters.filter((c) => c.status === 'revived').length,
-      totalOps,
-      totalFiles: allFiles.size,
-    };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Helper: Build milestoned op hash set from ops
-// ---------------------------------------------------------------------------
-
-/**
- * Build a set of op hashes that fall within milestone ranges.
- * Used by the engine to provide GardenContext.getMilestonedOpHashes().
- */
-export function buildMilestonedOpHashes(ops: VcsOp[]): Set<string> {
-  const milestoned = new Set<string>();
-  const milestoneOps = ops.filter((o) => o.kind === 'vcs:milestoneCreate');
-
-  for (const mOp of milestoneOps) {
-    const from = mOp.vcs?.fromOpHash;
-    const to = mOp.vcs?.toOpHash;
-
-    if (!from || !to) continue;
-
-    const fromIdx = ops.findIndex((o) => o.hash === from);
-    const toIdx = ops.findIndex((o) => o.hash === to);
-
-    if (fromIdx >= 0 && toIdx >= 0) {
-      for (let i = fromIdx; i <= toIdx; i++) {
-        milestoned.add(ops[i].hash);
-      }
-    }
-
-    // Also mark the milestone op itself
-    milestoned.add(mOp.hash);
-  }
-
-  return milestoned;
-}

package/src/garden/index.ts

@@ -1,29 +0,0 @@
-/**
- * Idea Garden — Public Surface
- *
- * @module garden
- *
- * Re-exports cluster detection heuristics (context-switch, revert, stale-branch)
- * and the {@link IdeaGarden} query/revive layer.
- *
- * @see DESIGN.md §7 for the full Idea Garden specification.
- */
-
-export {
-  detectClusters,
-  defaultDetectors,
-  contextSwitchDetector,
-  revertDetector,
-  staleBranchDetector,
-} from './cluster.js';
-
-export type { IdeaCluster, ClusterDetector } from './cluster.js';
-
-export { IdeaGarden, buildMilestonedOpHashes } from './garden.js';
-
-export type {
-  ScoredCluster,
-  GardenSearchOpts,
-  GardenContext,
-  GardenEmbedder,
-} from './garden.js';