radar gate (run)

The radar run command is a CI-optimized gate check. It scans the codebase, calculates a debt score from weighted violations, and exits with code 1 if the score exceeds the blocking threshold. Use it in CI pipelines to prevent dangerous code from reaching production.

Usage

radar run <path> [options]

Options

Flag	Description	Default
-c, --config <path>	Path to radar.yml	./radar.yml
-r, --rules <path>	Path to rules.yml	./rules.yml

Scoring Formula

Every violation detected by the analyzers is assigned debt points based on its type and severity. The total score determines whether the gate passes or fails.

Point Values

Violation Type	Points
Architecture violation	+5
Circular dependency	+10
Event loop blocking (Critical)	+8
Event loop warning	+3
Performance risk (XL/XXL tables)	+8
Performance risk (L/M tables)	+3
N+1 query detected	+8
Unhandled promise	+5
Missing error handling	+3
Code duplication	+2
Dead code	+1
Coverage drop	+3
Indirect violation (cross-file)	+2
Violation fixed (credit)	-5 to -8

Gate Threshold

The gate boundary is a score of 15 points:

• Score of 15 or below: PASS -- merge is allowed
• Score of 16 or above: FAIL -- merge is blocked

This means a single circular dependency (+10) with a missing error handler (+3) is still safe to merge (13 points), but add one architecture violation (+5) and the gate blocks (18 points).

Score Examples

Scenario	Score	Result
2 dead code findings, 1 code duplication	1+1+2 = 4	PASS
1 architecture violation, 2 missing error handlers	5+3+3 = 11	PASS
1 circular dependency, 1 architecture violation	10+5 = 15	PASS
1 circular dependency, 1 architecture violation, 1 dead code	10+5+1 = 16	FAIL
1 event loop block, 1 N+1 query	8+8 = 16	FAIL
3 architecture violations	5+5+5 = 15	PASS
1 circular dependency, 1 unhandled promise	10+5 = 15	PASS
1 circular dependency, 1 unhandled promise, 1 dead code	10+5+1 = 16	FAIL

Credits

When a violation that existed in the base branch is fixed in the PR, you receive negative points (credits). This rewards teams for paying down debt:

Fix Type	Credit
Fixed architecture violation	-5
Fixed circular dependency	-8
Fixed runtime risk	-5
Fixed performance issue	-5

A PR that introduces 1 architecture violation (+5) but fixes a circular dependency (-8) nets -3 points, which easily passes.

Gate Conditions

Beyond the total score, the gate evaluates specific blocking conditions from your rules.yml:

gates:
  block_merge:
    - architecture_violations > 0
    - circular_dependencies_introduced > 0
    - runtime_risk_critical > 0
    - reliability_critical > 0
    - critical_performance_risk > 0
    - debt_delta_score > 15
  warn:
    - complexity_increase > 5
    - coverage_drop > 2%
    - maintainability_violations > 3

A PR fails if any block_merge condition is met, regardless of total score.

Output

The run command produces minimal, CI-friendly output without ANSI colors when not running in a TTY.

Pass

$ radar run src/

RADAR PASS | Score: 8 | Warnings: 3

Exit code: 0

Fail

$ radar run src/

RADAR FAIL | Score: 38 | Blocking: 3 | Warnings: 9
  src/events/event.service.ts:42 [perf-unbounded-query] Query on XL table "events" without LIMIT
  src/orders/order.handler.ts:18 [runtime-sync-fs] Synchronous file read in request handler
  src/billing/payment.service.ts:91 [reliability-unhandled-promise] Unhandled promise rejection

Exit code: 1

CI Integration

GitHub Actions

name: Radar Gate
on: [pull_request]

jobs:
  radar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx @radar/cli run src/

GitLab CI

radar-gate:
  stage: test
  script:
    - npm ci
    - npx @radar/cli run src/
  rules:
    - if: $CI_MERGE_REQUEST_ID

Pre-commit Hook

#!/bin/sh
# .husky/pre-commit
npx @radar/cli run src/ || exit 1

Customizing the Threshold

The default blocking threshold of 15 is defined in your rules.yml under gates.block_merge. Adjust the debt_delta_score condition:

gates:
  block_merge:
    # Stricter: block on score > 10
    - debt_delta_score > 10

gates:
  block_merge:
    # More lenient: block on score > 25
    - debt_delta_score > 25

Difference from radar scan

Feature	radar scan	radar run
Output	Rich, colored, multi-section	One-line summary
AI support	Summary, cross-file analysis	None
Formats	6 output formats	Fixed format
Use case	Local development	CI pipelines
TTY detection	Always colored	Plain text when piped