Invariant

Semantic code analysis for the AI era

Invariant is a fast, multi-language code analysis tool that extracts structural facts from your codebase and connects to DataGrout for semantic analysis. It enables:

• Consequential analysis — What breaks if we merge this PR?
• Semantic time machine — Query code properties across commits
• Agent feedback loop — Real-time validation for AI-generated code
• Architectural governance — Encode and enforce team invariants

Read the paper · Library & docs · Live demo

Quick Start

# Build
cargo build --release

# Initialize (bootstraps mTLS identity when available)
invariant init --url https://gateway.datagrout.ai/servers/{uuid}/mcp --token <your-token>

# Analyze your codebase (extracts structural facts + uploads to Invariant)
invariant lens

# Query for issues (via DataGrout Invariant)
invariant query orphans
invariant query test_gaps
invariant query intent_mismatches

# Analyze a diff against a stated goal
invariant diff --before old.py --after new.py --goal "add rate limiting"

After the first invariant init, Invariant prefers a persisted mTLS identity in ~/.conduit/. If the gateway rejects identity bootstrap, Invariant falls back to the saved bearer token so subsequent runs still authenticate automatically.

How It Works

┌───────────────────────────────────────┐
│  Invariant (local)                    │
│                                       │
│  tree-sitter AST → structural facts   │
│  file scanning, ignore patterns       │
└──────────────┬────────────────────────┘
               │ Conduit SDK (mTLS)
               ↓
┌───────────────────────────────────────┐
│  DataGrout Invariant (server)         │
│                                       │
│  semantic enrichment (LLM)            │
│  consequence queries                  │
│  intent analysis                      │
│  cross-repo aggregation               │
└───────────────────────────────────────┘

Invariant performs fast, local structural extraction using tree-sitter. It understands Python, Rust, TypeScript, TSX, JavaScript, Go, Elixir, and Ruby ASTs natively. Facts are uploaded to DataGrout Invariant via the Conduit SDK for server-side semantic enrichment — LLM-powered intent classification, security analysis, and consequence reasoning.

Installation

# From source
cargo install --path invariant-cli

# Or run directly
cargo run -p invariant-cli -- lens src/

Commands

invariant init

Initialize Invariant for the current repository. Bootstraps an mTLS identity on first run when the gateway supports it, otherwise saves the bearer token for future fallback auth.

invariant init --url https://gateway.datagrout.ai/servers/{uuid}/mcp --token <token>

invariant lens [paths...]

Extract structural facts from code files.

invariant lens                    # Analyze entire repo
invariant lens src/ lib/          # Analyze specific directories
invariant lens --language python  # Filter by language
invariant lens --language elixir  # Elixir support
invariant lens --local-only       # Extract without uploading
invariant -v lens                 # Verbose output (debug logging)

invariant query <query>

Run semantic queries via DataGrout Invariant.

invariant query orphans              # Functions never called
invariant query test_gaps            # Untested public functions
invariant query intent_mismatches    # Functions whose behavior doesn't match their name
invariant query dependency_cycles    # Circular dependencies
invariant query security_concerns   # Potential security issues
invariant query hotspots             # High-complexity, high-change-rate functions
invariant query summary              # Aggregate statistics

invariant diff

Analyze code changes for goal alignment.

invariant diff --before v1.py --after v2.py --goal "add user auth"

invariant status

Show connection, identity, and configuration status.

Supported Languages

Architecture

invariant/
├── invariant-core/    # Library: parser, analyzer, facts, bridge
└── invariant-cli/     # CLI binary

• invariant-core — Tree-sitter parsing, AST fact extraction, Conduit SDK bridge
• invariant-cli — Command-line interface with auto-enrollment, config persistence

Development

cargo test                    # Run tests
cargo clippy                  # Lint
cargo build --release         # Build release binary
cargo doc --open              # API documentation

Powered By

DataGrout AI — Intelligence Infrastructure for Autonomous Systems

License

Elastic License 2.0