@kodus/kodus-graph 0.2.8 → 0.2.10

package/dist/analysis/search.d.ts

@@ -0,0 +1,11 @@
+import type { IndexedGraph } from '../graph/loader';
+import type { GraphNode } from '../graph/types';
+export interface SearchOptions {
+    query?: string;
+    kind?: string;
+    file?: string;
+    limit?: number;
+}
+export declare function searchNodes(graph: IndexedGraph, opts: SearchOptions): GraphNode[];
+export declare function findCallers(graph: IndexedGraph, qualifiedName: string): GraphNode[];
+export declare function findCallees(graph: IndexedGraph, qualifiedName: string): GraphNode[];

package/dist/analysis/search.js

@@ -0,0 +1,64 @@
+export function searchNodes(graph, opts) {
+    const { query, kind, file, limit = 50 } = opts;
+    let results = graph.nodes;
+    if (query) {
+        const matcher = buildMatcher(query);
+        results = results.filter((n) => matcher(n.name) || matcher(n.qualified_name));
+    }
+    if (kind) {
+        results = results.filter((n) => n.kind === kind);
+    }
+    if (file) {
+        const fileMatcher = buildMatcher(file);
+        results = results.filter((n) => fileMatcher(n.file_path));
+    }
+    results.sort((a, b) => a.file_path.localeCompare(b.file_path) || a.line_start - b.line_start);
+    return results.slice(0, limit);
+}
+export function findCallers(graph, qualifiedName) {
+    const edges = graph.reverseAdjacency.get(qualifiedName) || [];
+    const callers = [];
+    for (const e of edges) {
+        if (e.kind !== 'CALLS') {
+            continue;
+        }
+        const node = graph.byQualified.get(e.source_qualified);
+        if (node) {
+            callers.push(node);
+        }
+    }
+    return callers;
+}
+export function findCallees(graph, qualifiedName) {
+    const edges = graph.adjacency.get(qualifiedName) || [];
+    const callees = [];
+    for (const e of edges) {
+        if (e.kind !== 'CALLS') {
+            continue;
+        }
+        const node = graph.byQualified.get(e.target_qualified);
+        if (node) {
+            callees.push(node);
+        }
+    }
+    return callees;
+}
+function buildMatcher(pattern) {
+    // Regex: /pattern/flags
+    if (pattern.startsWith('/')) {
+        const lastSlash = pattern.lastIndexOf('/');
+        if (lastSlash > 0) {
+            const regex = new RegExp(pattern.slice(1, lastSlash), pattern.slice(lastSlash + 1));
+            return (text) => regex.test(text);
+        }
+    }
+    // Glob: contains *
+    if (pattern.includes('*')) {
+        const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+        const regex = new RegExp(`^${escaped}$`, 'i');
+        return (text) => regex.test(text);
+    }
+    // Substring (case-insensitive)
+    const lower = pattern.toLowerCase();
+    return (text) => text.toLowerCase().includes(lower);
+}

package/dist/analysis/test-gaps.d.ts

@@ -0,0 +1,2 @@
+import type { GraphData, TestGap } from '../graph/types';
+export declare function findTestGaps(graph: GraphData, changedFiles: string[]): TestGap[];

package/dist/analysis/test-gaps.js

