openclew 0.2.0 → 0.3.0

package/lib/search.js

@@ -0,0 +1,242 @@
+/**
+ * openclew search <query> — search docs by keyword.
+ *
+ * Searches metadata line (category, keywords, type, status) and
+ * L1 fields (subject, doc_brief) across all refdocs and logs.
+ * Returns results sorted by relevance score.
+ *
+ * Zero dependencies — Node 16+ standard library only.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ── Parsers (JS port of generate-index.py) ─────────────────────────
+
+function parseMetadataLine(content) {
+  const meta = {};
+  const firstLine = content.split("\n", 1)[0].trim();
+  if (!firstLine.startsWith("openclew@")) return meta;
+
+  const parts = firstLine.split(" · ");
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith("openclew@")) {
+      meta.version = trimmed.split("@")[1];
+      continue;
+    }
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx > 0) {
+      const key = trimmed.slice(0, colonIdx).trim().toLowerCase();
+      const value = trimmed.slice(colonIdx + 1).trim();
+      meta[key] = value;
+    }
+  }
+  return meta;
+}
+
+function parseL1(content) {
+  const meta = {};
+  const match = content.match(
+    /<!--\s*L1_START\s*-->([\s\S]+?)<!--\s*L1_END\s*-->/
+  );
+  if (!match) return meta;
+
+  const block = match[1];
+  const subjectMatch = block.match(/\*\*subject:\*\*\s*(.+)/);
+  if (subjectMatch) meta.subject = subjectMatch[1].trim();
+
+  const briefMatch = block.match(/\*\*doc_brief:\*\*\s*(.+)/);
+  if (briefMatch) meta.doc_brief = briefMatch[1].trim();
+
+  return meta;
+}
+
+function parseL1Legacy(content) {
+  const meta = {};
+  const match = content.match(
+    /<!--\s*L1_START\s*-->([\s\S]+?)<!--\s*L1_END\s*-->/
+  );
+  if (!match) return meta;
+
+  for (const line of match[1].split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx > 0) {
+      const key = trimmed.slice(0, colonIdx).trim().toLowerCase();
+      const value = trimmed.slice(colonIdx + 1).trim();
+      meta[key] = value;
+    }
+  }
+  return meta;
+}
+
+function parseFile(filepath) {
+  let content;
+  try {
+    content = fs.readFileSync(filepath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const metaLine = parseMetadataLine(content);
+  const l1 = parseL1(content);
+
+  if (l1.subject) {
+    return { ...metaLine, ...l1 };
+  }
+
+  const legacy = parseL1Legacy(content);
+  if (Object.keys(legacy).length) {
+    return { ...metaLine, ...legacy };
+  }
+
+  return null;
+}
+
+// ── Collector ───────────────────────────────────────────────────────
+
+function collectDocs(docDir) {
+  const docs = [];
+
+  // Refdocs: doc/_*.md
+  if (fs.existsSync(docDir)) {
+    for (const entry of fs.readdirSync(docDir).sort()) {
+      if (entry.startsWith("_") && entry.endsWith(".md") && entry !== "_INDEX.md") {
+        const filepath = path.join(docDir, entry);
+        const meta = parseFile(filepath);
+        if (meta) docs.push({ filepath, filename: entry, kind: "refdoc", meta });
+      }
+    }
+  }
+
+  // Logs: doc/log/*.md
+  const logDir = path.join(docDir, "log");
+  if (fs.existsSync(logDir)) {
+    for (const entry of fs.readdirSync(logDir).sort().reverse()) {
+      if (entry.endsWith(".md")) {
+        const filepath = path.join(logDir, entry);
+        const meta = parseFile(filepath);
+        if (meta) docs.push({ filepath, filename: entry, kind: "log", meta });
+      }
+    }
+  }
+
+  return docs;
+}
+
+// ── Search engine ───────────────────────────────────────────────────
+
+/**
+ * Score a document against query terms.
+ * Higher score = more relevant.
+ *
+ * Weights: subject (3), doc_brief (2), keywords (2), category (1.5), type (1), status (0.5)
+ */
+function scoreDoc(doc, queryTerms) {
+  const fields = [
+    { value: doc.meta.subject || "", weight: 3 },
+    { value: doc.meta.doc_brief || "", weight: 2 },
+    { value: doc.meta.keywords || "", weight: 2 },
+    { value: doc.meta.category || "", weight: 1.5 },
+    { value: doc.meta.type || "", weight: 1 },
+    { value: doc.meta.status || "", weight: 0.5 },
+  ];
+
+  let score = 0;
+  for (const term of queryTerms) {
+    const termLower = term.toLowerCase();
+    for (const field of fields) {
+      const valueLower = field.value.toLowerCase();
+      if (valueLower.includes(termLower)) {
+        score += field.weight;
+        // Bonus for exact word match (not substring)
+        if (new RegExp(`\\b${termLower.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(field.value)) {
+          score += field.weight * 0.5;
+        }
+      }
+    }
+  }
+  return score;
+}
+
+/**
+ * Search docs matching query. Returns sorted results.
+ *
+ * @param {string} docDir - Path to doc/ directory
+ * @param {string} query - Search query (space-separated terms, AND logic)
+ * @returns {Array<{filepath, filename, kind, meta, score}>}
+ */
+function searchDocs(docDir, query) {
+  const docs = collectDocs(docDir);
+  const queryTerms = query.trim().split(/\s+/).filter(Boolean);
+  if (!queryTerms.length) return [];
+
+  const results = [];
+  for (const doc of docs) {
+    const score = scoreDoc(doc, queryTerms);
+    if (score > 0) {
+      results.push({ ...doc, score });
+    }
+  }
+
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}
+
+// ── CLI runner ──────────────────────────────────────────────────────
+
+function run() {
+  const args = process.argv.slice(2);
+  const cmdIndex = args.indexOf("search");
+  const queryArgs = cmdIndex >= 0 ? args.slice(cmdIndex + 1) : args.slice(1);
+  const query = queryArgs.join(" ");
+
+  if (!query) {
+    console.error('Usage: openclew search <query>');
+    console.error('');
+    console.error('Examples:');
+    console.error('  openclew search auth          # find docs about authentication');
+    console.error('  openclew search "API design"   # multi-word search');
+    process.exit(1);
+  }
+
+  const projectRoot = process.cwd();
+  const docDir = path.join(projectRoot, "doc");
+  if (!fs.existsSync(docDir)) {
+    console.error("No doc/ directory found. Run 'openclew init' first.");
+    process.exit(1);
+  }
+
+  const results = searchDocs(docDir, query);
+
+  if (!results.length) {
+    console.log(`No docs matching "${query}".`);
+    process.exit(0);
+  }
+
+  console.log(`Found ${results.length} doc${results.length > 1 ? "s" : ""} matching "${query}":\n`);
+
+  for (const r of results) {
+    const relPath = path.relative(projectRoot, r.filepath);
+    const icon = r.kind === "refdoc" ? "📘" : "📝";
+    const subject = r.meta.subject || r.filename;
+    const brief = r.meta.doc_brief || "";
+    const status = r.meta.status ? ` [${r.meta.status}]` : "";
+
+    console.log(`${icon} ${subject}${status}`);
+    console.log(`   ${relPath}`);
+    if (brief) console.log(`   ${brief}`);
+    console.log("");
+  }
+}
+
+// Export for MCP server + tests
+module.exports = { searchDocs, collectDocs, parseFile, parseMetadataLine, parseL1, parseL1Legacy };
+
+// Run as CLI (invoked via dispatcher or directly)
+const calledAsSearch = process.argv.includes("search");
+if (require.main === module || calledAsSearch) {
+  run();
+}

package/lib/status.js

@@ -0,0 +1,151 @@
+/**
+ * openclew status — documentation health dashboard.
+ *
+ * Shows stats, docs missing doc_brief, stale docs, and distribution.
+ * Zero dependencies — Node 16+ standard library only.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { collectDocs, parseFile } = require("./search");
+const { parseLegacyDoc } = require("./migrate");
+
+function run() {
+  const projectRoot = process.cwd();
+  const docDir = path.join(projectRoot, "doc");
+
+  if (!fs.existsSync(docDir)) {
+    console.error("No doc/ directory found. Run 'openclew init' first.");
+    process.exit(1);
+  }
+
+  const docs = collectDocs(docDir);
+  const refdocs = docs.filter((d) => d.kind === "refdoc");
+  const logs = docs.filter((d) => d.kind === "log");
+
+  // ── Overview ──────────────────────────────────────────────────
+  console.log("openclew status\n");
+  console.log(`  Refdocs: ${refdocs.length}`);
+  console.log(`  Logs:    ${logs.length}`);
+  console.log(`  Total:   ${docs.length}`);
+  console.log("");
+
+  // ── Legacy format detection ──────────────────────────────────
+  let legacyCount = 0;
+  for (const d of docs) {
+    try {
+      const content = fs.readFileSync(d.filepath, "utf-8");
+      const parsed = parseLegacyDoc(content);
+      if (parsed.isLegacy) legacyCount++;
+    } catch {}
+  }
+  if (legacyCount > 0) {
+    console.log(`Legacy format: ${legacyCount} docs need migration`);
+    console.log(`  Run 'openclew migrate' to preview, 'openclew migrate --write' to apply.\n`);
+  }
+
+  // ── Missing doc_brief ─────────────────────────────────────────
+  const missingBrief = docs.filter(
+    (d) => !d.meta.doc_brief || d.meta.doc_brief === ""
+  );
+  if (missingBrief.length) {
+    console.log(`Missing doc_brief (${missingBrief.length}):`);
+    for (const d of missingBrief) {
+      const relPath = path.relative(projectRoot, d.filepath);
+      const subject = d.meta.subject || d.filename;
+      console.log(`  - ${relPath}  (${subject})`);
+    }
+    console.log("");
+  }
+
+  // ── Missing subject ───────────────────────────────────────────
+  const missingSubject = docs.filter(
+    (d) => !d.meta.subject || d.meta.subject === ""
+  );
+  if (missingSubject.length) {
+    console.log(`Missing subject (${missingSubject.length}):`);
+    for (const d of missingSubject) {
+      const relPath = path.relative(projectRoot, d.filepath);
+      console.log(`  - ${relPath}`);
+    }
+    console.log("");
+  }
+
+  // ── Stale refdocs (updated > 30 days ago) ─────────────────────
+  const now = new Date();
+  const staleThresholdMs = 30 * 24 * 60 * 60 * 1000;
+  const staleRefdocs = refdocs.filter((d) => {
+    const updated = d.meta.updated || d.meta.created;
+    if (!updated) return true; // No date = stale
+    const docDate = new Date(updated);
+    return !isNaN(docDate.getTime()) && now - docDate > staleThresholdMs;
+  });
+  if (staleRefdocs.length) {
+    console.log(`Stale refdocs (not updated in 30+ days): ${staleRefdocs.length}`);
+    for (const d of staleRefdocs) {
+      const relPath = path.relative(projectRoot, d.filepath);
+      const updated = d.meta.updated || d.meta.created || "no date";
+      const subject = d.meta.subject || d.filename;
+      console.log(`  - ${relPath}  (${subject}, last: ${updated})`);
+    }
+    console.log("");
+  }
+
+  // ── Status distribution ───────────────────────────────────────
+  const statusCounts = {};
+  for (const d of docs) {
+    const st = d.meta.status || "—";
+    statusCounts[st] = (statusCounts[st] || 0) + 1;
+  }
+  const statusEntries = Object.entries(statusCounts).sort((a, b) => b[1] - a[1]);
+  if (statusEntries.length) {
+    console.log("Status distribution:");
+    for (const [status, count] of statusEntries) {
+      console.log(`  ${status}: ${count}`);
+    }
+    console.log("");
+  }
+
+  // ── Category distribution ─────────────────────────────────────
+  const catCounts = {};
+  for (const d of docs) {
+    const cat = d.meta.category || "—";
+    if (cat && cat !== "—") catCounts[cat] = (catCounts[cat] || 0) + 1;
+  }
+  const catEntries = Object.entries(catCounts).sort((a, b) => b[1] - a[1]);
+  if (catEntries.length) {
+    console.log("Category distribution:");
+    for (const [cat, count] of catEntries) {
+      console.log(`  ${cat}: ${count}`);
+    }
+    console.log("");
+  }
+
+  // ── Health score ──────────────────────────────────────────────
+  const total = docs.length;
+  if (total === 0) {
+    console.log("Health: no docs yet. Run 'openclew new' to create one.");
+    return;
+  }
+
+  const withBrief = total - missingBrief.length;
+  const withSubject = total - missingSubject.length;
+  const freshRefdocs = refdocs.length - staleRefdocs.length;
+  const healthPct = Math.round(
+    ((withBrief + withSubject + freshRefdocs) /
+      (total + total + Math.max(refdocs.length, 1))) *
+      100
+  );
+
+  console.log(`Health: ${healthPct}%`);
+  if (healthPct === 100) {
+    console.log("  All docs have subject + doc_brief, no stale refdocs.");
+  }
+}
+
+module.exports = { run };
+
+const calledAsStatus = process.argv.includes("status");
+if (require.main === module || calledAsStatus) {
+  run();
+}