@kodus/kodus-graph 0.2.8 → 0.2.9

package/dist/graph/edges.js

@@ -0,0 +1,105 @@
+import { basename, extname } from 'path';
+/**
+ * Extract the "stem" from a test file name by stripping test-related
+ * prefixes/suffixes. Returns null if no test pattern was found.
+ */
+export function extractTestStem(testFile) {
+    const base = basename(testFile, extname(testFile));
+    const cleaned = base
+        .replace(/_spec$/, '') // user_spec → user (Ruby/RSpec)
+        .replace(/_test$/, '') // user_test → user (Python/Go)
+        .replace(/^test_/, '') // test_user → user (Python)
+        .replace(/\.test$/, '') // user.test → user (JS/TS)
+        .replace(/\.spec$/, '') // user.spec → user (JS/TS)
+        .replace(/-test$/, '') // user-test → user
+        .replace(/-spec$/, '') // user-spec → user
+        .replace(/^spec_/, '') // spec_user → user
+        .replace(/Test$/, '') // UserTest → User (Java)
+        .replace(/Spec$/, ''); // UserSpec → User (Scala)
+    if (!cleaned || cleaned === base) {
+        return null;
+    }
+    return cleaned;
+}
+export function deriveEdges(graph, importEdges) {
+    // INHERITS: class extends another class
+    const inherits = graph.classes
+        .filter((c) => c.extends)
+        .map((c) => ({ source: c.qualified, target: c.extends, file: c.file }));
+    // IMPLEMENTS: class implements interface(s)
+    const implements_ = [];
+    for (const c of graph.classes) {
+        for (const iface of c.implements) {
+            implements_.push({ source: c.qualified, target: iface, file: c.file });
+        }
+    }
+    // TESTED_BY: two heuristics, deduplicated
+    const testFiles = new Set(graph.tests.map((t) => t.file));
+    const testedBySet = new Set();
+    const testedBy = [];
+    const addTestedBy = (source, target) => {
+        const key = `${source}|${target}`;
+        if (testedBySet.has(key)) {
+            return;
+        }
+        testedBySet.add(key);
+        testedBy.push({ source, target });
+    };
+    // Heuristic 1: Resolved imports from test files (high signal)
+    for (const e of importEdges) {
+        if (testFiles.has(e.source) && e.resolved) {
+            addTestedBy(e.target, e.source);
+        }
+    }
+    // Heuristic 2: File-name matching (catches Ruby, Python, and any
+    // language where imports don't resolve)
+    const allSourceFiles = new Set();
+    for (const f of graph.functions) {
+        allSourceFiles.add(f.file);
+    }
+    for (const c of graph.classes) {
+        allSourceFiles.add(c.file);
+    }
+    for (const i of graph.interfaces) {
+        allSourceFiles.add(i.file);
+    }
+    for (const e of graph.enums) {
+        allSourceFiles.add(e.file);
+    }
+    for (const tf of testFiles) {
+        allSourceFiles.delete(tf);
+    }
+    const sourceByBase = new Map();
+    for (const file of allSourceFiles) {
+        const base = basename(file, extname(file));
+        const list = sourceByBase.get(base);
+        if (list) {
+            list.push(file);
+        }
+        else {
+            sourceByBase.set(base, [file]);
+        }
+    }
+    for (const testFile of testFiles) {
+        const stem = extractTestStem(testFile);
+        if (!stem) {
+            continue;
+        }
+        const matches = sourceByBase.get(stem);
+        if (!matches) {
+            continue;
+        }
+        for (const sourceFile of matches) {
+            addTestedBy(sourceFile, testFile);
+        }
+    }
+    // CONTAINS: file contains function/class
+    const contains = [];
+    for (const f of graph.functions) {
+        contains.push({ source: f.file, target: f.qualified });
+    }
+    for (const c of graph.classes) {
+        contains.push({ source: c.file, target: c.qualified });
+    }
+    return { inherits, implements: implements_, testedBy, contains };
+}

package/dist/graph/json-writer.d.ts

@@ -0,0 +1,9 @@
+import type { GraphEdge, GraphNode, ParseMetadata } from './types';
+/**
+ * Write graph output as JSON to disk using incremental serialization.
+ *
+ * Instead of JSON.stringify on the full output (which creates a ~100-300 MB
+ * string for large repos), this writes each node/edge individually.
+ * Peak memory: only one JSON.stringify(singleNode) string at a time (~1 KB).
+ */
+export declare function writeGraphJSON(out: string, metadata: ParseMetadata, nodes: GraphNode[], edges: GraphEdge[]): void;

package/dist/graph/json-writer.js

@@ -0,0 +1,38 @@
+import { closeSync, openSync, writeSync } from 'fs';
+/**
+ * Write graph output as JSON to disk using incremental serialization.
+ *
+ * Instead of JSON.stringify on the full output (which creates a ~100-300 MB
+ * string for large repos), this writes each node/edge individually.
+ * Peak memory: only one JSON.stringify(singleNode) string at a time (~1 KB).
+ */
+export function writeGraphJSON(out, metadata, nodes, edges) {
+    const fd = openSync(out, 'w');
+    try {
+        writeSync(fd, '{"metadata":');
+        writeSync(fd, JSON.stringify(metadata));
+        // Nodes
+        writeSync(fd, ',"nodes":[');
+        for (let i = 0; i < nodes.length; i++) {
+            if (i > 0) {
+                writeSync(fd, ',');
+            }
+            writeSync(fd, '\n');
+            writeSync(fd, JSON.stringify(nodes[i]));
+        }
+        writeSync(fd, '\n]');
+        // Edges
+        writeSync(fd, ',"edges":[');
+        for (let i = 0; i < edges.length; i++) {
+            if (i > 0) {
+                writeSync(fd, ',');
+            }
+            writeSync(fd, '\n');
+            writeSync(fd, JSON.stringify(edges[i]));
+        }
+        writeSync(fd, '\n]}');
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/graph/loader.d.ts

@@ -0,0 +1,13 @@
+import type { GraphData, GraphEdge, GraphNode, ParseMetadata } from './types';
+export interface IndexedGraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    byQualified: Map<string, GraphNode>;
+    byFile: Map<string, GraphNode[]>;
+    adjacency: Map<string, GraphEdge[]>;
+    reverseAdjacency: Map<string, GraphEdge[]>;
+    edgesByKind: Map<string, GraphEdge[]>;
+    metadata: ParseMetadata;
+}
+export declare function indexGraph(data: GraphData, metadata?: ParseMetadata): IndexedGraph;
+export declare function loadGraph(path: string): IndexedGraph;

package/dist/graph/loader.js

@@ -0,0 +1,101 @@
+// src/graph/loader.ts
+import { readFileSync } from 'fs';
+import { z } from 'zod';
+const ParseOutputSchema = z.object({
+    metadata: z.object({
+        repo_dir: z.string(),
+        files_parsed: z.number(),
+        total_nodes: z.number(),
+        total_edges: z.number(),
+        duration_ms: z.number(),
+        parse_errors: z.number(),
+        extract_errors: z.number(),
+        files_unchanged: z.number().optional(),
+        incremental: z.boolean().optional(),
+    }),
+    nodes: z.array(z.object({
+        kind: z.enum(['Function', 'Method', 'Constructor', 'Class', 'Interface', 'Enum', 'Test']),
+        name: z.string(),
+        qualified_name: z.string(),
+        file_path: z.string(),
+        line_start: z.number(),
+        line_end: z.number(),
+        language: z.string(),
+        is_test: z.boolean(),
+        file_hash: z.string().optional(),
+        parent_name: z.string().optional(),
+        params: z.string().optional(),
+        return_type: z.string().optional(),
+        modifiers: z.string().optional(),
+    })),
+    edges: z.array(z.object({
+        kind: z.enum(['CALLS', 'IMPORTS', 'INHERITS', 'IMPLEMENTS', 'TESTED_BY', 'CONTAINS']),
+        source_qualified: z.string(),
+        target_qualified: z.string(),
+        file_path: z.string(),
+        line: z.number(),
+        confidence: z.number().optional(),
+    })),
+});
+export function indexGraph(data, metadata) {
+    const { nodes, edges } = data;
+    const meta = metadata ?? {
+        repo_dir: '',
+        files_parsed: 0,
+        total_nodes: nodes.length,
+        total_edges: edges.length,
+        duration_ms: 0,
+        parse_errors: 0,
+        extract_errors: 0,
+    };
+    const byQualified = new Map();
+    const byFile = new Map();
+    const adjacency = new Map();
+    const reverseAdjacency = new Map();
+    const edgesByKind = new Map();
+    for (const node of nodes) {
+        byQualified.set(node.qualified_name, node);
+        const list = byFile.get(node.file_path);
+        if (list) {
+            list.push(node);
+        }
+        else {
+            byFile.set(node.file_path, [node]);
+        }
+    }
+    for (const edge of edges) {
+        const fwd = adjacency.get(edge.source_qualified);
+        if (fwd) {
+            fwd.push(edge);
+        }
+        else {
+            adjacency.set(edge.source_qualified, [edge]);
+        }
+        const rev = reverseAdjacency.get(edge.target_qualified);
+        if (rev) {
+            rev.push(edge);
+        }
+        else {
+            reverseAdjacency.set(edge.target_qualified, [edge]);
+        }
+        const byKind = edgesByKind.get(edge.kind);
+        if (byKind) {
+            byKind.push(edge);
+        }
+        else {
+            edgesByKind.set(edge.kind, [edge]);
+        }
+    }
+    return { nodes, edges, byQualified, byFile, adjacency, reverseAdjacency, edgesByKind, metadata: meta };
+}
+export function loadGraph(path) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (err) {
+        throw new Error(`Failed to read graph file: ${path} — ${String(err)}`);
+    }
+    const parsed = ParseOutputSchema.parse(raw);
+    return indexGraph({ nodes: parsed.nodes, edges: parsed.edges }, parsed.metadata);
+}

