@monoes/monograph 1.1.0 → 1.2.0

package/src/parsers/named-bindings.ts

@@ -0,0 +1,63 @@
+export type BindingLanguage = 'typescript' | 'javascript' | 'python' | 'java' | 'kotlin' | 'go' | 'rust';
+
+export interface NamedBinding {
+  decoratorName: string;
+  targetName: string | null;
+  hasArguments: boolean;
+  line: number;
+  filePath: string;
+}
+
+const TS_DECORATOR_RE = /^([ \t]*)@([\w.]+)([ \t]*\()?/gm;
+const PY_DECORATOR_RE = /^([ \t]*)@([\w.]+)([ \t]*\()?/gm;
+const JAVA_ANNOTATION_RE = /^([ \t]*)@([A-Z]\w*)([ \t]*\()?/gm;
+
+function extractWithRegex(
+  source: string,
+  filePath: string,
+  re: RegExp,
+): NamedBinding[] {
+  const results: NamedBinding[] = [];
+  const lines = source.split('\n');
+  re.lastIndex = 0;
+
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source)) !== null) {
+    const charsBefore = source.slice(0, m.index);
+    const lineNum = (charsBefore.match(/\n/g)?.length ?? 0) + 1;
+    const nextLine = lines[lineNum] ?? '';
+
+    let targetName: string | null = null;
+    const targetMatch = /(?:class|def|function|public|private|protected|export)\s+(\w+)/.exec(nextLine);
+    if (targetMatch) targetName = targetMatch[1] ?? null;
+
+    results.push({
+      decoratorName: m[2]!,
+      targetName,
+      hasArguments: !!m[3]?.trim(),
+      line: lineNum,
+      filePath,
+    });
+  }
+
+  return results;
+}
+
+export function extractNamedBindings(
+  source: string,
+  filePath: string,
+  language: BindingLanguage,
+): NamedBinding[] {
+  switch (language) {
+    case 'typescript':
+    case 'javascript':
+      return extractWithRegex(source, filePath, TS_DECORATOR_RE);
+    case 'python':
+      return extractWithRegex(source, filePath, PY_DECORATOR_RE);
+    case 'java':
+    case 'kotlin':
+      return extractWithRegex(source, filePath, JAVA_ANNOTATION_RE);
+    default:
+      return [];
+  }
+}

package/src/parsers/php.ts

@@ -0,0 +1,37 @@
+import { createRequire } from 'module';
+import type { LanguageConfig } from './language-config.js';
+
+const require = createRequire(import.meta.url);
+
+export const phpConfig: LanguageConfig = {
+  name: 'php',
+  extensions: ['.php'],
+  treeSitterModule: 'tree-sitter-php',
+  getLanguage: () => {
+    const mod = require('tree-sitter-php');
+    // tree-sitter-php exports { php, php_only } — use the full PHP grammar
+    return mod.php as import('tree-sitter').Language;
+  },
+  classNodeTypes: new Set(['class_declaration']),
+  structNodeTypes: new Set([]),
+  enumNodeTypes: new Set(['enum_declaration']),
+  functionNodeTypes: new Set(['function_definition']),
+  methodNodeTypes: new Set(['method_declaration']),
+  constructorNodeTypes: new Set([]),
+  interfaceNodeTypes: new Set(['interface_declaration']),
+  importNodeTypes: new Set(['namespace_use_declaration']),
+  callNodeTypes: new Set(['function_call_expression', 'member_call_expression']),
+  decoratorNodeTypes: new Set([]),
+  nameField: 'name',
+  importExtractor: (_source, node) => {
+    // use App\Models\User; → extract qualified name
+    for (let i = 0; i < node.childCount; i++) {
+      const c = node.child(i)!;
+      if (c.type === 'namespace_use_clause') {
+        return c.text.trim() || null;
+      }
+    }
+    return null;
+  },
+  exportDetector: (_node, _source) => true,
+};

package/src/parsers/ruby.ts

