Inspectra

<p align="center"> <img src="banner.png" alt="Inspectra Banner" width="100%"/> </p>

<h1 align="center">Inspectra</h1>

Hybrid code audit system powered by GitHub Copilot and MCP.

Inspectra runs deterministic MCP tools across 12 audit domains, then performs a single structured synthesis pass with optional hotspot exploration to produce structured, scored, and actionable code quality reports.

Supported Languages

Full support (deterministic tools + conditional explorer)

Partial support (hotspot explorer only)

Full support = deterministic MCP tool scans (naming, file lengths, complexity, DRY, etc.) + conditional hotspot exploration. Partial support = conditional hotspot explorer only — no dedicated MCP tool scans. More languages on the roadmap.

---

Installation

# Clone the repository
git clone https://github.com/Fascinax/Inspectra.git
cd Inspectra

# Install dependencies
npm install

# Build the MCP server
npm run build

# Install globally
npm install -g .

---

Quick Start

Prerequisites

• Node.js 20+
• npm 10+
• GitHub Copilot with Custom Agents support

Option A — Global Setup (recommended, zero project footprint)

inspectra setup

This installs everything into your VS Code user directory:*

• MCP server registered in VS Code user settings
• Agents + prompts available globally in all projects

Then open any project in VS Code → Copilot Chat → type /audit.

No files are added to your projects.

Option A′ — Claude Code Setup

cd /path/to/my-project
inspectra setup --claude

This creates in the current directory:

• .mcp.json — Claude Code auto-connects to the Inspectra MCP server
• CLAUDE.md — project context with audit instructions, tool list, scoring model
• policies/ + schemas/ — scoring rules and contracts

Then open the project with Claude Code and ask to run an audit.

See docs/claude-code-setup.md for detailed instructions.

Option A″ — OpenAI Codex Setup

cd /path/to/my-project
inspectra setup --codex

This creates in the current directory:

• AGENTS.md — Codex reads this as project instructions (audit workflow, tools, scoring)
• .codex/config.toml — MCP server configuration (Codex auto-connects)
• policies/ + schemas/ — scoring rules and contracts

Then run codex "Run a full Inspectra audit on this project."

See docs/codex-setup.md for detailed instructions.

Option B — Per-project (symlinks, gitignored)

inspectra init /path/to/my-project

This creates symlinked Inspectra workflow assets in the target project (gitignored automatically):

• .github/prompts/ — audit prompt shortcuts (symlinked, gitignored)
• .vscode/mcp.json — MCP server auto-starts when the project opens
• policies/ + schemas/ — scoring rules and contracts (copied)

On Windows, directory junctions are used (no Developer Mode or elevation required). File symlinks are used on Unix.

Option C — Per-project (committed copies)

inspectra init /path/to/my-project --copy

Same as Option B but files are real copies committed with the repo. Useful for CI or when team members don't have Inspectra installed.

Run an Audit

Open the target project in VS Code, open Copilot Chat, and type:

• /audit : full audit (all 12 domains, Tier B hybrid workflow)
• /audit-pr : audit scoped to changed files

---

Usage

Running Audits

Full audit (all 12 domains, Tier B):

/audit

PR audit (only changed files):

/audit-pr

Domain-specific audit:

/audit-domain

Then specify the domain to audit in the prompt, for example: security, tests, architecture, observability.

Working with Reports

Generate HTML report:

inspectra render report.json --html

Export to PDF:

inspectra render report.json --pdf

Compare reports:

inspectra compare baseline.json current.json

View trends:

inspectra trend report1.json report2.json report3.json

CLI Commands

Command	Description
inspectra setup	Global setup (VS Code user settings)
inspectra setup --claude	Claude Code setup (current directory)
inspectra setup --codex	OpenAI Codex setup (current directory)
inspectra init <path>	Per-project setup with symlinks
inspectra init <path> --copy	Per-project setup with copies
inspectra doctor	Diagnose installation issues

Environment Variables

Variable	Default	Description
INSPECTRA_LOG_LEVEL	info	Log verbosity (debug, info, warn, error)
INSPECTRA_PROFILE	generic	Active policy profile
NODE_ENV	production	Runtime environment

Profile Selection

Profiles are auto-detected based on package.json and pom.xml. Explicit override:

{
  "inspectra": {
    "profile": "java-angular-playwright"
  }
}

Or via environment:

export INSPECTRA_PROFILE=java-backend

---

Project Structure

