gitnexus 1.0.0

package/skills/exploring.md

@@ -0,0 +1,112 @@
+---
+name: gitnexus-exploring
+description: Navigate unfamiliar code using GitNexus knowledge graph
+---
+
+# Exploring Codebases
+
+## Quick Start
+```
+0. If "Index is stale" → gitnexus_analyze({})
+1. READ gitnexus://context        → Get codebase overview (~150 tokens)
+2. READ gitnexus://clusters       → See all functional clusters
+3. READ gitnexus://cluster/{name} → Deep dive on specific cluster
+```
+
+## When to Use
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+
+## Workflow Checklist
+```
+Exploration Progress:
+- [ ] READ gitnexus://context for codebase overview
+- [ ] READ gitnexus://clusters to list all clusters
+- [ ] Identify the relevant cluster by name
+- [ ] READ gitnexus://cluster/{name} for cluster details
+- [ ] Use gitnexus_explore for specific symbols
+```
+
+## Resource Reference
+
+### gitnexus://context
+Codebase overview. **Read first.**
+```yaml
+project: my-app
+stats:
+  files: 42
+  symbols: 918
+  clusters: 12
+  processes: 45
+tools_available: [search, explore, impact, overview, cypher]
+resources_available: [clusters, processes, cluster/{name}, process/{name}]
+```
+
+### gitnexus://clusters
+All functional clusters with cohesion scores.
+```yaml
+clusters:
+  - name: "Auth"
+    symbols: 47
+    cohesion: 92%
+  - name: "Database"
+    symbols: 32
+    cohesion: 88%
+```
+
+### gitnexus://cluster/{name}
+Members of a specific cluster.
+```yaml
+name: Auth
+symbols: 47
+cohesion: 92%
+members:
+  - name: validateUser
+    type: Function
+    file: src/auth/validator.ts
+```
+
+### gitnexus://process/{name}
+Full execution trace.
+```yaml
+name: LoginFlow
+type: cross_community
+steps:
+  1: handleLogin (src/auth/handler.ts)
+  2: validateUser (src/auth/validator.ts)
+  3: createSession (src/auth/session.ts)
+```
+
+## Tool Reference (When Resources Aren't Enough)
+
+### gitnexus_explore
+For detailed symbol context with callers/callees:
+```
+gitnexus_explore({name: "validateUser", type: "symbol"})
+→ Callers: loginHandler, apiMiddleware
+→ Callees: checkToken, getUserById
+```
+
+### gitnexus_search
+For finding code by query:
+```
+gitnexus_search({query: "payment validation", depth: "full"})
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://context
+   → 918 symbols, 12 clusters
+
+2. READ gitnexus://clusters
+   → Clusters: Auth, Payment, Database, API...
+
+3. READ gitnexus://cluster/Payment
+   → Members: processPayment, validateCard, PaymentService
+
+4. READ gitnexus://process/CheckoutFlow
+   → handleCheckout → validateCart → processPayment → sendConfirmation
+```

package/skills/impact-analysis.md

