@kodus/kodus-graph 0.2.8 → 0.2.9

package/dist/resolver/symbol-table.js

@@ -0,0 +1,60 @@
+/**
+ * Symbol table with dual-index lookup (GitNexus pattern).
+ *
+ * Provides both exact (file + name) and global (name-only) lookups.
+ * The exact lookup is high-confidence; global lookup is lower-confidence
+ * but useful when import resolution fails.
+ */
+export function createSymbolTable() {
+    const byFile = new Map();
+    const byName = new Map();
+    return {
+        add(file, name, qualified) {
+            if (!byFile.has(file)) {
+                byFile.set(file, new Map());
+            }
+            const fileMap = byFile.get(file);
+            if (!fileMap.has(name)) {
+                fileMap.set(name, []);
+            }
+            fileMap.get(name).push(qualified);
+            if (!byName.has(name)) {
+                byName.set(name, []);
+            }
+            byName.get(name).push(qualified);
+        },
+        lookupExact(file, name) {
+            const candidates = byFile.get(file)?.get(name);
+            if (!candidates || candidates.length === 0) {
+                return null;
+            }
+            // Only return if unambiguous within this file
+            return candidates.length === 1 ? candidates[0] : null;
+        },
+        lookupInFile(file, name, className) {
+            const candidates = byFile.get(file)?.get(name);
+            if (!candidates || candidates.length === 0) {
+                return null;
+            }
+            return candidates.find((q) => q.includes(`::${className}.${name}`)) ?? null;
+        },
+        isUnique(name) {
+            return (byName.get(name)?.length ?? 0) === 1;
+        },
+        lookupGlobal(name) {
+            return byName.get(name) ?? [];
+        },
+        get size() {
+            let count = 0;
+            for (const m of byFile.values()) {
+                for (const arr of m.values()) {
+                    count += arr.length;
+                }
+            }
+            return count;
+        },
+        get fileCount() {
+            return byFile.size;
+        },
+    };
+}

package/dist/shared/extract-calls.d.ts

@@ -0,0 +1,26 @@
+import type { SgNode } from '@ast-grep/napi';
+import type { RawCallSite } from '../graph/types';
+/**
+ * Language-specific configuration for call extraction.
+ * Each language provides its self/super patterns and how to find class context in the AST.
+ */
+export interface CallExtractionConfig {
+    /** Prefixes indicating a self-reference (e.g., 'self.', 'this.') */
+    selfPrefixes: string[];
+    /** Prefixes indicating a super-reference (e.g., 'super().', 'super.', 'base.') */
+    superPrefixes: string[];
+    /** Find the enclosing class/module/impl node from a call site */
+    findEnclosingClass: (node: SgNode) => SgNode | null;
+    /** Extract the parent class name from a class node (for super resolution) */
+    getParentClass?: (classNode: SgNode) => string | undefined;
+    /** Skip this callee entirely (e.g., TS skips this.field.method — handled by DI) */
+    skipCallee?: (callee: string) => boolean;
+}
+/**
+ * Shared call extraction for all languages.
+ *
+ * Parses `$CALLEE($$$ARGS)` pattern, detects self/super references
+ * based on language config, and populates resolveInClass for
+ * class-aware resolution downstream.
+ */
+export declare function extractCalls(rootNode: SgNode, fp: string, config: CallExtractionConfig, calls: RawCallSite[]): void;

package/dist/shared/extract-calls.js

