@monoes/monograph 1.5.6 → 1.5.7

package/src/skills/platform-skills.ts

@@ -1,233 +0,0 @@
-/**
- * Multi-platform IDE Skill File Installer
- *
- * Generates and installs per-community skill files for various IDE/platform
- * targets (Claude, Cursor, VS Code, Zed, Codex, Gemini, Aider, Copilot, Kiro).
- * Each platform gets one file per community describing exported symbols from
- * that community.
- */
-
-import fs from 'fs/promises';
-import fsSync from 'fs';
-import path from 'path';
-
-// ============================================================================
-// TYPES
-// ============================================================================
-
-export type SkillPlatform = 'claude' | 'cursor' | 'vscode' | 'zed' | 'codex' | 'gemini' | 'aider' | 'copilot' | 'kiro';
-
-export interface PlatformSkillConfig {
-  platform: SkillPlatform;
-  /** Override output directory. Default: platform-specific. */
-  outputDir?: string;
-}
-
-export interface SkillInstallResult {
-  platform: SkillPlatform;
-  filesWritten: string[];
-  outputDir: string;
-}
-
-export interface SyncSkillInstallResult {
-  filesWritten: string[];
-}
-
-// ============================================================================
-// SUPPORTED PLATFORMS
-// ============================================================================
-
-export const SUPPORTED_PLATFORMS: string[] = [
-  'claude',
-  'cursor',
-  'vscode',
-  'zed',
-  'codex',
-  'gemini',
-  'aider',
-  'copilot',
-  'kiro',
-];
-
-// ============================================================================
-// PLATFORM CONFIG
-// ============================================================================
-
-const PLATFORM_DEFAULTS: Record<SkillPlatform, { subPath: string[]; ext: string }> = {
-  claude:  { subPath: ['.claude', 'skills'], ext: '.md' },
-  cursor:  { subPath: ['.cursor', 'rules'], ext: '.md' },
-  vscode:  { subPath: ['.vscode'], ext: '.json' },
-  zed:     { subPath: ['.zed'], ext: '.md' },
-  codex:   { subPath: [], ext: '.md' },
-  gemini:  { subPath: [], ext: '.md' },
-  aider:   { subPath: [], ext: '.md' },
-  copilot: { subPath: ['.github'], ext: '.md' },
-  kiro:    { subPath: ['.kiro', 'steering'], ext: '.md' },
-};
-
-/**
- * Fixed file names for single-file platforms (no per-community files).
- * When defined, a single skill file is written regardless of communities.
- */
-const PLATFORM_FIXED_FILE: Partial<Record<SkillPlatform, string>> = {
-  codex:   'AGENTS.md',
-  gemini:  'GEMINI.md',
-  aider:   'AGENTS.md',
-  copilot: 'copilot-instructions.md',
-  kiro:    'monograph.md',
-};
-
-// ============================================================================
-// SYNC INSTALLER (for new platforms + compatibility)
-// ============================================================================
-
-/**
- * Synchronously install a skill file for a specific platform into the repo.
- * Returns { filesWritten } where filesWritten contains absolute paths to written files.
- *
- * New single-file platforms (codex, gemini, aider, copilot, kiro) always write
- * one file regardless of communities. Existing multi-file platforms write one
- * file per community entry.
- */
-export function installPlatformSkill(
-  repoPath: string,
-  platform: string,
-  communities: Array<{ name: string; symbols: string[] } | string>,
-): SyncSkillInstallResult {
-  const platformConfig = PLATFORM_DEFAULTS[platform as SkillPlatform];
-  if (!platformConfig) {
-    return { filesWritten: [] };
-  }
-
-  const outputDir = platformConfig.subPath.length > 0
-    ? path.join(repoPath, ...platformConfig.subPath)
-    : repoPath;
-
-  fsSync.mkdirSync(outputDir, { recursive: true });
-
-  const filesWritten: string[] = [];
-  const fixedFileName = PLATFORM_FIXED_FILE[platform as SkillPlatform];
-
-  if (fixedFileName) {
-    // Single-file platform: write one skill overview file
-    const filePath = path.join(outputDir, fixedFileName);
-    const content = renderMonographSkillDoc(platform);
-    fsSync.writeFileSync(filePath, content, 'utf-8');
-    filesWritten.push(filePath);
-  } else {
-    // Multi-file platform: one file per community (existing behavior)
-    const ext = platformConfig.ext;
-    const normalised = communities.map(c =>
-      typeof c === 'string' ? { name: c, symbols: [] } : c,
-    );
-    for (const community of normalised) {
-      const fileName = `${community.name}-skills${ext}`;
-      const filePath = path.join(outputDir, fileName);
-      let content: string;
-      if (ext === '.json') {
-        content = renderVsCodeSnippet(community);
-      } else {
-        content = renderMarkdown(community);
-      }
-      fsSync.writeFileSync(filePath, content, 'utf-8');
-      filesWritten.push(filePath);
-    }
-  }
-
-  return { filesWritten };
-}
-
-// ============================================================================
-// MAIN EXPORT
-// ============================================================================
-
-/**
- * Install skill files for a specific platform into the repo.
- *
- * Platform output directories (relative to repoPath):
- *   claude  → .claude/skills/
- *   cursor  → .cursor/rules/
- *   vscode  → .vscode/
- *   zed     → .zed/
- *
- * Each platform gets one file per community. File names use the community name.
- * Format:
- *   claude/cursor/zed → <communityName>-skills.md
- *   vscode            → <communityName>-skills.json (VS Code snippets format)
- */
-export async function installSkillsForPlatform(
-  repoPath: string,
-  communities: Array<{ name: string; symbols: string[] }>,
-  config: PlatformSkillConfig,
-): Promise<SkillInstallResult> {
-  const platformConfig = PLATFORM_DEFAULTS[config.platform];
-  const outputDir = config.outputDir ?? path.join(repoPath, ...platformConfig.subPath);
-
-  if (communities.length === 0) {
-    return { platform: config.platform, filesWritten: [], outputDir };
-  }
-
-  await fs.mkdir(outputDir, { recursive: true });
-
-  const filesWritten: string[] = [];
-  const ext = platformConfig.ext;
-
-  for (const community of communities) {
-    const fileName = `${community.name}-skills${ext}`;
-    const filePath = path.join(outputDir, fileName);
-
-    let content: string;
-    if (ext === '.json') {
-      content = renderVsCodeSnippet(community);
-    } else {
-      content = renderMarkdown(community);
-    }
-
-    await fs.writeFile(filePath, content, 'utf-8');
-    filesWritten.push(filePath);
-  }
-
-  return { platform: config.platform, filesWritten, outputDir };
-}
-
-// ============================================================================
-// RENDERERS
-// ============================================================================
-
-function renderMonographSkillDoc(platform: string): string {
-  const lines: string[] = [];
-  lines.push(`# Monograph Skills — ${platform.charAt(0).toUpperCase() + platform.slice(1)}`);
-  lines.push('');
-  lines.push('This file was generated by Monograph to document available skills for this platform.');
-  lines.push('');
-  lines.push('## Usage');
-  lines.push('');
-  lines.push('Monograph indexes your codebase and exposes symbol-level knowledge to AI assistants.');
-  lines.push('Run `monograph build` to update the knowledge graph and regenerate skill files.');
-  lines.push('');
-  return lines.join('\n');
-}
-
-function renderMarkdown(community: { name: string; symbols: string[] }): string {
-  const lines: string[] = [];
-  lines.push(`# ${community.name} Skills`);
-  lines.push('');
-  for (const symbol of community.symbols) {
-    lines.push(`- ${symbol}`);
-  }
-  lines.push('');
-  return lines.join('\n');
-}
-
-function renderVsCodeSnippet(community: { name: string; symbols: string[] }): string {
-  const snippetKey = community.name;
-  const body = community.symbols;
-  const snippet = {
-    [snippetKey]: {
-      prefix: community.name,
-      body,
-      description: `${community.name} monograph skill`,
-    },
-  };
-  return JSON.stringify(snippet, null, 2);
-}