@@ -0,0 +1,14 @@
+export function findTestGaps(graph, changedFiles) {
+    const changedSet = new Set(changedFiles);
+    const testedFiles = new Set(graph.edges.filter((e) => e.kind === 'TESTED_BY').map((e) => e.source_qualified));
+    return graph.nodes
+        .filter((n) => changedSet.has(n.file_path) &&
+        (n.kind === 'Function' || n.kind === 'Method') &&
+        !n.is_test &&
+        !testedFiles.has(n.file_path))
+        .map((n) => ({
+        function: n.qualified_name,
+        file_path: n.file_path,
+        line_start: n.line_start,
+    }));
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env bun
+import { Command } from 'commander';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { executeAnalyze } from './commands/analyze';
+import { executeCommunities } from './commands/communities';
+import { executeContext } from './commands/context';
+import { executeDiff } from './commands/diff';
+import { executeFlows } from './commands/flows';
+import { executeParse } from './commands/parse';
+import { executeSearch } from './commands/search';
+import { executeUpdate } from './commands/update';
+const program = new Command();
+import pkg from '../package.json';
+import { log } from './shared/logger';
+log.info(`kodus-graph v${pkg.version}`, { node: process.version, platform: process.platform });
+program.name('kodus-graph').description('Code graph builder for Kodus code review').version(pkg.version);
+program
+    .command('parse')
+    .description('Parse source files and generate nodes + edges')
+    .option('--all', 'Parse all files in repo')
+    .option('--files <paths...>', 'Parse specific files')
+    .option('--repo-dir <path>', 'Repository root directory', '.')
+    .option('--include <glob...>', 'Include only files matching glob (repeatable)')
+    .option('--exclude <glob...>', 'Exclude files matching glob (repeatable)')
+    .option('--skip-tests', 'Skip test detection (no Test nodes, TESTED_BY edges, or test gaps)')
+    .option('--max-memory <mb>', 'Maximum memory usage in MB (default: 768)', (v) => parseInt(v, 10))
+    .requiredOption('--out <path>', 'Output JSON file path')
+    .action(async (opts) => {
+    const repoDir = resolve(opts.repoDir);
+    if (!existsSync(repoDir)) {
+        log.error('--repo-dir does not exist', { path: repoDir });
+        process.exit(1);
+    }
+    await executeParse({
+        repoDir: opts.repoDir,
+        files: opts.files,
+        all: opts.all ?? false,
+        out: opts.out,
+        include: opts.include,
+        exclude: opts.exclude,
+        skipTests: opts.skipTests ?? false,
+        maxMemoryMB: opts.maxMemory,
+    });
+});
+program
+    .command('analyze')
+    .description('Compute blast radius, risk score, and test gaps')
+    .requiredOption('--files <paths...>', 'Changed files to analyze')
+    .option('--repo-dir <path>', 'Repository root directory', '.')
+    .option('--graph <path>', 'Path to main graph JSON')
+    .option('--skip-tests', 'Skip test detection (no TESTED_BY edges or test gaps)')
+    .requiredOption('--out <path>', 'Output JSON file path')
+    .action(async (opts) => {
+    const repoDir = resolve(opts.repoDir);
+    if (!existsSync(repoDir)) {
+        log.error('--repo-dir does not exist', { path: repoDir });
+        process.exit(1);
+    }
+    await executeAnalyze({
+        repoDir: opts.repoDir,
+        files: opts.files,
+        graph: opts.graph,
+        out: opts.out,
+        skipTests: opts.skipTests ?? false,
+    });
+});
+program
+    .command('context')
+    .description('Generate enriched review context for agents')
+    .requiredOption('--files <paths...>', 'Changed files')
+    .option('--repo-dir <path>', 'Repository root directory', '.')
+    .option('--graph <path>', 'Path to main graph JSON')
+    .requiredOption('--out <path>', 'Output JSON file path')
+    .option('--min-confidence <n>', 'Minimum CALLS edge confidence', '0.5')
+    .option('--max-depth <n>', 'Blast radius BFS depth', '3')
+    .option('--format <type>', 'Output format: json or prompt', 'json')
+    .option('--skip-tests', 'Skip test detection (no Test nodes, TESTED_BY edges, or test gaps)')
+    .action(async (opts) => {
+    const repoDir = resolve(opts.repoDir);
+    if (!existsSync(repoDir)) {
+        log.error('--repo-dir does not exist', { path: repoDir });
+        process.exit(1);
+    }
+    if (opts.format !== 'json' && opts.format !== 'prompt') {
+        log.error('--format must be "json" or "prompt"', { got: opts.format });
+        process.exit(1);
+    }
+    await executeContext({
+        repoDir: opts.repoDir,
+        files: opts.files,
+        graph: opts.graph,
+        out: opts.out,
+        minConfidence: Number.parseFloat(opts.minConfidence),
+        maxDepth: Number.parseInt(opts.maxDepth, 10),
+        format: opts.format,
+        skipTests: opts.skipTests ?? false,
+    });
+});
+program
+    .command('diff')
+    .description('Compare changed files against an existing graph')
+    .option('--base <ref>', 'Git ref to diff against')
+    .option('--files <paths...>', 'Explicit list of changed files')
+    .option('--repo-dir <path>', 'Repository root directory', '.')
+    .option('--graph <path>', 'Previous graph JSON', '.kodus-graph/graph.json')
+    .requiredOption('--out <path>', 'Output JSON file path')
+    .action(async (opts) => {
+    if (!opts.base && !opts.files) {
+        log.error('one of --base or --files is required');
+        process.exit(1);
+    }
+    const repoDir = resolve(opts.repoDir);
+    if (!existsSync(repoDir)) {
+        log.error('--repo-dir does not exist', { path: repoDir });
+        process.exit(1);
+    }
+    await executeDiff({
+        repoDir: opts.repoDir,
+        base: opts.base,
+        files: opts.files,
+        graph: opts.graph,
+        out: opts.out,
+    });
+});
+program
+    .command('update')
+    .description('Incrementally update graph (only re-parse changed files)')
+    .option('--repo-dir <path>', 'Repository root directory', '.')
+    .option('--graph <path>', 'Previous graph JSON (default: .kodus-graph/graph.json)')
+    .option('--out <path>', 'Output path (default: same as --graph)')
+    .action(async (opts) => {
+    const repoDir = resolve(opts.repoDir);
+    if (!existsSync(repoDir)) {
+        log.error('--repo-dir does not exist', { path: repoDir });
+        process.exit(1);
+    }
+    await executeUpdate({
+        repoDir: opts.repoDir,
+        graph: opts.graph,
+        out: opts.out,
+    });
+});
+program
+    .command('communities')
+    .description('Detect module clusters and coupling between them')
+    .requiredOption('--graph <path>', 'Path to graph JSON')
+    .requiredOption('--out <path>', 'Output JSON file path')
+    .option('--min-size <n>', 'Minimum nodes per community', '2')
+    .option('--depth <n>', 'Directory grouping depth', '2')
+    .action((opts) => {
+    executeCommunities({
+        graph: opts.graph,
+        out: opts.out,
+        minSize: parseInt(opts.minSize, 10),
+        depth: parseInt(opts.depth, 10),
+    });
+});
+program
+    .command('flows')
+    .description('Detect entry points and trace execution paths')
+    .requiredOption('--graph <path>', 'Path to graph JSON')
+    .requiredOption('--out <path>', 'Output JSON file path')
+    .option('--max-depth <n>', 'Max BFS trace depth', '10')
+    .option('--type <kind>', 'Filter: test, http, all', 'all')
+    .action((opts) => {
+    executeFlows({
+        graph: opts.graph,
+        out: opts.out,
+        maxDepth: parseInt(opts.maxDepth, 10),
+        type: opts.type,
+    });
+});
+program
+    .command('search')
+    .description('Search the graph by name, kind, file, or relations')
+    .requiredOption('--graph <path>', 'Path to graph JSON')
+    .option('--query <pattern>', 'Search by name/qualified_name (glob or /regex/)')
+    .option('--kind <type>', 'Filter by kind: Function, Method, Class, Interface, Enum, Test')
+    .option('--file <pattern>', 'Filter by file path (glob)')
+    .option('--callers-of <qualified>', 'Find callers of this node')
+    .option('--callees-of <qualified>', 'Find callees of this node')
+    .option('--limit <n>', 'Max results', '50')
+    .option('--out <path>', 'Output file (default: stdout)')
+    .action((opts) => {
+    const modes = [opts.query, opts.callersOf, opts.calleesOf].filter(Boolean).length;
+    if (modes === 0) {
+        log.error('one of --query, --callers-of, or --callees-of is required');
+        process.exit(1);
+    }
+    if (modes > 1) {
+        log.error('--query, --callers-of, and --callees-of are mutually exclusive');
+        process.exit(1);
+    }
+    executeSearch({
+        graph: opts.graph,
+        query: opts.query,
+        kind: opts.kind,
+        file: opts.file,
+        callersOf: opts.callersOf,
+        calleesOf: opts.calleesOf,
+        limit: parseInt(opts.limit, 10),
+        out: opts.out,
+    });
+});
+program.parseAsync().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(message);
+    process.exit(1);
+});

