📝 Add index pages for documentation sections by dubzzz · Pull Request #6845 · dubzzz/fast-check

dubzzz · 2026-04-11T22:02:42Z

Description

Adds a landing/index page to every documentation category that previously had none, using the same index.md + <DocCardList /> pattern that the tutorials/ section already uses. Each new page carries a specific cross-cutting insight (arbitraries pipeline, canonical shrink targets, two-level configuration model, …) instead of rephrasing its children — <DocCardList /> handles the child listing automatically.

The migration/ category has only one guide today; rather than adding a boilerplate landing page, its _category_.json is re-pointed directly at from-3.x-to-4.x so clicking the sidebar category opens the guide.

New files (10):

website/docs/introduction/index.md
website/docs/core-blocks/index.md
website/docs/core-blocks/arbitraries/index.md
website/docs/core-blocks/arbitraries/primitives/index.md
website/docs/core-blocks/arbitraries/composites/index.md
website/docs/core-blocks/arbitraries/combiners/index.md
website/docs/core-blocks/arbitraries/fake-data/index.md
website/docs/configuration/index.md
website/docs/advanced/index.md
website/docs/tutorials/quick-start/index.md

Modified (1):

website/docs/migration/_category_.json — added link: { type: "doc", id: "migration/from-3.x-to-4.x" }

Verified locally with pnpm exec docusaurus build: every new URL renders with breadcrumb, H1, prose, and the child DocCardList cards. No broken links or slug conflicts.

Checklist

— Don't delete this checklist and make sure you do the following before opening the PR

I have a full understanding of every line in this PR — whether the code was hand-written, AI-generated, copied from external sources or produced by any other tool
I flagged the impact of my change (minor / patch / major) either by running pnpm run bump or by following the instructions from the changeset bot
I kept this PR focused on a single concern and did not bundle unrelated changes
I followed the gitmoji specification for the name of the PR, including the package scope (e.g. 🐛(vitest) Something...) when the change targets a package other than fast-check
I added relevant tests and they would have failed without my PR (when applicable)

Adds a landing page to every doc category that previously had none, using the same `index.md` + `<DocCardList />` pattern as the tutorials section. Each page carries a specific cross-cutting insight (arbitraries pipeline, shrink targets, two-level configuration model, ...) rather than rephrasing its children. The migration category has only one guide, so its `_category_.json` is re-pointed directly at that guide instead of adding a boilerplate index.

changeset-bot · 2026-04-11T22:02:47Z

⚠️ No Changeset found

Latest commit: 549a7cc

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

github-actions · 2026-04-11T22:02:51Z

👋 It looks like the PR template was not used for this pull request.

Please edit the PR description to use the template, or close this PR and open a new one that uses it.
Not using the template may result in your change not being reviewed.

The template includes:

A Description section
A Checklist section with items to verify before submitting

Thank you for your contribution! 🙏

pkg-pr-new · 2026-04-11T22:04:32Z

@fast-check/examples

@fast-check/ava

npm i https://pkg.pr.new/@fast-check/ava@6845

fast-check

npm i https://pkg.pr.new/fast-check@6845

@fast-check/jest

npm i https://pkg.pr.new/@fast-check/jest@6845

@fast-check/packaged

npm i https://pkg.pr.new/@fast-check/packaged@6845

@fast-check/poisoning

npm i https://pkg.pr.new/@fast-check/poisoning@6845

@fast-check/vitest

npm i https://pkg.pr.new/@fast-check/vitest@6845

@fast-check/worker

npm i https://pkg.pr.new/@fast-check/worker@6845

commit: 549a7cc

Converts `*italic*` to `_italic_` per the repo's prettier config.

dubzzz · 2026-04-28T21:02:59Z

@claude do we still need the category.json if we have the index pages? if not drop them

claude · 2026-04-28T21:03:24Z

Claude finished @dubzzz's task in 7m 24s —— View job

Done — `_category_.json` files dropped where redundant

Short answer: No, you don't need them anymore for the 10 categories that now have an index.md. Kept only migration/_category_.json (no index page, the link is what makes the category navigable).

Why it works in Docusaurus 3.9.2 — from @docusaurus/plugin-content-docs/lib/sidebars/generator.js, when a category has an index doc the resolution order is:

label    = _category_.json.label    ?? indexDoc.frontMatter.sidebar_label ?? indexDoc.title (H1) ?? folderName
position = _category_.json.position ?? indexDoc.frontMatter.sidebar_position ?? folder number prefix