package/src/staleness/git-staleness.ts

@@ -1,66 +0,0 @@
-import { execSync } from 'child_process';
-import type { MonographDb } from '../storage/db.js';
-
-export interface StalenessReport {
-  isStale: boolean;
-  indexedAt: string | null;
-  indexedCommit: string | null;
-  currentCommit: string | null;
-  changedSince: string[];
-  staleSince: string | null;
-}
-
-export function checkStaleness(db: MonographDb, repoPath: string): StalenessReport {
-  // 1. Get stored commit hash
-  const row = db.prepare("SELECT value FROM index_meta WHERE key = 'last_commit_hash'").get() as { value: string } | undefined;
-  const indexedCommitFull = row?.value ?? null;
-
-  // 2. Get current HEAD (full SHA — --short output length varies by repo size)
-  let currentCommit: string | null = null;
-  try {
-    currentCommit = execSync('git rev-parse HEAD', { cwd: repoPath, encoding: 'utf8' }).trim();
-  } catch {
-    // Not a git repo or git not available
-    return { isStale: false, indexedAt: null, indexedCommit: null, currentCommit: null, changedSince: [], staleSince: null };
-  }
-
-  // Display short SHA (7 chars) for the interface field; compare short SHAs for staleness
-  const indexedCommitShort = indexedCommitFull ? indexedCommitFull.slice(0, 7) : null;
-  const currentCommitShort = currentCommit ? currentCommit.slice(0, 7) : null;
-
-  // 3. If SHAs match → fresh. If no stored commit → staleness unknown (not "fresh").
-  if (indexedCommitShort === currentCommitShort) {
-    return { isStale: false, indexedAt: null, indexedCommit: indexedCommitShort, currentCommit: currentCommitShort, changedSince: [], staleSince: null };
-  }
-  if (!indexedCommitFull) {
-    return { isStale: true, indexedAt: null, indexedCommit: null, currentCommit: currentCommitShort, changedSince: [], staleSince: null };
-  }
-
-  // Guard: indexedCommitFull is read from SQLite — validate before shell interpolation
-  if (!/^[0-9a-f]{7,40}$/i.test(indexedCommitFull)) {
-    return { isStale: true, indexedAt: null, indexedCommit: indexedCommitShort, currentCommit: currentCommitShort, changedSince: [], staleSince: null };
-  }
-
-  // 4. Get changed files between indexed commit and HEAD
-  let changedSince: string[] = [];
-  try {
-    const diff = execSync(`git diff --name-only ${indexedCommitFull}..HEAD`, { cwd: repoPath, encoding: 'utf8' });
-    changedSince = diff.trim().split('\n').filter(Boolean);
-  } catch {
-    changedSince = [];
-  }
-
-  // 5. Get staleSince timestamp (first diverging commit after indexed commit)
-  let staleSince: string | null = null;
-  try {
-    const firstCommit = execSync(
-      `git log --format="%ai" ${indexedCommitFull}..HEAD --reverse --max-count=1`,
-      { cwd: repoPath, encoding: 'utf8' }
-    ).trim();
-    staleSince = firstCommit || null;
-  } catch {
-    staleSince = null;
-  }
-
-  return { isStale: true, indexedAt: null, indexedCommit: indexedCommitShort, currentCommit: currentCommitShort, changedSince, staleSince };
-}