@@ -0,0 +1,57 @@
+import { NOISE } from './filters';
+/**
+ * Shared call extraction for all languages.
+ *
+ * Parses `$CALLEE($$$ARGS)` pattern, detects self/super references
+ * based on language config, and populates resolveInClass for
+ * class-aware resolution downstream.
+ */
+export function extractCalls(rootNode, fp, config, calls) {
+    for (const m of rootNode.findAll('$CALLEE($$$ARGS)')) {
+        const callee = m.getMatch('CALLEE')?.text();
+        if (!callee) {
+            continue;
+        }
+        if (config.skipCallee?.(callee)) {
+            continue;
+        }
+        const callName = callee.includes('.') ? callee.split('.').pop() : callee;
+        if (NOISE.has(callName)) {
+            continue;
+        }
+        let resolveInClass;
+        // Check self-reference: callee must be exactly `prefix + methodName` (no further chaining)
+        for (const prefix of config.selfPrefixes) {
+            if (!callee.startsWith(prefix)) {
+                continue;
+            }
+            const rest = callee.substring(prefix.length);
+            if (rest.includes('.')) {
+                break; // chained access (e.g., this.field.method) — not a self call
+            }
+            const classNode = config.findEnclosingClass(m);
+            resolveInClass = classNode?.field('name')?.text();
+            break;
+        }
+        // Check super-reference if no self match
+        if (!resolveInClass) {
+            for (const prefix of config.superPrefixes) {
+                const matches = callee === prefix || (callee.startsWith(prefix) && !callee.substring(prefix.length).includes('.'));
+                if (!matches) {
+                    continue;
+                }
+                const classNode = config.findEnclosingClass(m);
+                if (classNode && config.getParentClass) {
+                    resolveInClass = config.getParentClass(classNode);
+                }
+                break;
+            }
+        }
+        calls.push({
+            source: fp,
+            callName,
+            line: m.range().start.line,
+            ...(resolveInClass ? { resolveInClass } : {}),
+        });
+    }
+}

package/dist/shared/file-hash.d.ts

@@ -0,0 +1,3 @@
+export declare function computeFileHash(filePath: string): string;
+/** Hash a node's source text (function body, class body, etc.) */
+export declare function computeContentHash(sourceText: string): string;

package/dist/shared/file-hash.js

@@ -0,0 +1,10 @@
+import { createHash } from 'crypto';
+import { readFileSync } from 'fs';
+export function computeFileHash(filePath) {
+    const content = readFileSync(filePath);
+    return createHash('sha256').update(content).digest('hex');
+}
+/** Hash a node's source text (function body, class body, etc.) */
+export function computeContentHash(sourceText) {
+    return createHash('sha256').update(sourceText).digest('hex');
+}

package/dist/shared/filters.d.ts

@@ -0,0 +1,3 @@
+export declare const SKIP_DIRS: Set<string>;
+export declare function isSkippableFile(fileName: string): boolean;
+export declare const NOISE: Set<string>;

package/dist/shared/filters.js

