feat(recheck): add word-count, sentence-count, and reading-time formulas to the metric assertion

[adamaltman]

What/Why/How?

Ports the size formulas of the recheck metric assertion from the Redocly monorepo (Redocly/redocly#28017).

• metric accepts three new formulas next to the six readability formulas: word-count, sentence-count, and reading-time.
• reading-time is minutes at a new wordsPerMinute option, default 200, rounded to one decimal before the bounds check so the number in the message is the number that was compared.
• Config validation rejects a wordsPerMinute that is not a positive number, and rejects the option with any formula other than reading-time.
• Size formulas use the size fallback message Document %s is %s; expected between %s and %s.; the placeholder order (formula, score, min, max) is unchanged.
• The counts read the same prose as the readability formulas: code blocks, front matter, headings, and Markdoc tags are left out, and a file with no prose is never reported.

The engine README documents the formulas and adds a page-size budget example: a word cap on .claude/skills/**/SKILL.md.

Docs conflict with #3182. That PR adds docs/@v2/recheck/assertions.md with the metric option table. This PR does not touch that page, to avoid an add/add conflict. After #3182 merges, the formula row needs the three size formulas and the table needs a wordsPerMinute row. I can open that follow-up.

Reference

• Redocly/redocly#28017
• docs(recheck): document the recheck command and update the agent skills #3182

Testing

• Unit tests in metric.test.ts cover the three formulas, the default and custom wordsPerMinute, the rounding before comparison, and the new validation cases.
• The README drift test now checks the size-budget example fires only on a skill file over the cap.
• npm run compile, npm run typecheck, and the recheck unit suite pass.
• Ran the CLI end to end with a word-count rule and a reading-time rule against a skill file, and confirmed a misplaced wordsPerMinute is rejected at config load.

Screenshots (optional)

Check yourself

• This PR follows the contributing guide
• All new/updated code is covered by tests
• Core code changed? - Tested with other Redocly products (internal contributions only)
• New package installed? - Tested in different environments (browser/node)
• Documentation update has been considered

Security

• The security impact of the change has been considered
• Code follows company security practices and guidelines

🤖 Generated with Claude Code

---

Note

Low Risk
Additive linting behavior and stricter config validation for metric options; no auth, data, or runtime security surface changes.

Overview
Extends recheck’s metric assertion with size formulas (word-count, sentence-count, reading-time) alongside the existing readability formulas, so whole-file prose can be bounded by length or estimated reading time—not only readability scores.

reading-time uses optional wordsPerMinute (default 200), rounded to one decimal before min/max comparison so diagnostics match the verdict. Size metrics reuse the same prose extraction as readability (code, front matter, headings, Markdoc stripped); empty prose is never flagged. Size violations use the fallback Document %s is %s; expected between %s and %s. Config validation accepts the new formulas and rejects invalid wordsPerMinute usage.

The package README documents the formulas and adds a recheck/skill-size-budget example (word cap on .claude/skills/**/SKILL.md). Tests cover execution, validation, and README snippet drift.

^{Reviewed by Cursor Bugbot for commit 4fe3552. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4fe3552

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]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	83.46% (🎯 79%)	20136 / 24125
🔵	Statements	83.09% (🎯 78%)	21758 / 26185
🔵	Functions	85.24% (🎯 82%)	3830 / 4493
🔵	Branches	75.61% (🎯 71%)	14626 / 19344

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/recheck/src/config/validate.ts	97.52%	93.57%	100%	98.55%	39, 66-70, 103, 978-984, 1067, 1070, 1089, 1136, 1184-1187
packages/recheck/src/rules/scope/metric.ts	100%	100%	100%	100%

Generated in workflow #12249 for commit 4fe3552 by the Vitest Coverage Report Action

[github-actions]

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓ 1.00x (Fastest)	▓ 1.00x ± 0.01	▓ 1.00x (Fastest)
cli-next	▓ 1.01x ± 0.01	▓ 1.00x (Fastest)	▓ 1.01x ± 0.01

[AlbinaBlazhko17]

I wanted to clarify: word-count with min never reports a page with no prose (the stats.words === 0 early return, tested in never flags a document with no prose). Is it intended?