OrangePro

What is OrangePro about?

OrangePro creates a deterministic evidence graph of all public behaviors in a repository, classifies each behavior into evidence tiers (e.g., Dynamically Proven, Runtime‑covered, Statistically Linked, Unconfirmed Candidate, No Signal), and visualizes blind spots in an interactive HTML report.

How to use OrangePro?

# Install and run in one step (no API key needed for analysis)
npx -y @orangepro/mcp-server@latest start .
open .orangepro/behavior-coverage.html

• To enable AI‑driven test generation, export a model key before running the same command:

export ANTHROPIC_API_KEY="..."   # or OPENAI_API_KEY / OLLAMA_BASE_URL
npx -y @orangepro/mcp-server@latest start .

• The CLI (opro) offers granular commands such as opro analyze, opro gaps, opro generate, opro prove, and opro mcp for integration with MCP‑compatible agents.

Key Features of OrangePro

• Behavior Mapping: Automatic AST walk builds a knowledge graph of all public symbols and flows.
• Evidence Tiers: Precise classification of test evidence without guesswork.
• Interactive Report: Simple (high‑level blind spots) and Expert (full list, flows, system map) modes.
• Grounded Test Generation: AI‑generated, language‑specific test drafts for top‑risk gaps.
• Dynamic Proof: Mutation‑kill oracle confirms that a generated test would fail if the behavior regressed.
• Local‑First & Private: All analysis runs in‑process; no source code leaves the machine.
• Multi‑language Support: Built‑in for TypeScript/JavaScript, Python, Go, Java (and plans for many more) via tree‑sitter.
• MCP Server Compatibility: Can be invoked by Claude Code, Cursor, Copilot, Codex, and other MCP‑aware agents.
• Delta Reporting: Shows new behaviors, risk changes, and resolved gaps on each run.

Use Cases of OrangePro

• CI Gatekeeping: Fail a pull request if high‑risk behaviors remain untested.
• Test Gap Auditing: Quickly identify which public APIs lack reliable test coverage.
• Automated Test Creation: Generate runnable Jest, pytest, Go, or JUnit tests for uncovered flows.
• Regression Safety Net: Apply mutation testing to prove that critical behaviors are defended by tests.
• Developer Onboarding: New team members can visualize system behavior and testing status instantly.
• Agent‑Driven Development: Link with Claude Code or similar agents to let the AI write, run, and prove tests end‑to‑end.

FAQ from OrangePro

Q: Do I need an API key to run the analysis? A: No. Analysis, scoring, and proof are completely offline. A model key is only required for AI‑generated tests.

Q: Will my source code be uploaded anywhere? A: No. The tool reads files in‑process and never persists or transmits code.

Q: Can I use OrangePro with languages not listed? A: Static mapping works for many languages via tree‑sitter. Dynamic proof and test generation are currently supported for TS/JS, Python, Go, and Java, with others planned.

Q: How do I integrate with a coding agent? A: Add an MCP server entry to the agent’s config, e.g., { "mcpServers": { "orangepro-local": { "command": "npx", "args": ["-y", "@orangepro/mcp-server@latest", "mcp"] } } }. The agent can then call tools like orangepro_generate_tests and orangepro_prove.

Q: What is the difference between "Dynamically Proven" and "Runtime‑covered"? A: "Dynamically Proven" requires a targeted mutation that a test kills, proving behavior change is detected. "Runtime‑covered" simply means a coverage tool executed the code during a test run.

Q: How are test drafts stored? A: Generated drafts appear under .orangepro/ai/ and are written to orangepro_generated/ without modifying existing source files.

---

OrangePro maps every public behavior in your codebase, scores each one by real test evidence, and shows you the structural blind spots before your users find them. Runs locally. Your code never leaves your machine.

npx -y @orangepro/mcp-server@latest start .

---

Table of Contents

• What you get
• Evidence tiers
• Quick start
• Use with your coding agent
• How it works
• Language support
• Privacy
• CLI reference
• MCP tools
• Platform
• Contributing

---

What you get

One command produces an interactive HTML report:

npx -y @orangepro/mcp-server@latest start .
open .orangepro/behavior-coverage.html

The report has two modes: Simple (integration-level blind spots, plain English) and Expert (full behavior list, evidence tiers, flows, system map). Toggle with the pill switch at the top.

→ Live example: Twenty CRM (5,237 behaviors mapped)

System map — entry lanes (GraphQL, HTTP, Jobs) flowing into services, sized by traffic, colored by evidence tier, red-ringed by risk.

Priority gaps of another open source Project HONO — top 20 unproven behaviors ranked by blast radius, with generated test drafts.

---

Evidence tiers

Every behavior gets exactly one tier. Nothing is labeled "tested" on faith.

