DEVTOOLS/portfolio
three tools · one tooling story · zero flaky tests

Precision instruments for engineers.

A trio of fully-tested developer tools built around clean CLI ergonomics, fast feedback, and golden-file testing. ContractCheck guards APIs against drift, DevBox spins up reproducible environments, and CodeScope X-rays a codebase's health.

Explore the toolkit Source ↗
3
shipping tools
167
passing tests
0→1
exit-code clean
100%
golden-file gated
contractcheck — zsh
live output
$ contractcheck petstore.yaml -u http://127.0.0.1:8080
╭───────────────────────────────╮
│ ContractCheck Petstore 1.0.0 │
╰───────────────────────────────╯
PASS GET /pets -> 200
FAIL POST /pets -> 500
x unexpected status: status 500 is not documented
FAIL GET /pets/{petId} -> 200
x missing field: missing required field 'name'
3 operations · 1 passed · 2 failed · 3 violations
✗ contract violations detected
$ echo $? 1
the toolkit

Three instruments, one bench.

Each tool is self-contained, shares the same DX spine — rich human output, a schema-validated --json mode, and CI-grade exit codes — and ships with a verification harness that decides when it's actually done.

INSTRUMENT 01 — API CONFORMANCE

ContractCheck

Verify a running API matches its OpenAPI spec — and fail CI when it drifts.

OpenAPI 3.xhttpxJSON Schemapure validator core--json
gate conforming API → exit 0
gate violating API → exit 1, exact drifts
gate --json validates against report schema
gate 31 golden + mock-transport tests
README → source →
$ contractcheck petstore.yaml --json | jq .summary
{
"operations": 3,
"passed": 0, "failed": 3,
"violations": 4,
"conformant": false
}

Pure core: (spec, operation, response) → violations. No I/O — so every edge case is golden-tested.

INSTRUMENT 02 — LOCAL ENVIRONMENTS

DevBox

Spin up a full local dev environment from one config file — health-gated and reproducible.

Docker SDKYAMLtopological orderhealth-gatedclean teardown
gate topological order + cycle detection
gate real stack: up → healthy → seed → ready
gate down leaves no containers/volumes
gate --json status validates against schema
README → source →
$ devbox up -f devbox.yaml
· started db (postgres:16-alpine)
· db is healthy → seed → ready
· started app (redis:7-alpine)
· app is healthy → ready
✓ stack is up 2 ready · 0 failed

Pure resolver + health logic unit-tested without Docker; the orchestration is proven against a real Postgres + Redis stack.

INSTRUMENT 03 — CODEBASE HEALTH

CodeScope

X-ray a repo: complexity, coverage, churn × complexity hotspots, and a transparent debt score.

Tree-sitterPython + JScyclomatichotspotsReact dashboard
gate complexity == hand-verified values
gate debt + hotspot formulas deterministic
gate metrics JSON validates against schema
gate dashboard renders the produced JSON
live dashboard ↓ source →
$ codescope tools --coverage coverage.xml
DEBT score 37.3 / 100 grade B
LOC python 6,186 · javascript 40 · 65 files
HOT 1. imports.py cx 70
HOT 2. config.py cx 60

The debt formula is documented and transparent — no magic. Every metric is a tested pure function.

shared architecture

The same disciplined spine.

Every tool follows one pipeline: parse inputs into immutable models, compute in a pure I/O-free core, then render both a human view and a schema-validated machine view. That's what makes them testable, scriptable, and CI-ready.

01

Parse

Read the spec / config / source into frozen dataclasses. Clear errors on bad input.

→
02

Plan

Derive the work deterministically — requests, startup order, file walk.

→
03

Core

Pure functions do the thinking. No network, no disk — exhaustively golden-tested.

→
04

Report

Rich console output for humans; a --json view validated against its schema.

→
05

Exit

0 = green, non-zero = act. The verification gate that ends the loop.

codescope · live

A dashboard that renders real metrics.

This is CodeScope's React dashboard, fed the exact JSON the analyzer emits when pointed at this very monorepo — complexity, coverage, churn hotspots, dependency graph, and the transparent debt score.

codescope-dashboard — metrics.json
interactive