package/src/storage/db.ts

@@ -1,110 +0,0 @@
-import Database from 'better-sqlite3';
-import { mkdirSync, existsSync, renameSync, unlinkSync } from 'fs';
-import { dirname } from 'path';
-import {
-  CREATE_NODES, CREATE_EDGES, CREATE_COMMUNITIES,
-  CREATE_INDEX_META, CREATE_NODES_FTS, CREATE_INDEXES, FTS_SYNC_TRIGGERS,
-  CREATE_EMBEDDINGS, CREATE_WIKI_PAGES,
-  CREATE_AGENT_INTERACTIONS, CREATE_AGENT_INTERACTIONS_IDX,
-  CREATE_AGENT_INTERACTIONS_ORG_IDX, CREATE_AGENT_INTERACTIONS_TYPE_IDX,
-  CREATE_AGENT_INTERACTIONS_TS_IDX,
-} from './schema.js';
-import { MonographError } from '../types.js';
-
-export type MonographDb = Database.Database;
-
-export interface OpenDbOptions {
-  /**
-   * When true, throw a clear error instead of silently creating a fresh,
-   * empty-but-migrated database if `dbPath` doesn't exist yet. Defaults to
-   * false to preserve legacy build-time behavior (the `monograph build`
-   * codepath legitimately creates new DBs). Read-only analysis tools should
-   * pass `true` so pointing them at a repo whose real index lives elsewhere
-   * (e.g. running from a subdirectory) fails loudly instead of reporting
-   * fake-successful-looking empty results.
-   */
-  fileMustExist?: boolean;
-}
-
-export function openDb(dbPath: string, options: OpenDbOptions = {}): MonographDb {
-  if (options.fileMustExist && !existsSync(dbPath)) {
-    throw new MonographError(`Monograph database does not exist at ${dbPath}. Run monograph build first.`);
-  }
-  try {
-    mkdirSync(dirname(dbPath), { recursive: true });
-    const db = new Database(dbPath);
-    db.pragma('journal_mode = WAL');
-    db.pragma('foreign_keys = ON');
-    // Concurrent pipeline phases + long-lived MCP connections share this DB —
-    // without a busy timeout, writers fail immediately with "database is locked".
-    db.pragma('busy_timeout = 10000');
-    db.pragma('synchronous = NORMAL');
-    // node-store uses INSERT OR REPLACE; without recursive_triggers the implicit
-    // DELETE never fires the nodes_fts delete trigger, leaving ghost FTS rows that
-    // corrupt queries ("missing row N from content table") and bloat the index.
-    db.pragma('recursive_triggers = ON');
-    applyMigrations(db);
-    return db;
-  } catch (err) {
-    throw new MonographError(`Failed to open database at ${dbPath}`, err);
-  }
-}
-
-export function closeDb(db: MonographDb): void {
-  db.close();
-}
-
-function applyMigrations(db: MonographDb): void {
-  db.exec(CREATE_NODES);
-  db.exec(CREATE_EDGES);
-  db.exec(CREATE_COMMUNITIES);
-  db.exec(CREATE_INDEX_META);
-  db.exec(CREATE_NODES_FTS);
-  for (const idx of CREATE_INDEXES) db.exec(idx);
-  db.exec(FTS_SYNC_TRIGGERS);
-  db.exec(CREATE_EMBEDDINGS);
-  db.exec(CREATE_WIKI_PAGES);
-  db.exec(CREATE_AGENT_INTERACTIONS);
-  db.exec(CREATE_AGENT_INTERACTIONS_IDX);
-  db.exec(CREATE_AGENT_INTERACTIONS_ORG_IDX);
-  db.exec(CREATE_AGENT_INTERACTIONS_TYPE_IDX);
-  db.exec(CREATE_AGENT_INTERACTIONS_TS_IDX);
-
-  // Schema version table — tracks incremental column additions.
-  db.exec(`CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY)`);
-  const row = db.prepare('SELECT MAX(version) AS v FROM schema_version').get() as { v: number | null };
-  const current = row?.v ?? 0;
-
-  if (current < 1) {
-    // v1: added `reason TEXT` to edges
-    try { db.exec('ALTER TABLE edges ADD COLUMN reason TEXT'); } catch { /* already present */ }
-    db.prepare('INSERT OR REPLACE INTO schema_version VALUES (1)').run();
-  }
-}
-
-/** Write to a .tmp file then rename for atomic replacement. */
-export function atomicRebuild(dbPath: string, buildFn: (db: MonographDb) => void): void {
-  const tmpPath = dbPath + '.tmp';
-  const db = openDb(tmpPath);
-  try {
-    buildFn(db);
-    db.close();
-    renameSync(tmpPath, dbPath);
-    // The old db's WAL-mode sidecar files belong to the file we just replaced —
-    // if left behind, the next process to open dbPath pairs the NEW db file with
-    // a STALE -wal/-shm whose salt/checkpoint state doesn't match, which can
-    // surface as "file is not a database" or subtle corruption.
-    for (const suffix of ['-wal', '-shm']) {
-      const sidecar = dbPath + suffix;
-      if (existsSync(sidecar)) {
-        try { unlinkSync(sidecar); } catch { /* best-effort cleanup */ }
-      }
-    }
-  } catch (err) {
-    db.close();
-    if (existsSync(tmpPath)) {
-      try { unlinkSync(tmpPath); } catch { /* ignore */ }
-    }
-    throw err;
-  }
-}