Tier	Color	What it means
Dynamically Proven	🟢	A real test kills a targeted mutation of this behavior
Runtime-covered	🟢	Coverage tool executed this code
Statically Linked	🟡	A test imports and calls this code — structural link, not proof
Unconfirmed Candidate	⚪	A similar test file exists — a lead, not evidence
No Signal	🔴	Nothing tests this behavior

"Dynamically Proven 0" is normal on first run. Proof requires running tests against targeted mutations. That's the trust model.

---

Quick start

cd /path/to/your/repo
npm install          # install the repo's own dependencies first

npx -y @orangepro/mcp-server@latest start .
open .orangepro/behavior-coverage.html

No API key needed. The report shows your system map, evidence tiers, priority gaps, and delta since last run.

Want test generation? Add a model key (BYOK):

export ANTHROPIC_API_KEY="..."   # or OPENAI_API_KEY / OLLAMA_BASE_URL
npx -y @orangepro/mcp-server@latest start .

AI output never changes evidence tiers. Only the mutation-kill oracle can mint Dynamically Proven.

Output:

.orangepro/
├── behavior-coverage.html   ← open this
├── graph.json               ← deterministic evidence graph
├── COVERAGE_REPORT.md       ← coverage and gap summary
└── ai/                      ← candidate flows (when a key is configured)

orangepro_generated/         ← generated tests; your source files are never touched

Each rerun shows a delta banner: what entered the codebase, what moved up in risk, what got resolved.

---

Use with your coding agent

OrangePro runs as an MCP server. Add to your client's config:

{
  "mcpServers": {
    "orangepro-local": {
      "command": "npx",
      "args": ["-y", "@orangepro/mcp-server@latest", "mcp"]
    }
  }
}

Client	Where to put it
Claude Code	.mcp.json or ~/.claude.json
Cursor	~/.cursor/mcp.json or Settings → MCP
VS Code / Copilot	MCP settings
Codex / OpenCode	Run npx -y @orangepro/mcp-server@latest agent --client codex

The workflow: Tell your agent:

"Use orangepro_start, then orangepro_generate_tests with base_ref=main. Write each test to its suggested_path, run it, and report pass/fail."

The agent writes the test, runs it, calls orangepro_prove, and the behavior turns Dynamically Proven. One prompt, full loop.

---

Works with

Any MCP-compatible agent can drive OrangePro. No vendor lock-in.

---

How it works

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Your Code  │ ──► │  Knowledge   │ ──► │  Evidence   │
│  (any lang) │     │    Graph     │     │   Tiers     │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                    ┌──────┴──────┐
                    ▼             ▼
             ┌───────────┐  ┌──────────┐
             │ Gap Report│  │ Generate │
             │ + Risks   │  │  Tests   │
             └───────────┘  └──────────┘

Phase	What happens	Needs a model key?
Analyze	AST walk → behaviors, flows, evidence tiers	No
Score	Graph readiness score (0–100)	No
Generate	Grounded tests for top gaps	Yes (BYOK)
Prove	Mutation-kill oracle confirms test breaks if behavior changes	No

Same code = same score. Deterministic. Always.

---

Language support

Language	Static mapping	Generated tests	Dynamic proof
TypeScript / JavaScript	✓	✓ Jest / Vitest / Mocha	✓
Python	✓	✓ pytest	✓
Go	✓	✓ *_test.go	✓
Java	✓	✓ JUnit 4/5	✓
Kotlin, Rust, PHP, C#, Ruby, Swift, C, C++	✓	planned	planned

Static mapping works across many languages via tree-sitter. Dynamic proof is deliberately narrower — each language needs a runner, mutation locator, and sandbox profile.

---

Highest-value local run

Use the repository's own setup and test commands first, and keep unit and integration coverage in separate artifacts. Then run opro start; it performs analysis, ingests the artifacts, attempts targeted proof, generates report-visible drafts, and writes the final report. A separate opro analyze is unnecessary when opro start follows it.

# 1. Install/build exactly as the repository documents.
# 2. Run the repository's unit and integration coverage commands separately.
# 3. Record artifact provenance (example paths and commands):
mkdir -p .orangepro
# create .orangepro/coverage-suites.json using the schema below

opro coverage .                    # optional preflight: discover/generate artifacts
opro start . --proof-limit 5 --generate-limit 20

{
  "artifacts": {
    ".orangepro/coverage/unit.coverprofile": {
      "suite": "unit",
      "command": "make unit-test-coverage"
    },
    ".orangepro/coverage/integration.coverprofile": {
      "suite": "integration",
      "command": "make integration-test-coverage"
    }
  }
}

