@kodus/kodus-graph 0.1.0

package/src/shared/filters.ts

@@ -0,0 +1,243 @@
+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: RegExp[] = [
+  /\.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: string): boolean {
+  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/src/shared/logger.ts

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

package/src/shared/qualified-name.ts

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

package/src/shared/safe-path.ts

@@ -0,0 +1,31 @@
+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: string, repoRoot: string): string {
+  let absRoot: string;
+  try {
+    absRoot = realpathSync(resolve(repoRoot));
+  } catch {
+    absRoot = resolve(repoRoot);
+  }
+
+  let absPath: string;
+  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/src/shared/schemas.ts

@@ -0,0 +1,31 @@
+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(),
+  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({
+  nodes: z.array(GraphNodeSchema),
+  edges: z.array(GraphEdgeSchema),
+});

package/src/shared/temp.ts

@@ -0,0 +1,17 @@
+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.
+ * File name uses crypto.randomBytes for unpredictability.
+ *
+ * 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 };
+}