@monoes/monograph 1.1.0 → 1.2.1

package/src/lsp/diagnostics.ts

@@ -0,0 +1,98 @@
+import type { LspRange } from './code-lens.js';
+
+export type DiagnosticSeverity = 1 | 2 | 3 | 4;  // Error | Warning | Information | Hint
+export type DiagnosticTag = 1 | 2;                // Unnecessary | Deprecated
+
+export interface RelatedInformation {
+  uri: string;
+  range: LspRange;
+  message: string;
+}
+
+export interface MonographDiagnostic {
+  range: LspRange;
+  severity: DiagnosticSeverity;
+  code: string;
+  source: string;
+  message: string;
+  tags?: DiagnosticTag[];
+  relatedInformation?: RelatedInformation[];
+}
+
+export interface DuplicateExportLocation {
+  uri: string;
+  line: number;   // 1-based
+  col: number;
+  exportName: string;
+}
+
+export interface DuplicateExportGroup {
+  name: string;
+  locations: DuplicateExportLocation[];
+}
+
+export interface StaleSuppressionInfo {
+  uri: string;
+  line: number;   // 1-based
+  description: string;
+}
+
+function makeRange(line: number, col: number, nameLength: number): LspRange {
+  return {
+    start: { line: line - 1, character: col - 1 },
+    end:   { line: line - 1, character: col - 1 + nameLength },
+  };
+}
+
+export function buildDuplicateExportDiagnostics(
+  groups: DuplicateExportGroup[],
+): Map<string, MonographDiagnostic[]> {
+  const map = new Map<string, MonographDiagnostic[]>();
+  for (const group of groups) {
+    for (const loc of group.locations) {
+      const related: RelatedInformation[] = group.locations
+        .filter(other => other !== loc)
+        .map(other => ({
+          uri: other.uri,
+          range: makeRange(other.line, other.col, group.name.length),
+          message: `Also exported as '${group.name}' here`,
+        }));
+      const diag: MonographDiagnostic = {
+        range: makeRange(loc.line, loc.col, group.name.length),
+        severity: 2,  // Warning
+        code: 'monograph/duplicate-export',
+        source: 'monograph',
+        message: `'${group.name}' is exported from ${group.locations.length} files`,
+        relatedInformation: related,
+      };
+      const arr = map.get(loc.uri) ?? [];
+      arr.push(diag);
+      map.set(loc.uri, arr);
+    }
+  }
+  return map;
+}
+
+export function buildStaleSuppressionDiagnostics(
+  suppressions: StaleSuppressionInfo[],
+): Map<string, MonographDiagnostic[]> {
+  const map = new Map<string, MonographDiagnostic[]>();
+  for (const s of suppressions) {
+    const range: LspRange = {
+      start: { line: s.line - 1, character: 0 },
+      end:   { line: s.line - 1, character: 65535 },
+    };
+    const diag: MonographDiagnostic = {
+      range,
+      severity: 4,  // Hint
+      code: 'monograph/stale-suppression',
+      source: 'monograph',
+      message: s.description,
+      tags: [1],  // Unnecessary
+    };
+    const arr = map.get(s.uri) ?? [];
+    arr.push(diag);
+    map.set(s.uri, arr);
+  }
+  return map;
+}

package/src/lsp/hover.ts

@@ -0,0 +1,64 @@
+import type { LspRange } from './code-lens.js';
+
+export interface MonographHover {
+  contents: string;   // Markdown
+  range?: LspRange;
+}
+
+export interface UnusedExportInfo {
+  exportName: string;
+  line: number;       // 1-based
+  col: number;
+  referenceCount: number;
+  suppressionHint?: string;
+}
+
+export interface DuplicationInfo {
+  line: number;       // 1-based
+  col: number;
+  groupSize: number;
+  instanceCount: number;
+  similarityScore: number;
+}
+
+export function buildHover(
+  unusedExports: UnusedExportInfo[],
+  duplication: DuplicationInfo[],
+  position: { line: number; character: number },  // 0-based LSP
+  filePath: string,
+): MonographHover | null {
+  const lspLine = position.line;
+
+  // Priority: unused export > duplication
+  for (const ue of unusedExports) {
+    if (ue.line - 1 === lspLine) {
+      const lines = [
+        `**Unused Export**: \`${ue.exportName}\``,
+        '',
+        `References found: **${ue.referenceCount}**`,
+        '',
+        ue.referenceCount === 0
+          ? 'This export has no detected consumers outside the current file.'
+          : 'This export may be consumed only internally.',
+      ];
+      if (ue.suppressionHint) lines.push('', `To suppress: ${ue.suppressionHint}`);
+      return { contents: lines.join('\n') };
+    }
+  }
+
+  for (const dup of duplication) {
+    if (dup.line - 1 === lspLine) {
+      const contents = [
+        `**Code Duplication Detected**`,
+        '',
+        `- Clone group size: **${dup.groupSize}** instances`,
+        `- Similarity: **${(dup.similarityScore * 100).toFixed(0)}%**`,
+        '',
+        'Consider extracting the duplicated logic into a shared function.',
+      ].join('\n');
+      return { contents };
+    }
+  }
+
+  return null;
+}