So both fields fall back to the index doc, making _category_.json redundant once we put sidebar_position in the index frontmatter (the H1 already covered the label).

What was applied (commit 8370cf7 — turns out an earlier run had already made the identical change, so my second commit was auto-dropped during rebase):

Updated sidebar_position in each new index.md to match the previous _category_.json position (introduction→1, core-blocks→2, configuration→3, advanced→4, arbitraries→1, primitives→1, composites→2, combiners→3, fake-data→4, quick-start→1).
Deleted the 10 redundant _category_.json files.
Kept website/docs/migration/_category_.json — it has no index doc and its link: { type: doc, ... } is the only thing pointing the sidebar entry at from-3.x-to-4.x.

Verification: the full pnpm run build requires Node 22 (the prebuild image-optimizer uses fs.promises.glob); this runner has Node 20. Instead, I ran the Docusaurus sidebar generator directly against the repo state — every category resolves to the right label and the items keep their original order: Introduction → Core Blocks → Configuration → Advanced → Tutorials → Ecosystem → AI-Powered Testing → Migration Guides → Support us. Same pattern the existing tutorials/, tutorials/setting-up-your-test-environment/ and tutorials/detect-race-conditions/ folders have been using in production.
• Branch: claude/add-category-introductions-jtE7i

Co-authored-by: Nicolas DUBIEN <[email protected]>

With index.md pages in each category, the _category_.json files are no longer needed — sidebar_position in the index frontmatter replaces the category position and the H1 replaces the label. Moves each position value into the corresponding index.md and deletes the 10 redundant _category_.json files. Keeps migration/_category_.json (no index page there). Also applies review feedback: drop Oxford commas and unnecessary bold/italic formatting in configuration/index.md.

dubzzz · 2026-04-28T21:07:51Z

+Combiners are the only arbitraries in fast-check that do not generate anything on their own. They take one or more existing arbitraries as input and return a new one — they are the functional glue that lets a handful of primitives and composites cover the full space of values a real codebase cares about.
+
+You will reach for a combiner whenever you want to:
+
+- **promote plain values** into the arbitrary world (`constant`, `constantFrom`),
+- **choose between alternatives** (`oneof`, `option`),
+- **tie arbitraries together recursively** (`letrec`) to generate trees, ASTs, or JSON-like structures,
+- **refine or transform** an existing arbitrary with `.filter`, `.map`, `.chain`, or adjust its shrinking with `noShrink` / `limitShrink`.
+
+Because every combiner wraps another arbitrary, shrinking composes too: the combiner preserves (or deliberately limits) the shrink behaviour of the arbitrary it wraps, so a counterexample through `oneof(...).map(...)` still collapses toward the simple values defined by the innermost primitive.


Suggested change

Combiners are the only arbitraries in fast-check that do not generate anything on their own. They take one or more existing arbitraries as input and return a new one — they are the functional glue that lets a handful of primitives and composites cover the full space of values a real codebase cares about.

You will reach for a combiner whenever you want to:

- **promote plain values** into the arbitrary world (`constant`, `constantFrom`),

- **choose between alternatives** (`oneof`, `option`),

- **tie arbitraries together recursively** (`letrec`) to generate trees, ASTs, or JSON-like structures,

- **refine or transform** an existing arbitrary with `.filter`, `.map`, `.chain`, or adjust its shrinking with `noShrink` / `limitShrink`.

Because every combiner wraps another arbitrary, shrinking composes too: the combiner preserves (or deliberately limits) the shrink behaviour of the arbitrary it wraps, so a counterexample through `oneof(...).map(...)` still collapses toward the simple values defined by the innermost primitive.

Combiners are the only arbitraries in fast-check that do not generate anything on their own. They take one or more existing arbitraries as input and return a new one. They are the functional glue that lets a handful of primitives and composites cover the full space of values a real codebase cares about.

You will reach for a combiner whenever you want to:

- **promote plain values** into the arbitrary world (`constant`, `constantFrom`),

- **choose between alternatives** (`oneof`, `option`),

- **tie arbitraries together recursively** (`letrec`) to generate trees, ASTs or JSON-like structures,

- **refine or transform** an existing arbitrary with `.filter`, `.map`, `.chain`, or adjust its shrinking with `noShrink` / `limitShrink`.

