@monoes/monograph 1.5.5 → 1.5.7

package/src/mcp-tools/rename.ts

@@ -1,118 +0,0 @@
-import { readFileSync, statSync } from 'fs';
-import type Database from 'better-sqlite3';
-import type { MonographNode } from '../types.js';
-
-// ── Row → MonographNode mapper ─────────────────────────────────────────────────
-
-function rowToNode(row: Record<string, unknown>): MonographNode {
-  return {
-    id: row.id as string,
-    label: row.label as MonographNode['label'],
-    name: row.name as string,
-    normLabel: row.norm_label as string,
-    filePath: row.file_path as string | undefined,
-    startLine: row.start_line as number | undefined,
-    endLine: row.end_line as number | undefined,
-    communityId: row.community_id as number | undefined,
-    isExported: (row.is_exported as number) === 1,
-    language: row.language as string | undefined,
-    properties: row.properties ? JSON.parse(row.properties as string) : undefined,
-  };
-}
-
-// ── Output type ────────────────────────────────────────────────────────────────
-
-export interface MonographRenameResult {
-  symbol: MonographNode | null;
-  referencingFiles: string[];
-  changes: Array<{ file: string; line: number; before: string; after: string }>;
-  error?: string;
-}
-
-// ── Implementation ─────────────────────────────────────────────────────────────
-
-export function getMonographRename(
-  db: Database.Database,
-  input: { oldName: string; newName: string; filePath?: string; dryRun?: boolean },
-): MonographRenameResult {
-  // Find the canonical node
-  let nodeRow: Record<string, unknown> | undefined;
-  if (input.filePath) {
-    nodeRow = db
-      .prepare('SELECT * FROM nodes WHERE name = ? AND file_path = ? LIMIT 1')
-      .get(input.oldName, input.filePath) as Record<string, unknown> | undefined;
-  } else {
-    nodeRow = db
-      .prepare('SELECT * FROM nodes WHERE name = ? LIMIT 1')
-      .get(input.oldName) as Record<string, unknown> | undefined;
-  }
-
-  if (!nodeRow) {
-    return { symbol: null, referencingFiles: [], changes: [] };
-  }
-
-  const symbol = rowToNode(nodeRow);
-  const nodeId = symbol.id;
-
-  // Find all nodes with CALLS or IMPORTS edges pointing to this node
-  const referencingRows = db
-    .prepare(
-      `SELECT DISTINCT n.id, n.file_path, n.start_line FROM nodes n
-       JOIN edges e ON n.id = e.source_id
-       WHERE e.target_id = ? AND e.relation IN ('CALLS', 'IMPORTS')
-       AND n.file_path IS NOT NULL`,
-    )
-    .all(nodeId) as Array<{ id: string; file_path: string; start_line: number | null }>;
-
-  const referencingFiles = [...new Set(referencingRows.map(r => r.file_path))];
-
-  // Build changes list by reading source files
-  const changes: Array<{ file: string; line: number; before: string; after: string }> = [];
-  // Two separate regexes: testRe has no `g` flag (safe for repeated test()), replaceRe has `g`
-  const testRe = new RegExp(`\\b${escapeRegExp(input.oldName)}\\b`);
-  const replaceRe = new RegExp(`\\b${escapeRegExp(input.oldName)}\\b`, 'g');
-  const MAX_FILE_BYTES = 1_048_576; // 1 MiB guard
-
-  // File line cache to avoid re-reading the same file multiple times
-  const fileLineCache = new Map<string, string[]>();
-
-  const getLines = (filePath: string): string[] => {
-    if (fileLineCache.has(filePath)) return fileLineCache.get(filePath)!;
-    try {
-      const st = statSync(filePath);
-      if (st.size > MAX_FILE_BYTES) { fileLineCache.set(filePath, []); return []; }
-      const content = readFileSync(filePath, 'utf-8');
-      const lines = content.split('\n');
-      fileLineCache.set(filePath, lines);
-      return lines;
-    } catch {
-      fileLineCache.set(filePath, []);
-      return [];
-    }
-  };
-
-  for (const row of referencingRows) {
-    if (!row.file_path || row.start_line == null) continue;
-
-    const lines = getLines(row.file_path);
-    const lineIdx = row.start_line - 1; // convert 1-based to 0-based
-    if (lineIdx < 0 || lineIdx >= lines.length) continue;
-
-    const originalLine = lines[lineIdx];
-    if (!testRe.test(originalLine)) continue;
-
-    const updatedLine = originalLine.replace(replaceRe, input.newName);
-    changes.push({
-      file: row.file_path,
-      line: row.start_line,
-      before: originalLine,
-      after: updatedLine,
-    });
-  }
-
-  return { symbol, referencingFiles, changes };
-}
-
-function escapeRegExp(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

package/src/mcp-tools/route-map.ts

@@ -1,98 +0,0 @@
-import { readFileSync, statSync } from 'fs';
-import type Database from 'better-sqlite3';
-import { extractMiddlewareChain } from '../pipeline/phases/middleware-extractor.js';
-
-// ── Output types ───────────────────────────────────────────────────────────────
-
-export interface RouteMapEntry {
-  method: string;
-  path: string;
-  handlerName: string | null;
-  handlerFile: string | null;
-  handlerLine: number | null;
-  routeNodeId: string;
-  middlewareChain: string[];
-}
-
-export interface MonographRouteMapResult {
-  routes: RouteMapEntry[];
-  total: number;
-}
-
-const MAX_FILE_BYTES = 1_048_576; // 1 MiB guard for middleware source reads
-
-// ── Implementation ─────────────────────────────────────────────────────────────
-
-export function getMonographRouteMap(
-  db: Database.Database,
-  input: { prefix?: string; method?: string; includeMiddleware?: boolean; repoPath?: string },
-): MonographRouteMapResult {
-  // 1. Build SQL-level filters to avoid loading the whole Route table into JS
-  const conditions: string[] = ["label = 'Route'"];
-  const params: unknown[] = [];
-
-  if (input.prefix) {
-    // Route name format: "METHOD /path" — prefix applies to path portion after first space
-    conditions.push("name LIKE ?");
-    params.push(`% ${input.prefix}%`);
-  }
-
-  if (input.method) {
-    const methodUpper = input.method.toUpperCase();
-    conditions.push("(name LIKE ? OR name LIKE ?)");
-    params.push(`${methodUpper} %`, 'ANY %');
-  }
-
-  const sql = `SELECT * FROM nodes WHERE ${conditions.join(' AND ')}`;
-  const routeRows = db.prepare(sql).all(...params) as Record<string, unknown>[];
-
-  // 2. For each route, find handler via HANDLES_ROUTE edge (prepared once)
-  const handlerStmt = db.prepare(
-    `SELECT n.name, n.file_path, n.start_line FROM nodes n
-     JOIN edges e ON n.id = e.target_id
-     WHERE e.source_id = ? AND e.relation = 'HANDLES_ROUTE'
-     LIMIT 1`,
-  );
-
-  const routes: RouteMapEntry[] = routeRows.map((row) => {
-    const routeNodeId = row.id as string;
-    const name = row.name as string;
-
-    // Parse method and path from name (format: "METHOD /path")
-    const spaceIdx = name.indexOf(' ');
-    const method = spaceIdx >= 0 ? name.slice(0, spaceIdx) : 'ANY';
-    const path = spaceIdx >= 0 ? name.slice(spaceIdx + 1) : name;
-
-    // Look up handler
-    const handlerRow = handlerStmt.get(routeNodeId) as
-      | { name: string; file_path: string | null; start_line: number | null }
-      | undefined;
-
-    // Detect middleware chain at query time when requested
-    let middlewareChain: string[] = [];
-    if (input.includeMiddleware && input.repoPath && handlerRow?.name && handlerRow?.file_path) {
-      try {
-        const absPath = `${input.repoPath}/${handlerRow.file_path}`;
-        const st = statSync(absPath);
-        if (st.size <= MAX_FILE_BYTES) {
-          const source = readFileSync(absPath, 'utf-8');
-          middlewareChain = extractMiddlewareChain(source, handlerRow.name).middlewareNames;
-        }
-      } catch {
-        // File not found, unreadable, or too large — leave middlewareChain as []
-      }
-    }
-
-    return {
-      method,
-      path,
-      handlerName: handlerRow?.name ?? null,
-      handlerFile: handlerRow?.file_path ?? null,
-      handlerLine: handlerRow?.start_line ?? null,
-      routeNodeId,
-      middlewareChain,
-    };
-  });
-
-  return { routes, total: routes.length };
-}

package/src/mcp-tools/serve.ts

@@ -1,41 +0,0 @@
-import type Database from 'better-sqlite3';
-import { startServer, isServerRunning, getActiveUrl } from '../web/server.js';
-
-export interface ServeOptions {
-  port?: number;
-  open?: boolean;
-  db: Database.Database;
-}
-
-export interface ServeResult {
-  url: string;
-  status: 'started' | 'already_running';
-}
-
-/**
- * Start the Monograph web UI server.
- * If the server is already running, returns the existing URL.
- */
-export async function serveMonograph(options: ServeOptions): Promise<ServeResult> {
-  const { port = 7374, open = false, db } = options;
-
-  if (isServerRunning()) {
-    const url = getActiveUrl() ?? `http://localhost:${port}`;
-    return { url, status: 'already_running' };
-  }
-
-  const handle = await startServer({ port, db });
-
-  if (open) {
-    // Use spawn with an argument array to avoid shell injection via URL characters
-    const { spawn } = await import('child_process');
-    const [bin, ...args] = process.platform === 'win32'
-      ? ['cmd', '/c', 'start', '', handle.url]
-      : process.platform === 'darwin'
-        ? ['open', handle.url]
-        : ['xdg-open', handle.url];
-    spawn(bin as string, args, { stdio: 'ignore', detached: true }).unref();
-  }
-
-  return { url: handle.url, status: 'started' };
-}

package/src/mcp-tools/shape-check.ts

@@ -1,182 +0,0 @@
-import { readFileSync, statSync } from 'fs';
-import { join } from 'path';
-import type Database from 'better-sqlite3';
-import {
-  extractHandlerReturnKeys,
-  extractAccessedKeys,
-  compareShapes,
-  type RouteShape,
-} from '../analysis/shape-extractor.js';
-
-// ── Output types ───────────────────────────────────────────────────────────────
-
-export interface ShapeCheckResult {
-  route: {
-    path: string;
-    method: string;
-    handlerName: string;
-    handlerFile: string;
-  } | null;
-  shape: RouteShape;
-  consumers: { name: string; filePath: string }[];
-  message: string;
-}
-
-// ── Internal helpers ───────────────────────────────────────────────────────────
-
-const MAX_FILE_BYTES = 1_048_576; // 1 MiB guard
-
-function safeReadFile(absPath: string): string {
-  try {
-    const st = statSync(absPath);
-    if (st.size > MAX_FILE_BYTES) return '';
-    return readFileSync(absPath, 'utf-8');
-  } catch {
-    return '';
-  }
-}
-
-// ── Implementation ─────────────────────────────────────────────────────────────
-
-/**
- * Check whether the JSON shape returned by a route handler matches what its
- * consumers actually access.
- *
- * @param db        - Open monograph SQLite database
- * @param repoPath  - Absolute path to repository root (used to resolve file_path)
- * @param options   - `route` searches by route name/path substring;
- *                    `file` searches by exact file_path of the Route node
- */
-export function getShapeCheck(
-  db: Database.Database,
-  repoPath: string,
-  options: { route?: string; file?: string },
-): ShapeCheckResult {
-  const UNKNOWN_SHAPE: RouteShape = {
-    returnedKeys: [],
-    accessedKeys: [],
-    mismatches: [],
-    extra: [],
-    status: 'UNKNOWN',
-  };
-
-  // 1. Find the Route node
-  let routeRow: Record<string, unknown> | undefined;
-
-  if (options.file) {
-    routeRow = db
-      .prepare("SELECT * FROM nodes WHERE label = 'Route' AND file_path = ? LIMIT 1")
-      .get(options.file) as Record<string, unknown> | undefined;
-  } else if (options.route) {
-    // Search by name substring (name is like "GET /api/users") using SQL LIKE to avoid full scan
-    // The route path follows the first space, so we match anywhere after it via a LIKE pattern.
-    const likeTerm = `% ${options.route.toLowerCase()}%`;
-    routeRow = db
-      .prepare("SELECT * FROM nodes WHERE label = 'Route' AND lower(name) LIKE ? LIMIT 1")
-      .get(likeTerm) as Record<string, unknown> | undefined;
-
-    // Fallback: match anywhere in the name (e.g. no space prefix)
-    if (!routeRow) {
-      routeRow = db
-        .prepare("SELECT * FROM nodes WHERE label = 'Route' AND lower(name) LIKE ? LIMIT 1")
-        .get(`%${options.route.toLowerCase()}%`) as Record<string, unknown> | undefined;
-    }
-  }
-
-  if (!routeRow) {
-    return {
-      route: null,
-      shape: UNKNOWN_SHAPE,
-      consumers: [],
-      message: 'Route not found',
-    };
-  }
-
-  const routeId = routeRow.id as string;
-  const routeName = routeRow.name as string;
-  const spaceIdx = routeName.indexOf(' ');
-  const method = spaceIdx >= 0 ? routeName.slice(0, spaceIdx) : 'ANY';
-  const routePath = spaceIdx >= 0 ? routeName.slice(spaceIdx + 1) : routeName;
-
-  // 2. Follow HANDLES_ROUTE edge to find the handler function node
-  const handlerRow = db
-    .prepare(
-      `SELECT n.id, n.name, n.file_path FROM nodes n
-       JOIN edges e ON n.id = e.target_id
-       WHERE e.source_id = ? AND e.relation = 'HANDLES_ROUTE'
-       LIMIT 1`,
-    )
-    .get(routeId) as { id: string; name: string; file_path: string | null } | undefined;
-
-  if (!handlerRow || !handlerRow.file_path) {
-    return {
-      route: {
-        path: routePath,
-        method,
-        handlerName: handlerRow?.name ?? '',
-        handlerFile: handlerRow?.file_path ?? '',
-      },
-      shape: UNKNOWN_SHAPE,
-      consumers: [],
-      message: 'Handler not found or has no source file',
-    };
-  }
-
-  // 3. Read handler source and extract return keys
-  const handlerAbsPath = join(repoPath, handlerRow.file_path);
-  const handlerSource = safeReadFile(handlerAbsPath);
-  const returnedKeys = extractHandlerReturnKeys(handlerSource);
-
-  // 4. Find consumers: functions that CALLS or FETCHES the handler node,
-  //    or that FETCHES the Route node directly
-  const consumerRows = db
-    .prepare(
-      `SELECT DISTINCT n.id, n.name, n.file_path FROM nodes n
-       JOIN edges e ON n.id = e.source_id
-       WHERE (
-         (e.target_id = ? AND (e.relation = 'CALLS' OR e.relation = 'FETCHES'))
-         OR
-         (e.target_id = ? AND e.relation = 'FETCHES')
-       )
-       AND n.file_path IS NOT NULL`,
-    )
-    .all(handlerRow.id, routeId) as { id: string; name: string; file_path: string }[];
-
-  // 5. Extract accessed keys from each consumer's source
-  const allAccessedKeys = new Set<string>();
-
-  for (const consumer of consumerRows) {
-    const consumerAbsPath = join(repoPath, consumer.file_path);
-    const consumerSource = safeReadFile(consumerAbsPath);
-    const accessed = extractAccessedKeys(consumerSource);
-    for (const k of accessed) allAccessedKeys.add(k);
-  }
-
-  // 6. Compare shapes
-  const accessedKeys = Array.from(allAccessedKeys).sort();
-  const shape = compareShapes(returnedKeys, accessedKeys);
-
-  const consumers = consumerRows.map((c) => ({
-    name: c.name,
-    filePath: c.file_path,
-  }));
-
-  const statusMsg =
-    shape.status === 'MATCH'
-      ? 'Shape matches: all accessed keys are returned by handler'
-      : shape.status === 'MISMATCH'
-        ? `Shape mismatch: ${shape.mismatches.join(', ')} accessed but not returned`
-        : 'Shape unknown: insufficient source information';
-
-  return {
-    route: {
-      path: routePath,
-      method,
-      handlerName: handlerRow.name,
-      handlerFile: handlerRow.file_path,
-    },
-    shape,
-    consumers,
-    message: statusMsg,
-  };
-}

package/src/mcp-tools/staleness.ts

@@ -1,13 +0,0 @@
-import { openDb } from '../storage/db.js';
-import { checkStaleness, type StalenessReport } from '../staleness/git-staleness.js';
-
-export async function getMonographStaleness(repoPath: string): Promise<StalenessReport> {
-  const { join } = await import('path');
-  const dbPath = join(repoPath, '.monomind', 'monograph.db');
-  const db = openDb(dbPath);
-  try {
-    return checkStaleness(db, repoPath);
-  } finally {
-    db.close();
-  }
-}

package/src/mcp-tools/tool-map.ts

@@ -1,66 +0,0 @@
-import type Database from 'better-sqlite3';
-
-// ── Output types ───────────────────────────────────────────────────────────────
-
-export interface ToolEntry {
-  id: string;
-  name: string;
-  description: string | null;
-  filePath: string | null;
-  handlerName: string | null;
-  handlerFile: string | null;
-  handlerLine: number | null;
-}
-
-// ── Implementation ─────────────────────────────────────────────────────────────
-
-export function getToolMap(
-  db: Database.Database,
-  options?: { tool?: string },
-): ToolEntry[] {
-  const toolFilter = options?.tool ?? null;
-
-  const rows = db
-    .prepare(
-      `SELECT t.id, t.name, t.properties, t.file_path,
-              h.name as handler_name, h.file_path as handler_file, h.start_line as handler_line
-       FROM nodes t
-       LEFT JOIN edges e ON e.source_id = t.id AND e.relation = 'HANDLES_TOOL'
-       LEFT JOIN nodes h ON h.id = e.target_id
-       WHERE t.label = 'Tool'
-       AND (? IS NULL OR t.name LIKE '%' || ? || '%')
-       ORDER BY t.name
-       LIMIT 100`,
-    )
-    .all(toolFilter, toolFilter) as Array<{
-    id: string;
-    name: string;
-    properties: string | null;
-    file_path: string | null;
-    handler_name: string | null;
-    handler_file: string | null;
-    handler_line: number | null;
-  }>;
-
-  return rows.map((row) => {
-    let description: string | null = null;
-    if (row.properties) {
-      try {
-        const props = JSON.parse(row.properties) as Record<string, unknown>;
-        description = typeof props['description'] === 'string' ? props['description'] : null;
-      } catch {
-        // ignore malformed JSON
-      }
-    }
-
-    return {
-      id: row.id,
-      name: row.name,
-      description,
-      filePath: row.file_path ?? null,
-      handlerName: row.handler_name ?? null,
-      handlerFile: row.handler_file ?? null,
-      handlerLine: row.handler_line ?? null,
-    };
-  });
-}

package/src/mcp-tools/wiki-build.ts

@@ -1,37 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-import type { LlmClient, GenerateAllWikiPagesOptions } from '../wiki/wiki-generator.js';
-import { generateAllWikiPages } from '../wiki/wiki-generator.js';
-
-export interface WikiBuildToolInput {
-  communityId?: string;
-  force?: boolean;
-  model?: string;
-  /** Injected LLM client for testing (not part of MCP schema) */
-  llmClient?: LlmClient;
-}
-
-export interface WikiBuildToolResult {
-  generated?: number;
-  skipped?: number;
-  errors?: number;
-  error?: string;
-}
-
-/**
- * monograph_wiki_build MCP tool handler.
- * Generates wiki pages for communities using the LLM.
- */
-export async function runWikiBuildTool(
-  db: MonographDb,
-  input: WikiBuildToolInput,
-): Promise<WikiBuildToolResult> {
-  const opts: GenerateAllWikiPagesOptions = {
-    force: input.force ?? false,
-    model: input.model,
-    communityId: input.communityId,
-    llmClient: input.llmClient,
-  };
-
-  const result = await generateAllWikiPages(db, opts);
-  return result;
-}

package/src/mcp-tools/wiki.ts

@@ -1,28 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-import { getWikiPage, listWikiPages } from '../wiki/wiki-store.js';
-
-export interface WikiToolInput {
-  communityId?: string;
-}
-
-export interface WikiPage {
-  communityId: string;
-  content: string;
-  generatedAt: string;
-}
-
-export interface WikiToolResult {
-  pages: WikiPage[];
-}
-
-/**
- * monograph_wiki MCP tool handler.
- * Returns one wiki page (by communityId) or all pages.
- */
-export function getWikiToolResult(db: MonographDb, input: WikiToolInput): WikiToolResult {
-  if (input.communityId != null) {
-    const page = getWikiPage(db, String(input.communityId));
-    return { pages: page ? [page] : [] };
-  }
-  return { pages: listWikiPages(db) };
-}

package/src/migrate/jscpd.ts

@@ -1,78 +0,0 @@
-import { readFileSync, existsSync } from 'fs';
-export type { MigrationWarning } from './knip.js';
-import type { MigrationWarning } from './knip.js';
-
-export interface JscpdMigrationResult {
-  monographConfig: Record<string, unknown>;
-  warnings: MigrationWarning[];
-  inputFile: string;
-}
-
-const JSCPD_REPORTERS_WARNING = 'Use monograph --format sarif|codeclimate|markdown instead';
-
-export function migrateFromJscpd(jscpdConfigPath: string): JscpdMigrationResult {
-  if (!existsSync(jscpdConfigPath)) {
-    throw new Error(`jscpd config not found: ${jscpdConfigPath}`);
-  }
-
-  const raw = readFileSync(jscpdConfigPath, 'utf-8');
-  const warnings: MigrationWarning[] = [];
-  const monographConfig: Record<string, unknown> = {};
-
-  let jscpdConfig: Record<string, unknown>;
-  try {
-    jscpdConfig = JSON.parse(raw);
-  } catch {
-    warnings.push({
-      field: '<file>',
-      message: 'Failed to parse config as JSON',
-      knipValue: raw.slice(0, 100),
-    });
-    return { monographConfig, warnings, inputFile: jscpdConfigPath };
-  }
-
-  const knownFields = new Set([
-    'threshold',
-    'minTokens',
-    'ignore',
-    'reporters',
-    'languages',
-    'gitignore',
-  ]);
-
-  for (const [key, value] of Object.entries(jscpdConfig)) {
-    switch (key) {
-      case 'threshold':
-        monographConfig['cloneThreshold'] = value;
-        break;
-      case 'minTokens':
-        monographConfig['cloneMinTokens'] = value;
-        break;
-      case 'ignore':
-        monographConfig['exclude'] = value;
-        break;
-      case 'reporters':
-        warnings.push({
-          field: key,
-          message: JSCPD_REPORTERS_WARNING,
-          knipValue: value,
-        });
-        break;
-      case 'languages':
-        monographConfig['languages'] = value;
-        break;
-      case 'gitignore':
-        monographConfig['respectGitignore'] = value;
-        break;
-      default:
-        warnings.push({
-          field: key,
-          message: 'No equivalent in monograph config',
-          knipValue: value,
-        });
-        break;
-    }
-  }
-
-  return { monographConfig, warnings, inputFile: jscpdConfigPath };
-}