@@ -0,0 +1,240 @@
+export const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.next',
+    'coverage',
+    'vendor',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'target',
+    '.turbo',
+    '.cache',
+    '.output',
+    'out',
+    '.nuxt',
+    '.svelte-kit',
+    '.idea',
+    '.mypy_cache',
+    '.tox',
+    '.pytest_cache',
+    '.eggs',
+    'bower_components',
+]);
+/** File name patterns to skip during discovery (minified, bundled, vendored) */
+const SKIP_FILE_PATTERNS = [
+    /\.min\.\w+$/, // *.min.js, *.min.css
+    /[.-]bundle\.\w+$/, // *.bundle.js, *-bundle.js
+    /\.chunk\.\w+$/, // *.chunk.js (webpack)
+    /\.packed\.\w+$/, // *.packed.js
+];
+export function isSkippableFile(fileName) {
+    return SKIP_FILE_PATTERNS.some((p) => p.test(fileName));
+}
+export const NOISE = new Set([
+    // JS/TS builtins
+    'log',
+    'error',
+    'warn',
+    'info',
+    'debug',
+    'trace',
+    'push',
+    'pop',
+    'shift',
+    'unshift',
+    'splice',
+    'slice',
+    'map',
+    'filter',
+    'reduce',
+    'forEach',
+    'find',
+    'findIndex',
+    'some',
+    'every',
+    'flat',
+    'flatMap',
+    'sort',
+    'reverse',
+    'join',
+    'split',
+    'trim',
+    'replace',
+    'match',
+    'test',
+    'includes',
+    'indexOf',
+    'lastIndexOf',
+    'startsWith',
+    'endsWith',
+    'keys',
+    'values',
+    'entries',
+    'assign',
+    'freeze',
+    'create',
+    'stringify',
+    'parse',
+    'toString',
+    'toLowerCase',
+    'toUpperCase',
+    'concat',
+    'charAt',
+    'substring',
+    'parseInt',
+    'parseFloat',
+    'isNaN',
+    'isFinite',
+    'isArray',
+    'resolve',
+    'reject',
+    'all',
+    'allSettled',
+    'race',
+    'any',
+    'then',
+    'catch',
+    'finally',
+    'get',
+    'set',
+    'has',
+    'delete',
+    'clear',
+    'add',
+    'next',
+    'return',
+    'throw',
+    'setTimeout',
+    'clearTimeout',
+    'setInterval',
+    'clearInterval',
+    'require',
+    'length',
+    'call',
+    'apply',
+    'bind',
+    'createElement',
+    'useState',
+    'useEffect',
+    'useRef',
+    'useCallback',
+    'useMemo',
+    'useContext',
+    'useReducer',
+    'render',
+    // Test helpers
+    'expect',
+    'toBe',
+    'toEqual',
+    'toBeDefined',
+    'toBeNull',
+    'toBeUndefined',
+    'toBeTruthy',
+    'toBeFalsy',
+    'toContain',
+    'toHaveLength',
+    'toThrow',
+    'toHaveBeenCalled',
+    'toHaveBeenCalledWith',
+    'toMatchObject',
+    'toHaveBeenCalledTimes',
+    'toHaveProperty',
+    'describe',
+    'it',
+    'test',
+    'beforeEach',
+    'afterEach',
+    'beforeAll',
+    'afterAll',
+    'fn',
+    'spyOn',
+    'mock',
+    'mockResolvedValue',
+    'mockReturnValue',
+    'mockImplementation',
+    'mockReturnThis',
+    'now',
+    'toISOString',
+    'getTime',
+    // Globals
+    'console',
+    'Math',
+    'Date',
+    'JSON',
+    'Object',
+    'Array',
+    'String',
+    'Number',
+    'Boolean',
+    'Promise',
+    'Error',
+    'Map',
+    'Set',
+    'RegExp',
+    'Buffer',
+    'process',
+    // Python builtins
+    'print',
+    'len',
+    'range',
+    'enumerate',
+    'zip',
+    'isinstance',
+    'type',
+    'super',
+    'self',
+    'cls',
+    'None',
+    'True',
+    'False',
+    'append',
+    'extend',
+    'insert',
+    'remove',
+    'update',
+    'items',
+    'format',
+    'strip',
+    'upper',
+    'lower',
+    // Ruby builtins
+    'puts',
+    'raise',
+    'yield',
+    'each',
+    'do',
+    'end',
+    'attr_accessor',
+    'attr_reader',
+    'attr_writer',
+    'respond_to',
+    'render',
+    'redirect_to',
+    'before_action',
+    'after_action',
+    'validates',
+    'has_many',
+    'belongs_to',
+    'has_one',
+    'new',
+    'initialize',
+    // Go builtins
+    'fmt',
+    'Println',
+    'Printf',
+    'Sprintf',
+    'Errorf',
+    'make',
+    'panic',
+    'recover',
+    'defer',
+    // Java builtins
+    'System',
+    'println',
+    'equals',
+    'hashCode',
+    'getClass',
+]);

package/dist/shared/logger.d.ts

@@ -0,0 +1,6 @@
+export declare const log: {
+    info(msg: string, ctx?: Record<string, unknown>): void;
+    debug(msg: string, ctx?: Record<string, unknown>): void;
+    warn(msg: string, ctx?: Record<string, unknown>): void;
+    error(msg: string, ctx?: Record<string, unknown>): void;
+};

