Package Exports

gap-analysis

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (gap-analysis) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 git@github.com: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