package/src/storage/edge-store.ts

@@ -1,103 +0,0 @@
-import type Database from 'better-sqlite3';
-import type { EvidenceEntry, MonographEdge } from '../types.js';
-
-export function insertEdge(db: Database.Database, edge: MonographEdge): void {
-  db.prepare(`
-    INSERT OR REPLACE INTO edges (id, source_id, target_id, relation, confidence, confidence_score, reason, evidence)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(
-    edge.id,
-    edge.sourceId,
-    edge.targetId,
-    edge.relation,
-    edge.confidence,
-    edge.confidenceScore,
-    edge.reason ?? null,
-    edge.evidence != null ? JSON.stringify(edge.evidence) : null,
-  );
-}
-
-const INSERT_EDGE_SQL = `
-    INSERT OR REPLACE INTO edges (id, source_id, target_id, relation, confidence, confidence_score, reason, evidence)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-  `;
-
-export function insertEdges(db: Database.Database, edges: MonographEdge[]): void {
-  if (edges.length === 0) return;
-  // Prepare once and reuse across all rows — avoids N redundant prepare calls
-  const stmt = db.prepare(INSERT_EDGE_SQL);
-  const insertMany = db.transaction((rows: MonographEdge[]) => {
-    for (const e of rows) {
-      stmt.run(
-        e.id,
-        e.sourceId,
-        e.targetId,
-        e.relation,
-        e.confidence,
-        e.confidenceScore,
-        e.reason ?? null,
-        e.evidence != null ? JSON.stringify(e.evidence) : null,
-      );
-    }
-  });
-  insertMany(edges);
-}
-
-/** Batch-fetch edges for multiple source IDs using a single SQL IN query. Batches at 50 IDs. */
-export function getEdgesForSources(db: Database.Database, sourceIds: string[]): MonographEdge[] {
-  if (sourceIds.length === 0) return [];
-  const BATCH = 50;
-  const results: MonographEdge[] = [];
-  for (let i = 0; i < sourceIds.length; i += BATCH) {
-    const chunk = sourceIds.slice(i, i + BATCH);
-    const placeholders = chunk.map(() => '?').join(',');
-    const rows = db
-      .prepare(`SELECT * FROM edges WHERE source_id IN (${placeholders})`)
-      .all(...chunk) as Record<string, unknown>[];
-    for (const row of rows) results.push(rowToEdge(row));
-  }
-  return results;
-}
-
-export function getEdgesForSource(db: Database.Database, sourceId: string): MonographEdge[] {
-  const rows = db
-    .prepare('SELECT * FROM edges WHERE source_id = ?')
-    .all(sourceId) as Record<string, unknown>[];
-  return rows.map(rowToEdge);
-}
-
-export function getEdgesForTarget(db: Database.Database, targetId: string): MonographEdge[] {
-  const rows = db
-    .prepare('SELECT * FROM edges WHERE target_id = ?')
-    .all(targetId) as Record<string, unknown>[];
-  return rows.map(rowToEdge);
-}
-
-/**
- * Delete every edge that touches a node belonging to `filePath`, on either end.
- * Must be called BEFORE the corresponding nodes are deleted (the subselects need
- * the file's nodes to still exist to identify which edges to remove) — e.g.
- * `deleteEdgesForFile` then `deleteNodesForFile`, never the reverse.
- */
-export function deleteEdgesForFile(db: Database.Database, filePath: string): void {
-  db.prepare(`DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file_path = ?)`).run(filePath);
-  db.prepare(`DELETE FROM edges WHERE target_id IN (SELECT id FROM nodes WHERE file_path = ?)`).run(filePath);
-}
-
-export function countEdges(db: Database.Database): number {
-  const row = db.prepare('SELECT COUNT(*) as n FROM edges').get() as { n: number };
-  return row.n;
-}
-
-function rowToEdge(row: Record<string, unknown>): MonographEdge {
-  return {
-    id: row.id as string,
-    sourceId: row.source_id as string,
-    targetId: row.target_id as string,
-    relation: row.relation as MonographEdge['relation'],
-    confidence: row.confidence as MonographEdge['confidence'],
-    confidenceScore: row.confidence_score as number,
-    reason: row.reason as string | undefined,
-    evidence: row.evidence ? JSON.parse(row.evidence as string) as EvidenceEntry[] : undefined,
-  };
-}

package/src/storage/file-cache.ts

@@ -1,78 +0,0 @@
-import { createHash } from 'crypto';
-import type { MonographDb } from './db.js';
-
-export interface FileCacheEntry {
-  filePath: string;
-  contentHash: string;   // SHA-256 hex of file content (using node:crypto — xxh3 proxy)
-  lastParsed: number;    // unix timestamp ms
-  nodeCount: number;     // how many nodes were created from this file
-  edgeCount: number;
-}
-
-export function hashFileContent(content: string): string {
-  return createHash('sha256').update(content).digest('hex');
-}
-
-export function isFileCached(db: MonographDb, filePath: string, contentHash: string): boolean {
-  const row = db.prepare(
-    'SELECT content_hash FROM file_cache WHERE file_path = ?'
-  ).get(filePath) as { content_hash: string } | undefined;
-  return row?.content_hash === contentHash;
-}
-
-export function updateFileCache(db: MonographDb, entry: FileCacheEntry): void {
-  db.prepare(`
-    INSERT OR REPLACE INTO file_cache (file_path, content_hash, last_parsed, node_count, edge_count)
-    VALUES (?, ?, ?, ?, ?)
-  `).run(entry.filePath, entry.contentHash, entry.lastParsed, entry.nodeCount, entry.edgeCount);
-}
-
-/**
- * Bulk-upsert multiple file cache entries in a single transaction.
- * Prefer this over calling updateFileCache in a loop for pipeline batch writes.
- */
-export function batchUpdateFileCache(db: MonographDb, entries: FileCacheEntry[]): void {
-  if (entries.length === 0) return;
-  const stmt = db.prepare(`
-    INSERT OR REPLACE INTO file_cache (file_path, content_hash, last_parsed, node_count, edge_count)
-    VALUES (?, ?, ?, ?, ?)
-  `);
-  const insertMany = db.transaction((rows: FileCacheEntry[]) => {
-    for (const e of rows) {
-      stmt.run(e.filePath, e.contentHash, e.lastParsed, e.nodeCount, e.edgeCount);
-    }
-  });
-  insertMany(entries);
-}
-
-export function getFileCacheStats(db: MonographDb): {
-  totalCached: number;
-  hitRate: number;
-  stalePaths: string[];
-} {
-  // Single query: count cached entries and distinct indexed file paths in one pass.
-  const counts = db.prepare(`
-    SELECT
-      (SELECT COUNT(*) FROM file_cache) AS total_cached,
-      (SELECT COUNT(DISTINCT file_path) FROM nodes WHERE file_path IS NOT NULL) AS total_indexed
-  `).get() as { total_cached: number; total_indexed: number };
-
-  const totalCached = counts.total_cached;
-  const hitRate = counts.total_indexed > 0 ? totalCached / counts.total_indexed : 0;
-
-  // Find stale paths via SQL LEFT JOIN — avoids loading all rows into JS memory.
-  const stalePaths = (db.prepare(`
-    SELECT fc.file_path
-    FROM file_cache fc
-    LEFT JOIN (
-      SELECT DISTINCT file_path FROM nodes WHERE file_path IS NOT NULL
-    ) n ON fc.file_path = n.file_path
-    WHERE n.file_path IS NULL
-  `).all() as { file_path: string }[]).map(r => r.file_path);
-
-  return { totalCached, hitRate, stalePaths };
-}
-
-export function clearFileCache(db: MonographDb): void {
-  db.prepare('DELETE FROM file_cache').run();
-}