package/dist/graph/merger.d.ts

@@ -0,0 +1,7 @@
+import type { GraphData, MainGraphInput } from './types';
+/**
+ * Merge local parse (PR changed files) with the main graph (from Postgres).
+ * Replaces all nodes/edges from changed files with the local parse.
+ * Keeps everything else from the main graph intact.
+ */
+export declare function mergeGraphs(mainGraph: MainGraphInput | null, localParse: GraphData, changedFiles: string[]): GraphData;

package/dist/graph/merger.js

@@ -0,0 +1,18 @@
+/**
+ * Merge local parse (PR changed files) with the main graph (from Postgres).
+ * Replaces all nodes/edges from changed files with the local parse.
+ * Keeps everything else from the main graph intact.
+ */
+export function mergeGraphs(mainGraph, localParse, changedFiles) {
+    if (!mainGraph) {
+        return localParse;
+    }
+    const changedSet = new Set(changedFiles);
+    // Keep main graph nodes/edges NOT in changed files
+    const mainNodes = mainGraph.nodes.filter((n) => !changedSet.has(n.file_path));
+    const mainEdges = mainGraph.edges.filter((e) => !changedSet.has(e.file_path));
+    return {
+        nodes: [...mainNodes, ...localParse.nodes],
+        edges: [...mainEdges, ...localParse.edges],
+    };
+}

package/dist/graph/types.d.ts

