@monoes/monograph 1.5.6 → 1.5.8

package/src/check/rules.ts

@@ -1,61 +0,0 @@
-export type IssueSeverity = 'error' | 'warn' | 'off';
-
-export interface RuleEntry {
-  severity: IssueSeverity;
-  pattern?: string;
-}
-
-export interface RulesConfig {
-  unusedFiles?: IssueSeverity;
-  unusedExports?: IssueSeverity;
-  unusedDeps?: IssueSeverity;
-  unusedTypes?: IssueSeverity;
-  privateTypeLeaks?: IssueSeverity;
-  unusedEnumMembers?: IssueSeverity;
-  unusedClassMembers?: IssueSeverity;
-  unresolvedImports?: IssueSeverity;
-  unlistedDeps?: IssueSeverity;
-  duplicateExports?: IssueSeverity;
-  circularDeps?: IssueSeverity;
-  boundaryViolations?: IssueSeverity;
-  staleSuppressions?: IssueSeverity;
-}
-
-export type IssueKindKey = keyof RulesConfig;
-
-export interface AnalysisIssue {
-  kind: IssueKindKey;
-  filePath: string;
-  message: string;
-  severity?: IssueSeverity;
-}
-
-export function effectiveSeverity(kind: IssueKindKey, rules: RulesConfig): IssueSeverity {
-  return rules[kind] ?? 'error';
-}
-
-export function applyRules(issues: AnalysisIssue[], rules: RulesConfig): AnalysisIssue[] {
-  return issues
-    .filter(issue => effectiveSeverity(issue.kind, rules) !== 'off')
-    .map(issue => ({ ...issue, severity: effectiveSeverity(issue.kind, rules) }));
-}
-
-export function hasErrorSeverityIssues(issues: AnalysisIssue[], rules: RulesConfig): boolean {
-  return issues.some(issue => effectiveSeverity(issue.kind, rules) === 'error');
-}
-
-export const DEFAULT_RULES_CONFIG: RulesConfig = {
-  unusedFiles: 'error',
-  unusedExports: 'error',
-  unusedDeps: 'warn',
-  unusedTypes: 'warn',
-  privateTypeLeaks: 'warn',
-  unusedEnumMembers: 'warn',
-  unusedClassMembers: 'warn',
-  unresolvedImports: 'error',
-  unlistedDeps: 'warn',
-  duplicateExports: 'error',
-  circularDeps: 'warn',
-  boundaryViolations: 'error',
-  staleSuppressions: 'warn',
-};

package/src/ci-template.ts

@@ -1,84 +0,0 @@
-export type CiProvider = 'github' | 'gitlab';
-
-export interface CiTemplateOptions {
-  provider: CiProvider;
-  monographVersion?: string;   // default 'latest'
-  failOnNewDebt?: boolean;     // default true
-  healthThreshold?: string;    // e.g. 'B' — fail if below this grade
-}
-
-export interface CiTemplate {
-  filename: string;         // e.g. '.github/workflows/monograph.yml'
-  content: string;          // the YAML/config content
-  description: string;
-}
-
-// Grade letters that are >= a given threshold (A is highest, F is lowest)
-const GRADE_ORDER = ['A', 'B', 'C', 'D', 'F'];
-
-function gradesAtOrAbove(threshold: string): string {
-  const idx = GRADE_ORDER.indexOf(threshold.toUpperCase());
-  if (idx === -1) return threshold.toUpperCase();
-  return GRADE_ORDER.slice(0, idx + 1).join('');
-}
-
-export function generateCiTemplate(options: CiTemplateOptions): CiTemplate {
-  const version = options.monographVersion ?? 'latest';
-  const threshold = options.healthThreshold ?? 'B';
-  const acceptableGrades = gradesAtOrAbove(threshold);
-
-  if (options.provider === 'github') {
-    const content = `name: Monograph Graph Health
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-jobs:
-  monograph:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - name: Run monograph
-        run: npx @monoes/monograph@${version} build && npx @monoes/monograph@${version} health --format json > monograph-report.json
-      - name: Check health gate
-        run: |
-          GRADE=$(cat monograph-report.json | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8'); console.log(JSON.parse(d).grade)")
-          echo "Health grade: $GRADE"
-          [[ "$GRADE" =~ ^[${acceptableGrades}] ]] || (echo "Health below threshold ${threshold}" && exit 1)
-      - name: Upload report
-        uses: actions/upload-artifact@v4
-        with:
-          name: monograph-report
-          path: monograph-report.json
-`;
-
-    return {
-      filename: '.github/workflows/monograph.yml',
-      content,
-      description: 'GitHub Actions workflow that builds the Monograph graph, checks the health grade gate, and uploads the report as an artifact.',
-    };
-  }
-
-  // GitLab
-  const content = `monograph:
-  image: node:20
-  script:
-    - npx @monoes/monograph@${version} build
-    - npx @monoes/monograph@${version} health --format codeclimate > gl-code-quality-report.json
-  artifacts:
-    reports:
-      codequality: gl-code-quality-report.json
-`;
-
-  return {
-    filename: '.gitlab-ci.yml',
-    content,
-    description: 'GitLab CI job that builds the Monograph graph and publishes a Code Quality report via the codeclimate artifact.',
-  };
-}

