@monoes/monograph 1.5.6 → 1.5.8

package/src/groups/contract-registry.ts

@@ -1,263 +0,0 @@
-/**
- * Contract Registry
- *
- * Extracts HTTP contracts (Route nodes) from per-repo monograph databases,
- * identifies cross-repo links (same method + path in 2+ repos), and
- * persists/loads the registry in a SQLite database.
- */
-
-import { mkdirSync, existsSync } from 'fs';
-import { dirname } from 'path';
-import Database from 'better-sqlite3';
-
-// ── Public types ──────────────────────────────────────────────────────────────
-
-export interface HttpContract {
-  method: string;
-  path: string;
-  handlerName: string | null;
-  handlerFile: string | null;
-  repo: string;
-}
-
-export interface ContractLink {
-  path: string;
-  method: string;
-  producerRepo: string;
-  consumerRepos: string[];
-}
-
-// ── Internal types ────────────────────────────────────────────────────────────
-
-interface RouteRow {
-  name: string;
-  file_path: string | null;
-  handler_name: string | null;
-  handler_file: string | null;
-}
-
-interface ContractRow {
-  method: string;
-  path: string;
-  handler_name: string | null;
-  handler_file: string | null;
-  repo: string;
-}
-
-interface LinkRow {
-  path: string;
-  method: string;
-  producer_repo: string;
-  consumer_repos: string;
-}
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-/**
- * Parse a Route node name (format: "METHOD /path") into method and path.
- * Falls back gracefully if the format is unexpected.
- */
-function parseRouteName(name: string): { method: string; path: string } {
-  const spaceIdx = name.indexOf(' ');
-  if (spaceIdx === -1) {
-    return { method: 'ANY', path: name };
-  }
-  return {
-    method: name.slice(0, spaceIdx),
-    path: name.slice(spaceIdx + 1),
-  };
-}
-
-// ── Core functions ────────────────────────────────────────────────────────────
-
-/**
- * Extract all HTTP contracts (Route nodes) from a monograph database.
- *
- * Route nodes store method and path together in the `name` field as
- * `"METHOD /path"` (e.g., "GET /api/users"). The handler info is obtained by
- * following HANDLES_ROUTE edges where the Route node is the SOURCE.
- *
- * @param db       - Open better-sqlite3 database handle (read-only acceptable)
- * @param repoName - Logical name for this repo (used to tag returned contracts)
- * @returns Array of HttpContract objects
- */
-export function extractHttpContracts(db: Database.Database, repoName: string): HttpContract[] {
-  // Route is the source of HANDLES_ROUTE edges; handler is the target.
-  const rows = db
-    .prepare(
-      `SELECT
-         r.name        AS name,
-         r.file_path   AS file_path,
-         n.name        AS handler_name,
-         n.file_path   AS handler_file
-       FROM nodes r
-       LEFT JOIN edges e ON e.source_id = r.id AND e.relation = 'HANDLES_ROUTE'
-       LEFT JOIN nodes n ON n.id = e.target_id
-       WHERE r.label = 'Route'`,
-    )
-    .all() as RouteRow[];
-
-  return rows.map((row) => {
-    const { method, path } = parseRouteName(row.name);
-    return {
-      method,
-      path,
-      handlerName: row.handler_name ?? null,
-      handlerFile: row.handler_file ?? null,
-      repo: repoName,
-    };
-  });
-}
-
-/**
- * Group contracts by (method + path) and identify cross-repo links.
- *
- * A ContractLink is produced for every (method, path) pair that appears in
- * 2 or more repos. The first repo encountered for a given pair is treated as
- * the "producer"; all others become consumers. Repos are deduplicated via Set
- * so a repo appearing multiple times (e.g., two handlers for the same route)
- * is counted only once.
- *
- * @param contracts - Flat list of contracts from all repos
- * @returns Cross-repo contract links
- */
-export function buildContractLinks(contracts: HttpContract[]): ContractLink[] {
-  // key → ordered unique repos (first seen = producer)
-  const grouped = new Map<string, { repoOrder: string[]; repoSet: Set<string> }>();
-
-  for (const c of contracts) {
-    const key = `${c.method} ${c.path}`;
-    const existing = grouped.get(key);
-    if (existing) {
-      if (!existing.repoSet.has(c.repo)) {
-        existing.repoSet.add(c.repo);
-        existing.repoOrder.push(c.repo);
-      }
-    } else {
-      grouped.set(key, { repoOrder: [c.repo], repoSet: new Set([c.repo]) });
-    }
-  }
-
-  const links: ContractLink[] = [];
-  for (const [key, { repoOrder }] of grouped) {
-    if (repoOrder.length >= 2) {
-      const spaceIdx = key.indexOf(' ');
-      links.push({
-        method: key.slice(0, spaceIdx),
-        path: key.slice(spaceIdx + 1),
-        producerRepo: repoOrder[0],
-        consumerRepos: repoOrder.slice(1),
-      });
-    }
-  }
-
-  return links;
-}
-
-/**
- * Persist the contract registry to a SQLite file, overwriting any existing data.
- *
- * Tables created:
- *   - contracts (method, path, handler_name, handler_file, repo)
- *   - links     (path, method, producer_repo, consumer_repos TEXT — JSON array)
- *
- * @param registryPath - Absolute path to the target .contracts.db file
- * @param links        - Cross-repo contract links to store
- * @param contracts    - All individual contracts to store
- */
-export function saveContractRegistry(
-  registryPath: string,
-  links: ContractLink[],
-  contracts: HttpContract[],
-): void {
-  mkdirSync(dirname(registryPath), { recursive: true });
-
-  const db = new Database(registryPath);
-  try {
-    db.pragma('journal_mode = WAL');
-    db.exec(`
-      CREATE TABLE IF NOT EXISTS contracts (
-        method       TEXT NOT NULL,
-        path         TEXT NOT NULL,
-        handler_name TEXT,
-        handler_file TEXT,
-        repo         TEXT NOT NULL
-      );
-      CREATE TABLE IF NOT EXISTS links (
-        path           TEXT NOT NULL,
-        method         TEXT NOT NULL,
-        producer_repo  TEXT NOT NULL,
-        consumer_repos TEXT NOT NULL
-      );
-    `);
-
-    const insertContract = db.prepare(
-      `INSERT INTO contracts (method, path, handler_name, handler_file, repo)
-       VALUES (?, ?, ?, ?, ?)`,
-    );
-    const insertLink = db.prepare(
-      `INSERT INTO links (path, method, producer_repo, consumer_repos)
-       VALUES (?, ?, ?, ?)`,
-    );
-
-    // Truncate and repopulate atomically — DELETEs inside the transaction so a
-    // crash between clear and insert cannot leave the registry partially empty.
-    const storeAll = db.transaction(() => {
-      db.exec(`DELETE FROM contracts; DELETE FROM links;`);
-      for (const c of contracts) {
-        insertContract.run(c.method, c.path, c.handlerName, c.handlerFile, c.repo);
-      }
-      for (const l of links) {
-        insertLink.run(l.path, l.method, l.producerRepo, JSON.stringify(l.consumerRepos));
-      }
-    });
-
-    storeAll();
-  } finally {
-    db.close();
-  }
-}
-
-/**
- * Load a previously saved contract registry from disk.
- *
- * @param registryPath - Absolute path to the .contracts.db file
- * @returns Parsed contracts and links, or null if the file does not exist
- */
-export function loadContractRegistry(
-  registryPath: string,
-): { contracts: HttpContract[]; links: ContractLink[] } | null {
-  if (!existsSync(registryPath)) {
-    return null;
-  }
-
-  const db = new Database(registryPath, { readonly: true });
-  try {
-    const contractRows = db
-      .prepare(`SELECT method, path, handler_name, handler_file, repo FROM contracts`)
-      .all() as ContractRow[];
-
-    const linkRows = db
-      .prepare(`SELECT path, method, producer_repo, consumer_repos FROM links`)
-      .all() as LinkRow[];
-
-    const contracts: HttpContract[] = contractRows.map((r) => ({
-      method: r.method,
-      path: r.path,
-      handlerName: r.handler_name,
-      handlerFile: r.handler_file,
-      repo: r.repo,
-    }));
-
-    const links: ContractLink[] = linkRows.map((r) => ({
-      path: r.path,
-      method: r.method,
-      producerRepo: r.producer_repo,
-      consumerRepos: JSON.parse(r.consumer_repos) as string[],
-    }));
-
-    return { contracts, links };
-  } finally {
-    db.close();
-  }
-}

package/src/groups/group-config.ts

@@ -1,108 +0,0 @@
-/**
- * Group Config
- *
- * Parses a group.yaml file that describes a multi-repo group for cross-repo analysis.
- *
- * Format:
- *   name: my-org
- *   repos:
- *     backend: /path/to/backend
- *     frontend: /path/to/frontend
- */
-
-import { readFileSync, existsSync } from 'fs';
-
-export interface GroupRepo {
-  name: string;
-  path: string;
-}
-
-export interface GroupConfig {
-  name: string;
-  repos: GroupRepo[];
-}
-
-/**
- * Simple YAML key-value parser for the group.yaml format.
- * Handles top-level scalar keys and one level of indented key: value pairs.
- * Does not require any external yaml library.
- */
-function parseSimpleYaml(content: string): Record<string, unknown> {
-  const lines = content.split('\n');
-  const result: Record<string, unknown> = {};
-  let currentKey: string | null = null;
-  let currentMap: Record<string, string> | null = null;
-
-  for (const raw of lines) {
-    // Skip comments and blank lines
-    const line = raw.trimEnd();
-    if (!line || line.trimStart().startsWith('#')) continue;
-
-    const indent = line.length - line.trimStart().length;
-
-    if (indent === 0) {
-      // Top-level key
-      const match = line.match(/^(\w[\w-]*):\s*(.*)?$/);
-      if (!match) continue;
-
-      const key = match[1];
-      const val = (match[2] ?? '').trim();
-
-      if (val === '' || val === null) {
-        // This key will have children
-        currentMap = {};
-        currentKey = key;
-        result[key] = currentMap;
-      } else {
-        result[key] = val;
-        currentMap = null;
-        currentKey = null;
-      }
-    } else if (indent > 0 && currentMap !== null && currentKey !== null) {
-      // Indented child key-value
-      const trimmed = line.trimStart();
-      const match = trimmed.match(/^(\w[\w-]*):\s*(.*)?$/);
-      if (!match) continue;
-      currentMap[match[1]] = (match[2] ?? '').trim();
-    }
-  }
-
-  return result;
-}
-
-/**
- * Parse a group.yaml config file.
- * Missing or invalid repo paths are warned and skipped.
- *
- * @param configPath - Absolute path to group.yaml
- * @returns Parsed GroupConfig
- */
-export function parseGroupConfig(configPath: string): GroupConfig {
-  if (!existsSync(configPath)) {
-    throw new Error(`Group config not found: ${configPath}`);
-  }
-
-  const content = readFileSync(configPath, 'utf8');
-  const raw = parseSimpleYaml(content);
-
-  const name = (raw['name'] as string | undefined) ?? 'unnamed-group';
-  const reposRaw = raw['repos'];
-
-  const repos: GroupRepo[] = [];
-
-  if (reposRaw && typeof reposRaw === 'object' && !Array.isArray(reposRaw)) {
-    for (const [repoName, repoPath] of Object.entries(reposRaw as Record<string, string>)) {
-      if (typeof repoPath !== 'string' || !repoPath) {
-        console.warn(`[group-config] Skipping repo "${repoName}": missing path`);
-        continue;
-      }
-      if (!existsSync(repoPath)) {
-        console.warn(`[group-config] Skipping repo "${repoName}": path does not exist: ${repoPath}`);
-        continue;
-      }
-      repos.push({ name: repoName, path: repoPath });
-    }
-  }
-
-  return { name, repos };
-}