package/dist/commands/analyze.d.ts

@@ -0,0 +1,9 @@
+interface AnalyzeOptions {
+    repoDir: string;
+    files: string[];
+    graph?: string;
+    out: string;
+    skipTests?: boolean;
+}
+export declare function executeAnalyze(opts: AnalyzeOptions): Promise<void>;
+export {};

package/dist/commands/analyze.js

@@ -0,0 +1,116 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { relative, resolve } from 'path';
+import { computeBlastRadius } from '../analysis/blast-radius';
+import { computeRiskScore } from '../analysis/risk-score';
+import { findTestGaps } from '../analysis/test-gaps';
+import { buildGraphData } from '../graph/builder';
+import { mergeGraphs } from '../graph/merger';
+import { parseBatch } from '../parser/batch';
+import { discoverFiles } from '../parser/discovery';
+import { resolveAllCalls } from '../resolver/call-resolver';
+import { createImportMap } from '../resolver/import-map';
+import { loadTsconfigAliases, resolveImport } from '../resolver/import-resolver';
+import { buildReExportMap } from '../resolver/re-export-resolver';
+import { createSymbolTable } from '../resolver/symbol-table';
+import { computeFileHash } from '../shared/file-hash';
+import { log } from '../shared/logger';
+import { GraphInputSchema } from '../shared/schemas';
+export async function executeAnalyze(opts) {
+    const repoDir = resolve(opts.repoDir);
+    // Load main graph if provided
+    let mainGraph = null;
+    if (opts.graph) {
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(opts.graph, 'utf-8'));
+        }
+        catch (_err) {
+            log.error('failed to read --graph file', { path: opts.graph });
+            process.exit(1);
+        }
+        const validated = GraphInputSchema.safeParse(raw);
+        if (!validated.success) {
+            log.error('invalid graph JSON', { error: validated.error.message });
+            process.exit(1);
+        }
+        mainGraph = {
+            repo_id: '',
+            sha: '',
+            nodes: validated.data.nodes,
+            edges: validated.data.edges,
+        };
+    }
+    // Parse changed files locally
+    const localFiles = discoverFiles(repoDir, opts.files);
+    const rawGraph = await parseBatch(localFiles, repoDir, { skipTests: opts.skipTests });
+    // Resolve imports
+    const tsconfigAliases = loadTsconfigAliases(repoDir);
+    const symbolTable = createSymbolTable();
+    const importMap = createImportMap();
+    const importEdges = [];
+    for (const f of rawGraph.functions) {
+        symbolTable.add(f.file, f.name, f.qualified);
+    }
+    for (const c of rawGraph.classes) {
+        symbolTable.add(c.file, c.name, c.qualified);
+    }
+    for (const i of rawGraph.interfaces) {
+        symbolTable.add(i.file, i.name, i.qualified);
+    }
+    // Pre-resolve re-exports so barrel imports follow through to actual definitions
+    const barrelMap = buildReExportMap(rawGraph.reExports, repoDir, tsconfigAliases);
+    for (const imp of rawGraph.imports) {
+        const langKey = imp.lang;
+        const resolved = resolveImport(resolve(repoDir, imp.file), imp.module, langKey, repoDir, tsconfigAliases);
+        const resolvedRel = resolved ? relative(repoDir, resolved) : null;
+        importEdges.push({
+            source: imp.file,
+            target: resolvedRel || imp.module,
+            resolved: !!resolvedRel,
+            line: imp.line,
+        });
+        const target = resolvedRel || imp.module;
+        for (const name of imp.names) {
+            let finalTarget = target;
+            if (resolvedRel) {
+                const reExportedFiles = barrelMap.get(resolvedRel);
+                if (reExportedFiles) {
+                    for (const reFile of reExportedFiles) {
+                        if (symbolTable.lookupExact(reFile, name)) {
+                            finalTarget = reFile;
+                            break;
+                        }
+                    }
+                }
+            }
+            importMap.add(imp.file, name, finalTarget);
+        }
+    }
+    // Resolve calls
+    const { callEdges } = resolveAllCalls(rawGraph.rawCalls, rawGraph.diMaps, symbolTable, importMap);
+    // Build graph with file hashes
+    const fileHashes = new Map();
+    for (const f of localFiles) {
+        try {
+            fileHashes.set(relative(repoDir, f), computeFileHash(f));
+        }
+        catch (err) {
+            log.warn('Failed to compute file hash', { file: f, error: String(err) });
+        }
+    }
+    const localGraphData = buildGraphData(rawGraph, callEdges, importEdges, repoDir, fileHashes, symbolTable, importMap);
+    // Merge with main graph (or use local only)
+    const mergedGraph = mainGraph ? mergeGraphs(mainGraph, localGraphData, opts.files) : localGraphData;
+    // Analyze
+    // Temporary: convert file-level to function-level until Mudança 3 provides trulyChangedQN
+    const changedQN = mergedGraph.nodes.filter((n) => opts.files.includes(n.file_path)).map((n) => n.qualified_name);
+    const blastRadius = computeBlastRadius(mergedGraph, changedQN);
+    const riskScore = computeRiskScore(mergedGraph, opts.files, blastRadius, { skipTests: opts.skipTests });
+    const testGaps = opts.skipTests ? [] : findTestGaps(mergedGraph, opts.files);
+    const output = {
+        blast_radius: blastRadius,
+        risk_score: riskScore,
+        test_gaps: testGaps,
+    };
+    writeFileSync(opts.out, JSON.stringify(output, null, 2));
+}