package/src/claude-cli.ts

@@ -1,59 +0,0 @@
-/**
- * Thin wrapper around `claude --print` for LLM calls inside monograph.
- * Reuses Claude Code's existing auth — no ANTHROPIC_API_KEY needed.
- */
-import { spawn, execSync } from 'child_process';
-
-const DEFAULT_TIMEOUT_MS = 60_000;
-let _available: boolean | null = null;
-
-export function isClaudeCliAvailable(): boolean {
-  if (_available !== null) return _available;
-  try {
-    execSync('claude --version', { encoding: 'utf-8', stdio: 'pipe', timeout: 5000, windowsHide: true });
-    _available = true;
-  } catch {
-    _available = false;
-  }
-  return _available;
-}
-
-export function claudeCliCall(prompt: string, timeoutMs = DEFAULT_TIMEOUT_MS): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const child = spawn(
-      'claude',
-      ['--print', '--model', 'haiku', '--strict-mcp-config', '--no-session-persistence', '--', prompt],
-      { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true },
-    );
-
-    let stdout = '';
-    let stderr = '';
-    let settled = false;
-
-    const timer = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      try { child.kill('SIGTERM'); } catch { /* ignore */ }
-      setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* ignore */ } }, 3000);
-      reject(new Error(`claude --print timed out after ${timeoutMs}ms`));
-    }, timeoutMs);
-
-    child.stdout.on('data', (d: Buffer) => { stdout += d.toString(); });
-    child.stderr.on('data', (d: Buffer) => { stderr += d.toString(); });
-
-    child.on('close', (code) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (code === 0) resolve(stdout.trim());
-      else reject(new Error(stderr.trim() || `claude exited with code ${code}`));
-    });
-
-    child.on('error', (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      reject(err);
-    });
-  });
-}

package/src/cli/ai-context.ts

