Documentation

Parses the repository at PATH (defaults to current directory), builds the workspace call graph across 36 languages, executes Personalized PageRank, and streams ranked symbol definitions with incoming callers as canonical XML (bounded by --top-k symbol count or --max-tokens / --pack-budget streaming limits). Automatically caches compiled call graphs in TMPDIR for sub-second repeat queries (use --no-cache for cold parse). --scip=index.scip overlays a compiler-backed SCIP index: the call sites it resolves bind exactly (prov="scip", header precise=K) and bypass the cache.

The same global --scip=PATH overlay works before or after navigate, plain or task-ranked orient, and mcp. MCP retains its indexed graph for the session. Multiline calls match the callee identifier's index line; reports preserve the call expression's start line. Unreadable or malformed indexes fail explicitly without a name-only fallback.

Runs Tree-Sitter syntax queries in parallel via Rayon, interns symbols with Lasso, resolves call references through a multi-tier precedence ladder, and executes power iteration over a compressed sparse row (CSR) transpose in-edge matrix. Serializes binary cache payloads keyed by git HEAD SHA and file mtimes to deliver warm map responses in under 50ms on medium repos and ~600ms on 7,000+ file codebases with 60%–85% lower memory footprint than C++.

When first landing in an unfamiliar codebase, retrieving high-level architectural anchors, or packing dense, budget-bounded context into LLM prompts without hallucinated dependencies.

Compares uncommitted working tree changes against git HEAD (or a pinned baseline) and reports code quality regressions across complexity, duplication, dead code, and contract breaks. Exits non-zero if gating regressions are detected.

Computes multi-vector quality snapshots (Campbell cognitive complexity via cccc, cyclomatic complexity, Type-1/2/3 AST clones, arity changes) on both revisions and diffs the findings, filtering out expected churn and self-registering test macros.

In pre-commit hooks, local developer validation before git push, or automated CI/CD merge-safety pull request checks.

Scans the repository for AST code smells (complexity spikes, deep nesting, high parameter counts, dead functions) and emits Ripwire XML or standard SARIF 2.1.0 JSON when --sarif is passed.

In GitHub Code Scanning workflows, IDE diagnostics, or automated pull request quality checks.

Executes multi-file AST symbol edits transactionally with two-phase preflight validation and --dry-run verification.

When applying coordinated multi-symbol refactorings generated by an AI coding agent without risking partial file corruption.

Pre-PR verification gate: identifies all test suites that reach modified files and detects untested transitive blast radius. Exits with status code 4 if obligations remain.

Inspects git working tree diffs, traces reverse call graph reachability to test harnesses, and evaluates untested downstream symbols across 1-hop and transitive edges.

In pre-push and PR verification gates to ensure all modified code is tested before opening pull requests.

Expands full source bodies and callee signatures for comma-separated symbols, wrapped in token-dense CDATA XML blocks.

Extracts exact byte spans from the underlying source files, resolving qualified selectors (`Type::method`, `file:name`), and streams the function bodies to stdout.

When drilling down from architectural map summaries to implementation details of specific core functions.

Scans the entire workspace call graph and identifies internal functions and methods with zero incoming callers.

Computes in-degree matrix offsets across the graph, filtering out public library entry points and self-registering test macros.

During codebase refactoring, dead-weight cleanup, or technical debt audits to find safely removable internal code.

Verifies whether recent modifications to symbol <SYM> altered its parameter count or visibility, identifying all direct callers in the codebase that become incompatible with the new signature.

Extracts parameter counts and visibility modifiers from the AST at both revisions. Traverses 1-hop reverse call graph edges to check if existing call sites pass matching argument arity.

Immediately after refactoring or modifying a public function, method, or constructor signature, before executing full workspace test suites.

Identifies exactly which test files transitively reach the changed file or symbol <PATH>, ranking them by evidence tier (edited tests, partner-named tests, call hop distance).

Computes transitive reachability over reverse call graph edges from the target node, keeping nodes in test files (tests/, test_*, *_test.*, *.test.*, *.spec.*). Tests named after a changed file are added as partner="1" rows even with no call edge; a file with several candidate partners gets none.

To run a surgical, high-confidence subset of fast regression tests instead of running the entire multi-minute test suite during tight TDD loops.

Ranks repository files by maintenance risk score, combining commit churn with cognitive complexity to highlight fragile, high-risk code hotspots.

Mines git commit history with exponential half-life time decay (weighting recent revisions higher) and multiplies file commit frequency by average McCabe and Campbell cognitive complexity.

Prior to architectural refactoring, when scoping technical debt, or when allocating code review attention to the most defect-prone files in a repository.

Computes the Delta Maintainability Model (DMM) scalar in [0,1], quantifying the proportion of code volume churn that made the codebase healthier.

In CI gates or wave reviews to track whether refactorings genuinely reduced unit risk or introduced new technical debt.

Runs the unified 6-family quality panel (structural, lexical, confusion, historical, colocation, state) in one report ranked by distinct families fired.

Before major code convergence to perform a wide-angle sanity check across all quality evidence families simultaneously.

Surfaces companion files that historically change together with <FILE>, detecting hidden Fowler's Shotgun Surgery coupling.

Scans multi-file commit transactions across git history, filters out repository-wide merge-bombs (>100 files), and calculates co-change support, confidence, and surprise ratios.

Before editing an interface, schema, or configuration file, to guarantee that all implicit partner files (docs, test fixtures, downstream consumers) are updated in the same change.

Traces intra-procedural def-use variable occurrences inside function <SYM>, mapping how variable <VAR> is initialized, assigned, and consumed.

Implements the ARISE slicing algorithm (arXiv:2605.03117) over Tree-sitter AST nodes to build localized def-use chains, control dependencies, and reaching definitions in forward, backward, or bidirectional flow.

When debugging variable corruption, auditing taint propagation or untrusted user input, or tracing complex state mutations without stepping through a live debugger.

Scans the codebase for duplicate logic, grouping candidate functions into exact (Type-1), renamed identifier (Type-2), and near-miss gapped (Type-3) clone groups.

Tokenizes function bodies while skipping comments and string literals, computes $k$-gram token window hashes with in-place sort-dedup, evaluates Jaccard similarity, and validates near-misses via Longest Common Subsequence (LCS).

During code audits to consolidate duplicate utility routines into shared helpers, or to prevent boilerplate copy-pasting in team workflows.

Emits the 1-hop neighborhood of a symbol: all direct incoming callers, outgoing callees, definitions, and ambiguity metrics formatted as XML. Works seamlessly across code symbols and database tables (e.g. ripwire-rs . --callers=user_accounts lists all functions across Dart, Rust, Python, TypeScript, Go, etc. that query or mutate that table).

Interns <SYM> in $O(1)$ to find matching graph node IDs and directly indexes the CSR row offsets and target vectors without iterator allocations.

When tracing call hierarchies, checking who invokes a utility function, or inspecting the dependencies invoked by a given method.

Computes the full transitive downstream blast radius of modifying <SYM>, ranking all dependent symbols by PageRank influence. Automatically traces blast radius across language boundaries—including from .sql migration files through to application services and test suites that touch altered tables (pairs with --affected, --test-gate, and --situ).

Seeds Personalized PageRank with mass focused on <SYM> and runs power iteration across outgoing call edges to measure relative dependency concentration.

Unbound candidate calls appear separately as <dc> rows, not graph edges. dc_shown of declined_calls says how many a capped list holds; raise --token-budget to show more.

Before deprecating, modifying, or removing a core interface, data structure, or shared utility function to determine the full scope of downstream impact.

Emits every statically resolvable use-site of <SYM> across the repository (calls, reads, writes, imports, inheritance)—including cross-language embedded SQL table lineage extracted automatically from application string literals.

Lists every indexed site by default. Use --limit=N --offset=M for a path-and-line ordered window, then continue at next_offset.

Zero extra flags required. During standard AST ingestion across all 36 languages, string literals containing SQL DML (SELECT ... FROM, JOIN, INSERT INTO, UPDATE, DELETE FROM) automatically emit RefRole::Read and RefRole::Write references attributed to the enclosing function or method, resolving directly to .sql table definitions in the workspace graph.

Python, JavaScript/TypeScript, and Rust also index bare non-local variable reads, excluding bindings, writes, labels, and lexical shadows. Grep's reads and reads_at use these references rather than text estimates; unsupported binding forms remain evidence floors.

When refactoring database schemas or migrating tables (e.g. ripwire-rs . --uses=user_accounts) to identify every backend service, repository method, query function, or migration touching that table.

Finds the shortest directed call chain connecting symbol A to symbol B, returning the exact hop-by-hop sequence of intermediate functions.

Executes bidirectional breadth-first search (BFS) over the resolved directed CSR call graph edges, returning reachability and hop count.

Investigating how an API controller reaches a database query, or checking for unintended architectural layer breaches between disparate modules.

Exports a standalone, interactive HTML visualization of the call graph with pan-zoom canvas, node search, and configurable coloring modes.

Embeds graph topology and metadata into an SVG canvas with interactive controls, supporting coloring by language, Louvain community clusters, cognitive complexity, or churn.

Architecture reviews, developer onboarding, and visually communicating system structure to non-technical stakeholders.

Literal search with span tiering (code by default, --grep-in=any adds comments and strings), boolean filtering (--and, --not, --grep-scope) and path restriction (--in), annotating every hit with its enclosing AST definition and listing matches in off-index text files in a trailing <unindexed> element.

Classifies code, comment, and literal spans through language semantics. Comments are withheld when code hits exist; strings ride along with fewer than eight code hits. The innermost AST byte span identifies each hit's enclosing symbol.

Finding symbol references or keywords scoped to a specific directory or parent module while excluding noise.

Pins and updates architectural baselines and quality census snapshots stamped with git HEAD, enabling progressive ratcheting of codebase health without false alarms on legacy code.

