@veewo/gitnexus 1.3.11 → 1.4.6-rc

package/skills/gitnexus-pr-review.md

@@ -0,0 +1,163 @@
+---
+name: gitnexus-pr-review
+description: "Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check for missing test coverage. Examples: \"Review this PR\", \"What does PR #42 change?\", \"Is this PR safe to merge?\""
+---
+
+# PR Review with GitNexus
+
+## When to Use
+
+- "Review this PR"
+- "What does PR #42 change?"
+- "Is this safe to merge?"
+- "What's the blast radius of this PR?"
+- "Are there missing tests for this PR?"
+- Reviewing someone else's code changes before merge
+
+## Workflow
+
+```
+1. gh pr diff <number>                                    → Get the raw diff
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
+3. For each changed symbol:
+   gitnexus_impact({target: "<symbol>", direction: "upstream"})    → Blast radius per change
+4. gitnexus_context({name: "<key symbol>"})               → Understand callers/callees
+5. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+6. Summarize findings with risk assessment
+```
+
+> If "Index is stale" → run `npx -y @veewo/gitnexus@latest analyze` in terminal before reviewing.
+
+## Checklist
+
+```
+- [ ] Fetch PR diff (gh pr diff or git diff base...head)
+- [ ] gitnexus_detect_changes to map changes to affected execution flows
+- [ ] gitnexus_impact on each non-trivial changed symbol
+- [ ] Review d=1 items (WILL BREAK) — are callers updated?
+- [ ] gitnexus_context on key changed symbols to understand full picture
+- [ ] Check if affected processes have test coverage
+- [ ] Assess overall risk level
+- [ ] Write review summary with findings
+```
+
+## Review Dimensions
+
+| Dimension | How GitNexus Helps |
+| --- | --- |
+| **Correctness** | `context` shows callers — are they all compatible with the change? |
+| **Blast radius** | `impact` shows d=1/d=2/d=3 dependents — anything missed? |
+| **Completeness** | `detect_changes` shows all affected flows — are they all handled? |
+| **Test coverage** | `impact({includeTests: true})` shows which tests touch changed code |
+| **Breaking changes** | d=1 upstream items that aren't updated in the PR = potential breakage |
+
+## Risk Assessment
+
+| Signal | Risk |
+| --- | --- |
+| Changes touch <3 symbols, 0-1 processes | LOW |
+| Changes touch 3-10 symbols, 2-5 processes | MEDIUM |
+| Changes touch >10 symbols or many processes | HIGH |
+| Changes touch auth, payments, or data integrity code | CRITICAL |
+| d=1 callers exist outside the PR diff | Potential breakage — flag it |
+
+## Tools
+
+**gitnexus_detect_changes** — map PR diff to affected execution flows:
+
+```
+gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+
+→ Changed: 8 symbols in 4 files
+→ Affected processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Risk: MEDIUM
+```
+
+**gitnexus_impact** — blast radius per changed symbol:
+
+```
+gitnexus_impact({target: "validatePayment", direction: "upstream"})
+
+→ d=1 (WILL BREAK):
+  - processCheckout (src/checkout.ts:42) [CALLS, 100%]
+  - webhookHandler (src/webhooks.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - checkoutRouter (src/routes/checkout.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_impact with tests** — check test coverage:
+
+```
+gitnexus_impact({target: "validatePayment", direction: "upstream", includeTests: true})
+
+→ Tests that cover this symbol:
+  - validatePayment.test.ts [direct]
+  - checkout.integration.test.ts [via processCheckout]
+```
+
+**gitnexus_context** — understand a changed symbol's role:
+
+```
+gitnexus_context({name: "validatePayment"})
+
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates
+→ Processes: CheckoutFlow (step 3/7), RefundFlow (step 1/5)
+```
+
+## Example: "Review PR #42"
+
+```
+1. gh pr diff 42 > /tmp/pr42.diff
+   → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts
+
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+   → Changed symbols: validatePayment, PaymentInput, formatAmount
+   → Affected processes: CheckoutFlow, RefundFlow
+   → Risk: MEDIUM
+
+3. gitnexus_impact({target: "validatePayment", direction: "upstream"})
+   → d=1: processCheckout, webhookHandler (WILL BREAK)
+   → webhookHandler is NOT in the PR diff — potential breakage!
+
+4. gitnexus_impact({target: "PaymentInput", direction: "upstream"})
+   → d=1: validatePayment (in PR), createPayment (NOT in PR)
+   → createPayment uses the old PaymentInput shape — breaking change!
+
+5. gitnexus_context({name: "formatAmount"})
+   → Called by 12 functions — but change is backwards-compatible (added optional param)
+
+6. Review summary:
+   - MEDIUM risk — 3 changed symbols affect 2 execution flows
+   - BUG: webhookHandler calls validatePayment but isn't updated for new signature
+   - BUG: createPayment depends on PaymentInput type which changed
+   - OK: formatAmount change is backwards-compatible
+   - Tests: checkout.test.ts covers processCheckout path, but no webhook test
+```
+
+## Review Output Format
+
+Structure your review as:
+
+```markdown
+## PR Review: <title>
+
+**Risk: LOW / MEDIUM / HIGH / CRITICAL**
+
+### Changes Summary
+- <N> symbols changed across <M> files
+- <P> execution flows affected
+
+### Findings
+1. **[severity]** Description of finding
+   - Evidence from GitNexus tools
+   - Affected callers/flows
+
+### Missing Coverage
+- Callers not updated in PR: ...
+- Untested flows: ...
+
+### Recommendation
+APPROVE / REQUEST CHANGES / NEEDS DISCUSSION
+```

package/skills/gitnexus-refactoring.md

@@ -23,7 +23,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 5. Plan update order: interfaces → implementations → callers → tests
 ```
 
-> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+> If "Index is stale" → run `npx -y @veewo/gitnexus@latest analyze` in terminal.
 
 ## Checklists
 

package/dist/cli/claude-hooks.d.ts

@@ -1,22 +0,0 @@
-/**
- * Claude Code Hook Registration
- *
- * Registers the GitNexus PreToolUse hook in ~/.claude/hooks.json
- * so that grep/glob/bash calls are automatically augmented with
- * knowledge graph context.
- *
- * Idempotent — safe to call multiple times.
- */
-/**
- * Register (or verify) the GitNexus hook in Claude Code's global hooks.json.
- *
- * - Creates ~/.claude/ and hooks.json if they don't exist
- * - Preserves existing hooks from other tools
- * - Skips if GitNexus hook is already registered
- *
- * Returns a status message for the CLI output.
- */
-export declare function registerClaudeHook(): Promise<{
-    registered: boolean;
-    message: string;
-}>;

package/dist/cli/claude-hooks.js

@@ -1,97 +0,0 @@
-/**
- * Claude Code Hook Registration
- *
- * Registers the GitNexus PreToolUse hook in ~/.claude/hooks.json
- * so that grep/glob/bash calls are automatically augmented with
- * knowledge graph context.
- *
- * Idempotent — safe to call multiple times.
- */
-import fs from 'fs/promises';
-import path from 'path';
-import os from 'os';
-import { fileURLToPath } from 'url';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-/**
- * Get the absolute path to the gitnexus-hook.js file.
- * Works for both local dev and npm-installed packages.
- */
-function getHookScriptPath() {
-    // From dist/cli/claude-hooks.js → hooks/claude/gitnexus-hook.js
-    const packageRoot = path.resolve(__dirname, '..', '..');
-    return path.join(packageRoot, 'hooks', 'claude', 'gitnexus-hook.cjs');
-}
-/**
- * Register (or verify) the GitNexus hook in Claude Code's global hooks.json.
- *
- * - Creates ~/.claude/ and hooks.json if they don't exist
- * - Preserves existing hooks from other tools
- * - Skips if GitNexus hook is already registered
- *
- * Returns a status message for the CLI output.
- */
-export async function registerClaudeHook() {
-    const claudeDir = path.join(os.homedir(), '.claude');
-    const hooksFile = path.join(claudeDir, 'hooks.json');
-    const hookScript = getHookScriptPath();
-    // Check if the hook script exists
-    try {
-        await fs.access(hookScript);
-    }
-    catch {
-        return { registered: false, message: 'Hook script not found (package may be incomplete)' };
-    }
-    // Build the hook command — use node + absolute path for reliability
-    const hookCommand = `node "${hookScript}"`;
-    // Check if ~/.claude/ exists (user has Claude Code installed)
-    try {
-        await fs.access(claudeDir);
-    }
-    catch {
-        // No Claude Code installation — skip silently
-        return { registered: false, message: 'Claude Code not detected (~/.claude/ not found)' };
-    }
-    // Read existing hooks.json or start fresh
-    let hooksConfig = {};
-    try {
-        const existing = await fs.readFile(hooksFile, 'utf-8');
-        hooksConfig = JSON.parse(existing);
-    }
-    catch {
-        // File doesn't exist or is invalid — we'll create it
-    }
-    // Ensure the hooks structure exists
-    if (!hooksConfig.hooks) {
-        hooksConfig.hooks = {};
-    }
-    if (!Array.isArray(hooksConfig.hooks.PreToolUse)) {
-        hooksConfig.hooks.PreToolUse = [];
-    }
-    // Check if GitNexus hook is already registered
-    const existingEntry = hooksConfig.hooks.PreToolUse.find((entry) => {
-        if (!entry.hooks || !Array.isArray(entry.hooks))
-            return false;
-        return entry.hooks.some((h) => h.command && (h.command.includes('gitnexus-hook') ||
-            h.command.includes('gitnexus augment')));
-    });
-    if (existingEntry) {
-        return { registered: true, message: 'Claude Code hook already registered' };
-    }
-    // Add the GitNexus hook entry
-    hooksConfig.hooks.PreToolUse.push({
-        matcher: {
-            tool_name: "Grep|Glob|Bash"
-        },
-        hooks: [
-            {
-                type: "command",
-                command: hookCommand,
-                timeout: 8000
-            }
-        ]
-    });
-    // Write back
-    await fs.writeFile(hooksFile, JSON.stringify(hooksConfig, null, 2) + '\n', 'utf-8');
-    return { registered: true, message: 'Claude Code hook registered' };
-}

