Invariant Tools

Semantic code analysis powered by neuro-symbolic reasoning. Extract structural facts, query for patterns, and verify goal alignment with deterministic Prolog rules.

invariant.code_lens

Analyzes source code to extract structural and semantic facts.

What it does: Parses source code (Elixir via AST, other languages via LLM) and produces structured semantic facts describing functions, calls, dependencies, intent, side effects, and patterns. Facts are persisted per repo_id and commit_sha for temporal querying.

Parameters:

Name	Type	Required	Description
`code`	string	yes	Source code to analyze
`language`	string	yes	Programming language (`elixir`, `python`, `typescript`, `javascript`, `rust`, `go`, `ruby`, `php`)
`filepath`	string	no	File path for context
`commit_sha`	string	no	Git commit SHA for version indexing
`repo_id`	string	no	Repository identifier for fact persistence and querying
`options.include_intent`	boolean	no	Include semantic intent analysis (default: `true`)

Example:

{
  "code": "defmodule Auth do\n  def login(creds), do: verify(creds)\n  defp verify(c), do: {:ok, c}\nend",
  "language": "elixir",
  "filepath": "lib/auth.ex",
  "commit_sha": "abc123",
  "repo_id": "my-project"
}

Returns: facts (array of structured fact statements), summary (counts of modules, functions, calls).

Credits: 4 (with intent) / 2 (structural only)

invariant.code_query

Executes predefined semantic queries over lensed code facts using a Prolog reasoning engine.

What it does: Loads persisted facts for a given repo_id and commit_sha, consults the Invariant rule engine, and runs deterministic queries. No LLM involved at query time — results are reproducible and instant.

Parameters:

Name	Type	Required	Description
`repo_id`	string	yes	Repository identifier
`query`	string	yes	Query name
`commit_sha`	string	no	Git commit SHA (uses stored default if omitted)

Available queries:

Query	Description
`orphans`	Public functions with no callers
`test_gaps`	Public functions without corresponding tests
`dependency_cycles`	Circular module dependencies
`intent_mismatches`	Functions whose inferred intent doesn’t match their declared behavior
`security_concerns`	Functions handling user input, SQL, or shell execution
`hotspots`	Functions with high fan-in and complexity
`debug_in_prod`	Debug/logging calls in production code
`high_risk_changes`	Functions with many dependents

Credits: 3

invariant.diff_analyzer

Compares code before and after changes against a stated goal. Returns alignment score, concerns, and unexpected changes.

What it does: Takes a before/after code pair and a natural language goal, then evaluates whether the changes accomplish the stated intent without unintended side effects. Uses LLM for semantic understanding but produces structured, actionable output.

Parameters:

Name	Type	Required	Description
`before`	string	yes	Code before changes
`after`	string	yes	Code after changes
`goal`	string	yes	Stated goal/intent of the changes
`language`	string	no	Programming language
`context`	object	no	Additional context

Returns:

Field	Type	Description
`alignment_score`	number	0.0–1.0 score of goal alignment
`alignment_reasoning`	string	Explanation of the score
`changes_detected`	object	Structured breakdown of what changed
`concerns`	array	Issues with severity, type, message, and suggestion
`unexpected_changes`	array	Changes not expected given the stated goal

Credits: 4

invariant.review

Comprehensive, project-aware code review in a single call. Orchestrates diff analysis, Prolog-based code queries, and criteria/constraint evaluation to produce a structured verdict.

What it does: Accepts a diff (unified or before/after pair) alongside a goal, acceptance criteria, and constraints. Evaluates each criterion and constraint individually, producing a per-item status and an overall pass/fail verdict. Supports two modes: "check" for a lenient progress report, and "gate" for strict pass/fail gating.

Parameters:

Name	Type	Required	Description
`unified_diff`	string	conditional	Unified diff text (provide either this or `before`/`after`)
`before`	string	conditional	Code before changes
`after`	string	conditional	Code after changes
`goal`	string	no	Stated goal/intent of the changes
`criteria`	array	no	Acceptance criteria to evaluate
`constraints`	array	no	Invariants that must hold (e.g. “no new dependencies”)
`repo_id`	string	no	Repository ID for Prolog fact queries
`commit_sha`	string	no	Git commit SHA for Prolog queries
`mode`	string	no	`"check"` (lenient, default) or `"gate"` (strict)

Example:

{
  "unified_diff": "--- a/lib/auth.ex\n+++ b/lib/auth.ex\n...",
  "goal": "add rate limiting to login",
  "criteria": ["rate limit after 5 failures", "return 429 status"],
  "constraints": ["no new dependencies"],
  "mode": "gate"
}

Returns: verdict (pass/fail), mode, per-criterion results with status and reasoning, concerns, alignment_score.

Credits: 6

Agent feedback loop

Add these lines to an agent’s system prompt for automatic verification:

After making code changes, call invariant.diff_analyzer with your stated goal as the goal parameter. If alignment_score is below 0.8 or unexpected_changes is non-empty, review the concerns and revise before presenting your work.

This creates a neuro-symbolic self-correction loop where the agent’s probabilistic code generation is verified by deterministic semantic analysis.

CLI

The Invariant CLI provides local tree-sitter fact extraction for CI pipelines:

invariant lens .              # Extract facts from all supported files
invariant query orphans       # Find functions with no callers
invariant diff --before a.rs --after b.rs --goal "add caching"

Facts extracted locally are uploaded to DataGrout for server-side semantic enrichment and querying via invariant.code_query.