@@ -1,193 +0,0 @@
-/**
- * AI Context Injection
- *
- * Injects a natural-language description of monograph capabilities into
- * AGENTS.md and/or CLAUDE.md so AI agents (Claude Code, Cursor, Windsurf,
- * Copilot, Cline, etc.) understand how and when to use monograph tools.
- *
- * This is distinct from setup.ts which injects MCP server connection config.
- * Here the goal is agent comprehension: what monograph does, which tools to
- * call, and under what conditions — written in imperative prose that models
- * follow reliably.
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-
-// ─── Public types ─────────────────────────────────────────────────────────────
-
-export type AiContextTarget = 'claude' | 'agents-md';
-
-export interface AiContextOptions {
-  /** Absolute path to the repository root */
-  repoPath: string;
-  /** Which files to update. Defaults to both. */
-  targets?: AiContextTarget[];
-}
-
-export interface AiContextResult {
-  /** Files that were written or updated */
-  updated: string[];
-  /** Files skipped because the block was already present */
-  skipped: string[];
-  /** Files that could not be written (with reason) */
-  errors: string[];
-}
-
-// ─── Marker / sentinel ────────────────────────────────────────────────────────
-
-const START_MARKER = '<!-- monograph:context:start -->';
-const END_MARKER = '<!-- monograph:context:end -->';
-
-// Used for idempotency check without full marker parsing
-const SENTINEL = 'monograph:context:start';
-
-// ─── Content ──────────────────────────────────────────────────────────────────
-
-const AI_CONTEXT_BLOCK = `${START_MARKER}
-## Monograph — Code Intelligence
-
-This project is indexed by **Monograph**, a code knowledge graph that understands symbols, dependencies, and execution flows. Use the Monograph MCP tools to explore code, assess change impact, and navigate safely.
-
-> If any Monograph tool reports the index is stale, run \`monograph_build\` first.
-
-### Always Do
-
-- **MUST run \`monograph_impact\` before editing any symbol.** Before modifying a function, class, or method, call \`monograph_impact({name: "symbolName"})\` and report the blast radius (direct callers, risk level) to the user.
-- **MUST run \`monograph_detect_changes\` before committing** to verify changes only affect expected symbols.
-- **MUST warn the user** when impact analysis returns HIGH or CRITICAL risk.
-- When exploring unfamiliar code, use \`monograph_query({query: "concept"})\` to find relevant symbols instead of grepping.
-- When you need full context on a symbol — callers, callees, which community it belongs to — use \`monograph_context({name: "symbolName"})\`.
-
-### When to Use Each Tool
-
-| Situation | Tool |
-|-----------|------|
-| Understand architecture / "How does X work?" | \`monograph_query\`, \`monograph_context\` |
-| Blast radius / "What breaks if I change X?" | \`monograph_impact\` |
-| Trace bugs / "Why is X failing?" | \`monograph_context\`, \`monograph_cypher\` |
-| Rename / extract / split / refactor | \`monograph_rename\`, \`monograph_impact\` |
-| Find highly connected files | \`monograph_god_nodes\` |
-| Check index freshness | \`monograph_health\` |
-| Find all HTTP routes | \`monograph_route_map\` |
-
-### Never Do
-
-- NEVER edit a function, class, or method without first running \`monograph_impact\` on it.
-- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
-- NEVER rename symbols with find-and-replace — use \`monograph_rename\` which understands the call graph.
-- NEVER commit without running \`monograph_detect_changes\` to check the affected scope.
-${END_MARKER}`;
-
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-
-async function readFileSafe(filePath: string): Promise<string> {
-  try {
-    return await fs.readFile(filePath, 'utf-8');
-  } catch {
-    return '';
-  }
-}
-
-/**
- * Upsert the monograph AI context block in a markdown file.
- * - If absent: append the block.
- * - If present (by marker): replace the block so content stays current.
- * - Idempotent: a file with an up-to-date block is left unchanged.
- */
-async function upsertContextBlock(filePath: string): Promise<'updated' | 'skipped'> {
-  const existing = await readFileSafe(filePath);
-
-  // Fast idempotency check — if sentinel is absent the block is not there yet
-  if (!existing.includes(SENTINEL)) {
-    const updated = existing.trimEnd() + '\n\n' + AI_CONTEXT_BLOCK + '\n';
-    await fs.writeFile(filePath, updated, 'utf-8');
-    return 'updated';
-  }
-
-  // Block is already present. Replace it so the content stays fresh.
-  const startIdx = existing.indexOf(START_MARKER);
-  const endIdx = existing.indexOf(END_MARKER);
-
-  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    const before = existing.substring(0, startIdx);
-    const after = existing.substring(endIdx + END_MARKER.length);
-    const replaced = before + AI_CONTEXT_BLOCK + after;
-
-    // Only write if something actually changed
-    if (replaced === existing) return 'skipped';
-
-    await fs.writeFile(filePath, replaced.trimEnd() + '\n', 'utf-8');
-    return 'updated';
-  }
-
-  // Sentinel present but markers are malformed — skip to avoid corruption
-  return 'skipped';
-}
-
-// ─── Per-target handlers ──────────────────────────────────────────────────────
-
-async function handleClaude(repoPath: string, result: AiContextResult): Promise<void> {
-  const filePath = path.join(repoPath, 'CLAUDE.md');
-  try {
-    const outcome = await upsertContextBlock(filePath);
-    if (outcome === 'updated') {
-      result.updated.push('CLAUDE.md');
-    } else {
-      result.skipped.push('CLAUDE.md');
-    }
-  } catch (err: unknown) {
-    result.errors.push(`CLAUDE.md: ${(err as Error).message}`);
-  }
-}
-
-async function handleAgentsMd(repoPath: string, result: AiContextResult): Promise<void> {
-  const filePath = path.join(repoPath, 'AGENTS.md');
-  try {
-    const outcome = await upsertContextBlock(filePath);
-    if (outcome === 'updated') {
-      result.updated.push('AGENTS.md');
-    } else {
-      result.skipped.push('AGENTS.md');
-    }
-  } catch (err: unknown) {
-    result.errors.push(`AGENTS.md: ${(err as Error).message}`);
-  }
-}
-
-// ─── Public API ───────────────────────────────────────────────────────────────
-
-const ALL_TARGETS: AiContextTarget[] = ['claude', 'agents-md'];
-
-const TARGET_HANDLERS: Record<
-  AiContextTarget,
-  (repoPath: string, result: AiContextResult) => Promise<void>
-> = {
-  claude: handleClaude,
-  'agents-md': handleAgentsMd,
-};
-
-/**
- * Inject a natural-language monograph capabilities description into
- * AGENTS.md and/or CLAUDE.md so AI agents know how to use monograph tools.
- *
- * Running multiple times is safe: existing blocks are replaced in-place
- * (so the content stays current) and unchanged files are reported as skipped.
- *
- * @example
- * const result = await injectAiContext({ repoPath: '/path/to/repo' });
- * console.log(result.updated); // ['CLAUDE.md', 'AGENTS.md']
- */
-export async function injectAiContext(options: AiContextOptions): Promise<AiContextResult> {
-  const { repoPath, targets = ALL_TARGETS } = options;
-
-  const result: AiContextResult = {
-    updated: [],
-    skipped: [],
-    errors: [],
-  };
-
-  await Promise.all(targets.map((target) => TARGET_HANDLERS[target](repoPath, result)));
-
-  return result;
-}

