hypomnema 1.0.0

package/scripts/graph.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * Hypomnema graph script
+ *
+ * Generates a wikilink dependency graph from wiki pages.
+ * Outputs adjacency list (default) or Mermaid diagram.
+ *
+ * Usage:
+ *   node scripts/graph.mjs [options]
+ *
+ * Options:
+ *   --hypo-dir=<path>   Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
+ *   --format=<fmt>      Output format: json | mermaid | dot  (default: json)
+ *   --min-edges=<n>     Only include nodes with at least N edges (default: 0)
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative, extname, basename } from 'path';
+import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
+
+// ── arg parsing ───────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { hypoDir: null, format: 'json', minEdges: 0 };
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith('--hypo-dir='))  args.hypoDir  = expandHome(arg.slice(11));
+    else if (arg.startsWith('--format='))   args.format   = arg.slice(9);
+    else if (arg.startsWith('--min-edges=')) args.minEdges = parseInt(arg.slice(12), 10) || 0;
+  }
+  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  return args;
+}
+
+// ── page collector ────────────────────────────────────────────────────────────
+
+function collectPages(dir, root, pages = [], ignorePatterns = []) {
+  if (!existsSync(dir)) return pages;
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (isIgnored(full, root, ignorePatterns)) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      collectPages(full, root, pages, ignorePatterns);
+    } else if (extname(entry) === '.md' && !entry.startsWith('.')) {
+      const slug = relative(root, full).replace(/\.md$/, '').replace(/\\/g, '/');
+      pages.push({ path: full, slug, bare: basename(full, '.md') });
+    }
+  }
+  return pages;
+}
+
+// ── slug resolver ─────────────────────────────────────────────────────────────
+
+function buildSlugIndex(pages) {
+  const index = new Map();
+  for (const p of pages) {
+    index.set(p.slug, p.slug);
+    if (!index.has(p.bare)) index.set(p.bare, p.slug);
+  }
+  return index;
+}
+
+// ── wikilink extractor ────────────────────────────────────────────────────────
+
+function extractWikilinks(content) {
+  const links = [];
+  for (const m of content.matchAll(/\[\[([^\]|#]+?)(?:[|#][^\]]*?)?\]\]/g)) {
+    links.push(m[1].trim());
+  }
+  return links;
+}
+
+// ── graph builder ─────────────────────────────────────────────────────────────
+
+function buildGraph(pages, slugIndex) {
+  const edges = [];
+  const inDegree  = new Map();
+  const outDegree = new Map();
+
+  for (const p of pages) {
+    inDegree.set(p.slug, 0);
+    outDegree.set(p.slug, 0);
+  }
+
+  for (const p of pages) {
+    let content;
+    try { content = readFileSync(p.path, 'utf-8'); } catch { continue; }
+    for (const link of extractWikilinks(content)) {
+      const target = slugIndex.get(link);
+      if (target && target !== p.slug) {
+        edges.push({ from: p.slug, to: target });
+        outDegree.set(p.slug, (outDegree.get(p.slug) || 0) + 1);
+        inDegree.set(target, (inDegree.get(target) || 0) + 1);
+      }
+    }
+  }
+
+  return { edges, inDegree, outDegree };
+}
+
+// ── label escapers ────────────────────────────────────────────────────────────
+
+function escapeMermaid(s) { return s.replace(/"/g, '#quot;'); }
+function escapeDot(s)     { return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"'); }
+
+// ── formatters ────────────────────────────────────────────────────────────────
+
+function formatJson(pages, graph, minEdges) {
+  const nodes = pages
+    .map(p => ({
+      slug: p.slug,
+      in: graph.inDegree.get(p.slug) || 0,
+      out: graph.outDegree.get(p.slug) || 0,
+    }))
+    .filter(n => minEdges === 0 || n.in + n.out >= minEdges)
+    .sort((a, b) => (b.in + b.out) - (a.in + a.out));
+
+  const edges = graph.edges.filter(e => {
+    const fn = nodes.find(n => n.slug === e.from);
+    const tn = nodes.find(n => n.slug === e.to);
+    return fn && tn;
+  });
+
+  return JSON.stringify({ nodes, edges }, null, 2);
+}
+
+function formatMermaid(pages, graph, minEdges) {
+  const activeNodes = new Set(
+    pages
+      .filter(p => {
+        const total = (graph.inDegree.get(p.slug) || 0) + (graph.outDegree.get(p.slug) || 0);
+        return total >= minEdges;
+      })
+      .map(p => p.slug)
+  );
+
+  const lines = ['graph TD'];
+  for (const { from, to } of graph.edges) {
+    if (activeNodes.has(from) && activeNodes.has(to)) {
+      const f = from.replace(/[^a-zA-Z0-9_]/g, '_');
+      const t = to.replace(/[^a-zA-Z0-9_]/g, '_');
+      lines.push(`  ${f}["${escapeMermaid(from)}"] --> ${t}["${escapeMermaid(to)}"]`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function formatDot(pages, graph, minEdges) {
+  const activeNodes = new Set(
+    pages
+      .filter(p => {
+        const total = (graph.inDegree.get(p.slug) || 0) + (graph.outDegree.get(p.slug) || 0);
+        return total >= minEdges;
+      })
+      .map(p => p.slug)
+  );
+
+  const lines = ['digraph wiki {', '  rankdir=LR;'];
+  for (const { from, to } of graph.edges) {
+    if (activeNodes.has(from) && activeNodes.has(to)) {
+      lines.push(`  "${escapeDot(from)}" -> "${escapeDot(to)}";`);
+    }
+  }
+  lines.push('}');
+  return lines.join('\n');
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────
+
+const args = parseArgs(process.argv);
+
+const ignorePatterns = loadHypoIgnore(args.hypoDir);
+const scanDirs = ['pages', 'projects'].map(d => join(args.hypoDir, d));
+const pages    = scanDirs.flatMap(d => collectPages(d, args.hypoDir, [], ignorePatterns));
+const slugIndex = buildSlugIndex(pages);
+const graph    = buildGraph(pages, slugIndex);
+
+switch (args.format) {
+  case 'mermaid': console.log(formatMermaid(pages, graph, args.minEdges)); break;
+  case 'dot':     console.log(formatDot(pages, graph, args.minEdges)); break;
+  default:        console.log(formatJson(pages, graph, args.minEdges));
+}

package/scripts/ingest.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Hypomnema ingest helper script
+ *
+ * Lists files in sources/ that have no corresponding source-summary page,
+ * and reports pages that reference missing source files.
+ * Used by /hypo:ingest to surface what needs ingestion before Claude synthesizes.
+ *
+ * Usage:
+ *   node scripts/ingest.mjs [options]
+ *
+ * Options:
+ *   --hypo-dir=<path>   Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
+ *   --json              Output as JSON
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, extname, basename } from 'path';
+import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
+
+// ── arg parsing ──────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { hypoDir: null, json: false };
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
+    else if (arg === '--json')         args.json = true;
+  }
+  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  return args;
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function collectMdFiles(dir, acc = [], hypoDir = '', ignorePatterns = []) {
+  if (!existsSync(dir)) return acc;
+  for (const entry of readdirSync(dir)) {
+    if (entry.startsWith('.')) continue;
+    const full = join(dir, entry);
+    if (hypoDir && isIgnored(full, hypoDir, ignorePatterns)) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) collectMdFiles(full, acc, hypoDir, ignorePatterns);
+    else if (extname(entry) === '.md') acc.push(full);
+  }
+  return acc;
+}
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return {};
+  const fm = {};
+  for (const line of m[1].split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+  }
+  return fm;
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+const args = parseArgs(process.argv);
+
+const ignorePatterns = loadHypoIgnore(args.hypoDir);
+const sourcesDir = join(args.hypoDir, 'sources');
+const allSources = existsSync(sourcesDir)
+  ? readdirSync(sourcesDir).filter(e => !e.startsWith('.') && !statSync(join(sourcesDir, e)).isDirectory() && !isIgnored(join(sourcesDir, e), args.hypoDir, ignorePatterns))
+  : [];
+
+// collect all source: references in wiki pages
+const pageFiles = collectMdFiles(join(args.hypoDir, 'pages'), [], args.hypoDir, ignorePatterns);
+const referencedSources = new Set();
+
+for (const f of pageFiles) {
+  let content;
+  try { content = readFileSync(f, 'utf-8'); } catch { continue; }
+  const fm = parseFrontmatter(content);
+  if (fm.source && !fm.source.startsWith('session:')) {
+    referencedSources.add(fm.source);
+  }
+}
+
+// sources with no summary page
+const orphaned = allSources.filter(s => {
+  const slug = basename(s, extname(s));
+  return !referencedSources.has(s) && !referencedSources.has(slug);
+});
+
+// pages referencing sources that don't exist on disk
+const missingSource = [];
+for (const f of pageFiles) {
+  let content;
+  try { content = readFileSync(f, 'utf-8'); } catch { continue; }
+  const fm = parseFrontmatter(content);
+  if (!fm.source || fm.source.startsWith('session:')) continue;
+  const sourceFile = join(sourcesDir, fm.source);
+  const sourceFileWithExt = allSources.find(s => s === fm.source || basename(s, extname(s)) === fm.source);
+  if (!sourceFileWithExt && !existsSync(sourceFile)) {
+    missingSource.push({ page: f, source: fm.source });
+  }
+}
+
+if (args.json) {
+  console.log(JSON.stringify({
+    totalSources: allSources.length,
+    orphaned,
+    missingSource,
+  }, null, 2));
+} else {
+  console.log(`Sources: ${allSources.length} total`);
+
+  if (orphaned.length === 0) {
+    console.log('✓ All sources have a corresponding source-summary page');
+  } else {
+    console.log(`\n⊘ ${orphaned.length} source(s) not yet ingested:`);
+    for (const s of orphaned) console.log(`  sources/${s}`);
+  }
+
+  if (missingSource.length > 0) {
+    console.log(`\n⚠ ${missingSource.length} page(s) reference a missing source file:`);
+    for (const { page, source } of missingSource) {
+      console.log(`  ${page}  →  source: ${source}`);
+    }
+  }
+
+  if (orphaned.length > 0) {
+    console.log('\nRun /hypo:ingest to synthesize the listed sources into wiki pages.');
+  }
+}