gitnexus 1.3.10 → 1.4.0

package/README.md

@@ -139,7 +139,8 @@ Your AI agent gets these tools automatically:
 gitnexus setup                    # Configure MCP for your editors (one-time)
 gitnexus analyze [path]           # Index a repository (or update stale index)
 gitnexus analyze --force          # Force full re-index
-gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
+gitnexus analyze --embeddings     # Enable embedding generation (slower, better search)
+gitnexus analyze --verbose        # Log skipped files when parsers are unavailable
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
 gitnexus list                    # List all indexed repositories
@@ -156,7 +157,26 @@ GitNexus supports indexing multiple repositories. Each `gitnexus analyze` regist
 
 ## Supported Languages
 
-TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Swift
+TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift
+
+### Language Feature Matrix
+
+| Language | Imports | Types | Exports | Named Bindings | Config | Frameworks | Entry Points | Heritage |
+|----------|---------|-------|---------|----------------|--------|------------|-------------|----------|
+| TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| JavaScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| C# | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Java | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ |
+| Kotlin | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ |
+| Go | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
+| Rust | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ |
+| PHP | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — |
+| Swift | — | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
+| C | — | ✓ | ✓ | — | — | ✓ | ✓ | ✓ |
+| C++ | — | ✓ | ✓ | — | — | ✓ | ✓ | ✓ |
+
+**Imports** — cross-file import resolution · **Types** — type annotation extraction · **Exports** — public/exported symbol detection · **Named Bindings** — `import { X }` tracking · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics · **Heritage** — class inheritance / interface implementation
 
 ## Agent Skills
 

package/dist/cli/ai-context.d.ts

@@ -5,6 +5,7 @@
  * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Cline, etc.
  * CLAUDE.md is for Claude Code which only reads that file.
  */