@@ -0,0 +1,114 @@
+---
+name: gitnexus-impact-analysis
+description: Analyze blast radius before making code changes
+---
+
+# Impact Analysis
+
+## Quick Start
+```
+0. If "Index is stale" → gitnexus_analyze({})
+1. gitnexus_impact({target, direction: "upstream"}) → What depends on this
+2. READ gitnexus://clusters                         → Check affected areas
+3. READ gitnexus://processes                        → Affected execution flows
+```
+
+## When to Use
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+
+## Understanding Output
+
+| Depth | Risk Level | Meaning |
+|-------|-----------|---------|
+| d=1 | WILL BREAK | Direct callers/importers |
+| d=2 | LIKELY AFFECTED | Indirect dependencies |
+| d=3 | MAY NEED TESTING | Transitive effects |
+
+## Workflow Checklist
+```
+Impact Analysis:
+- [ ] gitnexus_impact(target, "upstream") to find dependents
+- [ ] READ gitnexus://clusters to understand affected areas
+- [ ] Check high-confidence (>0.8) dependencies first
+- [ ] Count affected clusters (cross-cutting = higher risk)
+- [ ] If >10 processes affected, consider splitting change
+```
+
+## Resource Reference
+
+### gitnexus://clusters
+Check which clusters might be affected:
+```yaml
+clusters:
+  - name: Auth
+    symbols: 47
+  - name: API
+    symbols: 32
+```
+
+### gitnexus://processes
+Find which processes touch the target:
+```yaml
+processes:
+  - name: LoginFlow
+    type: cross_community
+    steps: 5
+```
+
+## Tool Reference
+
+### gitnexus_impact
+Analyze blast radius:
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+
+→ Affected Processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM (3 processes)
+```
+
+## Risk Assessment
+
+| Affected | Risk |
+|----------|------|
+| <5 symbols, 1 cluster | LOW |
+| 5-15 symbols, 1-2 clusters | MEDIUM |
+| >15 symbols or 3+ clusters | HIGH |
+| Critical path (auth, payments) | CRITICAL |
+
+## Pre-Change Checklist
+```
+Before Committing:
+- [ ] Run impact analysis
+- [ ] Review all d=1 (WILL BREAK) items
+- [ ] Verify test coverage for affected processes
+- [ ] If risk > MEDIUM, get code review
+- [ ] If cross-cluster, coordinate with other teams
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware
+   → d=2: authRouter, sessionManager
+
+2. READ gitnexus://clusters
+   → Auth and API clusters affected
+
+3. Decision: 2 direct callers, 2 clusters = MEDIUM risk
+```

package/skills/refactoring.md

@@ -0,0 +1,119 @@
+---
+name: gitnexus-refactoring
+description: Plan safe refactors using blast radius and dependency mapping
+---
+
+# Refactoring with GitNexus
+
+## Quick Start
+```
+0. If "Index is stale" → gitnexus_analyze({})
+1. gitnexus_impact({target, direction: "upstream"}) → Map all dependents
+2. READ gitnexus://schema                           → Understand graph structure
+3. gitnexus_cypher                                  → Find all references
+```
+
+## When to Use
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Refactor without breaking things"
+
+## Checklists
+
+### Rename Symbol
+```
+Rename Refactoring:
+- [ ] gitnexus_impact(oldName, "upstream") — find all callers
+- [ ] gitnexus_search(oldName) — find string literals
+- [ ] Check for reflection/dynamic references
+- [ ] Update in order: interface → implementation → usages
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+```
+Extract Module:
+- [ ] gitnexus_explore(target, "symbol") — map dependencies
+- [ ] gitnexus_impact(target, "upstream") — find callers
+- [ ] READ gitnexus://cluster/{name} — check cohesion
+- [ ] Define new module interface
+- [ ] Update imports across affected files
+```
+
+### Split Function
+```
+Split Function:
+- [ ] gitnexus_explore(target, "symbol") — understand callees
+- [ ] Group related logic
+- [ ] gitnexus_impact — verify callers won't break
+- [ ] Create new functions
+- [ ] Update callers
+```
+
+## Resource Reference
+
+### gitnexus://schema
+Graph structure for Cypher queries:
+```yaml
+nodes: [Function, Class, Method, Community, Process]
+relationships: [CALLS, IMPORTS, EXTENDS, MEMBER_OF]
+
+example_queries:
+  find_callers: |
+    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"})
+    RETURN caller.name
+```
+
+### gitnexus://cluster/{name}
+Check if extraction preserves cohesion:
+```yaml
+name: Payment
+cohesion: 92%
+members: [processPayment, validateCard, PaymentService]
+```
+
+## Tool Reference
+
+### Finding all references
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath
+ORDER BY caller.filePath
+```
+
+### Finding imports of a module
+```cypher
+MATCH (importer)-[:CodeRelation {type: 'IMPORTS'}]->(f:File {name: "utils.ts"})
+RETURN importer.name, importer.filePath
+```
+
+## Example: Safely Rename `validateUser` to `authenticateUser`
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → loginHandler, apiMiddleware, testUtils
+
+2. gitnexus_search({query: "validateUser"})
+   → Found in: config.json (dynamic reference!)
+
+3. READ gitnexus://processes
+   → LoginFlow, TokenRefresh, APIGateway
+
+4. Plan update order:
+   1. Update declaration in auth.ts
+   2. Update config.json string reference
+   3. Update loginHandler
+   4. Update apiMiddleware
+   5. Run tests for LoginFlow, TokenRefresh
+```
+
+## Refactoring Safety Rules
+
+| Risk Factor | Mitigation |
+|-------------|------------|
+| Many callers (>5) | Update in small batches |
+| Cross-cluster | Coordinate with other teams |
+| String references | Search for dynamic usage |
+| Reflection | Check for dynamic invocation |
+| External exports | May break downstream repos |

package/vendor/leiden/index.cjs