package/src/groups/group-search.ts

@@ -1,139 +0,0 @@
-/**
- * Group Search
- *
- * Merged BM25 search across multiple repos using Reciprocal Rank Fusion (RRF).
- */
-
-import { join } from 'path';
-import { existsSync } from 'fs';
-import Database from 'better-sqlite3';
-import { type RankedResult } from '../search/rrf.js';
-import { ftsSearch } from '../storage/fts-store.js';
-import type { GroupConfig } from './group-config.js';
-
-export interface GroupResult {
-  id: string;
-  name: string;
-  label: string;
-  filePath: string | null;
-  repo: string;
-  score: number;
-}
-
-/**
- * Determine the monograph DB path for a given repo root.
- * Mirrors the convention used in monograph-tools.ts: <repoPath>/.monomind/monograph.db
- */
-function getRepoDbPath(repoPath: string): string {
-  return join(repoPath, '.monomind', 'monograph.db');
-}
-
-/**
- * Run BM25 FTS5 search against a single repo DB.
- * Returns raw rows tagged with the repo name.
- */
-function searchRepo(
-  dbPath: string,
-  repoName: string,
-  query: string,
-  perRepoLimit: number,
-): (RankedResult & { name: string; label: string; filePath: string | null; repo: string })[] {
-  if (!existsSync(dbPath)) {
-    console.warn(`[group-search] Skipping repo "${repoName}": DB not found at ${dbPath}`);
-    return [];
-  }
-
-  let db: Database.Database | null = null;
-  try {
-    db = new Database(dbPath, { readonly: true });
-
-    // Reuse the SAME ftsSearch() the single-repo `monograph_query` tool uses —
-    // its trigram-aware sanitization and MATCH/LIKE fallback (P2-15) — instead of
-    // a divergent inline query that appended `*` as if this were a prefix-match
-    // tokenizer. The trigram index needs no prefix wildcard and errors on terms
-    // shorter than 3 chars when one is appended, which silently produced empty
-    // results here before.
-    const rows = ftsSearch(db, query, perRepoLimit);
-
-    return rows.map((r, idx) => ({
-      id: `${repoName}::${r.id}`,
-      name: r.name,
-      label: r.label,
-      filePath: r.filePath,
-      repo: repoName,
-      // Use rank position as initial score so RRF can compute correctly
-      score: 1 / (60 + idx + 1),
-    }));
-  } catch (err) {
-    console.warn(`[group-search] Error searching repo "${repoName}": ${err}`);
-    return [];
-  } finally {
-    db?.close();
-  }
-}
-
-/**
- * Search across all repos in a group and merge results using RRF.
- *
- * @param groupConfig - Parsed group configuration
- * @param query       - Search query string
- * @param options     - Optional limit (default 20)
- * @returns Merged and re-ranked results
- */
-export async function groupQuery(
-  groupConfig: GroupConfig,
-  query: string,
-  options?: { limit?: number },
-): Promise<GroupResult[]> {
-  const limit = options?.limit ?? 20;
-  const perRepoLimit = 50;
-
-  // Collect results from each repo
-  const repoResults: (RankedResult & {
-    name: string;
-    label: string;
-    filePath: string | null;
-    repo: string;
-  })[][] = [];
-
-  for (const repo of groupConfig.repos) {
-    const dbPath = getRepoDbPath(repo.path);
-    const results = searchRepo(dbPath, repo.name, query, perRepoLimit);
-    if (results.length > 0) {
-      repoResults.push(results);
-    }
-  }
-
-  if (repoResults.length === 0) return [];
-
-  // Merge all repo result lists using direct RRF accumulation (not pairwise fold).
-  // Pairwise folding distorts scores because items from earlier repos get re-ranked
-  // at their merged-list position on each fold iteration instead of their original rank.
-  type RepoResult = (typeof repoResults)[0][0];
-  const scoreMap = new Map<string, { rrf: number; payload: RepoResult }>();
-  for (const results of repoResults) {
-    for (let idx = 0; idx < results.length; idx++) {
-      const item = results[idx]!;
-      const contribution = 1 / (60 + idx + 1);
-      const existing = scoreMap.get(item.id);
-      if (existing) {
-        existing.rrf += contribution;
-      } else {
-        scoreMap.set(item.id, { rrf: contribution, payload: item });
-      }
-    }
-  }
-  const merged = [...scoreMap.values()]
-    .sort((a, b) => b.rrf - a.rrf)
-    .map(({ rrf, payload }) => ({ ...payload, score: rrf }));
-
-  // Build final output, preserving repo metadata from merged payload
-  return merged.slice(0, limit).map((r) => ({
-    id: r.id,
-    name: r.name ?? '',
-    label: r.label ?? '',
-    filePath: r.filePath ?? null,
-    repo: r.repo ?? '',
-    score: r.score,
-  }));
-}