package/dist/mcp/core/kuzu-adapter.js

@@ -1,231 +0,0 @@
-/**
- * KuzuDB Adapter (Connection Pool)
- *
- * Manages a pool of KuzuDB databases keyed by repoId, each with
- * multiple Connection objects for safe concurrent query execution.
- *
- * KuzuDB Connections are NOT thread-safe — a single Connection
- * segfaults if concurrent .query() calls hit it simultaneously.
- * This adapter provides a checkout/return connection pool so each
- * concurrent query gets its own Connection from the same Database.
- *
- * @see https://docs.kuzudb.com/concurrency — multiple Connections
- * from the same Database is the officially supported concurrency pattern.
- */
-import fs from 'fs/promises';
-import kuzu from 'kuzu';
-const pool = new Map();
-/** Max repos in the pool (LRU eviction) */
-const MAX_POOL_SIZE = 5;
-/** Idle timeout before closing a repo's connections */
-const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
-/** Max connections per repo (caps concurrent queries per repo) */
-const MAX_CONNS_PER_REPO = 8;
-/** Connections created eagerly on init */
-const INITIAL_CONNS_PER_REPO = 2;
-let idleTimer = null;
-/**
- * Start the idle cleanup timer (runs every 60s)
- */
-function ensureIdleTimer() {
-    if (idleTimer)
-        return;
-    idleTimer = setInterval(() => {
-        const now = Date.now();
-        for (const [repoId, entry] of pool) {
-            if (now - entry.lastUsed > IDLE_TIMEOUT_MS) {
-                closeOne(repoId);
-            }
-        }
-    }, 60_000);
-    if (idleTimer && typeof idleTimer === 'object' && 'unref' in idleTimer) {
-        idleTimer.unref();
-    }
-}
-/**
- * Evict the least-recently-used repo if pool is at capacity
- */
-function evictLRU() {
-    if (pool.size < MAX_POOL_SIZE)
-        return;
-    let oldestId = null;
-    let oldestTime = Infinity;
-    for (const [id, entry] of pool) {
-        if (entry.lastUsed < oldestTime) {
-            oldestTime = entry.lastUsed;
-            oldestId = id;
-        }
-    }
-    if (oldestId) {
-        closeOne(oldestId);
-    }
-}
-/**
- * Close all connections for a repo and remove it from the pool
- */
-function closeOne(repoId) {
-    const entry = pool.get(repoId);
-    if (!entry)
-        return;
-    for (const conn of entry.available) {
-        try {
-            conn.close();
-        }
-        catch { }
-    }
-    try {
-        entry.db.close();
-    }
-    catch { }
-    pool.delete(repoId);
-}
-/**
- * Create a new Connection from a repo's Database.
- * Silences stdout to prevent native module output from corrupting MCP stdio.
- */
-function createConnection(db) {
-    const origWrite = process.stdout.write;
-    process.stdout.write = (() => true);
-    try {
-        return new kuzu.Connection(db);
-    }
-    finally {
-        process.stdout.write = origWrite;
-    }
-}
-const LOCK_RETRY_ATTEMPTS = 3;
-const LOCK_RETRY_DELAY_MS = 2000;
-/**
- * Initialize (or reuse) a Database + connection pool for a specific repo.
- * Retries on lock errors (e.g., when `gitnexus analyze` is running).
- */
-export const initKuzu = async (repoId, dbPath) => {
-    const existing = pool.get(repoId);
-    if (existing) {
-        existing.lastUsed = Date.now();
-        return;
-    }
-    // Check if database exists
-    try {
-        await fs.stat(dbPath);
-    }
-    catch {
-        throw new Error(`KuzuDB not found at ${dbPath}. Run: gitnexus analyze`);
-    }
-    evictLRU();
-    // Open in read-only mode — MCP server never writes to the database.
-    // This allows multiple MCP server instances to read concurrently, and
-    // avoids lock conflicts when `gitnexus analyze` is writing.
-    let lastError = null;
-    for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
-        const origWrite = process.stdout.write;
-        process.stdout.write = (() => true);
-        try {
-            const db = new kuzu.Database(dbPath, 0, // bufferManagerSize (default)
-            false, // enableCompression (default)
-            true);
-            process.stdout.write = origWrite;
-            // Pre-create a small pool of connections
-            const available = [];
-            for (let i = 0; i < INITIAL_CONNS_PER_REPO; i++) {
-                available.push(createConnection(db));
-            }
-            pool.set(repoId, { db, available, checkedOut: 0, waiters: [], lastUsed: Date.now(), dbPath });
-            ensureIdleTimer();
-            return;
-        }
-        catch (err) {
-            process.stdout.write = origWrite;
-            lastError = err instanceof Error ? err : new Error(String(err));
-            const isLockError = lastError.message.includes('Could not set lock')
-                || lastError.message.includes('lock');
-            if (!isLockError || attempt === LOCK_RETRY_ATTEMPTS)
-                break;
-            await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_DELAY_MS * attempt));
-        }
-    }
-    throw new Error(`KuzuDB unavailable for ${repoId}. Another process may be rebuilding the index. ` +
-        `Retry later. (${lastError?.message || 'unknown error'})`);
-};
-/**
- * Checkout a connection from the pool.
- * Returns an available connection, or creates a new one if under the cap.
- * If all connections are busy and at cap, queues the caller until one is returned.
- */
-function checkout(entry) {
-    // Fast path: grab an available connection
-    if (entry.available.length > 0) {
-        entry.checkedOut++;
-        return Promise.resolve(entry.available.pop());
-    }
-    // Grow the pool if under the cap
-    const totalConns = entry.available.length + entry.checkedOut;
-    if (totalConns < MAX_CONNS_PER_REPO) {
-        entry.checkedOut++;
-        return Promise.resolve(createConnection(entry.db));
-    }
-    // At capacity — queue the caller. checkin() will resolve this when
-    // a connection is returned, handing it directly to the next waiter.
-    return new Promise(resolve => {
-        entry.waiters.push(resolve);
-    });
-}
-/**
- * Return a connection to the pool after use.
- * If there are queued waiters, hand the connection directly to the next one
- * instead of putting it back in the available array (avoids race conditions).
- */
-function checkin(entry, conn) {
-    if (entry.waiters.length > 0) {
-        // Hand directly to the next waiter — no intermediate available state
-        const waiter = entry.waiters.shift();
-        waiter(conn);
-    }
-    else {
-        entry.checkedOut--;
-        entry.available.push(conn);
-    }
-}
-/**
- * Execute a query on a specific repo's connection pool.
- * Automatically checks out a connection, runs the query, and returns it.
- */
-export const executeQuery = async (repoId, cypher) => {
-    const entry = pool.get(repoId);
-    if (!entry) {
-        throw new Error(`KuzuDB not initialized for repo "${repoId}". Call initKuzu first.`);
-    }
-    entry.lastUsed = Date.now();
-    const conn = await checkout(entry);
-    try {
-        const queryResult = await conn.query(cypher);
-        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
-        const rows = await result.getAll();
-        return rows;
-    }
-    finally {
-        checkin(entry, conn);
-    }
-};
-/**
- * Close one or all repo pools.
- * If repoId is provided, close only that repo's connections.
- * If omitted, close all repos.
- */
-export const closeKuzu = async (repoId) => {
-    if (repoId) {
-        closeOne(repoId);
-        return;
-    }
-    for (const id of [...pool.keys()]) {
-        closeOne(id);
-    }
-    if (idleTimer) {
-        clearInterval(idleTimer);
-        idleTimer = null;
-    }
-};
-/**
- * Check if a specific repo's pool is active
- */
-export const isKuzuReady = (repoId) => pool.has(repoId);