+import { type GeneratedSkillInfo } from './skill-gen.js';
 interface RepoStats {
     files?: number;
     nodes?: number;
@@ -16,7 +17,7 @@ interface RepoStats {
 /**
  * Generate AI context files after indexing
  */
-export declare function generateAIContextFiles(repoPath: string, _storagePath: string, projectName: string, stats: RepoStats): Promise<{
+export declare function generateAIContextFiles(repoPath: string, _storagePath: string, projectName: string, stats: RepoStats, generatedSkills?: GeneratedSkillInfo[]): Promise<{
     files: string[];
 }>;
 export {};

package/dist/cli/ai-context.js

@@ -24,7 +24,18 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
  * - Exact tool commands with parameters — vague directives get ignored
  * - Self-review checklist — forces model to verify its own work
  */
-function generateGitNexusContent(projectName, stats) {
+function generateGitNexusContent(projectName, stats, generatedSkills) {
+    const generatedRows = (generatedSkills && generatedSkills.length > 0)
+        ? generatedSkills.map(s => `| Work in the ${s.label} area (${s.symbolCount} symbols) | \`.claude/skills/generated/${s.name}/SKILL.md\` |`).join('\n')
+        : '';
+    const skillsTable = `| 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\` |${generatedRows ? '\n' + generatedRows : ''}`;
     return `${GITNEXUS_START_MARKER}
 # GitNexus — Code Intelligence
 
@@ -96,11 +107,27 @@ Before completing any code modification task, verify:
 3. \`gitnexus_detect_changes()\` confirms changes match expected scope
 4. All d=1 (WILL BREAK) dependents were updated
 
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+\`\`\`bash
+npx gitnexus analyze
+\`\`\`
+
+If the index previously included embeddings, preserve them by adding \`--embeddings\`:
+
+\`\`\`bash
+npx gitnexus analyze --embeddings
+\`\`\`
+
+To check whether embeddings exist, inspect \`.gitnexus/meta.json\` — the \`stats.embeddings\` field shows the count (0 means no embeddings). **Running analyze without \`--embeddings\` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after \`git commit\` and \`git merge\`.
+
 ## CLI
 
-- Re-index: \`npx gitnexus analyze\`
-- Check freshness: \`npx gitnexus status\`
-- Generate docs: \`npx gitnexus wiki\`
+${skillsTable}
 
 ${GITNEXUS_END_MARKER}`;
 }
@@ -218,8 +245,8 @@ Use GitNexus tools to accomplish this task.
 /**
  * Generate AI context files after indexing
  */
-export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats) {
-    const content = generateGitNexusContent(projectName, stats);
+export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats, generatedSkills) {
+    const content = generateGitNexusContent(projectName, stats, generatedSkills);
     const createdFiles = [];
     // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.)
     const agentsPath = path.join(repoPath, 'AGENTS.md');

package/dist/cli/analyze.d.ts

@@ -6,5 +6,7 @@
 export interface AnalyzeOptions {
     force?: boolean;
     embeddings?: boolean;
+    skills?: boolean;
+    verbose?: boolean;
 }
 export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

package/dist/cli/analyze.js

@@ -16,6 +16,7 @@ import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReuse
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath } from '../storage/repo-manager.js';
 import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
 import { generateAIContextFiles } from './ai-context.js';
+import { generateSkillFiles } from './skill-gen.js';
 import fs from 'fs/promises';
 const HEAP_MB = 8192;
 const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
@@ -58,6 +59,9 @@ const PHASE_LABELS = {
 export const analyzeCommand = async (inputPath, options) => {
     if (ensureHeap())
         return;
+    if (options?.verbose) {
+        process.env.GITNEXUS_VERBOSE = '1';
+    }
     console.log('\n  GitNexus Analyzer\n');
     let repoPath;
     if (inputPath) {
@@ -80,7 +84,7 @@ export const analyzeCommand = async (inputPath, options) => {
     const { storagePath, kuzuPath } = getStoragePaths(repoPath);
     const currentCommit = getCurrentCommit(repoPath);
     const existingMeta = await loadMeta(storagePath);
-    if (existingMeta && !options?.force && existingMeta.lastCommit === currentCommit) {
+    if (existingMeta && !options?.force && !options?.skills && existingMeta.lastCommit === currentCommit) {
         console.log('  Already up to date\n');
         return;
     }
@@ -242,6 +246,13 @@ export const analyzeCommand = async (inputPath, options) => {
     }
     // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
     updateBar(98, 'Saving metadata...');
+    // Count embeddings in the index (cached + newly generated)
+    let embeddingCount = 0;
+    try {
+        const embResult = await executeQuery(`MATCH (e:CodeEmbedding) RETURN count(e) AS cnt`);
+        embeddingCount = embResult?.[0]?.cnt ?? 0;
+    }
+    catch { /* table may not exist if embeddings never ran */ }
     const meta = {
         repoPath,
         lastCommit: currentCommit,
@@ -252,6 +263,7 @@ export const analyzeCommand = async (inputPath, options) => {
             edges: stats.edges,
             communities: pipelineResult.communityResult?.stats.totalCommunities,
             processes: pipelineResult.processResult?.stats.totalProcesses,
+            embeddings: embeddingCount,
         },
     };
     await saveMeta(storagePath, meta);
@@ -267,6 +279,12 @@ export const analyzeCommand = async (inputPath, options) => {
         }
         aggregatedClusterCount = Array.from(groups.values()).filter(count => count >= 5).length;
     }
+    let generatedSkills = [];
+    if (options?.skills && pipelineResult.communityResult) {
+        updateBar(99, 'Generating skill files...');
+        const skillResult = await generateSkillFiles(repoPath, projectName, pipelineResult);
+        generatedSkills = skillResult.skills;
+    }
     const aiContext = await generateAIContextFiles(repoPath, storagePath, projectName, {
         files: pipelineResult.totalFileCount,
         nodes: stats.nodes,
@@ -274,7 +292,7 @@ export const analyzeCommand = async (inputPath, options) => {
         communities: pipelineResult.communityResult?.stats.totalCommunities,
         clusters: aggregatedClusterCount,
         processes: pipelineResult.processResult?.stats.totalProcesses,
-    });
+    }, generatedSkills);
     await closeKuzu();
     // Note: we intentionally do NOT call disposeEmbedder() here.
     // ONNX Runtime's native cleanup segfaults on macOS and some Linux configs.

package/dist/cli/index.js

@@ -20,6 +20,8 @@ program
     .description('Index a repository (full analysis)')
     .option('-f, --force', 'Force full re-index even if up to date')
     .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
+    .option('--skills', 'Generate repo-specific skill files from detected communities')
+    .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
 program
     .command('serve')

package/dist/cli/setup.js

@@ -147,36 +147,34 @@ async function installClaudeCodeHooks(result) {
             // 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}';`);
+            const jsonCli = JSON.stringify(normalizedCli);
+            content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = ${jsonCli};`);
             await fs.writeFile(dest, content, 'utf-8');
         }
         catch {
             // Script not found in source — skip
         }
-        const hookCmd = `node "${path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/')}"`;
+        const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
+        const hookCmd = `node "${hookPath.replace(/"/g, '\\"')}"`;
         // Merge hook config into ~/.claude/settings.json
         const existing = await readJsonFile(settingsPath) || {};
         if (!existing.hooks)
             existing.hooks = {};
-        // NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
-        // Session context is delivered via CLAUDE.md / skills instead.
-        // Add PreToolUse hook if not already present
-        if (!existing.hooks.PreToolUse)
-            existing.hooks.PreToolUse = [];
-        const hasPreToolHook = existing.hooks.PreToolUse.some((h) => h.hooks?.some((hh) => hh.command?.includes('gitnexus')));
-        if (!hasPreToolHook) {
-            existing.hooks.PreToolUse.push({
-                matcher: 'Grep|Glob|Bash',
-                hooks: [{
-                        type: 'command',
-                        command: hookCmd,
-                        timeout: 8000,
-                        statusMessage: 'Enriching with GitNexus graph context...',
-                    }],
-            });
+        function ensureHookEntry(eventName, matcher, timeout, statusMessage) {
+            if (!existing.hooks[eventName])
+                existing.hooks[eventName] = [];
+            const hasHook = existing.hooks[eventName].some((h) => h.hooks?.some(hh => hh.command?.includes('gitnexus-hook')));
+            if (!hasHook) {
+                existing.hooks[eventName].push({
+                    matcher,
+                    hooks: [{ type: 'command', command: hookCmd, timeout, statusMessage }],
+                });
+            }
         }
+        ensureHookEntry('PreToolUse', 'Grep|Glob|Bash', 10, 'Enriching with GitNexus graph context...');
+        ensureHookEntry('PostToolUse', 'Bash', 10, 'Checking GitNexus index freshness...');
         await writeJsonFile(settingsPath, existing);
-        result.configured.push('Claude Code hooks (PreToolUse)');
+        result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
     }
     catch (err) {
         result.errors.push(`Claude Code hooks: ${err.message}`);

package/dist/cli/skill-gen.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Skill File Generator
+ *
+ * Generates repo-specific SKILL.md files from detected Leiden communities.
+ * Each significant community becomes a skill that describes a functional area
+ * of the codebase, including key files, entry points, execution flows, and
+ * cross-community connections.
+ */
+import { PipelineResult } from '../types/pipeline.js';
+export interface GeneratedSkillInfo {
+    name: string;
+    label: string;
+    symbolCount: number;
+    fileCount: number;
+}
+/**
+ * @brief Generate repo-specific skill files from detected communities
+ * @param {string} repoPath - Absolute path to the repository root
+ * @param {string} projectName - Human-readable project name
+ * @param {PipelineResult} pipelineResult - In-memory pipeline data with communities, processes, graph
+ * @returns {Promise<{ skills: GeneratedSkillInfo[], outputPath: string }>} Generated skill metadata
+ */
+export declare const generateSkillFiles: (repoPath: string, projectName: string, pipelineResult: PipelineResult) => Promise<{
+    skills: GeneratedSkillInfo[];
+    outputPath: string;
+}>;