package/src/groups/group-sync.ts

@@ -1,82 +0,0 @@
-/**
- * Group Sync
- *
- * Rebuilds the Contract Registry for a group by scanning each repo's
- * monograph database for Route nodes and finding cross-repo HTTP contracts.
- */
-
-import { join, dirname } from 'path';
-import { existsSync } from 'fs';
-import Database from 'better-sqlite3';
-import { parseGroupConfig } from './group-config.js';
-import { extractHttpContracts, buildContractLinks, saveContractRegistry } from './contract-registry.js';
-import type { HttpContract } from './contract-registry.js';
-
-// ── Public types ──────────────────────────────────────────────────────────────
-
-export interface GroupSyncResult {
-  group: string;
-  reposScanned: number;
-  contractsFound: number;
-  crossRepoLinks: number;
-  registryPath: string;
-}
-
-// ── Implementation ────────────────────────────────────────────────────────────
-
-/**
- * Rebuild the contract registry for a group defined by a group.yaml file.
- *
- * For each repo in the group, opens its monograph database and extracts HTTP
- * contracts. Cross-repo links are identified and persisted to a SQLite
- * registry at `<group_config_dir>/.monograph-group/<groupName>.contracts.db`.
- *
- * Repos whose database does not exist are warned and skipped.
- *
- * @param configPath - Absolute path to the group.yaml file
- * @returns Summary of what was synced
- */
-export async function syncGroup(configPath: string): Promise<GroupSyncResult> {
-  const config = parseGroupConfig(configPath);
-
-  const allContracts: HttpContract[] = [];
-  let reposScanned = 0;
-
-  for (const repo of config.repos) {
-    const dbPath = join(repo.path, '.monomind', 'monograph.db');
-    if (!existsSync(dbPath)) {
-      console.warn(`[group-sync] Skipping repo "${repo.name}": DB not found at ${dbPath}`);
-      continue;
-    }
-
-    let db: Database.Database | null = null;
-    try {
-      db = new Database(dbPath, { readonly: true });
-      const contracts = extractHttpContracts(db, repo.name);
-      allContracts.push(...contracts);
-      reposScanned++;
-    } catch (err) {
-      console.warn(`[group-sync] Error reading repo "${repo.name}": ${err}`);
-    } finally {
-      db?.close();
-    }
-  }
-
-  const links = buildContractLinks(allContracts);
-
-  const registryPath = join(
-    dirname(configPath),
-    '.monograph-group',
-    `${config.name}.contracts.db`,
-  );
-
-  saveContractRegistry(registryPath, links, allContracts);
-
-  return {
-    group: config.name,
-    reposScanned,
-    contractsFound: allContracts.length,
-    crossRepoLinks: links.length,
-    registryPath,
-  };
-}

package/src/groups/grpc-extractor.ts

@@ -1,64 +0,0 @@
-export type GrpcRole = 'provider' | 'consumer';
-
-export interface GrpcContract {
-  serviceName: string;
-  role: GrpcRole;
-  methods: string[];
-  filePath: string;
-  packageName?: string;
-}
-
-// Proto: service definition
-// Matches service bodies up to one level of nested braces (covers rpc Foo() returns (Bar) {})
-const PROTO_SERVICE_RE = /\bservice\s+(\w+)\s*\{((?:[^{}]|\{[^}]*\})*)\}/gs;
-const PROTO_RPC_RE = /\brpc\s+(\w+)\s*\(/g;
-const PROTO_PACKAGE_RE = /^package\s+([\w.]+);/m;
-
-// Consumer patterns
-const GO_CLIENT_RE = /\bNew(\w+)Client\s*\(/g;
-const NODE_CLIENT_RE = /new\s+(\w+)Client\s*\(/g;
-const PYTHON_STUB_RE = /\bpb2_grpc\.(\w+)Stub\s*\(/g;
-const JAVA_CLIENT_RE = /(\w+)Grpc\.new\w+Stub\s*\(/g;
-
-export function extractGrpcContracts(source: string, filePath: string): GrpcContract[] {
-  const results: GrpcContract[] = [];
-  const ext = filePath.split('.').pop()?.toLowerCase() ?? '';
-
-  if (ext === 'proto') {
-    const packageMatch = PROTO_PACKAGE_RE.exec(source);
-    const packageName = packageMatch?.[1];
-
-    PROTO_SERVICE_RE.lastIndex = 0;
-    let m: RegExpExecArray | null;
-    while ((m = PROTO_SERVICE_RE.exec(source)) !== null) {
-      const serviceName = m[1]!;
-      const body = m[2]!;
-      const methods: string[] = [];
-      PROTO_RPC_RE.lastIndex = 0;
-      let rpc: RegExpExecArray | null;
-      while ((rpc = PROTO_RPC_RE.exec(body)) !== null) {
-        methods.push(rpc[1]!);
-      }
-      results.push({ serviceName, role: 'provider', methods, filePath, packageName });
-    }
-    return results;
-  }
-
-  // Consumer detection by file type
-  const consumerPatterns: Array<[RegExp, string]> = [];
-  if (ext === 'go') consumerPatterns.push([GO_CLIENT_RE, 'Service']);
-  else if (['ts', 'js', 'mjs'].includes(ext)) consumerPatterns.push([NODE_CLIENT_RE, 'Service']);
-  else if (ext === 'py') consumerPatterns.push([PYTHON_STUB_RE, '']);
-  else if (['java', 'kt'].includes(ext)) consumerPatterns.push([JAVA_CLIENT_RE, '']);
-
-  for (const [re, suffix] of consumerPatterns) {
-    re.lastIndex = 0;
-    let m: RegExpExecArray | null;
-    while ((m = re.exec(source)) !== null) {
-      const name = m[1]! + suffix;
-      results.push({ serviceName: name, role: 'consumer', methods: [], filePath });
-    }
-  }
-
-  return results;
-}