package/dist/commands/communities.d.ts

@@ -0,0 +1,8 @@
+interface CommunitiesCommandOptions {
+    graph: string;
+    out: string;
+    minSize: number;
+    depth: number;
+}
+export declare function executeCommunities(opts: CommunitiesCommandOptions): void;
+export {};

package/dist/commands/communities.js

@@ -0,0 +1,9 @@
+import { writeFileSync } from 'fs';
+import { detectCommunities } from '../analysis/communities';
+import { loadGraph } from '../graph/loader';
+export function executeCommunities(opts) {
+    const graph = loadGraph(opts.graph);
+    const result = detectCommunities(graph, { depth: opts.depth, minSize: opts.minSize });
+    writeFileSync(opts.out, JSON.stringify(result, null, 2));
+    process.stderr.write(`Communities: ${result.summary.total_communities} detected, avg cohesion ${result.summary.avg_cohesion}, ${result.summary.high_coupling_pairs} high-coupling pairs\n`);
+}

package/dist/commands/context.d.ts

@@ -0,0 +1,12 @@
+interface ContextOptions {
+    repoDir: string;
+    files: string[];
+    graph?: string;
+    out: string;
+    minConfidence: number;
+    maxDepth: number;
+    format: 'json' | 'prompt';
+    skipTests?: boolean;
+}
+export declare function executeContext(opts: ContextOptions): Promise<void>;
+export {};

