@duytransipher/gitnexus 1.4.6-sipher.0

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 gitnexus 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

@@ -0,0 +1,121 @@
+---
+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\""
+---
+
+# Refactoring with GitNexus
+
+## When to Use
+
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Move this to a new file"
+- Any task involving renaming, extracting, splitting, or restructuring code
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
+2. gitnexus_query({query: "X"})                            → Find execution flows involving X
+3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
+4. Plan update order: interfaces → implementations → callers → tests
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklists
+
+### Rename Symbol
+
+```
+- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
+- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
+- [ ] gitnexus_detect_changes() — verify only expected files changed
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+
+```
+- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
+- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
+- [ ] Define new module interface
+- [ ] Extract code, update imports
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+### Split Function/Service
+
+```
+- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] Group callees by responsibility
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
+- [ ] Update callers
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+## Tools
+
+**gitnexus_rename** — automated multi-file rename:
+
+```
+gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+→ 12 edits across 8 files
+→ 10 graph edits (high confidence), 2 ast_search edits (review)
+→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
+```
+
+**gitnexus_impact** — map all dependents first:
+
+```
+gitnexus_impact({target: "validateUser", direction: "upstream"})
+→ d=1: loginHandler, apiMiddleware, testUtils
+→ Affected Processes: LoginFlow, TokenRefresh
+```
+
+**gitnexus_detect_changes** — verify your changes after refactoring:
+
+```
+gitnexus_detect_changes({scope: "all"})
+→ Changed: 8 files, 12 symbols
+→ Affected processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM
+```
+
+**gitnexus_cypher** — custom reference queries:
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath ORDER BY caller.filePath
+```
+
+## Risk Rules
+
+| Risk Factor         | Mitigation                                |
+| ------------------- | ----------------------------------------- |
+| Many callers (>5)   | Use gitnexus_rename for automated updates |
+| Cross-area refs     | Use detect_changes after to verify scope  |
+| String/dynamic refs | gitnexus_query to find them               |
+| External/public API | Version and deprecate properly            |
+
+## Example: Rename `validateUser` to `authenticateUser`
+
+```
+1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+   → 12 edits: 10 graph (safe), 2 ast_search (review)
+   → Files: validator.ts, login.ts, middleware.ts, config.json...
+
+2. Review ast_search edits (config.json: dynamic reference!)
+
+3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+   → Applied 12 edits across 8 files
+
+4. gitnexus_detect_changes({scope: "all"})
+   → Affected: LoginFlow, TokenRefresh
+   → Risk: MEDIUM — run tests for these flows
+```

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;