@@ -0,0 +1,39 @@
+import { createRequire } from 'module';
+import type { LanguageConfig } from './language-config.js';
+
+const require = createRequire(import.meta.url);
+
+export const rubyConfig: LanguageConfig = {
+  name: 'ruby',
+  extensions: ['.rb'],
+  treeSitterModule: 'tree-sitter-ruby',
+  getLanguage: () => require('tree-sitter-ruby').language as import('tree-sitter').Language,
+  classNodeTypes: new Set(['class']),
+  structNodeTypes: new Set([]),
+  enumNodeTypes: new Set([]),
+  functionNodeTypes: new Set(['method']),
+  methodNodeTypes: new Set(['method']),
+  constructorNodeTypes: new Set([]),
+  interfaceNodeTypes: new Set(['module']),
+  // Ruby imports: require 'json' is a call expression at the top level
+  importNodeTypes: new Set(['call']),
+  callNodeTypes: new Set(['call']),
+  decoratorNodeTypes: new Set([]),
+  nameField: 'name',
+  importExtractor: (_source, node) => {
+    // Only extract 'require' and 'require_relative' calls
+    const receiver = node.child(0);
+    if (receiver?.text !== 'require' && receiver?.text !== 'require_relative') return null;
+    const args = node.childForFieldName('arguments') ?? node.child(1);
+    if (!args) return null;
+    // First argument is a string node
+    for (let i = 0; i < args.childCount; i++) {
+      const c = args.child(i)!;
+      if (c.type === 'string') {
+        return c.text.replace(/['"]/g, '');
+      }
+    }
+    return null;
+  },
+  exportDetector: (_node, _source) => true,
+};

package/src/parsers/swift.ts

@@ -0,0 +1,28 @@
+import { createRequire } from 'module';
+import type { LanguageConfig } from './language-config.js';
+
+const require = createRequire(import.meta.url);
+
+export const swiftConfig: LanguageConfig = {
+  name: 'swift',
+  extensions: ['.swift'],
+  treeSitterModule: 'tree-sitter-swift',
+  getLanguage: () => require('tree-sitter-swift').language as import('tree-sitter').Language,
+  classNodeTypes: new Set(['class_declaration']),
+  structNodeTypes: new Set(['struct_declaration']),
+  enumNodeTypes: new Set(['enum_declaration']),
+  functionNodeTypes: new Set(['function_declaration']),
+  methodNodeTypes: new Set(['function_declaration']),
+  constructorNodeTypes: new Set(['init_declaration']),
+  interfaceNodeTypes: new Set(['protocol_declaration']),
+  importNodeTypes: new Set(['import_declaration']),
+  callNodeTypes: new Set(['call_expression']),
+  decoratorNodeTypes: new Set(['attribute']),
+  nameField: 'name',
+  importExtractor: (_source, node) => {
+    // import Foundation → last child is identifier
+    const last = node.child(node.childCount - 1);
+    return last?.text ?? null;
+  },
+  exportDetector: (_node, _source) => true,
+};

package/src/parsers/vue.ts

@@ -0,0 +1,79 @@
+import { createRequire } from 'module';
+import type { LanguageConfig } from './language-config.js';
+
+/**
+ * Vue SFC parser.
+ *
+ * tree-sitter-vue (v0.2.1) fails to build on many platforms due to native compilation
+ * issues. This module provides a regex-based fallback that strips <template> and <style>
+ * blocks then delegates <script lang="ts"> content to the TypeScript node-type sets.
+ *
+ * The LanguageConfig below is configured to match TypeScript/JavaScript symbol types
+ * so the extractor correctly labels Classes, Functions, and Methods when fed the
+ * extracted script content.
+ */
+
+const require = createRequire(import.meta.url);
+
+function getLanguage(): import('tree-sitter').Language {
+  // Try tree-sitter-vue first; fall through to TypeScript grammar if unavailable.
+  try {
+    const mod = require('tree-sitter-vue');
+    const lang = (mod.default ?? mod) as import('tree-sitter').Language;
+    return lang;
+  } catch {
+    // Fall back to TypeScript grammar for script block parsing.
+    const ts = require('tree-sitter-typescript');
+    return ts.typescript as import('tree-sitter').Language;
+  }
+}
+
+export const vueConfig: LanguageConfig = {
+  name: 'vue',
+  extensions: ['.vue'],
+  treeSitterModule: 'tree-sitter-vue',
+  getLanguage,
+  // Use TypeScript-compatible node types since we parse the extracted script block
+  classNodeTypes: new Set(['class_declaration', 'class']),
+  structNodeTypes: new Set([]),
+  enumNodeTypes: new Set(['enum_declaration']),
+  functionNodeTypes: new Set([
+    'function_declaration', 'function', 'arrow_function',
+    'generator_function_declaration', 'generator_function',
+  ]),
+  methodNodeTypes: new Set(['method_definition', 'method_signature']),
+  constructorNodeTypes: new Set(['constructor']),
+  interfaceNodeTypes: new Set(['interface_declaration', 'type_alias_declaration']),
+  importNodeTypes: new Set(['import_statement', 'import_declaration']),
+  callNodeTypes: new Set(['call_expression', 'new_expression']),
+  decoratorNodeTypes: new Set(['decorator']),
+  nameField: 'name',
+  importExtractor: (_source, node) => {
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i)!;
+      if (child.type === 'string') {
+        return child.text.replace(/['"]/g, '');
+      }
+    }
+    return null;
+  },
+  exportDetector: (node, _source) => {
+    const parent = node.parent;
+    return parent?.type === 'export_statement' || parent?.type === 'export_default_declaration';
+  },
+};
+
+/**
+ * Extracts the <script> block content from a Vue SFC source string.
+ * Returns the inner content (stripping the <script> tags) and whether it is TypeScript.
+ */
+export function extractVueScriptContent(source: string): { content: string; isTypeScript: boolean } {
+  // Match <script lang="ts"> or <script setup lang="ts"> or just <script>
+  const tsMatch = source.match(/<script(?:\s+setup)?\s+lang=["']ts["'][^>]*>([\s\S]*?)<\/script>/i);
+  if (tsMatch) return { content: tsMatch[1], isTypeScript: true };
+
+  const jsMatch = source.match(/<script(?:\s+setup)?[^>]*>([\s\S]*?)<\/script>/i);
+  if (jsMatch) return { content: jsMatch[1], isTypeScript: false };
+
+  return { content: '', isTypeScript: false };
+}

package/src/pipeline/cluster-only.ts

@@ -0,0 +1,60 @@
+import type Database from 'better-sqlite3';
+import { loadGraphFromDb } from '../graph/loader.js';
+import { leiden } from './phases/leiden.js';
+import louvain from 'graphology-communities-louvain';
+
+export interface ClusterOnlyResult {
+  communityCount: number;
+  nodeCount: number;
+}
+
+/**
+ * Re-run community detection without re-extracting the full pipeline.
+ * Reads edges from the DB, runs Leiden (Louvain-based) community detection,
+ * and writes community_id assignments back to the nodes table.
+ */
+export async function runClusterOnly(db: Database.Database): Promise<ClusterOnlyResult> {
+  // Check if there are any edges at all
+  const edgeCount = (db.prepare('SELECT COUNT(*) as cnt FROM edges').get() as { cnt: number }).cnt;
+  if (edgeCount === 0) {
+    return { communityCount: 0, nodeCount: 0 };
+  }
+
+  // Build graphology graph from the DB
+  const graph = loadGraphFromDb(db as unknown as import('../storage/db.js').MonographDb);
+
+  if (graph.order === 0) {
+    return { communityCount: 0, nodeCount: 0 };
+  }
+
+  // Run community detection using Leiden (Louvain-based with refinement)
+  let communities: Record<string, number> = {};
+  try {
+    communities = leiden(graph, { seed: 42 });
+  } catch (e) {
+    console.warn('[monograph] Leiden failed in cluster-only, falling back to Louvain:', e);
+    try {
+      communities = louvain(graph, { randomWalk: false });
+    } catch {
+      // Assign all to community 0 as last resort
+      for (const nodeId of graph.nodes()) {
+        communities[nodeId] = 0;
+      }
+    }
+  }
+
+  // Write community assignments back to DB
+  const updateStmt = db.prepare('UPDATE nodes SET community_id = ? WHERE id = ?');
+  const updateAll = db.transaction(() => {
+    for (const [nodeId, commId] of Object.entries(communities)) {
+      updateStmt.run(commId, nodeId);
+    }
+  });
+  updateAll();
+
+  const communityIds = new Set(Object.values(communities));
+  return {
+    communityCount: communityIds.size,
+    nodeCount: Object.keys(communities).length,
+  };
+}

package/src/pipeline/effort.ts

@@ -0,0 +1,50 @@
+export type AnalysisEffort = 'low' | 'medium' | 'high';
+
+export interface EffortProfile {
+  runChurn: boolean;
+  runOwnership: boolean;
+  runHotspots: boolean;
+  runFileScores: boolean;
+  runSuffixArray: boolean;
+  runCrossReference: boolean;
+  maxFilesForExpensiveAnalysis: number;
+}
+
+const EFFORT_PROFILES: Record<AnalysisEffort, EffortProfile> = {
+  low: {
+    runChurn: false,
+    runOwnership: false,
+    runHotspots: false,
+    runFileScores: true,
+    runSuffixArray: false,
+    runCrossReference: false,
+    maxFilesForExpensiveAnalysis: 100,
+  },
+  medium: {
+    runChurn: true,
+    runOwnership: false,
+    runHotspots: true,
+    runFileScores: true,
+    runSuffixArray: false,
+    runCrossReference: true,
+    maxFilesForExpensiveAnalysis: 500,
+  },
+  high: {
+    runChurn: true,
+    runOwnership: true,
+    runHotspots: true,
+    runFileScores: true,
+    runSuffixArray: true,
+    runCrossReference: true,
+    maxFilesForExpensiveAnalysis: Infinity,
+  },
+};
+
+export function getEffortProfile(effort: AnalysisEffort = 'medium'): EffortProfile {
+  return EFFORT_PROFILES[effort];
+}
+
+export function parseEffort(s: string): AnalysisEffort {
+  if (s === 'low' || s === 'medium' || s === 'high') return s;
+  return 'medium';
+}

package/src/pipeline/orchestrator.ts

@@ -1,19 +1,39 @@
 import { resolve, join } from 'path';
+import { execSync } from 'child_process';
 import Graph from 'graphology';
 import { openDb, closeDb } from '../storage/db.js';
 import { PipelineRunner } from './runner.js';
 import { scanPhase } from './phases/scan.js';
 import { structurePhase } from './phases/structure.js';
 import { parsePhase } from './phases/parse.js';
+import { markdownPhase } from './phases/markdown.js';
+import { routesPhase } from './phases/routes.js';
+import { toolsPhase } from './phases/tools.js';
+import { ormPhase } from './phases/orm.js';
 import { crossFilePhase } from './phases/cross-file.js';
+import { scopeResolutionPhase } from './phases/scope-resolution.js';
 import { mroPhase } from './phases/mro.js';
 import { communitiesPhase } from './phases/communities.js';
+import { processesPhase } from './phases/processes.js';
 import { godNodesPhase } from './phases/god-nodes.js';
 import { surprisesPhase } from './phases/surprises.js';
 import { suggestPhase } from './phases/suggest.js';
+import { variablesPhase } from './phases/variables-phase.js';
+import { wildcardSynthesisPhase } from './phases/wildcard-phase.js';
+import { frameworkDetectPhase } from './phases/framework-detect.js';
+import { importResolverPhase } from './phases/import-resolver.js';
 import type { PipelineOptions, PipelineContext } from './types.js';
 import { DEFAULT_OPTIONS } from './types.js';
-import type { PipelineProgress } from '../types.js';
+import type { PipelineProgress, SuggestedQuestion } from '../types.js';
+import { generateGraphReport } from '../reporting/graph-report.js';
+
+function getCurrentCommitHash(repoPath: string): string | null {
+  try {
+    return execSync('git rev-parse HEAD', { cwd: repoPath, encoding: 'utf8' }).trim();
+  } catch {
+    return null;
+  }
+}
 
 export interface BuildOptions extends Partial<PipelineOptions> {
   onProgress?: (p: PipelineProgress) => void;
@@ -35,11 +55,22 @@ export async function buildAsync(repoPath: string, options: BuildOptions = {}):
     };
 
     const runner = new PipelineRunner([
-      scanPhase, structurePhase, parsePhase, crossFilePhase,
-      mroPhase, communitiesPhase, godNodesPhase, surprisesPhase, suggestPhase,
+      scanPhase, frameworkDetectPhase, structurePhase, parsePhase, variablesPhase,
+      markdownPhase, routesPhase, toolsPhase, ormPhase,
+      crossFilePhase, wildcardSynthesisPhase, importResolverPhase, scopeResolutionPhase,
+      mroPhase, communitiesPhase, processesPhase, godNodesPhase, surprisesPhase, suggestPhase,
     ]);
 
-    await runner.run(ctx);
+    const outputs = await runner.run(ctx);
+
+    const hash = getCurrentCommitHash(resolve(repoPath));
+    if (hash) {
+      db.prepare("INSERT OR REPLACE INTO index_meta VALUES ('last_commit_hash', ?)").run(hash);
+    }
+
+    const suggestOut = outputs.get('suggest') as { questions: SuggestedQuestion[] } | undefined;
+    const questions = suggestOut?.questions ?? [];
+    await generateGraphReport(resolve(repoPath), undefined, dbPath, questions);
   } finally {
     closeDb(db);
   }

package/src/pipeline/phases/boundary.ts

@@ -0,0 +1,113 @@
+import type Database from 'better-sqlite3';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export interface ZoneConfig {
+  name: string;
+  glob: string;
+}
+
+export interface MonographConfig {
+  zones?: ZoneConfig[];
+  allowedImports?: [string, string][];
+}
+
+export interface BoundaryViolation {
+  fromPath: string;
+  toPath: string;
+  fromZone: string;
+  toZone: string;
+  edgeRelation: string;
+}
+
+/**
+ * Convert a glob pattern to a regex.
+ * Handles: ** to .*, * to [^/]*, escapes other regex chars.
+ */
+function globToRegex(glob: string): RegExp {
+  const DOUBLE_STAR = '\x00DS\x00';
+  const pattern = glob
+    .replace(/\*\*/g, DOUBLE_STAR)
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '[^/]*')
+    .split(DOUBLE_STAR).join('.*');
+  return new RegExp('^' + pattern + '$');
+}
+
+/**
+ * Load .monographrc.json from repoRoot. Returns empty config if not found or invalid.
+ */
+export function loadMonographConfig(repoRoot: string): MonographConfig {
+  const configPath = join(repoRoot, '.monographrc.json');
+  if (!existsSync(configPath)) return {};
+  try {
+    const raw = readFileSync(configPath, 'utf-8');
+    return JSON.parse(raw) as MonographConfig;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Classify a file path into a zone name. Returns null if no zone matches.
+ */
+export function classifyZone(filePath: string, zones: ZoneConfig[]): string | null {
+  for (const zone of zones) {
+    const regex = globToRegex(zone.glob);
+    if (regex.test(filePath)) return zone.name;
+  }
+  return null;
+}
+
+/**
+ * Check all edges in the DB for boundary violations.
+ * Violations are cross-zone edges not present in the allowedImports allowlist.
+ * Intra-zone imports are always allowed.
+ * Returns [] if no .monographrc.json or no zones defined.
+ */
+export function detectBoundaryViolations(
+  db: Database.Database,
+  repoRoot: string,
+): BoundaryViolation[] {
+  const config = loadMonographConfig(repoRoot);
+
+  if (!config.zones || config.zones.length === 0) return [];
+
+  const zones = config.zones;
+  const allowedSet = new Set<string>(
+    (config.allowedImports ?? []).map(([from, to]) => `${from}→${to}`),
+  );
+
+  const rows = db.prepare(`
+    SELECT e.id, e.relation,
+           ns.file_path AS src_path,
+           nt.file_path AS tgt_path
+    FROM edges e
+    JOIN nodes ns ON ns.id = e.source_id
+    JOIN nodes nt ON nt.id = e.target_id
+    WHERE ns.file_path IS NOT NULL AND nt.file_path IS NOT NULL
+  `).all() as { id: string; relation: string; src_path: string; tgt_path: string }[];
+
+  const violations: BoundaryViolation[] = [];
+
+  for (const row of rows) {
+    const fromZone = classifyZone(row.src_path, zones);
+    const toZone = classifyZone(row.tgt_path, zones);
+
+    if (fromZone === null || toZone === null) continue;
+    if (fromZone === toZone) continue;
+
+    const key = `${fromZone}→${toZone}`;
+    if (!allowedSet.has(key)) {
+      violations.push({
+        fromPath: row.src_path,
+        toPath: row.tgt_path,
+        fromZone,
+        toZone,
+        edgeRelation: row.relation,
+      });
+    }
+  }
+
+  return violations;
+}

package/src/pipeline/phases/communities.ts

@@ -1,4 +1,5 @@
 import louvain from 'graphology-communities-louvain';
+import { leiden } from './leiden.js';
 import type { PipelinePhase, PipelineContext } from '../types.js';
 import type { MonographEdge } from '../../types.js';
 import { loadGraphFromEdges } from '../../graph/loader.js';
@@ -8,11 +9,40 @@ import type { ParseOutput } from './parse.js';
 export interface CommunitiesOutput {
   memberships: Map<string, number>;
   communityLabels: Map<number, string>;
+  cohesionScores: Map<number, number>;
+}
+
+export function computeCohesion(
+  communityId: number,
+  memberships: Map<string, number>,
+  edges: Array<{ sourceId: string; targetId: string }>,
+): number {
+  const members = [...memberships.entries()].filter(([, c]) => c === communityId).map(([id]) => id);
+  const n = members.length;
+  if (n <= 1) return 1;
+
+  const memberSet = new Set(members);
+  const maxEdges = (n * (n - 1)) / 2; // undirected: n*(n-1)/2
+  if (maxEdges === 0) return 1;
+
+  // Count unique undirected internal edges
+  const seen = new Set<string>();
+  let internalCount = 0;
+  for (const e of edges) {
+    if (memberSet.has(e.sourceId) && memberSet.has(e.targetId)) {
+      const key = [e.sourceId, e.targetId].sort().join('\0');
+      if (!seen.has(key)) {
+        seen.add(key);
+        internalCount++;
+      }
+    }
+  }
+  return internalCount / maxEdges;
 }
 
 export const communitiesPhase: PipelinePhase<CommunitiesOutput> = {
   name: 'communities',
-  deps: ['cross-file', 'mro'],
+  deps: ['parse', 'cross-file', 'mro'],
   async execute(_ctx, deps) {
     const { resolvedEdges } = deps.get('cross-file') as CrossFileOutput;
     const { allEdges } = deps.get('parse') as ParseOutput;
@@ -21,9 +51,14 @@ export const communitiesPhase: PipelinePhase<CommunitiesOutput> = {
     const graph = loadGraphFromEdges(allUsedEdges);
     let communities: Record<string, number> = {};
     try {
-      communities = louvain(graph);
-    } catch {
-      // Empty or disconnected graph
+      communities = leiden(graph, { seed: 42 });
+    } catch (e) {
+      console.warn('[monograph] Leiden failed, falling back to Louvain:', e);
+      try {
+        communities = louvain(graph, { randomWalk: false });
+      } catch {
+        // Empty or disconnected graph
+      }
     }
 
     const memberships = new Map<string, number>(Object.entries(communities).map(([k, v]) => [k, v]));
@@ -40,6 +75,25 @@ export const communitiesPhase: PipelinePhase<CommunitiesOutput> = {
       communityLabels.set(commId, `community-${commId}(${topNode.slice(0, 20)})`);
     }
 
-    return { memberships, communityLabels };
+    const communityIds = new Set([...memberships.values()]);
+    const cohesionScores = new Map<number, number>();
+    for (const cid of communityIds) {
+      cohesionScores.set(cid, computeCohesion(cid, memberships, allUsedEdges));
+    }
+
+    return { memberships, communityLabels, cohesionScores };
   },
 };
+
+/**
+ * Split a community that is too large into smaller sub-groups.
+ * By graphify convention, communities >25% of total graph nodes are split.
+ */
+export function splitOversizedCommunity(memberIds: string[], maxGroupSize: number): string[][] {
+  if (memberIds.length <= maxGroupSize) return [memberIds];
+  const groups: string[][] = [];
+  for (let i = 0; i < memberIds.length; i += maxGroupSize) {
+    groups.push(memberIds.slice(i, i + maxGroupSize));
+  }
+  return groups;
+}