oh-my-llmwikimode 1.0.0

package/src/wiki/lesson-proposal-analyzer.js

@@ -0,0 +1,463 @@
+/**
+ * B1 Auto Lesson Proposal — Usage Event Analyzer
+ *
+ * Analyzes usage event logs to detect repeated patterns
+ * and generates lesson proposal artifacts.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { listUsageEventFiles, readUsageEvents, USAGE_EVENTS } from "./usage-events.js";
+import { getWikiPaths, ensureWikiStructure } from "./store.js";
+
+export const PROPOSAL_VERSION = 1;
+export const PROPOSAL_DIR = ".system/lesson-proposals";
+
+// Minimum thresholds for generating proposals
+const MIN_QUERY_REPEATS = 2;
+const MIN_ENTRY_REPEATS = 2;
+const MIN_SEARCH_RESULT_USED = 3;
+const MAX_ANALYSIS_DAYS = 30;
+const MAX_PROPOSALS = 100;
+
+function hashString(input) {
+  return crypto.createHash("sha256").update(String(input)).digest("hex").slice(0, 16);
+}
+
+function compareStrings(left, right) {
+  return String(left ?? "").localeCompare(String(right ?? ""));
+}
+
+function ensureProposalDir(wikiRoot) {
+  const dir = path.join(wikiRoot, PROPOSAL_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function dedupKeysForPatternType(type, queryHashes = [], entryPaths = []) {
+  if (type === "repeated_query") {
+    return [...queryHashes]
+      .filter(Boolean)
+      .sort(compareStrings)
+      .map((queryHash) => "query:" + queryHash);
+  }
+
+  if (type === "repeated_entry") {
+    return [...entryPaths]
+      .filter(Boolean)
+      .sort(compareStrings)
+      .map((entryPath) => "entry:" + entryPath);
+  }
+
+  return [];
+}
+
+function dedupKeysForProposal(content) {
+  const evidence = content?.evidence || {};
+  const queryHashes = evidence.query_hashes || content?.query_hashes || [];
+  const entryPaths = evidence.entry_paths || [];
+  const patternType = content?.pattern_type || content?.type;
+  const typedKeys = dedupKeysForPatternType(patternType, queryHashes, entryPaths);
+
+  if (typedKeys.length > 0) return typedKeys;
+
+  // Legacy proposals did not store pattern_type. Index all stable keys so
+  // already-created proposals remain duplicate-protected after upgrading.
+  return [
+    ...dedupKeysForPatternType("repeated_query", queryHashes, entryPaths),
+    ...dedupKeysForPatternType("repeated_entry", queryHashes, entryPaths),
+  ];
+}
+
+function dedupKeyForPattern(pattern) {
+  const evidence = pattern?.evidence || {};
+  const queryHashes = pattern?.query_hash
+    ? [pattern.query_hash]
+    : (pattern?.query_hashes || evidence.query_hashes || []);
+  const entryPaths = pattern?.entry_path
+    ? [pattern.entry_path]
+    : (evidence.entry_paths || []);
+
+  return dedupKeysForPatternType(pattern?.type, queryHashes, entryPaths)[0] || "";
+}
+
+function listExistingProposals(wikiRoot) {
+  const dir = path.join(wikiRoot, PROPOSAL_DIR);
+  if (!fs.existsSync(dir)) return new Map();
+
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  const existing = new Map();
+
+  for (const file of files) {
+    try {
+      const content = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+      for (const key of dedupKeysForProposal(content)) {
+        existing.set(key, content.id);
+      }
+    } catch {
+      // Skip malformed
+    }
+  }
+
+  return existing;
+}
+
+function countProposals(wikiRoot) {
+  const dir = path.join(wikiRoot, PROPOSAL_DIR);
+  if (!fs.existsSync(dir)) return 0;
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".json")).length;
+}
+
+function dateKeyFromUsageFile(fileName) {
+  const match = /^(\d{4}-\d{2}-\d{2})\.jsonl$/.exec(fileName);
+  return match ? match[1] : "";
+}
+
+function deriveUsageEventAnchor(wikiRoot) {
+  let latestTimestamp = "";
+  let latestEventFileDate = "";
+
+  for (const fileName of listUsageEventFiles(wikiRoot)) {
+    const dateKey = dateKeyFromUsageFile(fileName);
+    if (!dateKey) continue;
+
+    const result = readUsageEvents(wikiRoot, dateKey + "T00:00:00.000Z");
+    if (!result.success || !Array.isArray(result.events) || result.events.length === 0) {
+      continue;
+    }
+
+    if (compareStrings(dateKey, latestEventFileDate) > 0) {
+      latestEventFileDate = dateKey;
+    }
+
+    for (const event of result.events) {
+      const timestamp = String(event.ts || "");
+      if (
+        timestamp
+        && !Number.isNaN(new Date(timestamp).getTime())
+        && compareStrings(timestamp, latestTimestamp) > 0
+      ) {
+        latestTimestamp = timestamp;
+      }
+    }
+  }
+
+  if (latestTimestamp) return new Date(latestTimestamp);
+  if (latestEventFileDate) return new Date(latestEventFileDate + "T00:00:00.000Z");
+  return null;
+}
+
+/**
+ * Read all usage events from the last N days.
+ *
+ * Deterministic: same anchor + same events = same result.
+ * If options.now is omitted, the anchor is derived from the latest usage event.
+ * If no events exist, there is no deterministic anchor and the result is empty.
+ */
+export function readAllUsageEvents(wikiRoot, options = {}) {
+  const days = Math.min(options.days ?? MAX_ANALYSIS_DAYS, MAX_ANALYSIS_DAYS);
+  const anchor = options.now ? new Date(options.now) : deriveUsageEventAnchor(wikiRoot);
+  if (!anchor) return [];
+
+  const allEvents = [];
+  for (let i = 0; i < days; i++) {
+    const date = new Date(anchor);
+    date.setUTCDate(date.getUTCDate() - i);
+    const result = readUsageEvents(wikiRoot, date);
+    if (result.success && Array.isArray(result.events)) {
+      allEvents.push(...result.events);
+    }
+  }
+
+  // Sort by timestamp for deterministic processing
+  allEvents.sort((a, b) => compareStrings(a.ts, b.ts));
+
+  return allEvents;
+}
+
+/**
+ * Generate a deterministic proposal ID from stable evidence.
+ * Uses evidence content (query hashes + entry paths + timestamps) rather than wall clock
+ * so the same usage pattern always produces the same ID.
+ */
+export function generateProposalId(evidence) {
+  const hashes = [...(evidence.query_hashes || [])].sort(compareStrings).join("|");
+  const entries = [...(evidence.entry_paths || [])].sort(compareStrings).join("|");
+  const input = `${hashes}::${entries}::${evidence.first_seen || ""}::${evidence.last_seen || ""}`;
+  return "lp_" + hashString(input);
+}
+
+/**
+ * Extract a suggested title from query hashes and entry paths.
+ */
+function suggestTitle(evidence) {
+  const { query_hashes, entry_paths } = evidence;
+
+  // Try to extract from entry paths first
+  if (entry_paths?.length > 0) {
+    const entry = entry_paths[0];
+    const basename = path.basename(entry, ".md");
+    // Remove date prefix if present
+    const clean = basename.replace(/^\d{4}-\d{2}-\d{2}[-T]/, "").replace(/-/g, " ");
+    if (clean) return clean.charAt(0).toUpperCase() + clean.slice(1);
+  }
+
+  // Fallback to query hash abbreviation
+  if (query_hashes?.length > 0) {
+    return `Lesson Proposal ${query_hashes[0].slice(0, 8)}`;
+  }
+
+  return "Lesson Proposal";
+}
+
+/**
+ * Build a proposal artifact from a detected pattern.
+ *
+ * Deterministic: same pattern evidence always produces the same artifact
+ * (same ID, same created_at, same all fields).
+ * created_at defaults to evidence.last_seen so identical usage events
+ * always produce identical artifacts regardless of analysis execution time.
+ * options.now is accepted only as an explicit override for testing or replay
+ * when evidence timestamps are unavailable.
+ */
+export function buildProposalArtifact(pattern, index, options = {}) {
+  const id = generateProposalId(pattern.evidence);
+  // Default to evidence timestamps for determinism.
+  // options.now is a last-resort fallback when evidence lacks timestamps.
+  const createdAt = pattern.evidence?.last_seen
+    || pattern.evidence?.first_seen
+    || (options.now ? new Date(options.now).toISOString() : "");
+
+  return {
+    version: PROPOSAL_VERSION,
+    id,
+    pattern_type: pattern.type || "unknown",
+    status: "review_required",
+    action: "consider_lesson",
+    proposed_title: suggestTitle(pattern.evidence),
+    evidence: pattern.evidence,
+    template_sections: pattern.template_sections || {
+      when_to_use: "_(Auto-generated: fill in context for when this lesson applies)_",
+      principles: "_(Auto-generated: fill in key principles)_",
+      checklist: ["_(Auto-generated: add checklist items)_"],
+      examples: "_(Auto-generated: add examples)_",
+      failure_patterns: "_(Auto-generated: add failure patterns)_",
+    },
+    auto_apply: false,
+    review_required: true,
+    created_at: createdAt,
+  };
+}
+
+/**
+ * Analyze usage events for repeated patterns.
+ */
+export function analyzeUsagePatterns(wikiRoot, options = {}) {
+  const events = readAllUsageEvents(wikiRoot, options);
+
+  if (events.length === 0) {
+    return {
+      success: true,
+      patterns: [],
+      total_events_analyzed: 0,
+      date_range: null,
+      proposals_generated: 0,
+    };
+  }
+
+  // Count occurrences
+  const queryCounts = new Map();
+  const entryCounts = new Map();
+  const queryEntries = new Map(); // query_hash -> Set of entry_paths
+
+  for (const event of events) {
+    const queryHash = event.query_hash;
+    const entryPath = event.entry_path;
+    const eventType = event.event;
+
+    if (queryHash) {
+      queryCounts.set(queryHash, (queryCounts.get(queryHash) || 0) + 1);
+      if (!queryEntries.has(queryHash)) queryEntries.set(queryHash, new Set());
+      if (entryPath) queryEntries.get(queryHash).add(entryPath);
+    }
+
+    if (entryPath) {
+      entryCounts.set(entryPath, (entryCounts.get(entryPath) || 0) + 1);
+    }
+  }
+
+  const patterns = [];
+  const seenQueryKeys = new Set();
+
+  // Detect repeated queries
+  for (const [queryHash, count] of queryCounts) {
+    if (count >= MIN_QUERY_REPEATS) {
+      const entries = [...(queryEntries.get(queryHash) || [])].sort(compareStrings);
+      const key = queryHash;
+
+      if (!seenQueryKeys.has(key)) {
+        seenQueryKeys.add(key);
+        patterns.push({
+          type: "repeated_query",
+          query_hash: queryHash,
+          query_hashes: [queryHash],
+          count,
+          related_entries: entries,
+          confidence: count >= MIN_SEARCH_RESULT_USED ? "high" : "medium",
+          evidence: {
+            query_hashes: [queryHash],
+            entry_paths: entries,
+            usage_count: count,
+            first_seen: events.find((e) => e.query_hash === queryHash)?.ts || "",
+            last_seen: [...events].reverse().find((e) => e.query_hash === queryHash)?.ts || "",
+          },
+        });
+      }
+    }
+  }
+
+  // Detect repeated entry references
+  for (const [entryPath, count] of entryCounts) {
+    if (count >= MIN_ENTRY_REPEATS) {
+      const relatedQueries = [...queryCounts.keys()].filter((q) => {
+        const entries = queryEntries.get(q);
+        return entries?.has(entryPath);
+      }).sort(compareStrings);
+
+      const key = `entry:${entryPath}`;
+      if (!seenQueryKeys.has(key)) {
+        seenQueryKeys.add(key);
+        patterns.push({
+          type: "repeated_entry",
+          entry_path: entryPath,
+          count,
+          related_queries: relatedQueries,
+          confidence: "medium",
+          evidence: {
+            query_hashes: relatedQueries,
+            entry_paths: [entryPath],
+            usage_count: count,
+            first_seen: events.find((e) => e.entry_path === entryPath)?.ts || "",
+            last_seen: [...events].reverse().find((e) => e.entry_path === entryPath)?.ts || "",
+          },
+        });
+      }
+    }
+  }
+
+  // Detect high-usage search_result_used events
+  // Instead of creating a duplicate pattern, upgrade repeated_query confidence to "high"
+  const searchResultCounts = new Map();
+  for (const event of events) {
+    if (event.event === USAGE_EVENTS.SEARCH_RESULT_USED && event.query_hash) {
+      searchResultCounts.set(event.query_hash, (searchResultCounts.get(event.query_hash) || 0) + 1);
+    }
+  }
+
+  for (const [queryHash, count] of searchResultCounts) {
+    if (count >= MIN_SEARCH_RESULT_USED) {
+      // Find the existing repeated_query pattern and upgrade its confidence
+      const existingPattern = patterns.find((p) => p.type === "repeated_query" && p.query_hash === queryHash);
+      if (existingPattern) {
+        existingPattern.confidence = "high";
+      }
+      // If there is no repeated_query (e.g. only search_result_used events),
+      // create one with high confidence instead of a separate high_usage_search pattern
+      if (!existingPattern) {
+        const key = queryHash;
+        if (!seenQueryKeys.has(key)) {
+          seenQueryKeys.add(key);
+          const entries = [...(queryEntries.get(queryHash) || [])].sort(compareStrings);
+          patterns.push({
+            type: "repeated_query",
+            query_hash: queryHash,
+            query_hashes: [queryHash],
+            count,
+            related_entries: entries,
+            confidence: "high",
+            evidence: {
+              query_hashes: [queryHash],
+              entry_paths: entries,
+              usage_count: count,
+              first_seen: events.find((e) => e.query_hash === queryHash)?.ts || "",
+              last_seen: [...events].reverse().find((e) => e.query_hash === queryHash)?.ts || "",
+            },
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    success: true,
+    patterns,
+    total_events_analyzed: events.length,
+    date_range: {
+      from: events[0]?.ts || "",
+      to: events[events.length - 1]?.ts || "",
+    },
+  };
+}
+
+/**
+ * Generate and save lesson proposals from usage patterns.
+ */
+export function generateLessonProposals(wikiRoot, options = {}) {
+  try {
+    const paths = getWikiPaths(wikiRoot);
+    ensureWikiStructure(paths);
+    ensureProposalDir(wikiRoot);
+
+    const analysis = analyzeUsagePatterns(wikiRoot, options);
+    if (!analysis.success) return analysis;
+
+    const existingProposals = listExistingProposals(wikiRoot);
+    const currentCount = countProposals(wikiRoot);
+    let generated = 0;
+    let skipped = 0;
+
+    // Track in-memory IDs within this run to prevent same-run collisions
+    const generatedThisRun = new Set();
+
+    for (let i = 0; i < analysis.patterns.length; i++) {
+      if (currentCount + generated >= MAX_PROPOSALS) break;
+
+      const pattern = analysis.patterns[i];
+      const dedupKey = dedupKeyForPattern(pattern);
+      if (!dedupKey) {
+        skipped++;
+        continue;
+      }
+
+      // Skip if already proposed (on disk or in this run)
+      if (existingProposals.has(dedupKey) || generatedThisRun.has(dedupKey)) {
+        skipped++;
+        continue;
+      }
+
+      const proposal = buildProposalArtifact(pattern, i, options);
+      const filePath = path.join(wikiRoot, PROPOSAL_DIR, `${proposal.id}.json`);
+
+      // NEVER overwrite an existing proposal file (preserves applied/rejected status)
+      if (fs.existsSync(filePath)) {
+        skipped++;
+        continue;
+      }
+
+      fs.writeFileSync(filePath, JSON.stringify(proposal, null, 2), "utf-8");
+      generated++;
+      generatedThisRun.add(dedupKey);
+    }
+
+    return {
+      success: true,
+      proposals_generated: generated,
+      proposals_skipped: skipped,
+      total_patterns: analysis.patterns.length,
+      total_events: analysis.total_events_analyzed,
+    };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}