Skip to main content
Welcome. This site supports keyboard navigation and screen readers. Press ? at any time for keyboard shortcuts. Press [ to focus the sidebar, ] to focus the content. High-contrast themes are available via the toolbar.
serard@dev00:~/cv

Onboarding Typed Specifications

From Zero to Compiler-Verified Features

A seven-part series documenting how a personal CV website evolved through four phases — SPA, static generation, multi-layer testing, and typed specifications — until the compiler itself could answer: "Is every feature tested?"

Written for developers and architects who want to add typed specifications to an existing project, not greenfield.

Table of Contents

Part I: Why Typed Specifications

644 tests, 20 features, 112 acceptance criteria — and no way to answer "is feature X fully tested?" The gap between "tests pass" and "features are verified," and what the end state looks like when the compiler closes it.

Part II: Building the Foundation

You can't specify what you can't test, and you can't test what you can't render deterministically. How the SPA gave us features worth specifying, and how static generation gave us output worth testing.

Part III: Multi-Layer Quality

Six test layers — unit, property-based, E2E, visual regression, accessibility, performance — each catching different classes of bugs. Coverage gates as ratchets. The moment we realized: tests exist, but the link to features is informal.

Part IV: Features as Abstract Classes

A feature is not a Jira ticket. It's an abstract class. An acceptance criterion is not a bullet point. It's an abstract method. The type system becomes the specification language.

Part V: The Decorator Chain

@FeatureTest, @Implements, @Exclude — three decorators that link every test to the feature it verifies. TypeScript's keyof T catches typos at compile time. The glue between specification and verification.

Part VI: The Compliance Scanner

A 300-line TypeScript scanner that reads feature definitions, scans test files for decorator references, cross-references the two, and produces a coverage matrix. Quality gates that fail the build. The self-referential loop: the requirements tracking feature tracks itself.

Part VII: V2 Roadmap

What's next: local workflow integration, pre-commit hooks, historical trend tracking, reverse mapping, ESLint enforcement, and dynamic test granularity. The gaps that remain and how to close them.

How to Read This Series

Developers adding specs to an existing project should read Parts I-III to understand why the foundation matters, then jump to Parts IV-V for the implementation pattern.

Architects evaluating the approach should read Parts I, IV, and VI for the design philosophy and compliance model.

QA engineers should focus on Parts III, V, and VI for the testing chain and compliance scanner.

Anyone in a hurry should read Part I (the problem) and Part V (the solution) — the rest is context and depth.

Prerequisites

  • TypeScript with experimentalDecorators enabled
  • A test framework (Playwright, Vitest, Jest — any will work)
  • A project with features worth specifying (this is not about hello-world)

Related Posts

This series builds on and references: