@monoes/monograph 1.5.6 → 1.5.7

package/src/wiki/prompt-builder.ts

@@ -1,35 +0,0 @@
-export interface CommunityContext {
-  communityId: string;
-  label: string;
-  topSymbols: { name: string; label: string; filePath: string | null }[];
-  incomingCount: number;
-  outgoingCount: number;
-}
-
-/**
- * Build an LLM prompt for generating a wiki page about a code community.
- */
-export function buildWikiPrompt(context: CommunityContext): string {
-  const symbolLines = context.topSymbols
-    .map(s => `  - [${s.label}] ${s.name}${s.filePath ? ` (${s.filePath})` : ''}`)
-    .join('\n');
-
-  return `You are a technical documentation writer. Write a concise markdown wiki page for the following code module (community).
-
-Community ID: ${context.communityId}
-Module Name: ${context.label}
-Incoming Dependencies: ${context.incomingCount} (other modules that depend on this one)
-Outgoing Dependencies: ${context.outgoingCount} (modules this one depends on)
-
-Top Symbols:
-${symbolLines || '  (none)'}
-
-Write a wiki page that includes:
-1. A brief description of what this module does
-2. The key entry points and their purpose
-3. What this module depends on and what depends on it
-4. Any notable architectural patterns observed
-
-Format the output as markdown with a top-level heading using the module name.
-Be concise but informative. Focus on the role this module plays in the overall system.`;
-}

package/src/wiki/providers.ts

