@veewo/gitnexus 1.3.4

package/dist/cli/ai-context.js

@@ -0,0 +1,184 @@
+/**
+ * AI Context Generator
+ *
+ * Creates AGENTS.md and CLAUDE.md with full inline GitNexus context.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Cline, etc.
+ * CLAUDE.md is for Claude Code which only reads that file.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+// ESM equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const GITNEXUS_START_MARKER = '<!-- gitnexus:start -->';
+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
+ */
+function generateGitNexusContent(projectName, stats) {
+    return `${GITNEXUS_START_MARKER}
+# GitNexus MCP
+
+This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows).
+
+## Always Start Here
+
+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**
+
+> If step 1 warns the index is stale, run \`npx gitnexus analyze\` in the terminal first.
+
+## Skills
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | \`.agents/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
+| Blast radius / "What breaks if I change X?" | \`.agents/skills/gitnexus/gitnexus-impact-analysis/SKILL.md\` |
+| Trace bugs / "Why is X failing?" | \`.agents/skills/gitnexus/gitnexus-debugging/SKILL.md\` |
+| Rename / extract / split / refactor | \`.agents/skills/gitnexus/gitnexus-refactoring/SKILL.md\` |
+| Tools, resources, schema reference | \`.agents/skills/gitnexus/gitnexus-guide/SKILL.md\` |
+| Index, status, clean, wiki CLI commands | \`.agents/skills/gitnexus/gitnexus-cli/SKILL.md\` |
+
+${GITNEXUS_END_MARKER}`;
+}
+/**
+ * Check if a file exists
+ */
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create or update GitNexus section in a file
+ * - If file doesn't exist: create with GitNexus content
+ * - If file exists without GitNexus section: append
+ * - If file exists with GitNexus section: replace that section
+ */
+async function upsertGitNexusSection(filePath, content) {
+    const exists = await fileExists(filePath);
+    if (!exists) {
+        await fs.writeFile(filePath, content, 'utf-8');
+        return 'created';
+    }
+    const existingContent = await fs.readFile(filePath, 'utf-8');
+    // 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) {
+        // Replace existing section
+        const before = existingContent.substring(0, startIdx);
+        const after = existingContent.substring(endIdx + GITNEXUS_END_MARKER.length);
+        const newContent = before + content + after;
+        await fs.writeFile(filePath, newContent.trim() + '\n', 'utf-8');
+        return 'updated';
+    }
+    // Append new section
+    const newContent = existingContent.trim() + '\n\n' + content + '\n';
+    await fs.writeFile(filePath, newContent, 'utf-8');
+    return 'appended';
+}
+/**
+ * Install repo-local GitNexus skills to .agents/skills/gitnexus/
+ * AGENTS.md should reference this path consistently.
+ */
+async function installSkills(repoPath) {
+    const skillsDir = path.join(repoPath, '.agents', 'skills', 'gitnexus');
+    const installedSkills = [];
+    // Skill definitions bundled with the package
+    const skills = [
+        {
+            name: 'gitnexus-exploring',
+            description: 'Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: "How does X work?", "What calls this function?", "Show me the auth flow"',
+        },
+        {
+            name: 'gitnexus-debugging',
+            description: 'Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: "Why is X failing?", "Where does this error come from?", "Trace this bug"',
+        },
+        {
+            name: 'gitnexus-impact-analysis',
+            description: 'Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: "Is it safe to change X?", "What depends on this?", "What will break?"',
+        },
+        {
+            name: 'gitnexus-refactoring',
+            description: 'Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: "Rename this function", "Extract this into a module", "Refactor this class", "Move this to a separate file"',
+        },
+        {
+            name: 'gitnexus-guide',
+            description: 'Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: "What GitNexus tools are available?", "How do I use GitNexus?"',
+        },
+        {
+            name: 'gitnexus-cli',
+            description: 'Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: "Index this repo", "Reanalyze the codebase", "Generate a wiki"',
+        },
+    ];
+    for (const skill of skills) {
+        const skillDir = path.join(skillsDir, skill.name);
+        const skillPath = path.join(skillDir, 'SKILL.md');
+        try {
+            // Create skill directory
+            await fs.mkdir(skillDir, { recursive: true });
+            // Try to read from package skills directory
+            const packageSkillPath = path.join(__dirname, '..', '..', 'skills', `${skill.name}.md`);
+            let skillContent;
+            try {
+                skillContent = await fs.readFile(packageSkillPath, 'utf-8');
+            }
+            catch {
+                // Fallback: generate minimal skill content
+                skillContent = `---
+name: ${skill.name}
+description: ${skill.description}
+---
+
+# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
+
+${skill.description}
+
+Use GitNexus tools to accomplish this task.
+`;
+            }
+            await fs.writeFile(skillPath, skillContent, 'utf-8');
+            installedSkills.push(skill.name);
+        }
+        catch (err) {
+            // Skip on error, don't fail the whole process
+            console.warn(`Warning: Could not install skill ${skill.name}:`, err);
+        }
+    }
+    return installedSkills;
+}
+/**
+ * Generate AI context files after indexing
+ */
+export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats) {
+    const content = generateGitNexusContent(projectName, stats);
+    const createdFiles = [];
+    // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.)
+    const agentsPath = path.join(repoPath, 'AGENTS.md');
+    const agentsResult = await upsertGitNexusSection(agentsPath, content);
+    createdFiles.push(`AGENTS.md (${agentsResult})`);
+    // Create CLAUDE.md (for Claude Code)
+    const claudePath = path.join(repoPath, 'CLAUDE.md');
+    const claudeResult = await upsertGitNexusSection(claudePath, content);
+    createdFiles.push(`CLAUDE.md (${claudeResult})`);
+    // Install skills to .agents/skills/gitnexus/
+    const installedSkills = await installSkills(repoPath);
+    if (installedSkills.length > 0) {
+        createdFiles.push(`.agents/skills/gitnexus/ (${installedSkills.length} skills)`);
+    }
+    return { files: createdFiles };
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/cli/ai-context.test.js

@@ -0,0 +1,30 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { generateAIContextFiles } from './ai-context.js';
+test('generateAIContextFiles installs repo skills under .agents/skills/gitnexus', async () => {
+    const repoPath = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ai-context-'));
+    try {
+        const result = await generateAIContextFiles(repoPath, '', 'demo-repo', {
+            nodes: 1,
+            edges: 2,
+            processes: 3,
+        });
+        const agentsPath = path.join(repoPath, 'AGENTS.md');
+        const claudePath = path.join(repoPath, 'CLAUDE.md');
+        const skillPath = path.join(repoPath, '.agents', 'skills', 'gitnexus', 'gitnexus-exploring', 'SKILL.md');
+        const legacyClaudeSkillsDir = path.join(repoPath, '.claude', 'skills');
+        const agentsContent = await fs.readFile(agentsPath, 'utf-8');
+        const claudeContent = await fs.readFile(claudePath, 'utf-8');
+        await fs.access(skillPath);
+        assert.match(agentsContent, /\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
+        assert.match(claudeContent, /\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
+        assert.ok(result.files.some((entry) => entry.includes('.agents/skills/gitnexus/')), 'expected generated file summary to include .agents/skills/gitnexus/');
+        await assert.rejects(fs.access(legacyClaudeSkillsDir));
+    }
+    finally {
+        await fs.rm(repoPath, { recursive: true, force: true });
+    }
+});

package/dist/cli/analyze-multi-scope-regression.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/analyze-multi-scope-regression.test.js

@@ -0,0 +1,22 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runPipelineFromRepo } from '../core/ingestion/pipeline.js';
+test('runPipelineFromRepo deduplicates overlapping scope matches and reports diagnostics', { timeout: 60_000 }, async () => {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const fixtureRepo = path.resolve(here, '../../../benchmarks/fixtures/unity-mini');
+    const result = await runPipelineFromRepo(fixtureRepo, () => { }, {
+        includeExtensions: ['.cs'],
+        scopeRules: ['Assets', 'Assets/Scripts'],
+    });
+    const fileNodes = [...result.graph.iterNodes()].filter((node) => node.label === 'File');
+    const uniqueFilePaths = new Set(fileNodes.map((node) => String(node.properties.filePath)));
+    assert.equal(uniqueFilePaths.size, 3);
+    assert.equal(fileNodes.length, 3);
+    assert.equal(result.scopeDiagnostics?.appliedRuleCount, 2);
+    assert.equal(result.scopeDiagnostics?.matchedFiles, 3);
+    assert.equal(result.scopeDiagnostics?.overlapFiles, 3);
+    assert.equal(result.scopeDiagnostics?.dedupedMatchCount, 3);
+    assert.equal(result.scopeDiagnostics?.normalizedCollisions.length, 0);
+});

package/dist/cli/analyze-options.d.ts

@@ -0,0 +1,7 @@
+export interface AnalyzeScopeOptions {
+    scopeManifest?: string;
+    scopePrefix?: string[] | string;
+}
+export declare function parseExtensionList(rawExtensions?: string): string[];
+export declare function normalizeRepoAlias(repoAlias?: string): string | undefined;
+export declare function resolveAnalyzeScopeRules(options?: AnalyzeScopeOptions): Promise<string[]>;

package/dist/cli/analyze-options.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeScopeRules, parseScopeRules } from '../core/ingestion/scope-filter.js';
+const REPO_ALIAS_REGEX = /^[a-zA-Z0-9._-]{3,64}$/;
+export function parseExtensionList(rawExtensions) {
+    return (rawExtensions || '')
+        .split(',')
+        .map((ext) => ext.trim().toLowerCase())
+        .filter(Boolean)
+        .map((ext) => (ext.startsWith('.') ? ext : `.${ext}`));
+}
+export function normalizeRepoAlias(repoAlias) {
+    if (!repoAlias)
+        return undefined;
+    const normalized = repoAlias.trim();
+    if (!normalized)
+        return undefined;
+    if (!REPO_ALIAS_REGEX.test(normalized)) {
+        throw new Error('Invalid repo alias. Use ^[a-zA-Z0-9._-]{3,64}$');
+    }
+    return normalized;
+}
+export async function resolveAnalyzeScopeRules(options) {
+    const rules = [];
+    if (options?.scopeManifest) {
+        const manifestPath = path.resolve(options.scopeManifest);
+        let content;
+        try {
+            content = await fs.readFile(manifestPath, 'utf-8');
+        }
+        catch {
+            throw new Error(`Scope manifest not found: ${manifestPath}`);
+        }
+        const manifestRules = parseScopeRules(content);
+        if (manifestRules.length === 0) {
+            throw new Error(`Scope manifest has no valid scope rules: ${manifestPath}`);
+        }
+        rules.push(...manifestRules);
+    }
+    const prefixesRaw = Array.isArray(options?.scopePrefix)
+        ? options?.scopePrefix || []
+        : options?.scopePrefix
+            ? [options.scopePrefix]
+            : [];
+    for (const prefix of prefixesRaw) {
+        const trimmed = prefix.trim();
+        if (trimmed) {
+            rules.push(trimmed);
+        }
+    }
+    const normalizedRules = normalizeScopeRules(rules);
+    if ((options?.scopeManifest || prefixesRaw.length > 0) && normalizedRules.length === 0) {
+        throw new Error('No valid scope rules provided.');
+    }
+    return normalizedRules;
+}

package/dist/cli/analyze-options.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/analyze-options.test.js

@@ -0,0 +1,36 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { normalizeRepoAlias, parseExtensionList, resolveAnalyzeScopeRules } from './analyze-options.js';
+test('parseExtensionList normalizes dot prefixes', () => {
+    const exts = parseExtensionList('cs,.ts, go ');
+    assert.deepEqual(exts, ['.cs', '.ts', '.go']);
+});
+test('normalizeRepoAlias validates format', () => {
+    assert.equal(normalizeRepoAlias(undefined), undefined);
+    assert.equal(normalizeRepoAlias('neonspark-v1-subset'), 'neonspark-v1-subset');
+    assert.throws(() => normalizeRepoAlias('ab'), /repo alias/i);
+    assert.throws(() => normalizeRepoAlias('bad alias'), /repo alias/i);
+});
+test('resolveAnalyzeScopeRules combines manifest and repeated prefixes', async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-scope-test-'));
+    const manifestPath = path.join(tmpDir, 'scope.txt');
+    await fs.writeFile(manifestPath, '# comment\nAssets/NEON/Code\n\nPackages/com.veewo.*\n', 'utf-8');
+    const rules = await resolveAnalyzeScopeRules({
+        scopeManifest: manifestPath,
+        scopePrefix: ['Packages/com.neonspark.*'],
+    });
+    assert.deepEqual(rules, [
+        'Assets/NEON/Code',
+        'Packages/com.veewo.*',
+        'Packages/com.neonspark.*',
+    ]);
+});
+test('resolveAnalyzeScopeRules fails when manifest has no usable rule', async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-scope-test-'));
+    const manifestPath = path.join(tmpDir, 'empty-scope.txt');
+    await fs.writeFile(manifestPath, '# only comments\n\n', 'utf-8');
+    await assert.rejects(resolveAnalyzeScopeRules({ scopeManifest: manifestPath }), /no valid scope rules/i);
+});

package/dist/cli/analyze.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Analyze Command
+ *
+ * Indexes a repository and stores the knowledge graph in .gitnexus/
+ */
+export interface AnalyzeOptions {
+    force?: boolean;
+    embeddings?: boolean;
+    extensions?: string;
+    repoAlias?: string;
+    scopeManifest?: string;
+    scopePrefix?: string[];
+}
+export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;