@@ -0,0 +1,249 @@
+export type NodeKind = 'Function' | 'Method' | 'Constructor' | 'Class' | 'Interface' | 'Enum' | 'Test';
+export type EdgeKind = 'CALLS' | 'IMPORTS' | 'INHERITS' | 'IMPLEMENTS' | 'TESTED_BY' | 'CONTAINS';
+export interface GraphNode {
+    kind: NodeKind;
+    ast_kind?: string;
+    name: string;
+    qualified_name: string;
+    file_path: string;
+    line_start: number;
+    line_end: number;
+    language: string;
+    parent_name?: string;
+    params?: string;
+    return_type?: string;
+    modifiers?: string;
+    is_test: boolean;
+    file_hash?: string;
+    content_hash?: string;
+}
+export interface GraphEdge {
+    kind: EdgeKind;
+    source_qualified: string;
+    target_qualified: string;
+    file_path: string;
+    line: number;
+    confidence?: number;
+}
+export interface GraphData {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+export interface ParseMetadata {
+    repo_dir: string;
+    files_parsed: number;
+    total_nodes: number;
+    total_edges: number;
+    duration_ms: number;
+    parse_errors: number;
+    extract_errors: number;
+    files_unchanged?: number;
+    incremental?: boolean;
+}
+export interface ParseOutput {
+    metadata: ParseMetadata;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+export interface BlastRadiusResult {
+    total_functions: number;
+    total_files: number;
+    by_depth: Record<string, string[]>;
+}
+export interface RiskFactor {
+    weight: number;
+    value: number;
+    detail: string;
+}
+export interface RiskScoreResult {
+    level: 'LOW' | 'MEDIUM' | 'HIGH';
+    score: number;
+    factors: {
+        blast_radius: RiskFactor;
+        test_gaps: RiskFactor;
+        complexity: RiskFactor;
+        inheritance: RiskFactor;
+    };
+}
+export interface TestGap {
+    function: string;
+    file_path: string;
+    line_start: number;
+}
+export interface AnalysisOutput {
+    blast_radius: BlastRadiusResult;
+    risk_score: RiskScoreResult;
+    test_gaps: TestGap[];
+}
+export interface ContextMetadata {
+    changed_functions: number;
+    caller_count: number;
+    callee_count: number;
+    untested_count: number;
+    blast_radius: {
+        functions: number;
+        files: number;
+    };
+    risk_level: 'LOW' | 'MEDIUM' | 'HIGH';
+    risk_score: number;
+}
+export interface ContextOutput {
+    text: string;
+    metadata: ContextMetadata;
+}
+export interface MainGraphInput {
+    repo_id: string;
+    sha: string;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+export interface CallerRef {
+    qualified_name: string;
+    name: string;
+    file_path: string;
+    line: number;
+    confidence: number;
+}
+export interface CalleeRef {
+    qualified_name: string;
+    name: string;
+    file_path: string;
+    signature: string;
+}
+export interface EnrichedFunction {
+    qualified_name: string;
+    name: string;
+    kind: NodeKind;
+    signature: string;
+    file_path: string;
+    line_start: number;
+    line_end: number;
+    callers: CallerRef[];
+    callees: CalleeRef[];
+    has_test_coverage: boolean;
+    diff_changes: string[];
+    is_new: boolean;
+    in_flows: string[];
+}
+export interface AffectedFlow {
+    entry_point: string;
+    type: 'test' | 'http';
+    touches_changed: string[];
+    depth: number;
+    path: string[];
+}
+export interface InheritanceEntry {
+    qualified_name: string;
+    file_path: string;
+    extends?: string;
+    implements: string[];
+    children: string[];
+}
+export interface ContextAnalysisMetadata {
+    changed_functions_count: number;
+    total_callers: number;
+    total_callees: number;
+    untested_count: number;
+    affected_flows_count: number;
+    duration_ms: number;
+    min_confidence: number;
+}
+export interface RawFunction {
+    name: string;
+    file: string;
+    line_start: number;
+    line_end: number;
+    params: string;
+    returnType: string;
+    kind: 'Function' | 'Method' | 'Constructor';
+    ast_kind: string;
+    className: string;
+    qualified: string;
+    content_hash?: string;
+}
+export interface RawClass {
+    name: string;
+    file: string;
+    line_start: number;
+    line_end: number;
+    extends: string;
+    implements: string[];
+    ast_kind: string;
+    qualified: string;
+    content_hash?: string;
+}
+export interface RawInterface {
+    name: string;
+    file: string;
+    line_start: number;
+    line_end: number;
+    methods: string[];
+    ast_kind: string;
+    qualified: string;
+    content_hash?: string;
+}
+export interface RawEnum {
+    name: string;
+    file: string;
+    line_start: number;
+    line_end: number;
+    ast_kind: string;
+    qualified: string;
+    content_hash?: string;
+}
+export interface RawTest {
+    name: string;
+    file: string;
+    line_start: number;
+    line_end: number;
+    ast_kind: string;
+    qualified: string;
+    content_hash?: string;
+}
+export interface RawImport {
+    module: string;
+    file: string;
+    line: number;
+    names: string[];
+    lang: string;
+}
+export interface RawReExport {
+    module: string;
+    file: string;
+    line: number;
+}
+export interface RawCallSite {
+    source: string;
+    callName: string;
+    line: number;
+    diField?: string;
+    resolveInClass?: string;
+}
+export interface RawCallEdge {
+    source: string;
+    target: string;
+    callName: string;
+    line: number;
+    confidence: number;
+}
+export interface ImportEdge {
+    source: string;
+    target: string;
+    resolved: boolean;
+    line: number;
+}
+export interface RawGraph {
+    functions: RawFunction[];
+    classes: RawClass[];
+    interfaces: RawInterface[];
+    enums: RawEnum[];
+    tests: RawTest[];
+    imports: RawImport[];
+    reExports: RawReExport[];
+    rawCalls: RawCallSite[];
+    diMaps: Map<string, Map<string, string>>;
+}
+export interface ParseBatchResult extends RawGraph {
+    parseErrors: number;
+    extractErrors: number;
+}

package/dist/graph/types.js

@@ -0,0 +1 @@
+export {};

package/dist/parser/batch.d.ts

@@ -0,0 +1,4 @@
+import type { ParseBatchResult } from '../graph/types';
+export declare function parseBatch(files: string[], repoRoot: string, options?: {
+    skipTests?: boolean;
+}): Promise<ParseBatchResult>;

package/dist/parser/batch.js

@@ -0,0 +1,78 @@
+import { parseAsync } from '@ast-grep/napi';
+import { readFileSync } from 'fs';
+import { extname, relative } from 'path';
+import { NOISE } from '../shared/filters';
+import { log } from '../shared/logger';
+import { extractCallsFromFile, extractFromFile } from './extractor';
+import { getLanguage } from './languages';
+const BATCH_SIZE = 50;
+export async function parseBatch(files, repoRoot, options) {
+    const graph = {
+        functions: [],
+        classes: [],
+        interfaces: [],
+        enums: [],
+        tests: [],
+        imports: [],
+        reExports: [],
+        rawCalls: [],
+        diMaps: new Map(),
+    };
+    const seen = new Set();
+    let parseErrors = 0;
+    let extractErrors = 0;
+    for (let i = 0; i < files.length; i += BATCH_SIZE) {
+        const batch = files.slice(i, i + BATCH_SIZE);
+        const promises = batch.map(async (filePath) => {
+            const lang = getLanguage(extname(filePath));
+            if (!lang) {
+                return;
+            }
+            let source;
+            try {
+                source = readFileSync(filePath, 'utf-8');
+            }
+            catch (err) {
+                log.warn('Failed to read file', { file: filePath, error: String(err) });
+                parseErrors++;
+                return;
+            }
+            let root;
+            try {
+                root = await parseAsync(lang, source);
+            }
+            catch (err) {
+                log.warn('Failed to parse file', { file: filePath, error: String(err) });
+                parseErrors++;
+                return;
+            }
+            const fp = relative(repoRoot, filePath);
+            try {
+                extractFromFile(root, fp, lang, seen, graph);
+            }
+            catch (err) {
+                log.error('Extraction crashed', { file: fp, error: String(err) });
+                extractErrors++;
+            }
+            try {
+                // Extract calls into a temporary buffer, then filter noise before pushing
+                const rawCalls = [];
+                extractCallsFromFile(root, fp, lang, rawCalls);
+                for (const call of rawCalls) {
+                    if (!NOISE.has(call.callName)) {
+                        graph.rawCalls.push(call);
+                    }
+                }
+            }
+            catch (err) {
+                log.error('Call extraction crashed', { file: fp, error: String(err) });
+                extractErrors++;
+            }
+        });
+        await Promise.all(promises);
+    }
+    if (options?.skipTests) {
+        graph.tests = [];
+    }
+    return { ...graph, parseErrors, extractErrors };
+}

package/dist/parser/discovery.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Walk the filesystem and find all supported source files.
+ * If `filterFiles` is provided, only return those specific files (resolved to absolute paths).
+ * If `include` patterns are provided, keep only files matching at least one pattern.
+ * If `exclude` patterns are provided, remove files matching any pattern.
+ */
+export declare function discoverFiles(repoDir: string, filterFiles?: string[], include?: string[], exclude?: string[]): string[];