Keep worked examples checked against the code
An example can still be present in a guide after the API it demonstrates has changed. A source link alone does not show that the example remains valid.
Wildo checks that example files stay within compiler coverage. It also checks the required connection between executable examples and their tests, so those samples have an explicit place to verify their behavior.
Example — Notice a changed seed contract
A seeding example can compile yet pass an invalid combination to a validating factory. Its runtime test imports the example and checks the constructed declaration, covering a different risk from a missing TypeScript field.
For engineers
Run the example checks in the framework workspace
# Verify the checker against its own fixtures.
pnpm run check:example-drift -- --self-test
# Check coverage, dedicated example compilation and required test links.
pnpm run check:example-drift
The command has distinct responsibilities:
| Check | What it establishes |
|---|---|
| Compiler coverage | The example belongs to a typecheck program |
| Dedicated example compilation | Diagnostics are checked for examples with a dedicated configuration |
| Required runtime-test import | An executable anchored example has the expected test connection |
Examples admitted by an ordinary package configuration rely on that package’s typecheck. The runtime-test import check is static: it does not execute the test suite. Run the owning tests to establish their behavior.
Test a constructed sample
These selected tests come from the data-seeding example’s contract test. The surrounding test suite imports the actual systemEmailTemplatesSeed example:
it('constructs through the real factory', () => {
expect(systemEmailTemplatesSeed.seedKey).toBe('system-emails:welcome');
expect(systemEmailTemplatesSeed.mode).toBe(DataSeedMode.UPGRADE);
expect(systemEmailTemplatesSeed.scope.kind).toBe(DataSeedScopeKind.APPLICATION);
});
it('declares a non-empty managedFields, which UPGRADE requires', () => {
expect(systemEmailTemplatesSeed.managedFields).toEqual(['subject', 'bodyHtml']);
});
Importing the sample reaches its real factory construction. The assertions then pin the mode, scope and managed fields the example is intended to teach. This is useful for executable examples whose validity is partly enforced at runtime.
Keep the proof with the sample
When changing an example, preserve its compiler inclusion and the appropriate runtime test. A green structural audit proves its reference can be resolved; compiler and executed test results establish additional, separate evidence about its use.