package/src/cli/augment.ts

@@ -1,114 +0,0 @@
-/**
- * augmentContext — Graph-RAG context augmentation
- *
- * Given a query string, retrieves the top-K relevant nodes from the
- * monograph knowledge graph using hybrid BM25+vector search (falls back
- * to BM25 when embeddings are unavailable) and returns a formatted
- * context block suitable for injection into an AI prompt.
- *
- * Usable from both CLI entry points and the monograph_augment MCP tool.
- */
-
-import { join } from 'path';
-import { openDb, closeDb } from '../storage/db.js';
-import { hybridQuery, type HybridResult } from '../search/hybrid-query.js';
-import { globalAugmentCache } from '../cache/augment-cache.js';
-
-export interface AugmentContextOptions {
-  /** The search query or task description */
-  query: string;
-  /** Absolute path to the repository root */
-  repoPath: string;
-  /** Number of results to retrieve (default: 10) */
-  topK?: number;
-  /** Output format (default: 'markdown') */
-  format?: 'markdown' | 'json';
-}
-
-export interface AugmentContextResult {
-  query: string;
-  topK: number;
-  format: 'markdown' | 'json';
-  results: HybridResult[];
-  context: string;
-}
-
-/**
- * Retrieve the top-K relevant code nodes for a query and return a
- * formatted context string.
- */
-export async function augmentContext(options: AugmentContextOptions): Promise<string> {
-  const { query, repoPath, topK = 10, format = 'markdown' } = options;
-
-  if (!query || query.trim().length === 0) {
-    return format === 'json'
-      ? JSON.stringify({ query, results: [], context: '' }, null, 2)
-      : '';
-  }
-
-  if (topK === 0) {
-    return format === 'json'
-      ? JSON.stringify({ query, results: [], context: '' }, null, 2)
-      : '';
-  }
-
-  const cacheKey = globalAugmentCache.makeKey(query, repoPath, topK, format);
-  const cached = globalAugmentCache.get(cacheKey);
-  if (cached !== undefined) return cached;
-
-  const dbPath = join(repoPath, '.monomind', 'monograph.db');
-  const db = openDb(dbPath);
-
-  let results: HybridResult[];
-  try {
-    results = await hybridQuery(db, query, { limit: topK });
-  } finally {
-    closeDb(db);
-  }
-
-  if (results.length === 0) {
-    return format === 'json'
-      ? JSON.stringify({ query, results: [], context: 'No relevant code context found.' }, null, 2)
-      : 'No relevant code context found.';
-  }
-
-  if (format === 'json') {
-    return JSON.stringify(
-      {
-        query,
-        results: results.map((r) => ({
-          id: r.id,
-          label: r.label ?? null,
-          name: r.name ?? r.id,
-          filePath: r.filePath ?? null,
-          score: r.score,
-        })),
-      },
-      null,
-      2,
-    );
-  }
-
-  // Markdown format — include file:line navigation hints so LLMs can jump directly to code.
-  const lines: string[] = ['## Relevant Code Context', ''];
-
-  for (const r of results) {
-    const label = r.label ?? 'Symbol';
-    const name = r.name ?? r.id;
-    // Build a file:line reference when available so the LLM can navigate directly.
-    let location: string | null = null;
-    if (r.filePath) {
-      location = r.startLine != null ? `${r.filePath}:${r.startLine}` : r.filePath;
-    }
-    const scoreHint = `score=${r.score.toFixed(3)}`;
-    const heading = location
-      ? `### ${label}: \`${name}\` — \`${location}\` (${scoreHint})`
-      : `### ${label}: \`${name}\` (${scoreHint})`;
-    lines.push(heading);
-    lines.push('');
-  }
-
-  const output = lines.join('\n').trimEnd();
-  globalAugmentCache.set(cacheKey, output);
-  return output;
-}