@@ -1,134 +0,0 @@
-export type LLMProvider = 'anthropic' | 'openai' | 'ollama';
-
-export interface LLMConfig {
-  provider: LLMProvider;
-  model?: string;       // e.g. "claude-3-haiku-20240307", "gpt-4o-mini", "mistral"
-  apiKey?: string;      // read from env if not provided
-  baseUrl?: string;     // for ollama: "http://localhost:11434"
-  maxTokens?: number;   // default 2048
-  temperature?: number; // default 0.2
-}
-
-export interface LLMResponse {
-  text: string;
-  inputTokens?: number;
-  outputTokens?: number;
-}
-
-const REASONING_MODELS = new Set(['o1', 'o1-mini', 'o1-preview', 'o3', 'o3-mini', 'o4-mini']);
-
-function isReasoningModel(model: string): boolean {
-  return REASONING_MODELS.has(model) || /^o\d+(-mini|-preview)?$/.test(model);
-}
-
-/**
- * Call an LLM provider with the given prompt and configuration.
- * Supports anthropic, openai, and ollama providers.
- */
-export async function callLLM(prompt: string, config: LLMConfig): Promise<LLMResponse> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 30_000);
-
-  try {
-    switch (config.provider) {
-      case 'anthropic':
-        return await callAnthropic(prompt, config, controller.signal);
-      case 'openai':
-        return await callOpenAI(prompt, config, controller.signal);
-      case 'ollama':
-        return await callOllama(prompt, config, controller.signal);
-      default: {
-        const _exhaustive: never = config.provider;
-        throw new Error(`Unknown LLM provider: ${_exhaustive}`);
-      }
-    }
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
-
-async function callAnthropic(
-  prompt: string,
-  _config: LLMConfig,
-  _signal: AbortSignal,
-): Promise<LLMResponse> {
-  // Route through Claude Code CLI — reuses host auth, no API key needed.
-  const { claudeCliCall } = await import('../claude-cli.js');
-  const text = await claudeCliCall(prompt);
-  return { text };
-}
-
-async function callOpenAI(
-  prompt: string,
-  config: LLMConfig,
-  signal: AbortSignal,
-): Promise<LLMResponse> {
-  const apiKey = config.apiKey ?? process.env['OPENAI_API_KEY'];
-  const response = await fetch('https://api.openai.com/v1/chat/completions', {
-    method: 'POST',
-    signal,
-    headers: {
-      'Authorization': `Bearer ${apiKey ?? ''}`,
-      'content-type': 'application/json',
-    },
-    body: (() => {
-      const reasoning = isReasoningModel(config.model ?? '');
-      const bodyObj: Record<string, unknown> = {
-        model: config.model ?? 'gpt-4o-mini',
-        messages: [{ role: 'user', content: prompt }],
-      };
-      if (reasoning) {
-        bodyObj['max_completion_tokens'] = config.maxTokens ?? 2048;
-      } else {
-        bodyObj['max_tokens'] = config.maxTokens ?? 2048;
-        bodyObj['temperature'] = config.temperature ?? 0.2;
-      }
-      return JSON.stringify(bodyObj);
-    })(),
-  });
-
-  if (!response.ok) {
-    throw new Error(`LLM provider openai error: ${response.status} ${response.statusText}`);
-  }
-
-  const data = await response.json() as {
-    choices: Array<{ message: { content: string } }>;
-    usage: { prompt_tokens: number; completion_tokens: number };
-  };
-
-  return {
-    text: data.choices[0].message.content,
-    inputTokens: data.usage.prompt_tokens,
-    outputTokens: data.usage.completion_tokens,
-  };
-}
-
-async function callOllama(
-  prompt: string,
-  config: LLMConfig,
-  signal: AbortSignal,
-): Promise<LLMResponse> {
-  const baseUrl = config.baseUrl ?? 'http://localhost:11434';
-  const response = await fetch(`${baseUrl}/api/generate`, {
-    method: 'POST',
-    signal,
-    headers: {
-      'content-type': 'application/json',
-    },
-    body: JSON.stringify({
-      model: config.model ?? 'mistral',
-      prompt,
-      stream: false,
-    }),
-  });
-
-  if (!response.ok) {
-    throw new Error(`LLM provider ollama error: ${response.status} ${response.statusText}`);
-  }
-
-  const data = await response.json() as { response: string };
-
-  return {
-    text: data.response,
-  };
-}

package/src/wiki/wiki-generator.ts

@@ -1,223 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-import { buildWikiPrompt } from './prompt-builder.js';
-import { upsertWikiPage, getWikiPage, listWikiPages } from './wiki-store.js';
-import { callLLM, type LLMConfig } from './providers.js';
-
-export type { LLMConfig } from './providers.js';
-export type { LLMProvider, LLMResponse } from './providers.js';
-
-export interface WikiGeneratorOptions {
-  repoPath: string;
-  reviewOnly?: boolean;
-  db?: MonographDb;
-}
-
-export interface WikiGeneratorResult {
-  reviewMode?: boolean;
-  proposedGroupings?: unknown[];
-  pages: string[];
-  pageCount: number;
-}
-
-/**
- * Top-level wiki generation entry point.
- * When reviewOnly is true, returns proposed community groupings without generating pages.
- */
-export async function generateWiki(options: WikiGeneratorOptions): Promise<WikiGeneratorResult> {
-  const db = options.db;
-
-  // Collect community groupings from DB (if available)
-  let groupings: unknown[] = [];
-  if (db) {
-    try {
-      const rows = db.prepare('SELECT DISTINCT community_id FROM nodes WHERE community_id IS NOT NULL').all();
-      groupings = rows as unknown[];
-    } catch {
-      groupings = [];
-    }
-  }
-
-  if (options.reviewOnly) {
-    return {
-      reviewMode: true,
-      proposedGroupings: groupings,
-      pages: [],
-      pageCount: 0,
-    };
-  }
-
-  // Full generation path
-  if (!db) {
-    return { pages: [], pageCount: 0 };
-  }
-
-  const result = await generateAllWikiPages(db);
-  return {
-    pages: [],
-    pageCount: result.generated,
-  };
-}
-
-export interface LlmClient {
-  generate: (prompt: string) => Promise<string>;
-}
-
-export interface GenerateWikiPageOptions {
-  model?: string;
-  apiKey?: string;
-  /** Inject a test client instead of calling Anthropic API */
-  llmClient?: LlmClient;
-  /** Use a multi-provider LLM config instead of the default Anthropic SDK */
-  llmConfig?: LLMConfig;
-}
-
-export interface GenerateAllWikiPagesOptions {
-  force?: boolean;
-  model?: string;
-  communityId?: string;
-  llmClient?: LlmClient;
-  /** Use a multi-provider LLM config instead of the default Anthropic SDK */
-  llmConfig?: LLMConfig;
-}
-
-export interface GenerateAllResult {
-  generated: number;
-  skipped: number;
-  errors: number;
-}
-
-/**
- * Generate a wiki page for a single community using the LLM.
- * Returns the generated markdown content and persists it to the DB.
- */
-export async function generateWikiPage(
-  db: MonographDb,
-  communityId: string,
-  options?: GenerateWikiPageOptions,
-): Promise<string> {
-  const communityIdStr = String(communityId);
-
-  // 1. Get community label
-  const commRow = db.prepare('SELECT id, label FROM communities WHERE id = ?')
-    .get(Number(communityIdStr)) as { id: number; label: string | null } | undefined;
-  const label = commRow?.label ?? `Community ${communityIdStr}`;
-
-  // 2. Get top 5 symbols by degree (count of connected edges, since no centrality column)
-  const symbolRows = db.prepare(`
-    SELECT n.name, n.label, n.file_path
-    FROM nodes n
-    LEFT JOIN (
-      SELECT node_id, SUM(cnt) AS deg FROM (
-        SELECT source_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY source_id
-        UNION ALL
-        SELECT target_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY target_id
-      ) GROUP BY node_id
-    ) d ON d.node_id = n.id
-    WHERE n.community_id = ?
-    ORDER BY d.deg DESC NULLS LAST, n.name ASC
-    LIMIT 5
-  `).all(Number(communityIdStr)) as { name: string; label: string; file_path: string | null }[];
-
-  // 3. Count incoming edges to community (edges whose target is in this community)
-  const incomingRow = db.prepare(`
-    SELECT COUNT(*) AS cnt FROM edges
-    WHERE target_id IN (SELECT id FROM nodes WHERE community_id = ?)
-  `).get(Number(communityIdStr)) as { cnt: number };
-
-  // 4. Count outgoing edges from community (edges whose source is in this community)
-  const outgoingRow = db.prepare(`
-    SELECT COUNT(*) AS cnt FROM edges
-    WHERE source_id IN (SELECT id FROM nodes WHERE community_id = ?)
-  `).get(Number(communityIdStr)) as { cnt: number };
-
-  // 5. Build prompt
-  const prompt = buildWikiPrompt({
-    communityId: communityIdStr,
-    label,
-    topSymbols: symbolRows.map(r => ({ name: r.name, label: r.label, filePath: r.file_path })),
-    incomingCount: incomingRow.cnt,
-    outgoingCount: outgoingRow.cnt,
-  });
-
-  // 6. Call LLM (injected client, multi-provider config, or Anthropic SDK)
-  let content: string;
-
-  if (options?.llmClient) {
-    content = await options.llmClient.generate(prompt);
-  } else if (options?.llmConfig) {
-    const result = await callLLM(prompt, options.llmConfig);
-    content = result.text;
-  } else {
-    const { claudeCliCall, isClaudeCliAvailable } = await import('../claude-cli.js');
-    if (!isClaudeCliAvailable()) {
-      // Spell out that no API key is wanted — users hitting this reasonably
-      // assume ANTHROPIC_API_KEY is the missing piece and go set one, which
-      // changes nothing (#43).
-      throw new Error(
-        'Claude Code CLI not found on PATH. Wiki generation runs through `claude --print` ' +
-        'and needs no ANTHROPIC_API_KEY. Install it with: npm install -g @anthropic-ai/claude-code',
-      );
-    }
-    content = await claudeCliCall(prompt);
-  }
-
-  // 7. Persist to DB — prepend OKF frontmatter if not already present
-  if (!content.startsWith('---')) {
-    const safeLabel = label.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-    content = `---\ntype: Code Community Wiki\ntitle: "${safeLabel}"\ntags: [monograph, wiki]\ntimestamp: ${new Date().toISOString()}\n---\n\n${content}`;
-  }
-  upsertWikiPage(db, communityIdStr, content);
-
-  return content;
-}
-
-/**
- * Generate wiki pages for all (or a filtered) communities.
- */
-export async function generateAllWikiPages(
-  db: MonographDb,
-  options?: GenerateAllWikiPagesOptions,
-): Promise<GenerateAllResult> {
-  // Get all distinct community_ids from nodes
-  let communityRows: { community_id: number }[];
-
-  if (options?.communityId != null) {
-    communityRows = [{ community_id: Number(options.communityId) }];
-  } else {
-    communityRows = db.prepare(
-      'SELECT DISTINCT community_id FROM nodes WHERE community_id IS NOT NULL',
-    ).all() as { community_id: number }[];
-  }
-
-  let generated = 0;
-  let skipped = 0;
-  let errors = 0;
-
-  for (const row of communityRows) {
-    const communityIdStr = String(row.community_id);
-
-    // Skip if already generated and force is not set
-    if (!options?.force) {
-      const existing = getWikiPage(db, communityIdStr);
-      if (existing) {
-        skipped++;
-        continue;
-      }
-    }
-
-    try {
-      await generateWikiPage(db, communityIdStr, {
-        model: options?.model,
-        llmClient: options?.llmClient,
-        llmConfig: options?.llmConfig,
-      });
-      generated++;
-    } catch {
-      errors++;
-    }
-  }
-
-  return { generated, skipped, errors };
-}
-
-export { upsertWikiPage, getWikiPage, listWikiPages };

package/src/wiki/wiki-store.ts

@@ -1,49 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-
-export interface WikiPage {
-  communityId: string;
-  content: string;
-  generatedAt: string;
-}
-
-/**
- * Upsert a wiki page for a community.
- * community_id is stored as TEXT (coerced from integer community_id in nodes).
- */
-export function upsertWikiPage(db: MonographDb, communityId: string, content: string): void {
-  const generatedAt = new Date().toISOString();
-  db.prepare(`
-    INSERT INTO wiki_pages (community_id, content, generated_at)
-    VALUES (?, ?, ?)
-    ON CONFLICT(community_id) DO UPDATE SET content = excluded.content, generated_at = excluded.generated_at
-  `).run(String(communityId), content, generatedAt);
-}
-
-/**
- * Get a single wiki page by community ID.
- */
-export function getWikiPage(db: MonographDb, communityId: string): WikiPage | null {
-  const row = db.prepare('SELECT community_id, content, generated_at FROM wiki_pages WHERE community_id = ?')
-    .get(String(communityId)) as { community_id: string; content: string; generated_at: string } | undefined;
-
-  if (!row) return null;
-  return {
-    communityId: row.community_id,
-    content: row.content,
-    generatedAt: row.generated_at,
-  };
-}
-
-/**
- * List all wiki pages.
- */
-export function listWikiPages(db: MonographDb): WikiPage[] {
-  const rows = db.prepare('SELECT community_id, content, generated_at FROM wiki_pages ORDER BY community_id')
-    .all() as { community_id: string; content: string; generated_at: string }[];
-
-  return rows.map(row => ({
-    communityId: row.community_id,
-    content: row.content,
-    generatedAt: row.generated_at,
-  }));
-}

package/tsconfig.json

@@ -1,11 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": ".",
-    "composite": true,
-    "types": ["node", "better-sqlite3", "express", "micromatch"]
-  },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist", "__tests__", "src/**/__tests__/**", "src/**/*.test.ts", "src/**/*.spec.ts"]
-}

package/vitest.config.ts

@@ -1,20 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    environment: 'node',
-    include: ['__tests__/**/*.test.ts', 'src/__tests__/**/*.test.ts'],
-    exclude: ['node_modules', 'dist', '**/._*'],
-    globals: true,
-    // Off by default to keep the edit/test loop fast; run
-    // `npm run test:coverage` (or pass --coverage) to measure.
-    coverage: {
-      enabled: false,
-      provider: 'v8',
-      reporter: ['text-summary', 'json-summary', 'html'],
-      reportsDirectory: './coverage',
-      include: ['src/**/*.ts'],
-      exclude: ['src/**/*.test.ts', 'src/__tests__/**', 'src/**/*.d.ts'],
-    },
-  },
-});