Skip to content
HedronitePublic

About

Protocol and drop-in kit for web code that is correct, dense, accessible, and fast. TypeScript, HTML, CSS, Tailwind, Astro.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

367 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Web-TOPS

Web-TOPS product mark and wordmark

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.

TypeScript Hedronite Protocol 0.3.0 Release License: MIT OR Apache-2.0 CI workflow: web-tops

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.

Pins

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

Quick start

bun install --frozen-lockfile
bun src/cli/main.ts check
bun src/cli/main.ts gate

check 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.

What you get

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

What you do not get

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

How it works

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)

Status

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.

Related

  • Rust-TOPS: the original protocol.
  • Go-TOPS: the Go protocol. Web-TOPS starts from its 0.3.0 fixes.

Contributing

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.

Credits and license

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.

About

Protocol and drop-in kit for web code that is correct, dense, accessible, and fast. TypeScript, HTML, CSS, Tailwind, Astro.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages