Angular: Record per-component docgen baselines from built sandboxes

[valentinpalkovic]

Closes #

What I did

Angular docgen is currently tested against small components written to exercise the extractor. That misses the failures users actually hit, which only appear across a whole project: two components sharing a class name, a story importing one file while the docs render another, a component the tsconfig never covered.

This records what docgen produces for every component in a real sandbox and commits it, so a change to the extractor shows up as a reviewable diff.

How a baseline is captured

yarn task build --template angular-vite/docgen-server-ts
        │
        ▼
storybook-static/services/core/docgen/<component-id>.json   ← build-storybook already writes these
        │                                                      (one per component, needs both flags on)
        ▼
yarn baselines:sandbox --update
        │  · keep only portable DocgenPayload fields (drops the raw Compodoc entry, ~117KB of sourceCode)
        │  · rewrite absolute sandbox paths to <sandbox>
        │  · skip components referenced as globalThis.__TEMPLATE_COMPONENTS__.*
        ▼
src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/<component-id>.json   ← committed

A committed baseline is just the portable payload:

{
  "argTypes": {
    "aliasedUnionType": {
      "name": "aliasedUnionType",
      "description": "\nUnion Type assigned as a Type Alias",
      "table": { "category": "inputs", "type": { "summary": "TypeAlias", "required": true } },
      "type": { "name": "enum", "value": ["Type Alias 1", "Type Alias 2", "Type Alias 3"] }
    }
  },
  "id": "stories-frameworks-angular-vite-basics-component-with-enums-enums-component",
  "name": "EnumsComponent",
  "path": "./src/stories/.../enums.stories.ts"
}

37 components for the Angular sandbox: 30 documented, 7 Angular classes declared inline in story files that Compodoc does not scan. Recording the second group keeps that visible instead of silently absent.

Scripts introduced

Command	What it does
yarn baselines:sandbox	Verify every server-docgen sandbox against its committed baselines
yarn baselines:sandbox --update	Re-record after reviewing the diff
yarn baselines:sandbox --template <key>	Narrow to one template

Run from code/lib/docgen-harness. CI runs the verify form right after Build storybook.

What a failure looks like

Findings are split by severity, and both fail the run:

angular-vite/docgen-server-ts: docgen baselines drifted.
2 regression(s):
  - example-button [argtypes] size2: [lost-arg] recorded in the baseline but missing from the candidate
  - stale-component [component-removed] recorded in the baseline but absent from this build; the story may have been removed, or indexing dropped it
1 change(s):
  - example-page [component-added] not in the baseline; re-record to adopt it

regression means docgen got worse and wants a fix, not a re-record. change is neutral or better and is adopted with --update.

Which sandboxes are covered

Derived from the templates themselves rather than a list, so there is nothing to keep in sync:

export const enablesDocgenServer = (template: Template): boolean => {
  const features = mainConfigFeatures(template);
  return DOCGEN_SERVER_FEATURES.every((feature) => features?.[feature] === true);
};

Both experimentalDocgenServer and componentsManifest are required - without the second, nothing is written to disk. A template that is flagged but has nothing recorded fails rather than skipping quietly.

A new Angular sandbox

Server docgen had no end-to-end coverage because no sandbox enabled it. Rather than flip the existing Angular sandbox, which would stop it guarding today's browser docgen, this adds angular-vite/docgen-server-ts differing only by those two flags. It has been published to the sandboxes repository, so CI clones it like any other template.

It runs daily rather than every PR while the feature is experimental, and skips chromatic (and test-runner, which the job list otherwise swaps in when chromatic is skipped). After 11.0 the standard sandboxes ship this docgen approach by default, at which point this template is removed rather than kept.

A bug this found immediately

With server docgen on, build-storybook finished its work and then never exited - on CI a ten-minute no-output timeout rather than a failure. Attaching a message listener to a worker re-references its port, so unreferencing the docgen worker before its listeners were attached left it holding the event loop open:

  this.worker = new Worker(scriptPath);
- this.worker.unref();
  this.worker.on('message', (msg) => this.handleMessage(msg));
  // ... and the `ready` promise attaches another
