Quality Gates API | Bootspring Docs

The Quality Gates API provides configurable quality checks for your codebase, including type checking, linting, testing, and security audits.

Overview#

Quality gates are predefined sets of checks that run at different stages of development:

pre-commit: Quick checks before committing code
pre-push: Thorough checks before pushing to remote
pre-deploy: Full audit before deployment

The system automatically detects available tools in your project and runs appropriate checks.

REST API Endpoints#

List Quality Gates#

GET /api/v1/quality/gates

Returns available quality gates.

Response:

{
  "data": [
    {
      "id": "pre-commit",
      "name": "Pre-Commit",
      "description": "Quick checks before committing code",
      "checks": ["typecheck", "lint", "format"]
    },
    {
      "id": "pre-push",
      "name": "Pre-Push",
      "description": "Thorough checks before pushing to remote",
      "checks": ["typecheck", "lint", "test", "build"]
    },
    {
      "id": "pre-deploy",
      "name": "Pre-Deploy",
      "description": "Full audit before deployment",
      "checks": ["typecheck", "lint", "test", "build", "security"]
    }
  ]
}

Run Quality Gate#

POST /api/v1/quality/run

Run a quality gate and get results.

Request Body:

{
  "gate": "pre-commit",
  "options": {
    "skip": ["format"],
    "strict": true,
    "verbose": false
  }
}

Response:

{
  "data": {
    "gate": "pre-commit",
    "name": "Pre-Commit",
    "status": "pass",
    "passed": 2,
    "failed": 0,
    "skipped": 1,
    "total": 3,
    "results": [
      {
        "id": "typecheck",
        "name": "TypeScript",
        "status": "pass",
        "message": "Passed"
      },
      {
        "id": "lint",
        "name": "Linting",
        "status": "pass",
        "message": "Passed"
      },
      {
        "id": "format",
        "name": "Formatting",
        "status": "skip",
        "message": "Skipped by user"
      }
    ]
  },
  "meta": {
    "executionTime": 5230,
    "requestId": "req_abc123"
  }
}

Get Report#

GET /api/v1/quality/reports/:id

Get a previously generated quality report.

JavaScript/Node.js API#

Module Import#

const quality = require('bootspring/quality');

Running Gates#

`runGate(gateId, projectRoot, options)`#

Run a quality gate against a project.

Parameters:

Parameter	Type	Description
`gateId`	string	Gate identifier (`pre-commit`, `pre-push`, `pre-deploy`)
`projectRoot`	string	Path to project root
`options`	object	Optional configuration

Options:

Option	Type	Default	Description
`customGates`	object	`{}`	Custom gate definitions
`skip`	array	`[]`	Check IDs to skip
`strict`	boolean	`false`	Stop on first failure
`verbose`	boolean	`false`	Include full output

Returns: Gate results object.

const results = quality.runGate('pre-commit', '/path/to/project', {
  skip: ['format'],
  strict: true
});

// Returns:
// {
//   gate: 'pre-commit',
//   name: 'Pre-Commit',
//   description: 'Quick checks before committing code',
//   status: 'pass', // or 'fail'
//   passed: 2,
//   failed: 0,
//   skipped: 1,
//   total: 3,
//   results: [
//     { id: 'typecheck', name: 'TypeScript', status: 'pass', message: 'Passed' },
//     { id: 'lint', name: 'Linting', status: 'pass', message: 'Passed' },
//     { id: 'format', name: 'Formatting', status: 'skip', message: 'Skipped by user' }
//   ]
// }

Check Management#

`resolveCheck(checkId, projectRoot)`#

Resolve a check to its executable command.

Parameters:

Parameter	Type	Description
`checkId`	string	Check identifier
`projectRoot`	string	Path to project root

Returns: Check configuration or null if tool not available.

const check = quality.resolveCheck('lint', '/path/to/project');
// Returns:
// {
//   id: 'lint',
//   name: 'Linting',
//   description: 'Code linting',
//   command: 'npx eslint .',
//   tool: 'eslint'
// }

`executeCheck(check, projectRoot, options)`#

Execute a single check.

Parameters:

Parameter	Type	Description
`check`	object	Check configuration from `resolveCheck`
`projectRoot`	string	Path to project root
`options`	object	Execution options

Options:

Option	Type	Default	Description
`timeout`	number	`300000`	Timeout in milliseconds (5 min)
`verbose`	boolean	`false`	Include full output

const check = quality.resolveCheck('test', '/path/to/project');
const result = quality.executeCheck(check, '/path/to/project', {
  timeout: 60000,
  verbose: true
});

// Returns:
// {
//   id: 'test',
//   name: 'Tests',
//   status: 'pass', // or 'fail'
//   message: 'Passed',
//   output: '...' // if verbose
// }

`getAvailableChecks(projectRoot)`#

Get all checks available for a project.

const checks = quality.getAvailableChecks('/path/to/project');
// Returns:
// [
//   { id: 'typecheck', name: 'TypeScript', tool: 'tsc', command: 'npx tsc --noEmit' },
//   { id: 'lint', name: 'Linting', tool: 'eslint', command: 'npx eslint .' },
//   { id: 'test', name: 'Tests', tool: 'vitest', command: 'npm test' },
//   // ...
// ]

Gate Management#

`getGate(gateId, customGates)`#

Get a gate definition.

const gate = quality.getGate('pre-commit');
// Returns:
// {
//   name: 'Pre-Commit',
//   description: 'Quick checks before committing code',
//   checks: ['typecheck', 'lint', 'format']
// }

`listGates(customGates)`#

List all available gate IDs.

const gates = quality.listGates();
// Returns: ['pre-commit', 'pre-push', 'pre-deploy']

