@monoes/monograph 1.1.0 → 1.2.0

package/src/groups/contract-registry.ts

@@ -0,0 +1,263 @@
+/**
+ * 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

@@ -0,0 +1,108 @@
+/**
+ * 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

@@ -0,0 +1,157 @@
+/**
+ * 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 type { GroupConfig } from './group-config.js';
+
+export interface GroupResult {
+  id: string;
+  name: string;
+  label: string;
+  filePath: string | null;
+  repo: string;
+  score: number;
+}
+
+interface RawFtsRow {
+  id: string;
+  name: string;
+  label: string;
+  file_path: string | null;
+}
+
+/**
+ * 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 });
+
+    // Sanitize and build prefix query
+    const safeQuery = query.replace(/['"*]/g, ' ').trim();
+    if (!safeQuery) return [];
+
+    const ftsPrefixQuery = safeQuery
+      .split(/\s+/)
+      .map((t) => t + '*')
+      .join(' ');
+
+    const sql = `
+      SELECT n.id, n.name, n.label, n.file_path
+      FROM nodes_fts
+      JOIN nodes n ON n.rowid = nodes_fts.rowid
+      WHERE nodes_fts MATCH ?
+      ORDER BY nodes_fts.rank
+      LIMIT ?
+    `;
+
+    const rows = db.prepare(sql).all(ftsPrefixQuery, perRepoLimit) as RawFtsRow[];
+
+    return rows.map((r, idx) => ({
+      id: `${repoName}::${r.id}`,
+      name: r.name,
+      label: r.label,
+      filePath: r.file_path ?? null,
+      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

@@ -0,0 +1,82 @@
+/**
+ * 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

@@ -0,0 +1,64 @@
+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;
+}