chore(docs): engineering docs test section validation - POC

[jaikamat]

This PR introduces a test-to-docs system where documentation test examples are automatically generated from real, executable test files.

The Problem

Test code examples in engineering documentation can become stale when component APIs change. Manually maintaining test examples in MDX files is error-prone and creates duplication.

The Solution

Inverted strategy: Tests live in .docs.spec.tsx files and are injected into documentation at build time.

How it works:

1. Write tests in .docs.spec.tsx files with JSDoc tags:

/**
 * @docs-section basic-rendering
 * @docs-title Basic Rendering Tests
 * @docs-description Verify the component renders with expected elements
 * @docs-order 1
 */
describe('Component - Basic rendering', () => {
  it('renders component', () => {
    render(
      <NimbusProvider>
        <Component />
      </NimbusProvider>
    );
    expect(screen.getByRole('button')).toBeInTheDocument();
  });
});

2. Add injection token in .dev.mdx:

## Testing your implementation

{{docs-tests: component.docs.spec.tsx}}

3. Build-time extraction:
   • TypeScript AST parser extracts tagged sections
   • Test code injected into MDX during docs build
   • Documentation always shows current, working tests

What's Included

Infrastructure

• ✅ TypeScript AST parser (packages/nimbus-docs-build/src/parsers/test-extractor.ts)
• ✅ Test section types (packages/nimbus-docs-build/src/types/test-section.ts)
• ✅ MDX token injection (packages/nimbus-docs-build/src/parsers/parse-mdx.ts)

Pilot Implementation

• ✅ TextInput .docs.spec.tsx with 5 test sections (14 tests - all passing)
• ✅ Updated text-input.dev.mdx with injection token
• ✅ Full transparency - shows complete code including <NimbusProvider> wrapping

Documentation

• ✅ Complete guide (docs/engineering-docs-validation.md)
• ✅ Updated component guidelines
• ✅ Updated /create-eng-docs slash command

Cleanup

• ✅ Removed old validation script
• ✅ Removed special CI step (tests run with normal test suite)
• ✅ Removed test:docs command

Benefits

✅ Single source of truth - Tests ARE the documentation examples
✅ Type-safe - TypeScript catches API changes in test files
✅ Normal workflow - Tests run with pnpm test, no special commands
✅ Always up-to-date - Documentation generated from working tests
✅ Full transparency - Shows complete code with provider setup
✅ Build-time validation - Missing/broken tests fail docs build
✅ IDE support - Full autocomplete and type checking in test files

Key Design Decision: Full Transparency

Documentation shows unmodified test code including all boilerplate:

• <NimbusProvider> wrapper visible in every example
• All imports shown (including NimbusProvider, ReactNode)
• No hidden abstractions or helper functions
• Consumers see exactly what they need to write

Technical Details

Dependencies added:

• @typescript-eslint/typescript-estree - TypeScript AST parser
• @typescript-eslint/types - AST type definitions

Build process:

1. MDX parser finds {{docs-tests: filename}} tokens
2. Locates companion .docs.spec.tsx file
3. Parses TypeScript AST with JSX support
4. Extracts describe() blocks with @docs-section JSDoc tags
5. Generates markdown sections with code blocks
6. Injects into MDX before runtime processing

Example Output

Test file (text-input.docs.spec.tsx):

describe("TextInput - Basic rendering", () => {
  it("renders input element", () => {
    render(
      <NimbusProvider>
        <TextInput placeholder="Enter text" />
      </NimbusProvider>
    );
    expect(screen.getByRole("textbox")).toBeInTheDocument();
  });
});

Generated documentation shows exactly the same code - no transformations, complete transparency.

Next Steps

• Expand to more components (Select, DatePicker, Menu, etc.)
• Create template for .docs.spec.tsx files
• Add to component creation workflow

[changeset-bot]

⚠️ No Changeset found

Latest commit: c521fe1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
nimbus-documentation	Ready	Preview	Comment	Nov 26, 2025 4:34pm
nimbus-storybook	Ready	Preview	Comment	Nov 26, 2025 4:34pm

[jaikamat]

This is the file that will extract the tests from the .docs.spec.tsx test files themselves

[ddouglasz]

I tried to follow the logic in this file, but there is a lot of AST data manipulation happening there, thanks for all for all the comments. Really helps to at least have a grasp of what each function does.

[jaikamat]

The changes here enable the extracted tests (below) to be built in the docs

[jaikamat]

This tag enables the mdx parser to inject the docs appropriately

[jaikamat]

JSDOC comments here allow us to formulate the transformed tests into documentation in a structured way.

[jaikamat]

Better to show consumers the actual boilerplate required to set up a test and be transparent, rather than abstracting the NimbusProvider away in some sort of custom renderProvider function that's out of these test's scopes.

[ddouglasz]

Immense work Jai! Thanks for the work put into this! 🙌🏽

[ddouglasz]

I tried to follow the logic in this file, but there is a lot of AST data manipulation happening there, thanks for all for all the comments. Really helps to at least have a grasp of what each function does.