package/dist/commands/context.js

@@ -0,0 +1,130 @@
+import { execSync } from 'child_process';
+import { readFileSync, rmSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { buildContextV2 } from '../analysis/context-builder';
+import { formatPrompt } from '../analysis/prompt-formatter';
+import { mergeGraphs } from '../graph/merger';
+import { log } from '../shared/logger';
+import { GraphInputSchema } from '../shared/schemas';
+import { createSecureTempFile } from '../shared/temp';
+import { executeParse } from './parse';
+export async function executeContext(opts) {
+    const repoDir = resolve(opts.repoDir);
+    log.info('context: starting', {
+        files: opts.files,
+        repoDir,
+        graph: opts.graph ?? null,
+        format: opts.format,
+        minConfidence: opts.minConfidence,
+        maxDepth: opts.maxDepth,
+    });
+    // Parse changed files using secure temp
+    const tmp = createSecureTempFile('ctx');
+    try {
+        await executeParse({
+            repoDir,
+            files: opts.files,
+            all: false,
+            out: tmp.filePath,
+            skipTests: opts.skipTests,
+        });
+        const parseResult = JSON.parse(readFileSync(tmp.filePath, 'utf-8'));
+        log.info('context: parse done', {
+            nodes: parseResult.nodes?.length ?? 0,
+            edges: parseResult.edges?.length ?? 0,
+        });
+        // Load and merge with main graph if provided
+        let mergedGraph;
+        let oldGraph = null;
+        if (opts.graph) {
+            let raw;
+            try {
+                raw = JSON.parse(readFileSync(opts.graph, 'utf-8'));
+            }
+            catch (_err) {
+                log.error('failed to read --graph file', { path: opts.graph });
+                process.exit(1);
+            }
+            const validated = GraphInputSchema.safeParse(raw);
+            if (!validated.success) {
+                log.error('invalid graph JSON', { error: validated.error.message });
+                process.exit(1);
+            }
+            const changedSet = new Set(opts.files);
+            // Detect same-branch via commit sha comparison
+            const graphSha = raw?.sha || '';
+            let headSha = '';
+            try {
+                headSha = execSync('git rev-parse HEAD', { cwd: repoDir, encoding: 'utf-8' }).trim();
+            }
+            catch {
+                log.debug('could not resolve HEAD sha');
+            }
+            const sameBranch = graphSha !== '' && graphSha === headSha;
+            log.info('context: baseline graph loaded', {
+                graphNodes: validated.data.nodes.length,
+                graphEdges: validated.data.edges.length,
+                sameBranch,
+                graphSha: graphSha ? graphSha.substring(0, 8) : 'none',
+                headSha: headSha ? headSha.substring(0, 8) : 'none',
+            });
+            if (sameBranch) {
+                // --graph was built from the same commit (e.g. kodus-ai's parse --all on PR branch).
+                // Exclude changed files from oldGraph so diff detects their functions as "added"
+                // instead of falsely marking everything "unchanged".
+                oldGraph = {
+                    nodes: validated.data.nodes.filter((n) => !changedSet.has(n.file_path)),
+                    edges: validated.data.edges.filter((e) => !changedSet.has(e.file_path)),
+                };
+                log.debug('Same-branch detected: excluding changed files from baseline', {
+                    changedFiles: opts.files.length,
+                });
+            }
+            else {
+                oldGraph = { nodes: validated.data.nodes, edges: validated.data.edges };
+            }
+            const mainGraph = {
+                repo_id: '',
+                sha: '',
+                nodes: validated.data.nodes,
+                edges: validated.data.edges,
+            };
+            mergedGraph = mergeGraphs(mainGraph, parseResult, opts.files);
+        }
+        else {
+            mergedGraph = { nodes: parseResult.nodes, edges: parseResult.edges };
+        }
+        // Build V2 context
+        const output = buildContextV2({
+            mergedGraph,
+            oldGraph,
+            changedFiles: opts.files,
+            minConfidence: opts.minConfidence,
+            maxDepth: opts.maxDepth,
+            skipTests: opts.skipTests,
+        });
+        log.info('context: analysis done', {
+            changedFunctions: output.analysis.changed_functions.length,
+            diff: output.analysis.structural_diff.summary,
+            blastRadius: output.analysis.blast_radius.total_functions,
+            risk: `${output.analysis.risk.level} (${output.analysis.risk.score})`,
+            testGaps: output.analysis.test_gaps.length,
+            affectedFlows: output.analysis.affected_flows.length,
+            duration_ms: output.analysis.metadata.duration_ms,
+        });
+        if (opts.format === 'prompt') {
+            writeFileSync(opts.out, formatPrompt(output));
+        }
+        else {
+            writeFileSync(opts.out, JSON.stringify(output, null, 2));
+        }
+    }
+    finally {
+        try {
+            rmSync(tmp.dir, { recursive: true, force: true });
+        }
+        catch (err) {
+            log.debug('Failed to clean up temp dir', { dir: tmp.dir, error: String(err) });
+        }
+    }
+}

package/dist/commands/diff.d.ts

@@ -0,0 +1,9 @@
+interface DiffCommandOptions {
+    repoDir: string;
+    base?: string;
+    files?: string[];
+    graph: string;
+    out: string;
+}
+export declare function executeDiff(opts: DiffCommandOptions): Promise<void>;
+export {};