gitnexus 1.3.6 → 1.3.8

package/dist/cli/ai-context.js

@@ -16,37 +16,91 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
 /**
  * Generate the full GitNexus context content.
  *
- * Design principles (learned from real agent behavior):
- * - AGENTS.md is the ROUTER — it tells the agent WHICH skill to read
- * - Skills contain the actual workflows — AGENTS.md does NOT duplicate them
- * - Bold **IMPORTANT** block + "Skills — Read First" heading — agents skip soft suggestions
- * - One-line quick start (read context resource) gives agents an entry point
- * - Tools/Resources sections are labeled "Reference" — agents treat them as lookup, not workflow
+ * Design principles (learned from real agent behavior and industry research):
+ * - Inline critical workflows — skills are skipped 56% of the time (Vercel eval data)
+ * - Use RFC 2119 language (MUST, NEVER, ALWAYS) — models follow imperative rules
+ * - Three-tier boundaries (Always/When/Never) — proven to change model behavior
+ * - Keep under 120 lines — adherence degrades past 150 lines
+ * - Exact tool commands with parameters — vague directives get ignored
+ * - Self-review checklist — forces model to verify its own work
  */
 function generateGitNexusContent(projectName, stats) {
     return `${GITNEXUS_START_MARKER}
-# GitNexus MCP
+# GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows).
+This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
-## Always Start Here
+> If any GitNexus tool warns the index is stale, run \`npx gitnexus analyze\` in terminal first.
 
-1. **Read \`gitnexus://repo/{name}/context\`** — codebase overview + check index freshness
-2. **Match your task to a skill below** and **read that skill file**
-3. **Follow the skill's workflow and checklist**
+## Always Do
 
-> If step 1 warns the index is stale, run \`npx gitnexus analyze\` in the terminal first.
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`gitnexus_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run \`gitnexus_detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use \`gitnexus_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`gitnexus_context({name: "symbolName"})\`.
 
-## Skills
+## When Debugging
 
-| Task | Read this skill file |
-|------|---------------------|
-| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
-| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md\` |
-| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/gitnexus-debugging/SKILL.md\` |
-| Rename / extract / split / refactor | \`.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md\` |
-| Tools, resources, schema reference | \`.claude/skills/gitnexus/gitnexus-guide/SKILL.md\` |
-| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus/gitnexus-cli/SKILL.md\` |
+1. \`gitnexus_query({query: "<error or symptom>"})\` — find execution flows related to the issue
+2. \`gitnexus_context({name: "<suspect function>"})\` — see all callers, callees, and process participation
+3. \`READ gitnexus://repo/${projectName}/process/{processName}\` — trace the full execution flow step by step
+4. For regressions: \`gitnexus_detect_changes({scope: "compare", base_ref: "main"})\` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use \`gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})\` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with \`dry_run: false\`.
+- **Extracting/Splitting**: MUST run \`gitnexus_context({name: "target"})\` to see all incoming/outgoing refs, then \`gitnexus_impact({target: "target", direction: "upstream"})\` to find all external callers before moving code.
+- After any refactor: run \`gitnexus_detect_changes({scope: "all"})\` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running \`gitnexus_impact\` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use \`gitnexus_rename\` which understands the call graph.
+- NEVER commit changes without running \`gitnexus_detect_changes()\` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| \`query\` | Find code by concept | \`gitnexus_query({query: "auth validation"})\` |
+| \`context\` | 360-degree view of one symbol | \`gitnexus_context({name: "validateUser"})\` |
+| \`impact\` | Blast radius before editing | \`gitnexus_impact({target: "X", direction: "upstream"})\` |
+| \`detect_changes\` | Pre-commit scope check | \`gitnexus_detect_changes({scope: "staged"})\` |
+| \`rename\` | Safe multi-file rename | \`gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})\` |
+| \`cypher\` | Custom graph queries | \`gitnexus_cypher({query: "MATCH ..."})\` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| \`gitnexus://repo/${projectName}/context\` | Codebase overview, check index freshness |
+| \`gitnexus://repo/${projectName}/clusters\` | All functional areas |
+| \`gitnexus://repo/${projectName}/processes\` | All execution flows |
+| \`gitnexus://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. \`gitnexus_impact\` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. \`gitnexus_detect_changes()\` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## CLI
+
+- Re-index: \`npx gitnexus analyze\`
+- Check freshness: \`npx gitnexus status\`
+- Generate docs: \`npx gitnexus wiki\`
 
 ${GITNEXUS_END_MARKER}`;
 }