Writes baseline sidecar files recording known violations so --quality-delta enforces zero net-new regressions. --quality-baseline refuses on a dirty tree that already gates against HEAD; --allow-dirty pins anyway and later deltas report baseline_absorbed=. A regression-free delta collapses stale ack rows to stale_by_kind=; --show-stale prints them.

Establishing a quality ratchet in legacy codebases or ratcheting quality improvements across release branches.

Generates executive Markdown architecture summaries (--report) or emits full schema legend dictionaries (--legend-dict) explaining all AST tags and attribute abbreviations.

Synthesizes connectivity, ranking, and quality panel metrics into human-readable Markdown or machine-verifiable schema definitions.

Creating architectural documentation for PR descriptions or configuring coding agent prompt preambles.

Analyzes a natural-language engineering task description and recommends the optimal ripwire-rs verb, flags, and syntax to answer it with minimal token cost.

Maps intent keywords and structural goals against ripwire-rs's operational ontology, returning recommended command invocations.

Coding agent prompt routing and developer onboarding when deciding which ripwire-rs command fits a complex debugging task.

Packages ranked signatures, top implementation bodies, 1-hop callers, and affected tests under a single token budget—or partitions the surface into 1 shared core plus N minimally-overlapping subagent bundles (N=2..16).

Carves assignable task symbols along Louvain call-graph communities (falling back to file grouping for edgeless types and median-splitting when K < N), packs bins largest-first, and reports pairwise Jaccard overlap.

Single-call agent task orientation or fanning a multi-symbol feature across parallel subagents without duplicate discovery spend.

Emits a deterministic 1-line JSON worktree plan predicting which parallel agent lanes will collide, touch each other's contracts, and in what order they should land.

Keys symbol claims on path-qualified FNV-1a hashes (path\0scope\0name), intersects claims against transitive caller blast radii, and orders lanes by fewest conflicts first.

Before spawning N parallel git worktree agents on a shared repository.

Returns a task-lens ranked inventory of building block symbols, signatures, and callers most relevant to a natural language task description.

Combines BM25 lexical token matching with Personalized PageRank proximity to score and rank symbol definitions under a deterministic byte or token ceiling.

The entry point for starting any multi-symbol feature, bug fix, or agent task in an unfamiliar repository.

Navigates symbol neighborhoods and downstream impact trees with explicit command options.

Direct CSR index traversals yielding file paths, line bounds, and call hierarchy rankings.

Scripted agent tools or editor extensions requiring structured subcommands rather than top-level flags.

Runs pre-commit verification checks in a unified batch, outputting structured pass/fail results for CI runners and git hooks.

Dispatches contract comparison, test reachability, and quality delta regression evaluation concurrently.

In .pre-commit-config.yaml, GitHub Actions PR workflows, or local git hook scripts before committing.

Analyzes repository codebase health, reporting cognitive complexity, Halstead volume, Posnett readability, and historical commit churn.

Parses AST control structures for McCabe and Campbell complexity alongside information-theoretic readability entropy models.

During sprint retrospectives, technical debt triage, and code quality audits.

Dedicated subcommand interface for intra-procedural def-use variable slicing with step-by-step dataflow tracing.

AST dataflow engine traversing intra-procedural expression trees and control statements.

Vulnerability auditing, finding dead variable assignments, and validating functional state immutability.

Starts a persistent stdio JSON-RPC server implementing the Model Context Protocol (MCP) for AI coding assistants.

Overlapping tools return canonical CLI XML/text in result.content[0].text, with identical facts, defaults, errors, limits, grouping, provenance, and declined evidence. Maps default to 200 symbols / 65536 bytes; rank signals are pagerank, authority, hub, degree, ccx, and stable (unknown signals error). Connect defaults to radius 2. Situational awareness emits ripwire-rs.situ/v1 XML. Slice shares CLI root, flow/depth validation, and errors.

Impact's optional MCP max_depth matches global CLI --impact-depth=N, also with navigate --impact. Reports preserve legends without session mutation. CLI --json preserves XML hierarchy and text/CDATA: root tag/attributes/items, leaf text, mixed text interleaved in items, reserved-name attributes under attributes, and namespaced names as {uri}local; malformed reports error. Batch uses the real root and shared registry, caps both transports at 16, and rejects recursive batches/writes per item.

Batch success entries retain tool/result/kind (xml|text|json); malformed names fail per item, and CLI XML safely escapes text/JSON results. MCP owners accepts integer detail > 0; whereis accepts listing=defs|refs|all and boolean full_text, rejecting invalid listings. Detail 2 includes all requested bodies with accurate shown/total; root/revision and effective connect radius remain canonical.

In any MCP-compatible client or coding agent to equip AI workflows with native code intelligence tools.

Provisions 17 pre-packaged ripwire-rs agent skills and the active manifest (.ripwire-rs-manifest-v1) directly into ~/.agents/skills (or a custom directory).

Embeds all 17 skill definition packages into the binary, resolving cross-platform agent discovery paths and repairing stale or broken symlinks safely.

When onboarding coding agents to immediately activate ripwire-rs skills across any repository.