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

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

![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-000000?style=for-the-badge&logo=github&logoColor=white)
![Claude Code](https://img.shields.io/badge/Claude_Code-D97757?style=for-the-badge&logo=anthropic&logoColor=white)
![OpenAI Codex](https://img.shields.io/badge/OpenAI_Codex-412991?style=for-the-badge&logo=openai&logoColor=white)

[![Validate Config](https://github.com/Fascinax/Inspectra/actions/workflows/validate-config.yml/badge.svg?branch=main)](https://github.com/Fascinax/Inspectra/actions/workflows/validate-config.yml)
[![npm version](https://img.shields.io/npm/v/inspectra?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/inspectra)
![Tests](https://img.shields.io/badge/tests-652%20passing-2ea043?style=for-the-badge)

**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)

![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black)
![Java](https://img.shields.io/badge/Java-ED8B00?style=for-the-badge&logo=openjdk&logoColor=white)

### Partial support (hotspot explorer only)

![Python](https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white)
![Go](https://img.shields.io/badge/Go-00ADD8?style=flat-square&logo=go&logoColor=white)
![Kotlin](https://img.shields.io/badge/Kotlin-7F52FF?style=flat-square&logo=kotlin&logoColor=white)
![C#](https://img.shields.io/badge/C%23-239120?style=flat-square&logo=csharp&logoColor=white)
![PHP](https://img.shields.io/badge/PHP-777BB4?style=flat-square&logo=php&logoColor=white)
![Ruby](https://img.shields.io/badge/Ruby-CC342D?style=flat-square&logo=ruby&logoColor=white)
![Swift](https://img.shields.io/badge/Swift-F05138?style=flat-square&logo=swift&logoColor=white)

> **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](docs/roadmap.md).

---

## Installation

```bash
# 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)

```bash
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

```bash
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](docs/claude-code-setup.md) for detailed instructions.

### Option A″ — OpenAI Codex Setup

```bash
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](docs/codex-setup.md) for detailed instructions.

### Option B — Per-project (symlinks, gitignored)

```bash
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)

```bash
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):

```markdown
/audit
```

**PR audit** (only changed files):

```markdown
/audit-pr
```

**Domain-specific audit**:

```markdown
/audit-domain
```

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

### Working with Reports

**Generate HTML report**:

```bash
inspectra render report.json --html
```

**Export to PDF**:

```bash
inspectra render report.json --pdf
```

**Compare reports**:

```bash
inspectra compare baseline.json current.json
```

**View trends**:

```bash
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:

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

Or via environment:

```bash
export INSPECTRA_PROFILE=java-backend
```

---

## Project Structure

```text
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

```bash
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](package.json) and update [CHANGELOG.md](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](.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

```bash
# 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](https://vitest.dev/) and live alongside source files in `mcp/src/__tests__/`.

---

## Extending

- **Contributing guide**: See [CONTRIBUTING.md](CONTRIBUTING.md)
- **Release notes**: See [CHANGELOG.md](CHANGELOG.md)
- **Add a tool**: See [docs/adding-a-tool.md](docs/adding-a-tool.md)
- **Architecture guide**: See [docs/architecture.md](docs/architecture.md)
- **Output formats**: See [docs/output-format.md](docs/output-format.md)
- **Scoring model**: See [docs/scoring-model.md](docs/scoring-model.md)
- **Roadmap**: See [docs/roadmap.md](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