@kodus/kodus-graph 0.2.8 → 0.2.10

package/dist/graph/edges.d.ts

@@ -0,0 +1,23 @@
+import type { ImportEdge, RawGraph } from './types';
+interface DerivedEdge {
+    source: string;
+    target: string;
+    file?: string;
+}
+export interface DerivedEdges {
+    inherits: DerivedEdge[];
+    implements: DerivedEdge[];
+    testedBy: DerivedEdge[];
+    contains: DerivedEdge[];
+}
+/**
+ * Extract the "stem" from a test file name by stripping test-related
+ * prefixes/suffixes. Returns null if no test pattern was found.
+ */
+export declare function extractTestStem(testFile: string): string | null;
+export declare function deriveEdges(graph: RawGraph, importEdges: ImportEdge[], symbolTable?: {
+    lookupGlobal(name: string): string[];
+}, importMap?: {
+    lookup(file: string, name: string): string | null;
+}): DerivedEdges;
+export {};

package/dist/graph/edges.js

@@ -0,0 +1,159 @@
+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;
+}
+/**
+ * Resolve a bare type name (e.g. "User", "IAuthService") to its qualified name
+ * using import map, same-file lookup, and global symbol table.
+ * Returns null if the name cannot be resolved (external class/interface).
+ */
+function resolveTypeName(name, file, graph, symbolTable, importMap) {
+    // 1. Check import map — was it imported in this file?
+    const importedFrom = importMap?.lookup(file, name);
+    if (importedFrom) {
+        // Look up the qualified name in the imported file
+        const candidates = symbolTable?.lookupGlobal(name) ?? [];
+        const match = candidates.find((q) => q.startsWith(`${importedFrom}::`));
+        if (match) {
+            return match;
+        }
+        // If importedFrom is not a local file (not in graph), it's an external package — skip
+        const isLocal = graph.classes.some((c) => c.file === importedFrom) ||
+            graph.interfaces.some((i) => i.file === importedFrom) ||
+            graph.functions.some((f) => f.file === importedFrom);
+        if (!isLocal) {
+            return null;
+        }
+        // Fallback: construct qualified name from local import target
+        return `${importedFrom}::${name}`;
+    }
+    // 2. Check same file — class or interface defined in same file
+    const sameFileClass = graph.classes.find((other) => other.name === name && other.file === file);
+    if (sameFileClass) {
+        return sameFileClass.qualified;
+    }
+    const sameFileInterface = graph.interfaces.find((other) => other.name === name && other.file === file);
+    if (sameFileInterface) {
+        return sameFileInterface.qualified;
+    }
+    // 3. Check global symbol table — unique match only
+    const globalCandidates = symbolTable?.lookupGlobal(name) ?? [];
+    if (globalCandidates.length === 1) {
+        return globalCandidates[0];
+    }
+    // 4. External class/interface (React.Component, Error, etc.) — unresolvable
+    return null;
+}
+export function deriveEdges(graph, importEdges, symbolTable, importMap) {
+    // INHERITS: class extends another class — resolve to qualified names
+    const inherits = [];
+    for (const c of graph.classes) {
+        if (!c.extends) {
+            continue;
+        }
+        const resolved = resolveTypeName(c.extends, c.file, graph, symbolTable, importMap);
+        if (resolved) {
+            inherits.push({ source: c.qualified, target: resolved, file: c.file });
+        }
+        // Skip unresolvable external classes (React.Component, Error, etc.)
+    }
+    // IMPLEMENTS: class implements interface(s) — resolve to qualified names
+    const implements_ = [];
+    for (const c of graph.classes) {
+        for (const iface of c.implements) {
+            const resolved = resolveTypeName(iface, c.file, graph, symbolTable, importMap);
+            if (resolved) {
+                implements_.push({ source: c.qualified, target: resolved, file: c.file });
+            }
+            // Skip unresolvable external interfaces
+        }
+    }
+    // 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,252 @@
+import type { ContractDiff } from '../analysis/diff';
+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[];
+    contract_diffs: ContractDiff[];
+    caller_impact?: 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,5 @@
+import type { ParseBatchResult } from '../graph/types';
+export declare function parseBatch(files: string[], repoRoot: string, options?: {
+    skipTests?: boolean;
+    maxMemoryMB?: number;
+}): Promise<ParseBatchResult>;