Without this manifest, OrangePro conservatively infers clear unit/integration names and labels everything else unclassified; it never guesses that an aggregate profile is unit-only. The report shows unit, integration, their overlap, unclassified coverage, and the combined union separately. --proof-limit controls dynamic proof attempts (which may draft a test for proof); --generate-limit independently controls the additional report-visible risk-gap drafting lane. A generation run also records its terminal status and exact reason, so a compiler/import failure is not misreported as a generic dependency problem.

---

Privacy

• No stored source. Reads code in-process. Never uploads to an OrangePro server.
• No existing-source mutation. Never edits your source or test files.
• Your keys stay yours. Read from env at call time, never persisted.
• BYOK is direct. Code context goes to the model provider you configure. OrangePro is not in that path.

---

opro                          # analyze + report + agent next actions
opro start --base main        # same, scoped to a branch diff
opro analyze                  # build the evidence graph
opro score                    # graph readiness (0–100)
opro gaps --limit 10          # top 10 untested behaviors
opro generate --base main     # tests for PR diff
opro generate --single        # top gap, whole repo
opro prove                    # mutation-kill oracle
opro rtm                      # traceability matrix
opro export                   # metadata-only evidence pack
opro mcp                      # run as MCP server (stdio)
opro doctor                   # what evidence to add next
opro coverage                 # discover/generate artifacts; analyze or start ingests them

Add --json to any read command for machine output. Run opro help for the full reference.

Tool	What it does
orangepro_start	One-command setup: analyze + report + next actions
orangepro_analyze_sources	Build/refresh the evidence graph
orangepro_generate_tests	Generate grounded tests for gaps
orangepro_prove	Run mutation-kill oracle on a behavior
orangepro_prove_loop	Setup + dynamic proof + report refresh for one behavior
orangepro_find_test_gaps	List behaviors with weak/missing tests, ranked by risk
orangepro_graph_score	Graph readiness score (0–100)
orangepro_status	Workspace state without generating anything
orangepro_doctor	Recommend next evidence to improve quality
orangepro_rtm	Requirements traceability matrix
orangepro_stats	Aggregate statistics
orangepro_changed_impact	What a diff touches (requires git + base ref)
orangepro_record_run	Record a test run result
orangepro_explain_test	Explain why a test was generated
orangepro_export_evidence_pack	Export metadata-only evidence pack
orangepro_update_graph	Incremental graph update
orangepro_ai_links	Weak behavior→symbol suggestions (optional AI)
orangepro_ai_flows	Candidate flow discovery (optional AI)

opro generate --base main              # tests for what this branch changed
opro generate --pr 1234                # checks out PR #1234
opro generate --changed                # current branch diff vs main

Each generated test includes:

• Grounding — the real files, symbols, and existing tests it cites
• Run hints — where to write it, how to run it
• Scenario bucket — what failure mode it targets

If dependencies aren't installed, tests are kept as Manual tests (Given/When/Then steps with the blocker named). Install dependencies and re-run to convert them to runnable tests.

Generation is evidence-gated. A category is produced only when the graph has supporting evidence.

Category	What it targets
Happy path	Primary expected behavior
Validation error	Bad/invalid input handling
Edge case	Boundaries, empty/null, concurrency, retries
Integration flow	Multi-step behavior across services
Security / privacy	Auth, injection, data leakage
Regression	Pinning a previously-broken behavior

Analysis, scoring, and proof need no model key. Generation does.

Provider	Environment variable
OpenAI-compatible	OPENAI_API_KEY (optional: OPENAI_BASE_URL, OPENAI_MODEL)
Anthropic	ANTHROPIC_API_KEY (optional: ANTHROPIC_MODEL)
Ollama (local, no key)	OLLAMA_BASE_URL (optional: OLLAMA_MODEL)

Auto-detect order: OpenAI → Ollama → Anthropic. Override with --provider and --model.

Run opro setup to configure interactively. Keys stay in your environment — never written to graph, config, or artifacts.

With a provider key, OrangePro stages weak AI behavior→symbol links and AI-suggested candidate flows. These are review/generation worklists, not evidence:

• AI links appear as AI-linked suggestions.
• AI flows are stored separately from deterministic flows.
• Neither lane changes evidence tiers or denominator counts.

Use them when you want the agent to find likely service-boundary flows faster; ignore them for a deterministic-only report.

---

What's on the hosted platform

This repo is the free local tool. The OrangePro platform adds:

• Persistent knowledge graph across PRs and repos
• PR/CI policy gates over evidence tiers and risk deltas
• Jira / Confluence / TestRail / OpenAPI enrichment
• Cross-repo intelligence and recurring-flow memory
• Production incident correlation and regression targeting
• Team dashboards and test lifecycle management

---

Contributing

git clone https://github.com/OrangeproAI/orangepro-mcp.git
cd orangepro-mcp && npm ci && npm run build
npm test

PRs welcome. Please open an issue first for large changes.

---