@comfanion/usethis_search 0.2.0-dev.0 → 3.0.0-dev.1

package/vectorizer/usage-tracker.ts

@@ -0,0 +1,204 @@
+/**
+ * Usage Tracker — records provenance and usage statistics for chunks.
+ *
+ * FR-060: Record provenance for each attached chunk {query, main_chunk_id, attached_via_edge_type}
+ * FR-061: Increment usage_count when chunk appears in search results
+ * FR-062: API to query "where is chunk X used?" → list of referencing chunks
+ * FR-063: Use usage_count as additional ranking signal
+ *
+ * Storage: JSON file at .opencode/vectors/<index>/usage-stats.json
+ * Updated asynchronously (non-blocking to search).
+ */
+
+import fs from "fs/promises"
+import path from "path"
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ProvenanceRecord {
+  /** The search query that triggered this attachment */
+  query: string
+  /** The main result chunk that caused context attachment */
+  mainChunkId: string
+  /** The edge type that linked main → attached chunk */
+  edgeType: string
+  /** Timestamp */
+  timestamp: number
+}
+
+export interface ChunkUsageStats {
+  /** How many times this chunk appeared in search results (main or attached) */
+  usageCount: number
+  /** Last time this chunk was returned in a search result */
+  lastUsed: number
+  /** Recent provenance records (max 20 per chunk to limit storage) */
+  provenance: ProvenanceRecord[]
+}
+
+export interface UsageData {
+  /** Per-chunk usage statistics, keyed by chunk_id */
+  chunks: Record<string, ChunkUsageStats>
+  /** Global counters */
+  totalSearches: number
+  lastUpdated: number
+}
+
+const MAX_PROVENANCE_PER_CHUNK = 20
+
+// ---------------------------------------------------------------------------
+// UsageTracker
+// ---------------------------------------------------------------------------
+
+export class UsageTracker {
+  private data: UsageData | null = null
+  private dirty = false
+  private savePath: string
+
+  constructor(private cacheDir: string) {
+    this.savePath = path.join(cacheDir, "usage-stats.json")
+  }
+
+  // ---- lifecycle ----------------------------------------------------------
+
+  async load(): Promise<void> {
+    try {
+      const raw = await fs.readFile(this.savePath, "utf-8")
+      this.data = JSON.parse(raw)
+    } catch {
+      this.data = { chunks: {}, totalSearches: 0, lastUpdated: Date.now() }
+    }
+  }
+
+  async save(): Promise<void> {
+    if (!this.dirty || !this.data) return
+    this.data.lastUpdated = Date.now()
+    try {
+      await fs.mkdir(path.dirname(this.savePath), { recursive: true })
+      await fs.writeFile(this.savePath, JSON.stringify(this.data, null, 2), "utf-8")
+      this.dirty = false
+    } catch {
+      // non-fatal
+    }
+  }
+
+  // ---- FR-060: record provenance ------------------------------------------
+
+  /**
+   * Record that `attachedChunkId` was attached to `mainChunkId` as context
+   * for `query`, via `edgeType` relation.
+   */
+  recordProvenance(
+    query: string,
+    mainChunkId: string,
+    attachedChunkId: string,
+    edgeType: string,
+  ): void {
+    if (!this.data) return
+    const stats = this.ensureChunkStats(attachedChunkId)
+    stats.provenance.push({
+      query,
+      mainChunkId,
+      edgeType,
+      timestamp: Date.now(),
+    })
+    // Cap provenance history
+    if (stats.provenance.length > MAX_PROVENANCE_PER_CHUNK) {
+      stats.provenance = stats.provenance.slice(-MAX_PROVENANCE_PER_CHUNK)
+    }
+    this.dirty = true
+  }
+
+  // ---- FR-061: increment usage_count --------------------------------------
+
+  /**
+   * Record that these chunk IDs appeared in search results.
+   * Call once per search with all result chunk IDs (main + attached).
+   */
+  recordSearchResults(chunkIds: string[]): void {
+    if (!this.data) return
+    this.data.totalSearches++
+    const now = Date.now()
+    for (const id of chunkIds) {
+      const stats = this.ensureChunkStats(id)
+      stats.usageCount++
+      stats.lastUsed = now
+    }
+    this.dirty = true
+  }
+
+  // ---- FR-062: "where is chunk X used?" -----------------------------------
+
+  /**
+   * Get provenance info for a chunk: which queries led to it,
+   * which main chunks it was attached to, via which edges.
+   */
+  getChunkProvenance(chunkId: string): ProvenanceRecord[] {
+    if (!this.data) return []
+    return this.data.chunks[chunkId]?.provenance ?? []
+  }
+
+  /**
+   * Get usage stats for a chunk.
+   */
+  getChunkStats(chunkId: string): ChunkUsageStats | null {
+    if (!this.data) return null
+    return this.data.chunks[chunkId] ?? null
+  }
+
+  // ---- FR-063: usage_count as ranking signal ------------------------------
+
+  /**
+   * Get usage count for a chunk (0 if never seen).
+   * Used as additional ranking signal in search.
+   */
+  getUsageCount(chunkId: string): number {
+    if (!this.data) return 0
+    return this.data.chunks[chunkId]?.usageCount ?? 0
+  }
+
+  /**
+   * Get a usage boost factor for ranking (0.0 – 1.0).
+   * Normalized: most-used chunk → 1.0, unused → 0.0.
+   */
+  getUsageBoost(chunkId: string): number {
+    if (!this.data) return 0
+    const stats = this.data.chunks[chunkId]
+    if (!stats || stats.usageCount === 0) return 0
+
+    // Find max usage count across all chunks for normalization
+    let maxUsage = 1
+    for (const s of Object.values(this.data.chunks)) {
+      if (s.usageCount > maxUsage) maxUsage = s.usageCount
+    }
+    return stats.usageCount / maxUsage
+  }
+
+  // ---- summary ------------------------------------------------------------
+
+  /**
+   * Get global usage summary.
+   */
+  getSummary(): { totalSearches: number; trackedChunks: number; lastUpdated: number } {
+    if (!this.data) return { totalSearches: 0, trackedChunks: 0, lastUpdated: 0 }
+    return {
+      totalSearches: this.data.totalSearches,
+      trackedChunks: Object.keys(this.data.chunks).length,
+      lastUpdated: this.data.lastUpdated,
+    }
+  }
+
+  // ---- internals ----------------------------------------------------------
+
+  private ensureChunkStats(chunkId: string): ChunkUsageStats {
+    if (!this.data!.chunks[chunkId]) {
+      this.data!.chunks[chunkId] = {
+        usageCount: 0,
+        lastUsed: 0,
+        provenance: [],
+      }
+    }
+    return this.data!.chunks[chunkId]
+  }
+}

package/vectorizer.yaml

@@ -39,6 +39,20 @@ vectorizer:
     hybrid: false          # Enable hybrid search (vector + BM25)
     bm25_weight: 0.3       # BM25 weight in hybrid mode (0.0-1.0)
 
+  # Graph-based context (v3)
+  graph:
+    enabled: true
+    max_related: 3           # How many related chunks to attach
+    min_relevance: 0.5       # Minimum score threshold for related context
+
+    # LSP for code analysis
+    lsp:
+      enabled: true
+      timeout_ms: 5000       # Timeout per file
+
+    # Read() intercept
+    read_intercept: true
+
   # Quality monitoring (v2)
   quality:
     enable_metrics: false   # Track search quality metrics