Because every combiner wraps another arbitrary, shrinking composes too: the combiner preserves (or deliberately limits) the shrink behaviour of the arbitrary it wraps, so a counterexample through `oneof(...).map(...)` still collapses toward the simple values defined by the innermost primitive.

Split em-dash run-on into two sentences, drop Oxford comma.

dubzzz · 2026-04-28T21:11:25Z

+
+# Composites
+
+Composite arbitraries take other arbitraries as input and assemble them into structured values. An `array` is built from an arbitrary for its elements, a `record` is built from arbitraries for each of its fields, and so on — there is no "random structure" to speak of, only a shape you describe and a child arbitrary that fills it.


Suggested change

Composite arbitraries take other arbitraries as input and assemble them into structured values. An `array` is built from an arbitrary for its elements, a `record` is built from arbitraries for each of its fields, and so on — there is no "random structure" to speak of, only a shape you describe and a child arbitrary that fills it.

Composite arbitraries take other arbitraries as input and assemble them into structured values. An `array` is built from an arbitrary for its elements, a `record` is built from arbitraries for each of its fields and so on. There is no "random structure" to speak of, only a shape you describe and a child arbitrary that fills it.

Split em-dash run-on into two sentences, drop Oxford comma.

dubzzz · 2026-04-28T21:12:42Z

+
+Two concepts recur on every page in this section and are worth learning once:
+
+- **Size control.** Most composites accept `minLength` / `maxLength` bounds and a `size` modifier that scales how large generated values tend to be in practice (see [`size` explained](/docs/configuration/larger-entries-by-default/#size-explained)). These are the main knobs to keep generation costs under control when your children are themselves expensive.


Suggested change

- **Size control.** Most composites accept `minLength` / `maxLength` bounds and a `size` modifier that scales how large generated values tend to be in practice (see [`size` explained](/docs/configuration/larger-entries-by-default/#size-explained)). These are the main knobs to keep generation costs under control when your children are themselves expensive.

- **Size control.** Most composites accept `minLength` / `maxLength` bounds and a `size` modifier that scales how large generated values tend to be in practice (see [`size` explained](/docs/configuration/larger-entries-by-default/#size-explained)).

Remove trailing sentence per reviewer feedback.

dubzzz · 2026-04-28T21:13:28Z

+Two concepts recur on every page in this section and are worth learning once:
+
+- **Size control.** Most composites accept `minLength` / `maxLength` bounds and a `size` modifier that scales how large generated values tend to be in practice (see [`size` explained](/docs/configuration/larger-entries-by-default/#size-explained)). These are the main knobs to keep generation costs under control when your children are themselves expensive.
+- **Two-dimensional shrinking.** When a test fails on a composite, fast-check shrinks along two axes independently: the **structure** (it tries shorter arrays, fewer object keys, smaller tuples) _and_ the **contents** (each surviving element is shrunk by its own arbitrary). This is why counterexamples on nested data tend to collapse cleanly to the minimal offender rather than to an opaque blob.


Suggested change

- **Two-dimensional shrinking.** When a test fails on a composite, fast-check shrinks along two axes independently: the **structure** (it tries shorter arrays, fewer object keys, smaller tuples) _and_ the **contents** (each surviving element is shrunk by its own arbitrary). This is why counterexamples on nested data tend to collapse cleanly to the minimal offender rather than to an opaque blob.

- **Two-dimensional shrinking.** When a test fails on a composite, fast-check shrinks along two axes independently: the **structure** (it tries shorter arrays, fewer object keys, smaller tuples) and the **contents** (each surviving element is shrunk by its own arbitrary). This is why counterexamples on nested data tend to collapse cleanly to the minimal offender rather than to an opaque blob.

codecov · 2026-04-28T21:38:11Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.75%. Comparing base (9621579) to head (549a7cc).
⚠️ Report is 56 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6845      +/-   ##
==========================================
- Coverage   94.86%   94.75%   -0.11%     
==========================================
  Files         209      211       +2     
  Lines        5665     5778     +113     
  Branches     1489     1526      +37     
==========================================
+ Hits         5374     5475     +101     
- Misses        283      295      +12     
  Partials        8        8

Flag	Coverage Δ
tests	`94.75% <ø> (-0.11%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

💄 Format docs with prettier

d17eca5

Converts `*italic*` to `_italic_` per the repo's prettier config.