gap-analysis

One-command OpenAPI contract compliance audit. Reduces full audit from 30min to 8min. 9 mechanical checks (< 5s) + parallel LLM semantic analysis.

Install

npm (recommended — one command, easy updates)

# One-time setup: configure user-level npm prefix (avoids EACCES on Linux)
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Install
npm install -g gap-analysis

# Update anytime
npm update -g gap-analysis

Linux users: npm install -g defaults to /usr/lib/node_modules/ which requires sudo. The one-time npm config set prefix above moves global installs to your home directory — no root needed.

curl (no npm required)

curl -sSL https://raw.githubusercontent.com/your-username/gap-analysis/main/install.sh | bash

git clone (private repo)

git clone [email protected]:your-username/gap-analysis.git
bash gap-analysis/install.sh
rm -rf gap-analysis

All methods install to:

• ~/.gap-analysis/ — shell scripts, output files, version info
• ~/.gap-analysis/templates/ — project config template
• ~/.claude/skills/gap-analysis/ — Claude Code slash command

Configure

Copy the template to your project root and edit:

cp ~/.gap-analysis/templates/gap-analysis.json ./gap-analysis.json

{
  "openapi_file": "contracts/openapi.yaml",
  "controller_dirs": ["src/modules/"],
  "prisma_schema": "prisma/schema.prisma",
  "api_prefix": "/v1"
}

Usage

Run from your project root:

Quick pre-scan (< 5 seconds)

gap-pre-scan                        # npm install
# or: bash ~/.gap-analysis/scripts/pre-scan.sh   # curl/git install

Full pipeline (mechanical only)

gap-run-all --phase1-only           # npm install
# or: bash ~/.gap-analysis/scripts/run-all.sh --phase1-only

Full audit in Claude Code

/gap-analysis

Runs the complete Contract-First cycle: pre-scan → parallel LLM agents → gap report → fix plan → TASK.json → auto-implement.

CI mode

gap-run-all --ci --phase1-only      # npm install
# or: bash ~/.gap-analysis/scripts/run-all.sh --ci --phase1-only

Exit codes:

• 0 — all checks passed, no issues found
• 1 — P0/P1 issues found (requires --ci flag)
• 2 — prerequisite failure (missing OpenAPI file, Python deps, etc.)

Self-test

Verify that gap-analysis is working correctly on your system:

gap-self-test                       # npm install
# or: bash ~/.gap-analysis/scripts/lib/self-test.sh

Runs pre-scan and validates: exit cleanly, JSON output is valid, required keys exist, no unexpected errors.

What it checks

| # | Check | Type | Phase | |---|-------|------|-------| | 1 | Endpoint path/method matching | Mechanical | 1 | | 2 | @Roles/@Public vs OpenAPI security | Mechanical | 1 | | 3 | camelCase naming violations | Mechanical | 1 | | 4 | \|\| null falsy traps (number fields) | Mechanical | 1 | | 5 | pageSize @Max(200) validation | Mechanical | 1 | | 6 | @HttpCode status code mismatches | Mechanical | 1 | | 7 | Prisma BigInt vs OpenAPI integer | Mechanical | 1 | | 8 | @ApiTags vs OpenAPI tags | Mechanical | 1 | | 9 | DTO required vs schema required | Mechanical | 1 | | 10 | Response body field completeness | LLM | 2 | | 11 | Permission level reasonability | LLM | 2 | | 12 | Error handling consistency | LLM | 2 |

Requirements

• python3 + pyyaml (pip install pyyaml)
• bash 4+
• git (for install)
• Claude Code (for /gap-analysis slash command)

How it works

Phase 1: pre-scan.sh (< 5 sec)
  9 mechanical checks → ~/.gap-analysis/scripts/.gap-pre-scan.json

Phase 2: parallel LLM agents (2-3 min, only if Phase 1 found issues)
  3 agents analyze semantics in parallel → .gap-segment-{A,B,C}.md

Phase 3: merge-reports.sh (< 1 sec)
  Combine Phase 1 JSON + Phase 2 segments → docs/verifications/project-gap-{ts}.md

Supported Frameworks

| Framework | Status | Auth Detection | Validation | |-----------|--------|----------------|------------| | NestJS | ✅ Full | @Roles/@Public/@ApiBearerAuth | class-validator decorators | | Express | ✅ Full | passport.authenticate('jwt') | Zod schemas | | Fastify | 🔜 Planned | — | — | | Spring Boot | 🔜 Planned | — | — | | FastAPI | 🔜 Planned | — | — |

Supported ORMs

| ORM | Status | BigInt Detection | |-----|--------|-----------------| | Prisma | ✅ Full | BigInt in schema.prisma | | TypeORM | ✅ Full | @Column({ type: 'bigint' }) | | Drizzle | ✅ Full | bigint(), pgBigInt() | | Mongoose | ✅ Full | BigInt, Schema.Types.Long | | SQLAlchemy | 🔜 Planned | — | | GORM | 🔜 Planned | — |

Configuration

See gap-analysis.json for all options. Key fields:

| Field | Default | Description | |-------|---------|-------------| | framework | nestjs | Backend framework | | orm | prisma | ORM/database layer | | validation_lib | nestjs | Validation library (nestjs, zod) | | route_dirs | ["backend-typescript/src/modules/"] | Directories containing route files | | route_pattern | *.controller.ts | Glob pattern for route files | | dto_dirs | ["backend-typescript/src/modules/"] | Directories containing DTO files |