package/src/lsp/server.ts

@@ -0,0 +1,254 @@
+import { createInterface } from 'readline';
+import type { MonographDb } from '../storage/db.js';
+
+// Minimal LSP stdio server exposing monograph diagnostics
+// Start with: node server.js --db /path/to/monograph.db
+
+export interface LspDiagnostic {
+  uri: string;
+  range: { start: { line: number; character: number }; end: { line: number; character: number } };
+  severity: 1 | 2 | 3 | 4;   // Error=1, Warning=2, Information=3, Hint=4
+  source: 'monograph';
+  message: string;
+  code?: string;
+}
+
+const FILE_RANGE = {
+  start: { line: 0, character: 0 },
+  end: { line: 0, character: 0 },
+};
+
+export function buildDiagnosticsFromDb(db: MonographDb, repoRoot: string): Map<string, LspDiagnostic[]> {
+  const result = new Map<string, LspDiagnostic[]>();
+
+  const normRoot = repoRoot.replace(/\/$/, '');
+
+  function uriForPath(filePath: string): string {
+    if (filePath.startsWith('/')) {
+      return `file://${filePath}`;
+    }
+    return `file:///${normRoot}/${filePath}`.replace(/\/+/g, '/').replace(/^file:\/\/\//, 'file:///');
+  }
+
+  function addDiag(filePath: string, diag: LspDiagnostic): void {
+    const uri = uriForPath(filePath);
+    const list = result.get(uri) ?? [];
+    list.push(diag);
+    result.set(uri, list);
+  }
+
+  // Unreachable files → Warning
+  try {
+    const unreachableFiles = db.prepare(
+      `SELECT file_path FROM nodes
+       WHERE label = 'File'
+         AND json_extract(properties, '$.reachabilityRole') = 'unreachable'`
+    ).all() as { file_path: string }[];
+
+    for (const row of unreachableFiles) {
+      if (!row.file_path) continue;
+      const uri = uriForPath(row.file_path);
+      addDiag(row.file_path, {
+        uri,
+        range: FILE_RANGE,
+        severity: 2,
+        source: 'monograph',
+        message: 'Unreachable file: not imported by any runtime entry point',
+        code: 'unreachable-file',
+      });
+    }
+  } catch {
+    // Table or column not available; skip
+  }
+
+  // God nodes — query node_properties for the threshold used during build
+  try {
+    // Use p95 fan-in as the threshold (consistent with god-nodes pipeline phase)
+    const GOD_NODE_DEGREE_THRESHOLD = 10; // fallback if we can't compute from DB
+
+    const fanInRows = db.prepare(
+      `SELECT target_id, COUNT(*) as c FROM edges GROUP BY target_id`
+    ).all() as { target_id: string; c: number }[];
+
+    const sorted = fanInRows.map(r => r.c).sort((a, b) => a - b);
+    let threshold = GOD_NODE_DEGREE_THRESHOLD;
+    if (sorted.length > 0) {
+      const idx = Math.min(Math.floor(0.95 * sorted.length), sorted.length - 1);
+      threshold = sorted[idx];
+    }
+
+    const fanInByNode = new Map<string, number>();
+    for (const row of fanInRows) {
+      fanInByNode.set(row.target_id, row.c);
+    }
+
+    const godNodeRows = db.prepare(
+      `SELECT n.id, n.file_path, COUNT(e.source_id) as fan_in
+       FROM nodes n
+       JOIN edges e ON e.target_id = n.id
+       WHERE n.label = 'File'
+       GROUP BY n.id
+       HAVING COUNT(e.source_id) > ?`
+    ).all(threshold) as { id: string; file_path: string; fan_in: number }[];
+
+    const totalNodes = (db.prepare('SELECT COUNT(*) as n FROM nodes').get() as { n: number }).n;
+
+    for (const row of godNodeRows) {
+      if (!row.file_path) continue;
+      const pct = totalNodes > 0 ? Math.round((row.fan_in / totalNodes) * 100) : 0;
+      const uri = uriForPath(row.file_path);
+      addDiag(row.file_path, {
+        uri,
+        range: FILE_RANGE,
+        severity: 2,
+        source: 'monograph',
+        message: `God node: ${row.fan_in} incoming dependencies (p${pct})`,
+        code: 'god-node',
+      });
+    }
+  } catch {
+    // Skip if edges table not available
+  }
+
+  // STRUCTURALLY_SIMILAR edges → Information
+  try {
+    const similarEdges = db.prepare(
+      `SELECT e.source_id, e.target_id, e.confidence_score,
+              ns.file_path as source_path, nt.file_path as target_path
+       FROM edges e
+       JOIN nodes ns ON ns.id = e.source_id
+       JOIN nodes nt ON nt.id = e.target_id
+       WHERE e.relation = 'STRUCTURALLY_SIMILAR'`
+    ).all() as {
+      source_id: string;
+      target_id: string;
+      confidence_score: number;
+      source_path: string;
+      target_path: string;
+    }[];
+
+    for (const row of similarEdges) {
+      if (!row.source_path || !row.target_path) continue;
+      const score = Math.round((row.confidence_score ?? 0) * 100);
+      const uri = uriForPath(row.source_path);
+      addDiag(row.source_path, {
+        uri,
+        range: FILE_RANGE,
+        severity: 3,
+        source: 'monograph',
+        message: `Similar to ${row.target_path} (similarity: ${score}%)`,
+        code: 'structurally-similar',
+      });
+    }
+  } catch {
+    // Skip if not available
+  }
+
+  return result;
+}
+
+// LSP JSON-RPC 2.0 over stdio
+function writeMessage(msg: unknown): void {
+  const json = JSON.stringify(msg);
+  const header = `Content-Length: ${Buffer.byteLength(json, 'utf-8')}\r\n\r\n`;
+  process.stdout.write(header + json);
+}
+
+function sendResponse(id: number | string | null, result: unknown): void {
+  writeMessage({ jsonrpc: '2.0', id, result });
+}
+
+function sendNotification(method: string, params: unknown): void {
+  writeMessage({ jsonrpc: '2.0', method, params });
+}
+
+function publishDiagnostics(diagnosticsMap: Map<string, LspDiagnostic[]>): void {
+  for (const [uri, diagnostics] of diagnosticsMap) {
+    sendNotification('textDocument/publishDiagnostics', { uri, diagnostics });
+  }
+}
+
+export function startLspServer(db: MonographDb, repoRoot: string): void {
+  // Build diagnostics once on startup
+  const diagnosticsMap = buildDiagnosticsFromDb(db, repoRoot);
+
+  // LSP header framing: read Content-Length header, then body
+  let buffer = Buffer.alloc(0);
+  let expectedLength: number | null = null;
+
+  process.stdin.on('data', (chunk: Buffer) => {
+    buffer = Buffer.concat([buffer, chunk]);
+
+    while (true) {
+      if (expectedLength === null) {
+        // Try to parse headers
+        const headerEnd = buffer.indexOf('\r\n\r\n');
+        if (headerEnd === -1) break;
+
+        const headerStr = buffer.slice(0, headerEnd).toString('utf-8');
+        const contentLengthMatch = headerStr.match(/Content-Length:\s*(\d+)/i);
+        if (!contentLengthMatch) {
+          // Malformed; skip
+          buffer = buffer.slice(headerEnd + 4);
+          break;
+        }
+        expectedLength = parseInt(contentLengthMatch[1], 10);
+        buffer = buffer.slice(headerEnd + 4);
+      }
+
+      if (buffer.length < expectedLength) break;
+
+      const body = buffer.slice(0, expectedLength).toString('utf-8');
+      buffer = buffer.slice(expectedLength);
+      expectedLength = null;
+
+      let msg: { jsonrpc: string; id?: number | string; method?: string; params?: unknown };
+      try {
+        msg = JSON.parse(body);
+      } catch {
+        continue;
+      }
+
+      const { id, method } = msg;
+
+      switch (method) {
+        case 'initialize':
+          sendResponse(id ?? null, {
+            capabilities: {
+              textDocumentSync: 1,
+              diagnosticProvider: {},
+            },
+          });
+          break;
+
+        case 'initialized':
+          // Push all diagnostics on connection established
+          publishDiagnostics(diagnosticsMap);
+          break;
+
+        case 'shutdown':
+          sendResponse(id ?? null, null);
+          break;
+
+        case 'exit':
+          process.exit(0);
+          break;
+
+        default:
+          // Unhandled request — send method not found
+          if (id !== undefined && id !== null) {
+            writeMessage({
+              jsonrpc: '2.0',
+              id,
+              error: { code: -32601, message: 'Method not found' },
+            });
+          }
+          break;
+      }
+    }
+  });
+
+  process.stdin.on('end', () => {
+    process.exit(0);
+  });
+}

package/src/mcp/params.ts

@@ -0,0 +1,201 @@
+// Typed parameter schemas for all MCP tool endpoints.
+
+export type EmailModeParam = 'full' | 'domain' | 'name';
+export type AuditGate = 'new-only' | 'all';
+
+export interface AnalyzeParams {
+  root: string;
+  configPath?: string;
+  changedSince?: string;
+  workspaceFilter?: string[];
+  threads?: number;
+}
+
+export interface HealthParams extends AnalyzeParams {
+  minScore?: number;
+  groupBy?: 'owner' | 'directory' | 'package' | 'section';
+  minInvocationsHot?: number;
+  minObservationVolume?: number;
+  lowTrafficThreshold?: number;
+  emailMode?: EmailModeParam;
+  withRuntimeCoverage?: boolean;
+}
+
+export interface CheckRuntimeCoverageParams {
+  root: string;
+  environment?: string;
+  period?: string;
+  commitSha?: string;
+  minInvocationsHot?: number;
+  lowTrafficThreshold?: number;
+  reporter?: string;
+  minConfidence?: number;
+}
+
+export interface AuditParams extends AnalyzeParams {
+  gate?: AuditGate;
+  productionOverride?: boolean;
+  baselinePath?: string;
+  deadCodeBaselinePath?: string;
+  duplicationBaselinePath?: string;
+  complexityBaselinePath?: string;
+  reporter?: string;
+}
+
+export interface FindDupesParams extends AnalyzeParams {
+  mode?: 'default' | 'aggressive' | 'lenient';
+  minLines?: number;
+  minTokens?: number;
+  groupBy?: 'owner' | 'directory' | 'package' | 'section';
+}
+
+export interface TraceExportParams {
+  root: string;
+  filePath: string;
+  exportName: string;
+}
+
+export interface TraceFileParams {
+  root: string;
+  filePath: string;
+}
+
+export interface TraceDependencyParams {
+  root: string;
+  packageName: string;
+  from?: string;
+  to?: string;
+}
+
+export interface TraceCloneParams {
+  root: string;
+  filePath: string;
+  line: number;
+  groupId?: string;
+}
+
+export interface ProjectInfoParams {
+  root: string;
+  includeWorkspaces?: boolean;
+  reporter?: string;
+}
+
+export interface FeatureFlagsParams extends AnalyzeParams {
+  sdkFilter?: string[];
+  includeEnvVars?: boolean;
+  includeSdkCalls?: boolean;
+  includeConfigObjects?: boolean;
+  crossReferenceDeadCode?: boolean;
+  reporter?: string;
+}
+
+export interface ListBoundariesParams extends AnalyzeParams {
+  showEntryPoints?: boolean;
+  showRules?: boolean;
+  groupBy?: 'zone' | 'plugin';
+  reporter?: string;
+}
+
+export function isValidEmailMode(v: unknown): v is EmailModeParam {
+  return v === 'full' || v === 'domain' || v === 'name';
+}
+
+export function isValidAuditGate(v: unknown): v is AuditGate {
+  return v === 'new-only' || v === 'all';
+}
+
+// ── Round 9: extended MCP params ──────────────────────────────────────────────
+
+export interface CheckChangedMcpParams {
+  root: string;
+  gitRef?: string;
+  filters?: string[];
+  workspace?: string;
+  includeEntryFiles?: boolean;
+}
+
+export interface FixMcpParams {
+  root: string;
+  apply?: boolean;
+  filterUnused?: boolean;
+  filterDeps?: boolean;
+}
+
+export interface ExplainMcpParams {
+  ruleId: string;
+  verbose?: boolean;
+}
+
+export function isValidFixMode(mode: unknown): mode is 'preview' | 'apply' {
+  return mode === 'preview' || mode === 'apply';
+}
+
+// ── Round 10: extended MCP params ─────────────────────────────────────────────
+
+export interface ExtendedAnalyzeParams extends AnalyzeParams {
+  production?: boolean;
+  workspace?: string;
+  issueTypes?: string[];
+  boundaryViolations?: boolean;
+  baseline?: string;
+  saveBaseline?: boolean;
+  failOnRegression?: boolean;
+  tolerance?: number;
+  groupBy?: 'owner' | 'directory' | 'package' | 'section';
+  file?: string;
+  includeEntryExports?: boolean;
+  entryPatterns?: string[];
+  tsconfig?: string;
+  reporter?: string;
+  noGitignore?: boolean;
+}
+
+export interface ExtendedHealthParams extends HealthParams {
+  maxCyclomatic?: number;
+  maxCognitive?: number;
+  maxCrap?: number;
+  complexityThreshold?: number;
+  crapThreshold?: number;
+  reporter?: string;
+  includeHotspots?: boolean;
+  coverageFile?: string;
+  top?: number;
+  sort?: 'crap' | 'cyclomatic' | 'cognitive' | 'mi';
+  complexity?: boolean;
+  fileScores?: boolean;
+  hotspots?: boolean;
+  ownership?: boolean;
+  ownershipEmailMode?: 'fullEmail' | 'domainEmail' | 'displayName';
+  targets?: boolean;
+  coverageGaps?: boolean;
+  score?: boolean;
+  minScore?: number;
+  minSeverity?: 'moderate' | 'high' | 'critical';
+  since?: string;
+  minCommits?: number;
+  saveSnapshot?: boolean;
+  trend?: boolean;
+  summary?: boolean;
+  coverage?: string;
+  coverageRoot?: string;
+  groupBy?: 'owner' | 'directory' | 'package' | 'section';
+}
+
+export interface ExtendedFindDupesParams extends FindDupesParams {
+  threshold?: number;
+  skipLocal?: boolean;
+  crossLanguage?: boolean;
+  ignoreImports?: boolean;
+  explainSkipped?: boolean;
+  top?: number;
+  baseline?: string;
+  saveBaseline?: boolean;
+  changedSince?: string;
+  groupBy?: 'owner' | 'directory' | 'package' | 'section';
+  reporter?: string;
+}
+
+export interface GetHotPathsMcpParams { root: string; minRequestsPerDay?: number; limit?: number }
+export interface GetBlastRadiusMcpParams { root: string; filePath: string; limit?: number }
+export interface GetImportanceMcpParams { root: string; limit?: number; minScore?: number }
+export interface GetCleanupCandidatesMcpParams { root: string; maxCoveragePct?: number; limit?: number }

package/src/mcp/resources.ts

@@ -6,8 +6,15 @@ export interface MCPResource {
   handler: (uri: string) => Promise<{ content: string }>;
 }
 
+export interface MCPToolDef {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (input: Record<string, unknown>) => Promise<{ content: Array<{ type: 'text'; text: string }> }>;
+}
+
 import { openDb, closeDb } from '../storage/db.js';
-import { countNodes } from '../storage/node-store.js';
+import { countNodes, listProperties, queryByProperty } from '../storage/node-store.js';
 import { countEdges } from '../storage/edge-store.js';
 import { join } from 'path';
 
@@ -67,3 +74,51 @@ export const monographResources: MCPResource[] = [
     },
   },
 ];
