A protocol and drop-in kit for web code that is correct, dense, accessible, and fast.
TypeScript is the foundational language; HTML, CSS, Tailwind CSS, and Astro complement it. The gate checks the source and the build output the browser receives.
Quick start · What you get · How it works · Status · Protocol · Harness · Changelog
Built by Hedronite. Structure adapted from Rust-TOPS and Go-TOPS.
CRAP scores use the 2007 Change Risk Anti-Patterns formula. This kit did not originate that metric.
Web-TOPS (Web Testing and Optimization Protocol Suite) is a protocol and drop-in kit for web work. TypeScript is the foundational language; HTML, CSS, Tailwind CSS, and Astro complement it. The gate is meant to check the source and the build output the browser receives.
The webtops CLI in this tree runs from source on Bun and gates this repository at tier 1, with native CRAP and StrykerJS mutation on the diff. The package is not published to npm.
| Plane | Pin | Where |
|---|---|---|
| Protocol | 0.3.0 | WEB_TOPS.md and PROTOCOL in src/config/protocol.ts |
| Package | 0.3.0, private | package.json. Not published to npm |
| GitHub release | v0.3.0 | Implements protocol 0.3.0 |
| Runtime | Bun >= 1.4.0; Node 22.23.4, 24.15.0, or 26 and later | package.json engines |
| TypeScript | 6.0.x | Pinned because typescript-eslint and @astrojs/check do not yet accept TypeScript 7. See §2 |
bun install --frozen-lockfile
bun src/cli/main.ts check
bun src/cli/main.ts gatecheck validates web-tops.yaml against the schema, then the semantic checks. gate runs hygiene, tests, coverage, CRAP, and mutation on the diff at tier 1. This repository's CI runs bun src/cli/main.ts gate --max-tier 1.
| Tooling you wire yourself | This kit today | |
|---|---|---|
| Contract | Docs and tests you arrange | Protocol 0.3.0, JSON Schemas, and profiles for five launch classes |
| Orchestrator | You sequence the commands | webtops init, check, gate, report, lock, doctor, version, survivors, baseline, run from source on Bun |
| CI on this repo | — | The one gate job in .github/workflows/web-tops.yml, on Linux and macOS |
The protocol's later layers, once they are on, check:
| Layer | Tools (pinned in §2) |
|---|---|
| Types and lint | TypeScript 6.0 (strict, erasableSyntaxOnly), type-aware typescript-eslint, astro check, Stylelint |
| Boundaries and packages | dependency-cruiser, publint, @arethetypeswrong/cli |
| Tests | Vitest with v8 coverage, one run; StrykerJS mutation on the diff |
| Risk | Native CRAP, one cap per class, ratcheted for adopters |
| What ships | html-validate and axe on built pages; JS and CSS bytes per page or route |
| Claim | Reality |
|---|---|
| An npm package | package.json is private. Install and run from this tree |
| Laws or build-output checks on this repo today | Those layers are off in web-tops.yaml, each with the milestone that turns it on. Native CRAP at cap 4 and StrykerJS mutation on the diff are on, with no unexplained survivors |
| A test framework or a design system | webtops runs Vitest, Playwright, Stryker, and related tools; it does not replace them, and it does not enforce an aesthetic |
The gate judges what ships: the browser receives HTML, CSS, and JavaScript, not .astro or .tsx. A layer that was not evaluated is reported as not evaluated, never as a pass.
| Path | Role |
|---|---|
WEB_TOPS.md |
The protocol, draft 0.3.0 |
schema/ |
web-tops.schema.json and gate-report.schema.json |
src/ |
The webtops CLI and the config, gate, init, lock, and report modules |
web-tops.yaml |
This repository's own config: class ts-library, enforce: hard |
config/AGENTS.md.tmpl |
The AGENTS.md section that webtops init will write into an adopting repo |
AGENTS.md |
Editing harness for this repository (CLAUDE.md imports it) |
Draft. Protocol 0.3.0; this tree implements it: one verdict set, the report shape, required layers and laws per class, and the protocol id checked by range. The package is version 0.3.0 (the 0.1.0 release implements 0.2.1): a GitHub release, private, not published to npm.
This repository has shipped milestones M1 and M2: the webtops CLI (init, check, gate, report, lock, doctor, version, survivors, baseline) runs from source on Bun and gates this repo on itself at tier 1, under enforce: hard, with native CRAP at cap 4 and StrykerJS mutation on the diff, no unexplained survivors, in the one gate job on Ubuntu and macOS. The laws layer and the build-output layers are off in web-tops.yaml, each with the milestone that turns it on. The package is not published to npm.
| Milestone | Contents |
|---|---|
| M0 | WEB_TOPS.md, schemas, profiles for five launch classes, the AGENTS template |
| M1 | init, check, gate: hygiene, tests, coverage, report.json; Web-TOPS gates itself |
| P3 | Protocol 0.3.0, the truth pass: one verdict set, required layers and laws per class, the report shape, risk definitions, the protocol id by range, ESLint 10 (this repo) |
| M2 | The risk engine, shipped: native CRAP, the Stryker adapter, the survivor ledger, baseline and ratchet; the kit runs CRAP and mutation on itself at hard |
| M3 | Laws v1: laws/W-NN.yaml, law fixtures, eslint-plugin-webtops, the non-lint readers, law-diff |
| M4 | Build output: HTML validity, links, page and route bytes, axe, size-limit per entry |
| M5 | Rendered interface and themes: reflow, focus, motion, theme contrast |
| M6 | Workspaces and adoption: the workspace-root and cli profiles, the adopter PRs |
| M7 | Calibration and 1.0 |
The full roadmap is in WEB_TOPS.md §19.
Read WEB_TOPS.md and AGENTS.md first. Work on a branch and open a draft PR. A change to laws, schema, profiles, thresholds, budgets, drop-in lint rules or normative spec text is a protocol change: it carries the protocol-change label, a changelog entry, and a protocol version bump.
Built by Hedronite. Structure adapted from Rust-TOPS and Go-TOPS. CRAP scores use the 2007 Change Risk Anti-Patterns formula (Savoia and Evans); this kit did not originate that metric.
Licensed under MIT OR Apache-2.0, at your option. See LICENSE, LICENSE-MIT, and LICENSE-APACHE.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