+ this.worker.unref();

Only reachable with the feature enabled, which is why nothing caught it before.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

1. Build the sandbox: yarn task build --template angular-vite/docgen-server-ts --start-from auto. It should exit on its own; before the worker fix it hung here.
2. From code/lib/docgen-harness, run yarn baselines:sandbox. It should report baselines match.
3. Open any file under src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/ that has argTypes, delete one property, and re-run. It should fail, name that property, and label it a regression.
4. yarn baselines:sandbox --update to restore, then re-run to confirm it matches again.

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9ab24f10-ebeb-42bb-92ff-be36504f9791

📥 Commits

Reviewing files that changed from the base of the PR and between baa40a0 and 49adc42.

📒 Files selected for processing (7)

• AGENTS.md
• code/lib/cli-storybook/src/sandbox-templates.ts
• code/lib/docgen-harness/package.json
• code/lib/docgen-harness/src/sandbox-baselines/compare-baselines.ts
• code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.ts
• code/lib/docgen-harness/src/sandbox-baselines/run.ts
• scripts/ci/sandboxes.ts

🚧 Files skipped from review as they are similar to previous changes (6)

• code/lib/docgen-harness/package.json
• code/lib/docgen-harness/src/sandbox-baselines/compare-baselines.ts
• code/lib/docgen-harness/src/sandbox-baselines/run.ts
• scripts/ci/sandboxes.ts
• code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.ts
• code/lib/cli-storybook/src/sandbox-templates.ts

---

Walkthrough

The PR adds an Angular Vite server-docgen sandbox, baseline reading and comparison utilities, committed Angular docgen snapshots, and CI verification. It also moves docgen worker unref() after message listener registration.

Changes

Docgen worker lifecycle

Layer / File(s)	Summary
Listener registration ordering code/core/src/shared/open-service/services/docgen/worker/docgen-worker-client.ts, code/core/src/shared/open-service/services/docgen/worker/docgen-worker-client.test.ts	The worker calls unref() after registering message listeners. The test verifies this ordering.

Sandbox docgen baseline verification

Layer / File(s)	Summary
Angular Vite template discovery code/lib/cli-storybook/src/sandbox-templates.ts	Adds the Angular Vite server-docgen template, daily cadence entry, and feature-based template discovery.
Snapshot reading and normalization code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.ts, code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.test.ts	Reads static snapshots, filters global components, removes unstable fields, normalizes paths, and validates output.
Baseline comparison code/lib/docgen-harness/src/sandbox-baselines/compare-baselines.ts, code/lib/docgen-harness/src/sandbox-baselines/compare-baselines.test.ts	Compares components and argTypes, formats findings, and produces deterministic serialization.
Harness and CI integration code/lib/docgen-harness/src/sandbox-baselines/run.ts, code/lib/docgen-harness/package.json, scripts/ci/sandboxes.ts, scripts/knip.config.ts, AGENTS.md, code/lib/docgen-harness/src/sandbox-baselines/README.md	Adds baseline commands, update and verification flows, CI execution, Knip registration, and documentation.
Angular Vite baseline fixtures code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/*	Adds generated documentation and error baselines for Angular components and stories.

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant SandboxBuild
  participant BaselineRunner
  participant SnapshotReader
  participant Comparator
  CI->>SandboxBuild: Build Angular Vite sandbox
  CI->>BaselineRunner: Run baselines:sandbox
  BaselineRunner->>SnapshotReader: Read generated snapshots
  SnapshotReader-->>BaselineRunner: Return normalized baselines
  BaselineRunner->>Comparator: Compare committed fixtures
  Comparator-->>CI: Return findings and exit status

Loading

Possibly related PRs

• storybookjs/storybook#35548: Extends the docgen harness with Angular baseline infrastructure.
• storybookjs/storybook#35733: Adds Angular Vite server-docgen functionality covered by these baselines.
• storybookjs/storybook#35796: Concerns Angular server-side docgen and its sandbox baselines.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (5)

code/core/src/shared/open-service/services/docgen/worker/docgen-worker-client.test.ts (1)

105-110: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Assert that all message listeners are registered before unref().

The constructor currently registers two message listeners. toBeGreaterThan(0) also passes if unref() runs after only the first listener. Assert toBe(2) so the test detects that ordering regression.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@code/core/src/shared/open-service/services/docgen/worker/docgen-worker-client.test.ts`
around lines 105 - 110, Update the assertion on worker.messageListenersAtUnref
in the worker client test to require exactly two registered message listeners
with toBe(2), ensuring both constructor listeners are attached before unref()
executes.

code/lib/docgen-harness/package.json (1)

29-29: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Run the new runner with native Node.

-    "baselines:sandbox": "node --import jiti/register ./src/sandbox-baselines/run.ts",
+    "baselines:sandbox": "node ./src/sandbox-baselines/run.ts",

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@code/lib/docgen-harness/package.json` at line 29, Update the
baselines:sandbox script to invoke the new runner using native Node without the
jiti/register import, while preserving the existing src/sandbox-baselines/run.ts
entry point.

Source: Coding guidelines

code/lib/docgen-harness/src/sandbox-baselines/compare-baselines.ts (1)

26-41: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Sort keys by code unit, not by locale.

stableStringify serializes the committed baseline files. localeCompare without an explicit locale uses the host default locale and ICU version, so key order can differ between a developer machine and CI. That produces a re-record diff that reflects the environment rather than the content.

Use a code-unit comparison so the output is byte-identical everywhere.

♻️ Proposed deterministic sort

       return Object.fromEntries(
         Object.entries(input)
-          .sort(([a], [b]) => a.localeCompare(b))
+          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
           .map(([key, item]) => [key, sortKeys(item)])
       );

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@code/lib/docgen-harness/src/sandbox-baselines/compare-baselines.ts` around
lines 26 - 41, Update the key comparator in stableStringify’s sortKeys
implementation to use deterministic code-unit ordering instead of localeCompare.
Preserve the recursive array/object traversal and JSON.stringify behavior while
ensuring identical key order across environments.

code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.ts (1)

84-85: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert the snapshot shape at the parse boundary.

Line 119 casts parsed JSON without validation. toBaseline then omits any field whose value is undefined. If a snapshot omits name, line 85 throws TypeError: Cannot read properties of undefined (reading 'startsWith'), and the message does not name the file or the component id.

Add a cheap assertion next to the parse so a malformed snapshot fails at the source with the file path.

♻️ Proposed boundary assertion

     for (const [id, payload] of Object.entries(components ?? {})) {
+      if (typeof payload?.name !== 'string') {
+        // eslint-disable-next-line local-rules/no-uncategorized-errors
+        throw new Error(`Snapshot ${path} holds a component (${id}) without a name.`);
+      }
       const baseline = toBaseline(payload, sandboxDir);

As per coding guidelines: "Encode assumptions with TypeScript types and existing lint rules when possible; otherwise add a cheap runtime assertion close to the relevant boundary so violations fail at the source."

Also applies to: 119-121

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.ts` around
lines 84 - 85, Validate the parsed snapshot immediately at the JSON parse
boundary before the cast or call toBaseline, asserting that required fields such
as name are present and reporting the snapshot file path and component id in the
failure. Keep isGloballyReferenced unchanged, while ensuring malformed snapshots
fail during parsing rather than later at name.startsWith.

Source: Coding guidelines

code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.test.ts (1)

8-11: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use the memfs spy-redirection pattern.

Replace the async factory mock with vi.mock('node:fs', { spy: true }). Redirect readdirSync and readFileSync with vi.mocked(...) in beforeEach.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.test.ts`
around lines 8 - 11, Replace the async `vi.mock('node:fs', ...)` factory with
the `{ spy: true }` mock form. In the test setup’s `beforeEach`, redirect
`readdirSync` and `readFileSync` using `vi.mocked(...)` and the existing memfs
implementations, preserving the current filesystem behavior.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In
`@code/core/src/shared/open-service/services/docgen/worker/docgen-worker-client.test.ts`:
- Around line 105-110: Update the assertion on worker.messageListenersAtUnref in
the worker client test to require exactly two registered message listeners with
toBe(2), ensuring both constructor listeners are attached before unref()
executes.

In `@code/lib/docgen-harness/package.json`:
- Line 29: Update the baselines:sandbox script to invoke the new runner using
native Node without the jiti/register import, while preserving the existing
src/sandbox-baselines/run.ts entry point.

In `@code/lib/docgen-harness/src/sandbox-baselines/compare-baselines.ts`:
- Around line 26-41: Update the key comparator in stableStringify’s sortKeys
implementation to use deterministic code-unit ordering instead of localeCompare.
Preserve the recursive array/object traversal and JSON.stringify behavior while
ensuring identical key order across environments.

In `@code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.test.ts`:
- Around line 8-11: Replace the async `vi.mock('node:fs', ...)` factory with the
`{ spy: true }` mock form. In the test setup’s `beforeEach`, redirect
`readdirSync` and `readFileSync` using `vi.mocked(...)` and the existing memfs
implementations, preserving the current filesystem behavior.

In `@code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.ts`:
- Around line 84-85: Validate the parsed snapshot immediately at the JSON parse
boundary before the cast or call toBaseline, asserting that required fields such
as name are present and reporting the snapshot file path and component id in the
failure. Keep isGloballyReferenced unchanged, while ensuring malformed snapshots
fail during parsing rather than later at name.startsWith.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 86af213a-7921-4873-ad33-f154f3fbc3ee

📥 Commits

Reviewing files that changed from the base of the PR and between 98fb332 and 90c110a.

📒 Files selected for processing (50)

• AGENTS.md
• code/core/src/shared/open-service/services/docgen/worker/docgen-worker-client.test.ts
• code/core/src/shared/open-service/services/docgen/worker/docgen-worker-client.ts
• code/lib/cli-storybook/src/sandbox-templates.ts
• code/lib/docgen-harness/package.json
• code/lib/docgen-harness/src/sandbox-baselines/README.md
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/example-button.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/example-header.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/example-page.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-argtypes-doc-button.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-argtypes-doc-directive.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-argtypes-doc-injectable.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-argtypes-doc-pipe.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-angular-forms-customcontrolvalueaccessor-custom-cva-component.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-complex-selectors-attribute-selectors-component.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-complex-selectors-class-selector-component.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-complex-selectors-multiple-class-selector-component.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-complex-selectors-multiple-selector-component.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-enums-enums-component.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-inheritance-base-button.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-inheritance-icon-button.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-ng-content-ng-content-about-parent.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-ng-content-ng-content-simple.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-ng-on-destroy-component-with-on-destroy.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-on-push-on-push.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-pipe-custom-pipes.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-provider-di-component.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-style-styled-component.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-with-template-template.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-without-selector-without-selector-ng-component-outlet.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-component-without-selector-without-selector.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-ng-module-import-module-chip.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-ng-module-import-module-for-root.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-basics-ng-module-import-module.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-core-decorators-componentwrapperdecorator-decorators.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-core-decorators-theme-decorator-decorators.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-core-modulemetadata-in-export-default.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-core-modulemetadata-in-stories.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-core-modulemetadata-merge-default-and-story.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-core-parameters-bootstrap-options.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-core-styles-story-styles.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-others-app-initializer-use-factory.json
• code/lib/docgen-harness/src/sandbox-baselines/__baselines__/angular-vite-docgen-server-ts/stories-frameworks-angular-vite-others-issues-12009-unknown-component.json
• code/lib/docgen-harness/src/sandbox-baselines/compare-baselines.test.ts
• code/lib/docgen-harness/src/sandbox-baselines/compare-baselines.ts
• code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.test.ts
• code/lib/docgen-harness/src/sandbox-baselines/read-static-docgen.ts
• code/lib/docgen-harness/src/sandbox-baselines/run.ts
• scripts/ci/sandboxes.ts
• scripts/knip.config.ts

[storybook-app-bot]

Package Benchmarks

^{Commit: 49adc42, ran on 10 August 2026 at 20:47:36 UTC}

No significant changes detected, all good. 👏