@@ -0,0 +1,355 @@
+/**
+ * Graphology Leiden Algorithm
+ * ============================
+ *
+ * JavaScript implementation of the Leiden community detection
+ * algorithm for graphology.
+ *
+ * Vendored from: https://github.com/graphology/graphology/tree/master/src/communities-leiden
+ * License: MIT
+ *
+ * [Reference]
+ * Traag, V. A., et al. "From Louvain to Leiden: Guaranteeing Well-Connected
+ * Communities". Scientific Reports, vol. 9, no 1, 2019, p. 5233.
+ * https://arxiv.org/abs/1810.08473
+ */
+var resolveDefaults = require('graphology-utils/defaults');
+var isGraph = require('graphology-utils/is-graph');
+var inferType = require('graphology-utils/infer-type');
+var SparseMap = require('mnemonist/sparse-map');
+var SparseQueueSet = require('mnemonist/sparse-queue-set');
+var createRandomIndex = require('pandemonium/random-index').createRandomIndex;
+var utils = require('./utils.cjs');
+
+var indices = require('graphology-indices/louvain');
+var addWeightToCommunity = utils.addWeightToCommunity;
+
+var UndirectedLouvainIndex = indices.UndirectedLouvainIndex;
+
+var UndirectedLeidenAddenda = utils.UndirectedLeidenAddenda;
+
+var DEFAULTS = {
+ attributes: {
+ community: 'community',
+ weight: 'weight'
+ },
+ randomness: 0.01,
+ randomWalk: true,
+ resolution: 1,
+ rng: Math.random,
+ weighted: false
+};
+
+var EPSILON = 1e-10;
+
+function tieBreaker(
+ bestCommunity,
+ currentCommunity,
+ targetCommunity,
+ delta,
+ bestDelta
+) {
+ if (Math.abs(delta - bestDelta) < EPSILON) {
+ if (bestCommunity === currentCommunity) {
+ return false;
+ } else {
+ return targetCommunity > bestCommunity;
+ }
+ } else if (delta > bestDelta) {
+ return true;
+ }
+
+ return false;
+}
+
+function undirectedLeiden(detailed, graph, options) {
+ var index = new UndirectedLouvainIndex(graph, {
+ attributes: {
+ weight: options.attributes.weight
+ },
+ keepDendrogram: detailed,
+ resolution: options.resolution,
+ weighted: options.weighted
+ });
+
+ var addenda = new UndirectedLeidenAddenda(index, {
+ randomness: options.randomness,
+ rng: options.rng
+ });
+
+ var randomIndex = createRandomIndex(options.rng);
+
+ // Communities
+ var currentCommunity, targetCommunity;
+ var communities = new SparseMap(Float64Array, index.C);
+
+ // Traversal
+ var queue = new SparseQueueSet(index.C),
+ start,
+ end,
+ weight,
+ ci,
+ ri,
+ s,
+ i,
+ j,
+ l;
+
+ // Metrics
+ var degree, targetCommunityDegree;
+
+ // Moves
+ var bestCommunity, bestDelta, deltaIsBetter, delta;
+
+ // Details
+ var deltaComputations = 0,
+ nodesVisited = 0,
+ moves = [],
+ currentMoves;
+
+ while (true) {
+ l = index.C;
+
+ currentMoves = 0;
+
+ // Traversal of the graph
+ ri = options.randomWalk ? randomIndex(l) : 0;
+
+ for (s = 0; s < l; s++, ri++) {
+ i = ri % l;
+ queue.enqueue(i);
+ }
+
+ while (queue.size !== 0) {
+ i = queue.dequeue();
+ nodesVisited++;
+
+ degree = 0;
+ communities.clear();
+
+ currentCommunity = index.belongings[i];
+
+ start = index.starts[i];
+ end = index.starts[i + 1];
+
+ // Traversing neighbors
+ for (; start < end; start++) {
+ j = index.neighborhood[start];
+ weight = index.weights[start];
+
+ targetCommunity = index.belongings[j];
+
+ // Incrementing metrics
+ degree += weight;
+ addWeightToCommunity(communities, targetCommunity, weight);
+ }
+
+ // Finding best community to move to
+ bestDelta = index.fastDeltaWithOwnCommunity(
+ i,
+ degree,
+ communities.get(currentCommunity) || 0,
+ currentCommunity
+ );
+ bestCommunity = currentCommunity;
+
+ for (ci = 0; ci < communities.size; ci++) {
+ targetCommunity = communities.dense[ci];
+
+ if (targetCommunity === currentCommunity) continue;
+
+ targetCommunityDegree = communities.vals[ci];
+
+ deltaComputations++;
+
+ delta = index.fastDelta(
+ i,
+ degree,
+ targetCommunityDegree,
+ targetCommunity
+ );
+
+ deltaIsBetter = tieBreaker(
+ bestCommunity,
+ currentCommunity,
+ targetCommunity,
+ delta,
+ bestDelta
+ );
+
+ if (deltaIsBetter) {
+ bestDelta = delta;
+ bestCommunity = targetCommunity;
+ }
+ }
+
+ if (bestDelta < 0) {
+ bestCommunity = index.isolate(i, degree);
+
+ if (bestCommunity === currentCommunity) continue;
+ } else {
+ if (bestCommunity === currentCommunity) {
+ continue;
+ } else {
+ index.move(i, degree, bestCommunity);
+ }
+ }
+
+ currentMoves++;
+
+ // Adding neighbors from other communities to the queue
+ start = index.starts[i];
+ end = index.starts[i + 1];
+
+ for (; start < end; start++) {
+ j = index.neighborhood[start];
+ targetCommunity = index.belongings[j];
+
+ if (targetCommunity !== bestCommunity) queue.enqueue(j);
+ }
+ }
+
+ moves.push(currentMoves);
+
+ if (currentMoves === 0) {
+ index.zoomOut();
+ break;
+ }
+
+ if (!addenda.onlySingletons()) {
+ // We continue working on the induced graph
+ addenda.zoomOut();
+ continue;
+ }
+
+ break;
+ }
+
+ var results = {
+ index: index,
+ deltaComputations: deltaComputations,
+ nodesVisited: nodesVisited,
+ moves: moves
+ };
+
+ return results;
+}
+
+/**
+ * Function returning the communities mapping of the graph.
+ *
+ * @param {boolean} assign - Assign communities to nodes attributes?
+ * @param {boolean} detailed - Whether to return detailed information.
+ * @param {Graph} graph - Target graph.
+ * @param {object} options - Options:
+ * @param {object} attributes - Attribute names:
+ * @param {string} community - Community node attribute name.
+ * @param {string} weight - Weight edge attribute name.
+ * @param {number} randomness - Randomness parameter.
+ * @param {boolean} randomWalk - Whether to traverse the graph in random order.
+ * @param {number} resolution - Resolution parameter.
+ * @param {function} rng - RNG function to use.
+ * @param {boolean} weighted - Whether to compute the weighted version.
+ * @return {object}
+ */
+function leiden(assign, detailed, graph, options) {
+ if (!isGraph(graph))
+ throw new Error(
+ 'graphology-communities-leiden: the given graph is not a valid graphology instance.'
+ );
+
+ var type = inferType(graph);
+
+ if (type === 'mixed')
+ throw new Error(
+ 'graphology-communities-leiden: cannot run the algorithm on a true mixed graph.'
+ );
+
+ if (type === 'directed')
+ throw new Error(
+ 'graphology-communities-leiden: not yet implemented for directed graphs.'
+ );
+
+ // Attributes name
+ options = resolveDefaults(options, DEFAULTS);
+
+ // Empty graph case
+ var c = 0;
+
+ if (graph.size === 0) {
+ if (assign) {
+ graph.forEachNode(function (node) {
+ graph.setNodeAttribute(node, options.attributes.communities, c++);
+ });
+
+ return;
+ }
+
+ var communities = {};
+
+ graph.forEachNode(function (node) {
+ communities[node] = c++;
+ });
+
+ if (!detailed) return communities;
+
+ return {
+ communities: communities,
+ count: graph.order,
+ deltaComputations: 0,
+ dendrogram: null,
+ level: 0,
+ modularity: NaN,
+ moves: null,
+ nodesVisited: 0,
+ resolution: options.resolution
+ };
+ }
+
+ var fn = undirectedLeiden;
+
+ var results = fn(detailed, graph, options);
+
+ var index = results.index;
+
+ // Standard output
+ if (!detailed) {
+ if (assign) {
+ index.assign(options.attributes.community);
+ return;
+ }
+
+ return index.collect();
+ }
+
+ // Detailed output
+ var output = {
+ count: index.C,
+ deltaComputations: results.deltaComputations,
+ dendrogram: index.dendrogram,
+ level: index.level,
+ modularity: index.modularity(),
+ moves: results.moves,
+ nodesVisited: results.nodesVisited,
+ resolution: options.resolution
+ };
+
+ if (assign) {
+ index.assign(options.attributes.community);
+ return output;
+ }
+
+ output.communities = index.collect();
+
+ return output;
+}
+
+/**
+ * Exporting.
+ */
+var fn = leiden.bind(null, false, false);
+fn.assign = leiden.bind(null, true, false);
+fn.detailed = leiden.bind(null, false, true);
+fn.defaults = DEFAULTS;
+
+module.exports = fn;