@monoes/monograph 1.1.0 → 1.2.0

package/src/check/index.ts

@@ -0,0 +1,99 @@
+import type { RulesConfig, AnalysisIssue } from './rules.js';
+import { applyRules, hasErrorSeverityIssues, DEFAULT_RULES_CONFIG } from './rules.js';
+import type { OutputFormat, TraceOptions } from './output.js';
+import { filterToWorkspaces, resolveWorkspaceScope } from './filtering.js';
+
+export * from './rules.js';
+export * from './filtering.js';
+export * from './output.js';
+
+export interface IssueFilters {
+  unusedFiles: boolean;
+  unusedExports: boolean;
+  unusedDeps: boolean;
+  unusedTypes: boolean;
+  privateTypeLeaks: boolean;
+  unusedEnumMembers: boolean;
+  unusedClassMembers: boolean;
+  unresolvedImports: boolean;
+  unlistedDeps: boolean;
+  duplicateExports: boolean;
+  circularDeps: boolean;
+  boundaryViolations: boolean;
+  staleSuppressions: boolean;
+}
+
+export interface CheckOptions {
+  root: string;
+  configPath?: string;
+  output: OutputFormat;
+  noCache: boolean;
+  threads: number;
+  quiet: boolean;
+  failOnIssues: boolean;
+  filters: IssueFilters;
+  changedSince?: string;
+  baseline?: string;
+  saveBaseline?: string;
+  sarifFile?: string;
+  production: boolean;
+  productionOverride?: boolean;
+  workspace?: string[];
+  changedWorkspaces?: string;
+  trace?: TraceOptions;
+}
+
+export const DEFAULT_ISSUE_FILTERS: IssueFilters = {
+  unusedFiles: true,
+  unusedExports: true,
+  unusedDeps: true,
+  unusedTypes: true,
+  privateTypeLeaks: true,
+  unusedEnumMembers: true,
+  unusedClassMembers: true,
+  unresolvedImports: true,
+  unlistedDeps: true,
+  duplicateExports: true,
+  circularDeps: true,
+  boundaryViolations: true,
+  staleSuppressions: true,
+};
+
+export interface CheckResult {
+  issues: AnalysisIssue[];
+  hasErrors: boolean;
+  filteredByWorkspace: boolean;
+}
+
+export function runCheckFilter(
+  issues: AnalysisIssue[],
+  opts: Pick<CheckOptions, 'filters' | 'workspace' | 'changedWorkspaces' | 'root'>,
+  rules: RulesConfig = DEFAULT_RULES_CONFIG,
+  allWorkspaceRoots: string[] = [],
+): CheckResult {
+  let filtered = applyRules(issues, rules);
+
+  const activeFilters = opts.filters;
+  filtered = filtered.filter(issue => {
+    const key = issue.kind as keyof IssueFilters;
+    return activeFilters[key] !== false;
+  });
+
+  const wsRoots = resolveWorkspaceScope(
+    opts.root,
+    opts.workspace,
+    opts.changedWorkspaces,
+    allWorkspaceRoots,
+  );
+
+  const filteredByWorkspace = wsRoots.length > 0;
+  if (filteredByWorkspace) {
+    filtered = filterToWorkspaces(filtered, wsRoots);
+  }
+
+  return {
+    issues: filtered,
+    hasErrors: hasErrorSeverityIssues(filtered, rules),
+    filteredByWorkspace,
+  };
+}

package/src/check/output.ts

@@ -0,0 +1,79 @@
+import type { IssueSeverity, AnalysisIssue } from './rules.js';
+
+export type OutputFormat = 'text' | 'json' | 'compact';
+
+export interface TraceOptions {
+  traceExport?: string;
+  traceFile?: string;
+  traceDependency?: string;
+  performance: boolean;
+}
+
+export interface SarifOutput {
+  version: '2.1.0';
+  $schema: string;
+  runs: SarifRun[];
+}
+
+export interface SarifRun {
+  tool: { driver: { name: string; version: string; rules: SarifRule[] } };
+  results: SarifResult[];
+}
+
+export interface SarifRule {
+  id: string;
+  shortDescription: { text: string };
+  defaultConfiguration: { level: 'error' | 'warning' | 'note' };
+}
+
+export interface SarifResult {
+  ruleId: string;
+  level: 'error' | 'warning' | 'note';
+  message: { text: string };
+  locations: Array<{ physicalLocation: { artifactLocation: { uri: string }; region?: { startLine: number } } }>;
+}
+
+export function parseTraceSpec(spec: string): [string, string] | null {
+  const idx = spec.lastIndexOf(':');
+  if (idx <= 0) return null;
+  return [spec.slice(0, idx), spec.slice(idx + 1)];
+}
+
+export function buildSarifOutput(
+  issues: AnalysisIssue[],
+  toolVersion: string,
+): SarifOutput {
+  const ruleIds = [...new Set(issues.map(i => i.kind))];
+  const rules: SarifRule[] = ruleIds.map(id => ({
+    id,
+    shortDescription: { text: id },
+    defaultConfiguration: { level: 'warning' },
+  }));
+
+  const results: SarifResult[] = issues.map(issue => ({
+    ruleId: issue.kind,
+    level: issue.severity === 'error' ? 'error' : issue.severity === 'warn' ? 'warning' : 'note',
+    message: { text: issue.message },
+    locations: [{
+      physicalLocation: {
+        artifactLocation: { uri: issue.filePath.replace(/\\/g, '/') },
+      },
+    }],
+  }));
+
+  return {
+    version: '2.1.0',
+    $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+    runs: [{ tool: { driver: { name: 'monograph', version: toolVersion, rules } }, results }],
+  };
+}
+
+export function formatIssuesAsText(issues: AnalysisIssue[], quiet: boolean): string {
+  if (quiet && issues.length === 0) return '';
+  const lines = issues.map(i => `[${(i.severity ?? 'error').toUpperCase()}] ${i.filePath}: ${i.message}`);
+  return lines.join('\n');
+}
+
+export function formatIssuesAsJson(issues: AnalysisIssue[]): string {
+  return JSON.stringify({ issues }, null, 2);
+}

package/src/check/rules.ts

@@ -0,0 +1,61 @@
+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

@@ -0,0 +1,84 @@
+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/cli/ai-context.ts

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

@@ -0,0 +1,107 @@
+/**
+ * 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
+  const lines: string[] = ['## Relevant Code Context', ''];
+
+  for (const r of results) {
+    const label = r.label ?? 'Symbol';
+    const name = r.name ?? r.id;
+    const location = r.filePath ? `${r.filePath}` : null;
+    const heading = location ? `### ${label}: \`${name}\` (${location})` : `### ${label}: \`${name}\``;
+    lines.push(heading);
+    lines.push('');
+  }
+
+  const output = lines.join('\n').trimEnd();
+  globalAugmentCache.set(cacheKey, output);
+  return output;
+}

package/src/cli/check-update.ts

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