Requirements as Code in TypeScript: A Type-Safe Chain on a Live Website📋

requirements/
├── base.ts              ← Feature abstract class, Priority enum, ACResult type
├── decorators.ts        ← @FeatureTest, @Implements, @Exclude
├── features/
│   ├── navigation.ts    ← 8 abstract AC methods
│   ├── scroll-spy.ts    ← 7 abstract AC methods
│   ├── search.ts        ← 5 abstract AC methods
│   ├── ... (20 files)
│   └── req-track.ts     ← 7 ACs (self-tracking)
└── index.ts             ← Re-exports everything

test/
├── e2e/*.spec.ts        ← @FeatureTest(Feature) + @Implements<Feature>('ac')
├── unit/*.test.ts        ← Same pattern
├── a11y/*.spec.ts        ← coversACs for dynamic tests
├── visual/*.spec.ts      ← coversACs for dynamic tests
└── perf/*.spec.ts        ← @Implements on each test

scripts/
└── compliance-report.ts  ← Scanner + quality gate

// requirements/base.ts
export enum Priority { Critical = 'critical', High = 'high', Medium = 'medium', Low = 'low' }

export interface ACResult {
  satisfied: boolean;
  reason?: string;
}

export abstract class Feature {
  abstract readonly id: string;
  abstract readonly title: string;
  abstract readonly priority: Priority;
}

// requirements/features/navigation.ts
export abstract class NavigationFeature extends Feature {
  readonly id = 'NAV';
  readonly title = 'SPA Navigation + Deep Links';
  readonly priority = Priority.Critical;

  /** Clicking a TOC entry loads the corresponding page. */
  abstract tocClickLoadsPage(): ACResult;
  /** The browser back button restores the previous page state. */
  abstract backButtonRestores(): ACResult;
  /** The active navigation item is visually highlighted. */
  abstract activeItemHighlights(): ACResult;
  /** Clicking an anchor link scrolls smoothly to the target. */
  abstract anchorScrollsSmoothly(): ACResult;
  /** Navigating directly to a URL loads the correct page. */
  abstract directUrlLoads(): ACResult;
  /** Pressing F5 reloads the page and preserves the current view. */
  abstract f5ReloadPreserves(): ACResult;
  /** Deep links resolve to the correct section within a page. */
  abstract deepLinkLoads(): ACResult;
  /** Every page state produces a bookmarkable URL. */
  abstract bookmarkableUrl(): ACResult;
}

// requirements/decorators.ts

/** Link a test class to a Feature. */
export function FeatureTest<T extends abstract new (...args: any[]) => Feature>(feature: T) {
  return function <C extends new (...args: any[]) => any>(target: C): C {
    (target as any).__feature = feature.name;
    return target;
  };
}

/** Link a test method to an acceptance criterion.
 *  The AC name must be keyof T — compiler catches typos. */
export function Implements<T extends Feature>(ac: keyof T & string) {
  return function (target: any, propertyKey: string, _descriptor: PropertyDescriptor): void {
    registry.push({ feature: '', ac, testClass: target.constructor.name, testMethod: propertyKey });
  };
}

/** Exclude a helper method from requirement scanning. */
export function Exclude() {
  return function (target: any, propertyKey: string, _descriptor: PropertyDescriptor): void {
    excludedMethods.add(`${target.constructor.name}.${propertyKey}`);
  };
}

// ✅ Compiles: 'tocClickLoadsPage' exists on NavigationFeature
@Implements<NavigationFeature>('tocClickLoadsPage')

// ❌ Compile error: 'tocClickLoadsPagee' is not assignable to keyof NavigationFeature
@Implements<NavigationFeature>('tocClickLoadsPagee')

// ❌ Compile error: 'neverThrows' does not exist on NavigationFeature
@Implements<NavigationFeature>('neverThrows')

// test/e2e/navigation.spec.ts
@FeatureTest(NavigationFeature)
class NavigationTests {

  @Exclude()
  private async waitForReady(page: Page): Promise<void> {
    await page.goto('/');
    await page.waitForLoadState('networkidle');
    await page.waitForTimeout(1500);
  }

  @Implements<NavigationFeature>('tocClickLoadsPage')
  async 'clicking TOC item loads page with fade transition'({ page }: { page: Page }): Promise<void> {
    await this.waitForReady(page);
    await page.click('.toc-item[data-path="content/blog/binary-wrapper.md"]');
    await page.waitForTimeout(500);
    await expect(page.locator('#markdown-output h1')).toContainText('BinaryWrapper');
    expect(page.url()).toContain('binary-wrapper');
  }

  @Implements<NavigationFeature>('backButtonRestores')
  async 'back button returns to previous page'({ page }: { page: Page }): Promise<void> {
    await this.waitForReady(page);
    // navigate to page A, then page B, then back
    await page.click('.toc-item[data-path="content/blog/binary-wrapper.md"]');
    await page.waitForTimeout(500);
    await page.click('.toc-item[data-path="content/skills.md"]');
    await page.waitForTimeout(500);
    await page.goBack();
    await page.waitForTimeout(1000);
    await expect(page.locator('#markdown-output h1')).toContainText('BinaryWrapper');
  }
}

// Register class methods as Playwright tests
const instance = new NavigationTests();
for (const method of Object.getOwnPropertyNames(NavigationTests.prototype)) {
  if (method === 'constructor' || method === 'waitForReady') continue;
  test(method, async ({ page }) => {
    await (instance as unknown as Record<string, Function>)[method]!({ page });
  });
}

// test/unit/slugify.test.ts
@FeatureTest(SlugifyFeature)
class SlugifyTests {

  @Implements<SlugifyFeature>('stripsHtmlMarkdownSpecialChars')
  'lowercases and replaces spaces'() {
    expect(slugify('Hello World')).toBe('hello-world');
  }

  @Implements<SlugifyFeature>('hierarchicalNesting')
  'h2 nests under h1'() {
    const parentSlugs: Record<number, string> = {};
    const slugCount: Record<string, number> = {};
    buildHierarchicalSlug('Root', 1, parentSlugs, slugCount);
    expect(buildHierarchicalSlug('Child', 2, parentSlugs, slugCount)).toBe('root--child');
  }

  @Implements<SlugifyFeature>('deduplicatesSlugs')
  'handles duplicate slugs'() {
    const p: Record<number, string> = {};
    const c: Record<string, number> = {};
    buildHierarchicalSlug('Root', 1, p, c);
    const s1 = buildHierarchicalSlug('Same', 2, p, c);
    const s2 = buildHierarchicalSlug('Same', 2, p, c);
    expect(s1).toBe('root--same');
    expect(s2).toBe('root--same-1');
  }
}

// test/visual/pages.spec.ts
@FeatureTest(VisualRegressionFeature)
class VisualTests {
  static readonly coversACs: (keyof VisualRegressionFeature)[] = [
    'desktopBaselinesMatch', 'mobileBaselinesMatch',
    'componentScreenshotsMatch', 'toleranceThresholdsCorrect'
  ];
}

// 176 tests generated dynamically from sitemap
for (const theme of themes) {
  for (const pagePath of pages) {
    test(`${pageSlug} [${theme.name}]`, async ({ page }) => {
      await applyTheme(page, theme);
      await expect(page).toHaveScreenshot(screenshotName, { fullPage: true });
    });
  }
}

$ npx tsx scripts/compliance-report.ts

  ── Feature Compliance Report ──

  ✓ NAV          SPA Navigation + Deep Links         8/8 ACs (100%)
  ✓ SPY          Scroll Spy                          7/7 ACs (100%)
  ✓ BUILD        Static Build Pipeline               13/13 ACs (100%)
  ✓ REQ-TRACK    Requirements Tracking System        7/7 ACs (100%)
  ...all 20 features at 100%...

  Coverage: 112/112 ACs (100%)
  Critical uncovered: 0
  Quality gate: PASS

// requirements/features/req-track.ts
export abstract class RequirementsTrackingFeature extends Feature {
  readonly id = 'REQ-TRACK';
  readonly title = 'Requirements Tracking System';
  readonly priority = Priority.Critical;

  abstract featureDefinitionsCompile(): ACResult;
  abstract everyFeatureHasTest(): ACResult;
  abstract scannerGeneratesJson(): ACResult;
  abstract scannerGeneratesConsole(): ACResult;
  abstract qualityGateFailsOnGap(): ACResult;
  abstract eslintFlagsMissingDecorator(): ACResult;
  abstract selfAppearsInReport(): ACResult;
}

REQ-TRACK (7 ACs)
    ├── AC-6: "REQ-TRACK itself appears in report at 100%"
    │         ↓
    │   test: 'REQ-TRACK is listed in compliance report at 100%'
    │         ↓
    │   @Implements<RequirementsTrackingFeature>('selfAppearsInReport')
    │         ↓
    │   scanner finds this test → links to REQ-TRACK AC-6
    │         ↓
    │   report shows REQ-TRACK: 7/7 ✓
    │         ↓
    │   test reads report → asserts 7/7 → passes
    │         ↓
    └── ✓ The system verified itself

// test/unit/compliance.test.ts
@Implements<RequirementsTrackingFeature>('selfAppearsInReport')
'REQ-TRACK is listed in compliance report at 100%'() {
  const json = execSync('npx tsx scripts/compliance-report.ts --json',
    { cwd: ROOT, encoding: 'utf8', stdio: 'pipe' });
  const report = JSON.parse(json);
  const reqTrack = report.features.find((f: any) => f.id === 'REQ-TRACK');
  expect(reqTrack).toBeDefined();
  expect(reqTrack.percentage).toBe(100);
}

// 1. Define the feature
// requirements/features/my-feature.ts
export abstract class MyFeature extends Feature {
  readonly id = 'MY';
  readonly title = 'My New Feature';
  readonly priority = Priority.High;

  abstract userCanDoX(): ACResult;
  abstract systemHandlesY(): ACResult;
}

// 2. Write decorated tests
// test/e2e/my-feature.spec.ts
@FeatureTest(MyFeature)
class MyFeatureTests {
  @Implements<MyFeature>('userCanDoX')
  async 'user can do X'({ page }: { page: Page }): Promise<void> { ... }

  @Implements<MyFeature>('systemHandlesY')
  async 'system handles Y'({ page }: { page: Page }): Promise<void> { ... }
}

// 3. Check compliance
// $ npx tsx scripts/compliance-report.ts
//   ✓ MY  My New Feature  2/2 ACs (100%)