@@ -78,7 +132,7 @@ async function upsertGitNexusSection(filePath, content) {
     // Check if GitNexus section already exists
     const startIdx = existingContent.indexOf(GITNEXUS_START_MARKER);
     const endIdx = existingContent.indexOf(GITNEXUS_END_MARKER);
-    if (startIdx !== -1 && endIdx !== -1) {
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
         // Replace existing section
         const before = existingContent.substring(0, startIdx);
         const after = existingContent.substring(endIdx + GITNEXUS_END_MARKER.length);

package/dist/cli/analyze.js

@@ -17,7 +17,6 @@ import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getG
 import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
 import { generateAIContextFiles } from './ai-context.js';
 import fs from 'fs/promises';
-import { registerClaudeHook } from './claude-hooks.js';
 const HEAP_MB = 8192;
 const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
 /** Re-exec the process with an 8GB heap if we're currently below that. */
@@ -258,7 +257,6 @@ export const analyzeCommand = async (inputPath, options) => {
     await saveMeta(storagePath, meta);
     await registerRepo(repoPath, meta);
     await addToGitignore(repoPath);
-    const hookResult = await registerClaudeHook();
     const projectName = path.basename(repoPath);
     let aggregatedClusterCount = 0;
     if (pipelineResult.communityResult?.communities) {
@@ -298,9 +296,6 @@ export const analyzeCommand = async (inputPath, options) => {
     if (aiContext.files.length > 0) {
         console.log(`  Context: ${aiContext.files.join(', ')}`);
     }
-    if (hookResult.registered) {
-        console.log(`  Hooks: ${hookResult.message}`);
-    }
     // Show a quiet summary if some edge types needed fallback insertion
     if (kuzuWarnings.length > 0) {
         const totalFallback = kuzuWarnings.reduce((sum, w) => {
@@ -316,10 +311,8 @@ export const analyzeCommand = async (inputPath, options) => {
         console.log('\n  Tip: Run `gitnexus setup` to configure MCP for your editor.');
     }
     console.log('');
-    // ONNX Runtime registers native atexit hooks that segfault during process
-    // shutdown on macOS (#38) and some Linux configs (#40). Force-exit to
-    // bypass them when embeddings were loaded.
-    if (!embeddingSkipped) {
-        process.exit(0);
-    }
+    // KuzuDB's native module holds open handles that prevent Node from exiting.
+    // ONNX Runtime also registers native atexit hooks that segfault on some
+    // platforms (#38, #40). Force-exit to ensure clean termination.
+    process.exit(0);
 };

package/dist/cli/eval-server.d.ts

@@ -27,4 +27,11 @@ export interface EvalServerOptions {
     port?: string;
     idleTimeout?: string;
 }
+export declare function formatQueryResult(result: any): string;
+export declare function formatContextResult(result: any): string;
+export declare function formatImpactResult(result: any): string;
+export declare function formatCypherResult(result: any): string;
+export declare function formatDetectChangesResult(result: any): string;
+export declare function formatListReposResult(result: any): string;
 export declare function evalServerCommand(options?: EvalServerOptions): Promise<void>;
+export declare const MAX_BODY_SIZE: number;

package/dist/cli/eval-server.js

@@ -28,7 +28,7 @@ import { LocalBackend } from '../mcp/local/local-backend.js';
 // ─── Text Formatters ──────────────────────────────────────────────────
 // Convert structured JSON results into compact, LLM-friendly text.
 // Design: minimize tokens, maximize actionability.
-function formatQueryResult(result) {
+export function formatQueryResult(result) {
     if (result.error)
         return `Error: ${result.error}`;
     const lines = [];
@@ -63,7 +63,7 @@ function formatQueryResult(result) {
     }
     return lines.join('\n').trim();
 }
-function formatContextResult(result) {
+export function formatContextResult(result) {
     if (result.error)
         return `Error: ${result.error}`;
     if (result.status === 'ambiguous') {
@@ -120,7 +120,7 @@ function formatContextResult(result) {
     }
     return lines.join('\n').trim();
 }
-function formatImpactResult(result) {
+export function formatImpactResult(result) {
     if (result.error)
         return `Error: ${result.error}`;
     const target = result.target;
@@ -154,7 +154,7 @@ function formatImpactResult(result) {
     }
     return lines.join('\n').trim();
 }
-function formatCypherResult(result) {
+export function formatCypherResult(result) {
     if (result.error)
         return `Error: ${result.error}`;
     if (Array.isArray(result)) {
@@ -174,7 +174,7 @@ function formatCypherResult(result) {
     }
     return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
 }
-function formatDetectChangesResult(result) {
+export function formatDetectChangesResult(result) {
     if (result.error)
         return `Error: ${result.error}`;
     const summary = result.summary || {};
@@ -205,7 +205,7 @@ function formatDetectChangesResult(result) {
     }
     return lines.join('\n').trim();
 }
-function formatListReposResult(result) {
+export function formatListReposResult(result) {
     if (!Array.isArray(result) || result.length === 0) {
         return 'No indexed repositories.';
     }
@@ -362,10 +362,19 @@ export async function evalServerCommand(options) {
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
 }
+export const MAX_BODY_SIZE = 1024 * 1024; // 1MB
 function readBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
-        req.on('data', (chunk) => chunks.push(chunk));
+        let totalSize = 0;
+        req.on('data', (chunk) => {
+            totalSize += chunk.length;
+            if (totalSize > MAX_BODY_SIZE) {
+                req.destroy(new Error('Request body too large (max 1MB)'));
+                return;
+            }
+            chunks.push(chunk);
+        });
         req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
         req.on('error', reject);
     });

package/dist/cli/index.js

@@ -1,24 +1,6 @@
 #!/usr/bin/env node
-// Raise Node heap limit for large repos (e.g. Linux kernel).
-// Must run before any heavy allocation. If already set by the user, respect it.
-if (!process.env.NODE_OPTIONS?.includes('--max-old-space-size')) {
-    const execArgv = process.execArgv.join(' ');
-    if (!execArgv.includes('--max-old-space-size')) {
-        // Re-spawn with a larger heap (8 GB)
-        const { execFileSync } = await import('node:child_process');
-        try {
-            execFileSync(process.execPath, ['--max-old-space-size=8192', ...process.argv.slice(1)], {
-                stdio: 'inherit',
-                env: { ...process.env, NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim() },
-            });
-            process.exit(0);
-        }
-        catch (e) {
-            // If the child exited with an error code, propagate it
-            process.exit(e.status ?? 1);
-        }
-    }
-}
+// Heap re-spawn removed — only analyze.ts needs the 8GB heap (via its own ensureHeap()).
+// Removing it from here improves MCP server startup time significantly.
 import { Command } from 'commander';
 import { analyzeCommand } from './analyze.js';
 import { serveCommand } from './serve.js';

package/dist/cli/mcp.js

@@ -12,6 +12,8 @@ export const mcpCommand = async () => {
     // KuzuDB lock conflicts and transient errors should degrade gracefully.
     process.on('uncaughtException', (err) => {
         console.error(`GitNexus MCP: uncaught exception — ${err.message}`);
+        // Process is in an undefined state after uncaughtException — exit after flushing
+        setTimeout(() => process.exit(1), 100);
     });
     process.on('unhandledRejection', (reason) => {
         const msg = reason instanceof Error ? reason.message : String(reason);

package/dist/cli/setup.js

@@ -142,7 +142,12 @@ async function installClaudeCodeHooks(result) {
         const src = path.join(pluginHooksPath, 'gitnexus-hook.cjs');
         const dest = path.join(destHooksDir, 'gitnexus-hook.cjs');
         try {
-            const content = await fs.readFile(src, 'utf-8');
+            let content = await fs.readFile(src, 'utf-8');
+            // Inject resolved CLI path so the copied hook can find the CLI
+            // even when it's no longer inside the npm package tree
+            const resolvedCli = path.join(__dirname, '..', 'cli', 'index.js');
+            const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
+            content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = '${normalizedCli}';`);
             await fs.writeFile(dest, content, 'utf-8');
         }
         catch {

package/dist/config/supported-languages.d.ts

@@ -9,5 +9,6 @@ export declare enum SupportedLanguages {
     Go = "go",
     Rust = "rust",
     PHP = "php",
+    Kotlin = "kotlin",
     Swift = "swift"
 }

package/dist/config/supported-languages.js

@@ -10,6 +10,7 @@ export var SupportedLanguages;
     SupportedLanguages["Go"] = "go";
     SupportedLanguages["Rust"] = "rust";
     SupportedLanguages["PHP"] = "php";
+    SupportedLanguages["Kotlin"] = "kotlin";
     // Ruby = 'ruby',
     SupportedLanguages["Swift"] = "swift";
 })(SupportedLanguages || (SupportedLanguages = {}));

package/dist/core/ingestion/call-processor.d.ts

@@ -2,7 +2,7 @@ import { KnowledgeGraph } from '../graph/types.js';
 import { ASTCache } from './ast-cache.js';
 import { SymbolTable } from './symbol-table.js';
 import { ImportMap } from './import-processor.js';
-import type { ExtractedCall } from './workers/parse-worker.js';
+import type { ExtractedCall, ExtractedRoute } from './workers/parse-worker.js';
 export declare const processCalls: (graph: KnowledgeGraph, files: {
     path: string;
     content: string;
@@ -13,3 +13,7 @@ export declare const processCalls: (graph: KnowledgeGraph, files: {
  * This function only does symbol table lookups + graph mutations.
  */
 export declare const processCallsFromExtracted: (graph: KnowledgeGraph, extractedCalls: ExtractedCall[], symbolTable: SymbolTable, importMap: ImportMap, onProgress?: (current: number, total: number) => void) => Promise<void>;
+/**
+ * Resolve pre-extracted Laravel routes to CALLS edges from route files to controller methods.
+ */
+export declare const processRoutesFromExtracted: (graph: KnowledgeGraph, extractedRoutes: ExtractedRoute[], symbolTable: SymbolTable, importMap: ImportMap, onProgress?: (current: number, total: number) => void) => Promise<void>;

package/dist/core/ingestion/call-processor.js

@@ -31,6 +31,10 @@ const FUNCTION_NODE_TYPES = new Set([
     // Rust
     'function_item',
     'impl_item', // Methods inside impl blocks
+    // Kotlin (function_declaration already included above via JS/TS)
+    'anonymous_function',
+    'lambda_literal',
+    // PHP — no additional node types needed
     // Swift
     'init_declaration',
     'deinit_declaration',
@@ -269,6 +273,22 @@ const BUILT_IN_NAMES = new Set([
     'open', 'read', 'write', 'close', 'append', 'extend', 'update',
     'super', 'type', 'isinstance', 'issubclass', 'getattr', 'setattr', 'hasattr',
     'enumerate', 'zip', 'sorted', 'reversed', 'min', 'max', 'sum', 'abs',
+    // Kotlin stdlib (IMPORTANT: keep in sync with parse-worker.ts BUILT_IN_NAMES)
+    'println', 'print', 'readLine', 'require', 'requireNotNull', 'check', 'assert', 'lazy', 'error',
+    'listOf', 'mapOf', 'setOf', 'mutableListOf', 'mutableMapOf', 'mutableSetOf',
+    'arrayOf', 'sequenceOf', 'also', 'apply', 'run', 'with', 'takeIf', 'takeUnless',
+    'TODO', 'buildString', 'buildList', 'buildMap', 'buildSet',
+    'repeat', 'synchronized',
+    // Kotlin coroutine builders & scope functions
+    'launch', 'async', 'runBlocking', 'withContext', 'coroutineScope',
+    'supervisorScope', 'delay',
+    // Kotlin Flow operators
+    'flow', 'flowOf', 'collect', 'emit', 'onEach', 'catch',
+    'buffer', 'conflate', 'distinctUntilChanged',
+    'flatMapLatest', 'flatMapMerge', 'combine',
+    'stateIn', 'shareIn', 'launchIn',
+    // Kotlin infix stdlib functions
+    'to', 'until', 'downTo', 'step',
     // C/C++ standard library and common kernel helpers
     'printf', 'fprintf', 'sprintf', 'snprintf', 'vprintf', 'vfprintf', 'vsprintf', 'vsnprintf',
     'scanf', 'fscanf', 'sscanf',
@@ -364,3 +384,61 @@ export const processCallsFromExtracted = async (graph, extractedCalls, symbolTab
     }
     onProgress?.(totalFiles, totalFiles);
 };
+/**
+ * Resolve pre-extracted Laravel routes to CALLS edges from route files to controller methods.
+ */
+export const processRoutesFromExtracted = async (graph, extractedRoutes, symbolTable, importMap, onProgress) => {
+    for (let i = 0; i < extractedRoutes.length; i++) {
+        const route = extractedRoutes[i];
+        if (i % 50 === 0) {
+            onProgress?.(i, extractedRoutes.length);
+            await yieldToEventLoop();
+        }
+        if (!route.controllerName || !route.methodName)
+            continue;
+        // Resolve controller class in symbol table
+        const controllerDefs = symbolTable.lookupFuzzy(route.controllerName);
+        if (controllerDefs.length === 0)
+            continue;
+        // Prefer import-resolved match
+        const importedFiles = importMap.get(route.filePath);
+        let controllerDef = controllerDefs[0];
+        let confidence = controllerDefs.length === 1 ? 0.7 : 0.5;
+        if (importedFiles) {
+            for (const def of controllerDefs) {
+                if (importedFiles.has(def.filePath)) {
+                    controllerDef = def;
+                    confidence = 0.9;
+                    break;
+                }
+            }
+        }
+        // Find the method on the controller
+        const methodId = symbolTable.lookupExact(controllerDef.filePath, route.methodName);
+        const sourceId = generateId('File', route.filePath);
+        if (!methodId) {
+            // Construct method ID manually
+            const guessedId = generateId('Method', `${controllerDef.filePath}:${route.methodName}`);
+            const relId = generateId('CALLS', `${sourceId}:route->${guessedId}`);
+            graph.addRelationship({
+                id: relId,
+                sourceId,
+                targetId: guessedId,
+                type: 'CALLS',
+                confidence: confidence * 0.8,
+                reason: 'laravel-route',
+            });
+            continue;
+        }
+        const relId = generateId('CALLS', `${sourceId}:route->${methodId}`);
+        graph.addRelationship({
+            id: relId,
+            sourceId,
+            targetId: methodId,
+            type: 'CALLS',
+            confidence,
+            reason: 'laravel-route',
+        });
+    }
+    onProgress?.(extractedRoutes.length, extractedRoutes.length);
+};

package/dist/core/ingestion/framework-detection.d.ts

@@ -45,5 +45,6 @@ export declare const FRAMEWORK_AST_PATTERNS: {
 /**
  * Detect framework entry points from AST definition text (decorators/annotations/attributes).
  * Returns null if no known pattern is found.
+ * Note: callers should slice definitionText to ~300 chars since annotations appear at the start.
  */
 export declare function detectFrameworkFromAST(language: string, definitionText: string): FrameworkHint | null;

package/dist/core/ingestion/framework-detection.js

@@ -96,6 +96,41 @@ export function detectFrameworkFromPath(filePath) {
     if ((p.includes('/service/') || p.includes('/services/')) && p.endsWith('.java')) {
         return { framework: 'java-service', entryPointMultiplier: 1.8, reason: 'java-service' };
     }
+    // ========== KOTLIN FRAMEWORKS ==========
+    // Spring Boot Kotlin controllers
+    if ((p.includes('/controller/') || p.includes('/controllers/')) && p.endsWith('.kt')) {
+        return { framework: 'spring-kotlin', entryPointMultiplier: 3.0, reason: 'spring-kotlin-controller' };
+    }
+    // Spring Boot - files ending in Controller.kt
+    if (p.endsWith('controller.kt')) {
+        return { framework: 'spring-kotlin', entryPointMultiplier: 3.0, reason: 'spring-kotlin-controller-file' };
+    }
+    // Ktor routes
+    if (p.includes('/routes/') && p.endsWith('.kt')) {
+        return { framework: 'ktor', entryPointMultiplier: 2.5, reason: 'ktor-routes' };
+    }
+    // Ktor plugins folder or Routing.kt files
+    if (p.includes('/plugins/') && p.endsWith('.kt')) {
+        return { framework: 'ktor', entryPointMultiplier: 2.0, reason: 'ktor-plugin' };
+    }
+    if (p.endsWith('routing.kt') || p.endsWith('routes.kt')) {
+        return { framework: 'ktor', entryPointMultiplier: 2.5, reason: 'ktor-routing-file' };
+    }
+    // Android Activities, Fragments
+    if ((p.includes('/activity/') || p.includes('/ui/')) && p.endsWith('.kt')) {
+        return { framework: 'android-kotlin', entryPointMultiplier: 2.5, reason: 'android-ui' };
+    }
+    if (p.endsWith('activity.kt') || p.endsWith('fragment.kt')) {
+        return { framework: 'android-kotlin', entryPointMultiplier: 2.5, reason: 'android-component' };
+    }
+    // Kotlin main entry point
+    if (p.endsWith('/main.kt')) {
+        return { framework: 'kotlin', entryPointMultiplier: 3.0, reason: 'kotlin-main' };
+    }
+    // Kotlin Application entry point (common naming)
+    if (p.endsWith('/application.kt')) {
+        return { framework: 'kotlin', entryPointMultiplier: 2.5, reason: 'kotlin-application' };
+    }
     // ========== C# / .NET FRAMEWORKS ==========
     // ASP.NET Controllers
     if (p.includes('/controllers/') && p.endsWith('.cs')) {
@@ -291,6 +326,12 @@ const AST_FRAMEWORK_PATTERNS_BY_LANGUAGE = {
         { framework: 'spring', entryPointMultiplier: 3.2, reason: 'spring-annotation', patterns: FRAMEWORK_AST_PATTERNS.spring },
         { framework: 'jaxrs', entryPointMultiplier: 3.0, reason: 'jaxrs-annotation', patterns: FRAMEWORK_AST_PATTERNS.jaxrs },
     ],
+    kotlin: [
+        { framework: 'spring-kotlin', entryPointMultiplier: 3.2, reason: 'spring-kotlin-annotation', patterns: FRAMEWORK_AST_PATTERNS.spring },
+        { framework: 'jaxrs', entryPointMultiplier: 3.0, reason: 'jaxrs-annotation', patterns: FRAMEWORK_AST_PATTERNS.jaxrs },
+        { framework: 'ktor', entryPointMultiplier: 2.8, reason: 'ktor-routing', patterns: ['routing', 'embeddedServer', 'Application.module'] },
+        { framework: 'android-kotlin', entryPointMultiplier: 2.5, reason: 'android-annotation', patterns: ['@AndroidEntryPoint', 'AppCompatActivity', 'Fragment('] },
+    ],
     csharp: [
         { framework: 'aspnet', entryPointMultiplier: 3.2, reason: 'aspnet-attribute', patterns: FRAMEWORK_AST_PATTERNS.aspnet },
     ],
@@ -298,20 +339,26 @@ const AST_FRAMEWORK_PATTERNS_BY_LANGUAGE = {
         { framework: 'laravel', entryPointMultiplier: 3.0, reason: 'php-route-attribute', patterns: FRAMEWORK_AST_PATTERNS.laravel },
     ],
 };
+/** Pre-lowercased patterns for O(1) pattern matching at runtime */
+const AST_PATTERNS_LOWERED = Object.fromEntries(Object.entries(AST_FRAMEWORK_PATTERNS_BY_LANGUAGE).map(([lang, cfgs]) => [
+    lang,
+    cfgs.map(cfg => ({ ...cfg, patterns: cfg.patterns.map(p => p.toLowerCase()) })),
+]));
 /**
  * Detect framework entry points from AST definition text (decorators/annotations/attributes).
  * Returns null if no known pattern is found.
+ * Note: callers should slice definitionText to ~300 chars since annotations appear at the start.
  */
 export function detectFrameworkFromAST(language, definitionText) {
     if (!language || !definitionText)
         return null;
-    const configs = AST_FRAMEWORK_PATTERNS_BY_LANGUAGE[language.toLowerCase()];
+    const configs = AST_PATTERNS_LOWERED[language.toLowerCase()];
     if (!configs || configs.length === 0)
         return null;
     const normalized = definitionText.toLowerCase();
     for (const cfg of configs) {
         for (const pattern of cfg.patterns) {
-            if (normalized.includes(pattern.toLowerCase())) {
+            if (normalized.includes(pattern)) {
                 return {
                     framework: cfg.framework,
                     entryPointMultiplier: cfg.entryPointMultiplier,