inspectra/
├─ .github/
│  ├─ agents/           # legacy benchmark/reference agent definitions
│  ├─ prompts/          # /audit, /audit-pr, /audit-domain, benchmark prompts
│  ├─ workflows/        # GitHub Actions CI/CD
│  └─ copilot-instructions.md
│
├─ mcp/src/             # MCP server (TypeScript, ES2022, Node 20+)
│  ├─ tools/            # Domain tool implementations (one file per domain)
│  ├─ register/         # Tool registration with input/output schemas
│  ├─ merger/           # Scoring engine, deduplication, merge
│  ├─ policies/         # YAML policy loader & scoring defaults
│  ├─ renderer/         # HTML, PDF, Markdown, SARIF renderers
│  └─ utils/            # Shared utilities (files, paths, project-config)
│
├─ schemas/             # JSON Schema 2020-12 contracts
├─ policies/            # Scoring rules, severity matrix & stack profiles
├─ docs/                # ADRs, guides, architecture docs
├─ examples/            # Sample findings & reports
├─ scripts/             # Dev & CI utility scripts
├─ Makefile             # Unified command runner
└─ bin/init.mjs         # CLI entry point

---

Docker

MCP Server

docker compose up inspectra

---

Audit Domains

Domain	Tool Group	MCP Tools	Prefix
Security	Security scan	inspectra_scan_secrets, inspectra_check_deps_vulns, inspectra_run_semgrep, inspectra_check_maven_deps	SEC-
Tests	Test audit	inspectra_parse_coverage, inspectra_parse_test_results, inspectra_detect_missing_tests, inspectra_parse_playwright_report, inspectra_detect_flaky_tests	TST-
Architecture	Architecture audit	inspectra_check_layering, inspectra_analyze_dependencies, inspectra_detect_circular_deps	ARC-
Conventions	Conventions audit	inspectra_check_naming, inspectra_check_file_lengths, inspectra_check_todos, inspectra_parse_lint_output, inspectra_detect_dry_violations	CNV-
Performance	Performance audit	inspectra_analyze_bundle_size, inspectra_check_build_timings, inspectra_detect_runtime_metrics	PRF-
Documentation	Documentation audit	inspectra_check_readme_completeness, inspectra_check_adr_presence, inspectra_detect_doc_code_drift	DOC-
Tech debt	Tech-debt audit	inspectra_analyze_complexity, inspectra_age_todos, inspectra_check_dependency_staleness	DEBT-
Accessibility	Accessibility audit	inspectra_check_a11y_templates	ACC-
API Design	API design audit	inspectra_check_rest_conventions	API-
Observability	Observability audit	inspectra_check_observability	OBS-
i18n	i18n audit	inspectra_check_i18n	INT-
UX Consistency	UX consistency audit	inspectra_check_ux_consistency	UX-

---

Scoring Model

• Domain scores: 0–100 (100 = no issues)
• Overall score: Weighted average across all audited domains (weights in policies/scoring-rules.yml)
• Grades: A (90+), B (75+), C (60+), D (40+), F (<40)

---

Make Commands

Command	Description
make bootstrap	Full setup: install, build, test
make build	Build the MCP server
make test	Run unit tests
make validate	Validate schemas + lint prompts
make smoke	Smoke test the MCP server
make init TARGET=/path	Copy agents into a project
make help	List all commands

npm Scripts

Script	Description
npm run build	Compile the MCP server (TypeScript → mcp/dist/)
npm test	Run the Vitest suite
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests with V8 coverage report
npm run lint	TypeScript type-check + ESLint
npm run lint:fix	Auto-fix ESLint violations
npm run format	Format source with Prettier
npm run format:check	Check Prettier formatting (CI-safe)
npm run release:check	Run the npm publication preflight (npm publish --dry-run)

---

Release Checklist

Before publishing a new version:

1. Bump the version in package.json and update CHANGELOG.md
2. Run npm run release:check
3. Create a GitHub release tag matching the package version, for example v0.7.0
4. Ensure the NPM_TOKEN repository secret is configured
5. Publish via the release workflow in .github/workflows/release.yml

The release workflow builds, tests, packs the artifact, publishes with npm provenance, and attaches the tarball to the GitHub release.

---

Testing

# Run the full test suite
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage

Tests are written with Vitest and live alongside source files in mcp/src/__tests__/.

---

Extending

• Contributing guide: See CONTRIBUTING.md
• Release notes: See CHANGELOG.md
• Add a tool: See docs/adding-a-tool.md
• Architecture guide: See docs/architecture.md
• Output formats: See docs/output-format.md
• Scoring model: See docs/scoring-model.md
• Roadmap: See docs/roadmap.md
• Add a domain: Add tools in mcp/src/tools/, expose them via prompts, and update scoring weights
• Add a profile: Create a YAML file in policies/profiles/

Available Profiles

Profile	Stack
generic	Any project (conservative defaults)
java-angular-playwright	Java + Angular + Playwright full-stack
java-backend	Java backend (Quarkus / Spring Boot)
angular-frontend	Angular SPA (TypeScript)

---

Tech Stack

• TypeScript (ES2022, Node 20+) — MCP server
• Zod — Runtime type validation
• JSON Schema 2020-12 — Output contracts
• MCP SDK — Tool registration and transport
• YAML — Policies and profiles

---

License

MIT