package/src/cli/check-update.ts

@@ -1,40 +0,0 @@
-import type Database from 'better-sqlite3';
-
-export interface CheckUpdateOptions {
-  maxAgeMs?: number;
-}
-
-export interface CheckUpdateResult {
-  needsUpdate: boolean;
-  indexedAt: string | null;
-  ageMs: number;
-  reason: string;
-}
-
-export function checkUpdate(db: Database.Database, options: CheckUpdateOptions = {}): CheckUpdateResult {
-  const maxAgeMs = options.maxAgeMs ?? 24 * 60 * 60 * 1000; // 24h default
-
-  let indexedAt: string | null = null;
-  try {
-    const row = db.prepare("SELECT value FROM index_meta WHERE key = 'indexed_at'").get() as { value: string } | undefined;
-    indexedAt = row?.value ?? null;
-  } catch {
-    // table may not exist
-  }
-
-  if (!indexedAt) {
-    return { needsUpdate: true, indexedAt: null, ageMs: Infinity, reason: 'No index found' };
-  }
-
-  const ageMs = Date.now() - new Date(indexedAt).getTime();
-  const needsUpdate = ageMs > maxAgeMs;
-
-  return {
-    needsUpdate,
-    indexedAt,
-    ageMs,
-    reason: needsUpdate
-      ? `Index is ${Math.round(ageMs / 60000)}m old (max: ${Math.round(maxAgeMs / 60000)}m)`
-      : 'Index is fresh',
-  };
-}