Tool Detection#

`detectTool(projectRoot, detect)`#

Check if a tool is available in the project.

Parameters:

Parameter	Type	Description
`projectRoot`	string	Path to project root
`detect`	string	Detection pattern

Detection Patterns:

filename - Check if file exists (e.g., tsconfig.json)
package.json:property - Check package.json property (e.g., package.json:scripts.test)

// Check for TypeScript
const hasTS = quality.detectTool('/path/to/project', 'tsconfig.json');

// Check for test script
const hasTests = quality.detectTool('/path/to/project', 'package.json:scripts.test');

Git Hook Generation#

`generateHookScript(gateId, options)`#

Generate a git hook script.

Parameters:

Parameter	Type	Description
`gateId`	string	Gate to run
`options`	object	Hook options

Options:

Option	Type	Default	Description
`strict`	boolean	`true`	Fail on first error
`skip`	array	`[]`	Checks to skip

const script = quality.generateHookScript('pre-commit', {
  skip: ['format']
});

// Returns:
// #!/bin/sh
// # Bootspring Quality Gate Hook
//
// npx bootspring quality pre-commit --strict --skip format

Available Checks#

typecheck#

TypeScript type checking.

Tool	Command	Detection
tsc	`npx tsc --noEmit`	`tsconfig.json`

lint#

Code linting.

Tool	Command	Detection
eslint	`npx eslint .`	`eslint.config.js`, `.eslintrc.js`, `.eslintrc.json`
biome	`npx biome check .`	`biome.json`

format#

Code formatting.

Tool	Command	Detection
prettier	`npx prettier --check .`	`.prettierrc`, `.prettierrc.json`, `prettier.config.js`
biome	`npx biome format --check .`	`biome.json`

test#

Test execution.

Tool	Command	Detection
jest	`npm test`	`jest.config.js`
vitest	`npm test`	`vitest.config.ts`
mocha	`npm test`	`package.json:mocha`
npm	`npm test`	`package.json:scripts.test`

build#

Production build.

Tool	Command	Detection
next	`npm run build`	`next.config.js`
vite	`npm run build`	`vite.config.ts`
npm	`npm run build`	`package.json:scripts.build`

security#

Security audit.

Tool	Command	Detection
npm	`npm audit --audit-level=high`	`package-lock.json`
yarn	`yarn audit --level high`	`yarn.lock`
pnpm	`pnpm audit --audit-level high`	`pnpm-lock.yaml`

Default Gates#

pre-commit#

Quick checks before committing.

Checks: typecheck, lint, format

pre-push#

Thorough checks before pushing.

Checks: typecheck, lint, test, build

pre-deploy#

Full audit before deployment.

Checks: typecheck, lint, test, build, security

MCP Tool#

The bootspring_quality MCP tool provides quality gate functionality.

Tool Definition#

{
  "name": "bootspring_quality",
  "description": "Run quality gates to check code quality and security",
  "inputSchema": {
    "properties": {
      "gate": {
        "type": "string",
        "enum": ["pre-commit", "pre-push", "pre-deploy"],
        "description": "Quality gate to run"
      }
    },
    "required": ["gate"]
  }
}

Example#

{
  "gate": "pre-commit"
}

Custom Gates#

Define custom gates for your project:

const quality = require('bootspring/quality');

const customGates = {
  'quick-check': {
    name: 'Quick Check',
    description: 'Fast validation for CI',
    checks: ['typecheck', 'lint']
  },
  'full-audit': {
    name: 'Full Audit',
    description: 'Complete project audit',
    checks: ['typecheck', 'lint', 'format', 'test', 'build', 'security']
  }
};

const results = quality.runGate('quick-check', '/path/to/project', {
  customGates
});

CLI Commands#

# Run pre-commit gate
bootspring quality pre-commit

# Run with strict mode (stop on first failure)
bootspring quality pre-push --strict

# Skip specific checks
bootspring quality pre-deploy --skip format --skip security

# Verbose output
bootspring quality pre-commit --verbose

Error Handling#

Unknown Gate#

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Unknown gate: invalid-gate"
  }
}

Check Failure#

// Individual check result on failure
{
  id: 'lint',
  name: 'Linting',
  status: 'fail',
  message: 'src/index.ts:10:5 - Unexpected any. Specify a different type.',
  exitCode: 1
}

Tool Not Available#

// When a check's tool is not detected
{
  id: 'typecheck',
  name: 'TypeScript',
  status: 'skip',
  message: 'Tool not available'
}

Constants#

DEFAULT_GATES#

const { DEFAULT_GATES } = require('bootspring/quality');

// {
//   'pre-commit': { name: 'Pre-Commit', checks: [...] },
//   'pre-push': { name: 'Pre-Push', checks: [...] },
//   'pre-deploy': { name: 'Pre-Deploy', checks: [...] }
// }

CHECK_DEFINITIONS#

const { CHECK_DEFINITIONS } = require('bootspring/quality');

// {
//   typecheck: { name: 'TypeScript', commands: [...] },
//   lint: { name: 'Linting', commands: [...] },
//   format: { name: 'Formatting', commands: [...] },
//   test: { name: 'Tests', commands: [...] },
//   build: { name: 'Build', commands: [...] },
//   security: { name: 'Security', commands: [...] }
// }

Best Practices#

Start with pre-commit: Run quick checks before every commit
Use pre-push for CI: Mirror your CI checks in pre-push
Skip thoughtfully: Only skip checks when necessary
Use strict mode in CI: Fail fast on any issue
Run pre-deploy before releases: Catch security issues early
Customize for your needs: Create custom gates for your workflow