package/dist/shared/logger.js

@@ -0,0 +1,17 @@
+// src/shared/logger.ts
+export const log = {
+    info(msg, ctx) {
+        process.stderr.write(`[INFO] ${msg}${ctx ? ` ${JSON.stringify(ctx)}` : ''}\n`);
+    },
+    debug(msg, ctx) {
+        if (process.env.KODUS_GRAPH_DEBUG) {
+            process.stderr.write(`[DEBUG] ${msg}${ctx ? ` ${JSON.stringify(ctx)}` : ''}\n`);
+        }
+    },
+    warn(msg, ctx) {
+        process.stderr.write(`[WARN] ${msg}${ctx ? ` ${JSON.stringify(ctx)}` : ''}\n`);
+    },
+    error(msg, ctx) {
+        process.stderr.write(`[ERROR] ${msg}${ctx ? ` ${JSON.stringify(ctx)}` : ''}\n`);
+    },
+};

package/dist/shared/qualified-name.d.ts

@@ -0,0 +1 @@
+export declare function qualifiedName(filePath: string, name: string, className?: string, isTest?: boolean): string;

package/dist/shared/qualified-name.js

@@ -0,0 +1,9 @@
+export function qualifiedName(filePath, name, className, isTest) {
+    if (isTest) {
+        return `${filePath}::test:${name}`;
+    }
+    if (className) {
+        return `${filePath}::${className}.${name}`;
+    }
+    return `${filePath}::${name}`;
+}

package/dist/shared/safe-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validate that a resolved path is within the repository root.
+ * Returns the validated absolute path.
+ * Throws if the path escapes the root.
+ */
+export declare function ensureWithinRoot(filePath: string, repoRoot: string): string;

package/dist/shared/safe-path.js

@@ -0,0 +1,29 @@
+import { realpathSync } from 'fs';
+import { relative, resolve } from 'path';
+/**
+ * Validate that a resolved path is within the repository root.
+ * Returns the validated absolute path.
+ * Throws if the path escapes the root.
+ */
+export function ensureWithinRoot(filePath, repoRoot) {
+    let absRoot;
+    try {
+        absRoot = realpathSync(resolve(repoRoot));
+    }
+    catch {
+        absRoot = resolve(repoRoot);
+    }
+    let absPath;
+    try {
+        absPath = realpathSync(resolve(absRoot, filePath));
+    }
+    catch {
+        // File doesn't exist yet or is unreadable — use resolve without symlink follow
+        absPath = resolve(absRoot, filePath);
+    }
+    const rel = relative(absRoot, absPath);
+    if (rel.startsWith('..') || resolve(absRoot, rel) !== absPath) {
+        throw new Error(`Path escapes repository root: ${filePath}`);
+    }
+    return absPath;
+}

package/dist/shared/schemas.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export declare const GraphInputSchema: z.ZodObject<{
+    sha: z.ZodOptional<z.ZodString>;
+    nodes: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            Function: "Function";
+            Method: "Method";
+            Constructor: "Constructor";
+            Class: "Class";
+            Interface: "Interface";
+            Enum: "Enum";
+            Test: "Test";
+        }>;
+        name: z.ZodString;
+        qualified_name: z.ZodString;
+        file_path: z.ZodString;
+        line_start: z.ZodNumber;
+        line_end: z.ZodNumber;
+        language: z.ZodString;
+        is_test: z.ZodBoolean;
+        file_hash: z.ZodOptional<z.ZodString>;
+        content_hash: z.ZodOptional<z.ZodString>;
+        parent_name: z.ZodOptional<z.ZodString>;
+        params: z.ZodOptional<z.ZodString>;
+        return_type: z.ZodOptional<z.ZodString>;
+        modifiers: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            CALLS: "CALLS";
+            IMPORTS: "IMPORTS";
+            INHERITS: "INHERITS";
+            IMPLEMENTS: "IMPLEMENTS";
+            TESTED_BY: "TESTED_BY";
+            CONTAINS: "CONTAINS";
+        }>;
+        source_qualified: z.ZodString;
+        target_qualified: z.ZodString;
+        file_path: z.ZodString;
+        line: z.ZodNumber;
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/shared/schemas.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+const GraphNodeSchema = 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(),
+    content_hash: z.string().optional(),
+    parent_name: z.string().optional(),
+    params: z.string().optional(),
+    return_type: z.string().optional(),
+    modifiers: z.string().optional(),
+});
+const GraphEdgeSchema = 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 const GraphInputSchema = z.object({
+    sha: z.string().optional(),
+    nodes: z.array(GraphNodeSchema),
+    edges: z.array(GraphEdgeSchema),
+});

package/dist/shared/temp.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Create a secure temp directory + file path.
+ * Directory is created with 0700 permissions via mkdtempSync.
+ * File name uses crypto.randomBytes for unpredictability.
+ *
+ * Caller is responsible for cleanup (rmSync(dir, { recursive: true, force: true })).
+ */
+export declare function createSecureTempFile(prefix: string): {
+    dir: string;
+    filePath: string;
+};

package/{src/shared/temp.ts → dist/shared/temp.js}

@@ -2,7 +2,6 @@ import { randomBytes } from 'crypto';
 import { mkdtempSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
-
 /**
  * Create a secure temp directory + file path.
  * Directory is created with 0700 permissions via mkdtempSync.
@@ -10,8 +9,8 @@ import { join } from 'path';
  *
  * Caller is responsible for cleanup (rmSync(dir, { recursive: true, force: true })).
  */
-export function createSecureTempFile(prefix: string): { dir: string; filePath: string } {
-  const dir = mkdtempSync(join(tmpdir(), `kodus-graph-${prefix}-`));
-  const filePath = join(dir, `${randomBytes(8).toString('hex')}.json`);
-  return { dir, filePath };
+export function createSecureTempFile(prefix) {
+    const dir = mkdtempSync(join(tmpdir(), `kodus-graph-${prefix}-`));
+    const filePath = join(dir, `${randomBytes(8).toString('hex')}.json`);
+    return { dir, filePath };
 }

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "@kodus/kodus-graph",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Code graph builder for Kodus code review — parses source code into structural graphs with nodes, edges, and analysis",
   "type": "module",
+  "main": "./dist/cli.js",
+  "types": "./dist/cli.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
   "bin": {
-    "kodus-graph": "./src/cli.ts"
+    "kodus-graph": "./dist/cli.js"
   },
   "files": [
-    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -19,7 +28,9 @@
     "format": "biome format --write src/ tests/",
     "typecheck": "tsc --noEmit",
     "check": "bun run typecheck && bun run lint && bun test",
-    "build": "bun build src/cli.ts --compile --outfile kodus-graph",
+    "build:dist": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build:dist",
+    "build": "bun build src/cli.ts --compile --outfile dist/kodus-graph",
     "build:all": "bun run build:darwin-arm64 && bun run build:darwin-x64 && bun run build:linux-x64 && bun run build:linux-arm64",
     "build:darwin-arm64": "bun build src/cli.ts --compile --target=bun-darwin-arm64 --outfile dist/kodus-graph-darwin-arm64",
     "build:darwin-x64": "bun build src/cli.ts --compile --target=bun-darwin-x64 --outfile dist/kodus-graph-darwin-x64",
@@ -39,8 +50,11 @@
     "type": "git",
     "url": "https://github.com/kodustech/kodus-graph.git"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.3.0"
   },
   "dependencies": {
     "@ast-grep/lang-csharp": "^0.0.6",
@@ -56,7 +70,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
-    "@types/bun": "latest",
+    "@types/bun": "^1.3.11",
     "typescript": "^6.0.2"
   }
 }