Skip to content
Arka Platform

GitNexus — navigation and impact analysis

GitNexus is a code graph indexing tool used by arka-deck. It indexes the project into clusters, execution processes and symbols, and lets you navigate or assess the impact of a change before making it.

When to use GitNexus

Section titled “When to use GitNexus”
  • Before modifying a symbol (function, class, port): know the upstream impact.
  • To understand an execution flow (e.g. “what happens during a project purge?”).
  • To explore an unknown domain (e.g. first contribution on memory).
  • For a safe refactor (rename, extract, split).

Main commands

Section titled “Main commands”

gitnexus impact — impact analysis

Section titled “gitnexus impact — impact analysis”
Terminal window
npx gitnexus impact --target <symbolName> --repo arka-deck --direction upstream

Shows direct callers (d=1, will break if the signature changes) and indirect (d=2, should test). To run before any modification of a function or port.

gitnexus query — concept search

Section titled “gitnexus query — concept search”
Terminal window
npx gitnexus query "auth validation"

Returns execution flows linked to the concept, ranked by relevance. Useful to explore without knowing the exact name.

gitnexus context — 360° view of a symbol

Section titled “gitnexus context — 360° view of a symbol”
Terminal window
npx gitnexus context --name validateUser

Lists all callers, callees and processes the symbol belongs to.

gitnexus rename — safe rename

Section titled “gitnexus rename — safe rename”
Terminal window
# Dry-run first
npx gitnexus rename --symbol-name old --new-name new --dry-run


# Once validated
npx gitnexus rename --symbol-name old --new-name new

Understands the call graph and renames in all call sites, not just a textual find-and-replace.

gitnexus detect_changes — scope check

Section titled “gitnexus detect_changes — scope check”
Terminal window
npx gitnexus detect-changes --scope staged

Before a commit: checks that changes only affect expected symbols and flows.

gitnexus analyze — reindex

Section titled “gitnexus analyze — reindex”
Terminal window
npx gitnexus analyze

After a commit, the index becomes stale. Reindex to keep results reliable. Preserve embeddings: --embeddings.

Impact risk levels

Section titled “Impact risk levels”
DepthMeaningAction
d=1Will break — direct callersUpdate these files
d=2Likely affectedTest
d=3Test if critical pathTargeted test

Never ignore HIGH or CRITICAL risk. Pause and explain the blast radius before proceeding.

Typical workflow

Section titled “Typical workflow”

Before modification

Section titled “Before modification”
  1. gitnexus impact <target> --direction upstream → direct and indirect callers.
  2. Read d=1 files — they will break.
  3. Decide: modify the signature with the call sites, or create a new function and migrate progressively.

During modification

Section titled “During modification”
  • Keep the announced perimeter.
  • Test locally the modified d=1 sites.

Before commit

Section titled “Before commit”
Terminal window
npx gitnexus detect-changes

Confirms changes match the expected scope.

After commit (maintainer)

Section titled “After commit (maintainer)”
Terminal window
npx gitnexus analyze --embeddings

Reindex for upcoming analyses.

Limits

Section titled “Limits”
  • The index can become stale after an intense session. Reindex when in doubt.
  • Semantic analyses (on strings, for example) require embeddings — check .gitnexus/meta.json (stats.embeddings > 0).
  • GitNexus sees the TypeScript graph; dynamic declarations or eval are not covered.

See also

Section titled “See also”