+
+function text(t: string) {
+  return { content: [{ type: 'text' as const, text: t }] };
+}
+
+export const monographTools: MCPToolDef[] = [
+  {
+    name: 'monograph_list_properties',
+    description: 'List all registered typed property definitions in the node property registry, including their types, cardinalities, view contexts, and queryability.',
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => {
+      const db = openDb(getDbPath());
+      try {
+        const props = listProperties(db);
+        return text(JSON.stringify(props, null, 2));
+      } finally { closeDb(db); }
+    },
+  },
+  {
+    name: 'monograph_query_by_property',
+    description: 'Query nodes by a typed metadata property (layer, ua_type, complexity, tags, etc). Returns nodes whose JSON properties contain the given value for the named property.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ident: { type: 'string', description: 'Property identifier (e.g. layer, ua_type, complexity, tags, language)' },
+        value: { type: 'string', description: 'Value to match against the property' },
+        comparator: { type: 'string', enum: ['=', 'LIKE', '>', '<'], description: 'Comparison operator (default =)' },
+        limit: { type: 'number', description: 'Max results to return (default 100)' },
+      },
+      required: ['ident', 'value'],
+    },
+    handler: async (input) => {
+      const db = openDb(getDbPath());
+      try {
+        const ident = input.ident as string;
+        const value = input.value as string;
+        const comparator = (input.comparator as '=' | 'LIKE' | '>' | '<' | undefined) ?? '=';
+        const limit = (input.limit as number | undefined) ?? 100;
+        const results = queryByProperty(db, ident, value, comparator, limit);
+        if (results.length === 0) return text('No nodes found matching the given property value.');
+        const lines = results.map(r =>
+          `[${r.label}] ${r.name}  ${r.filePath ?? ''}  (${ident}=${JSON.stringify(r.propertyValue)})`,
+        );
+        return text(lines.join('\n'));
+      } finally { closeDb(db); }
+    },
+  },
+];