test(website): guard the mechanical MDX authoring rules the audit fixed by hand - #1061
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
blove
enabled auto-merge (squash)
September 8, 2026 15:01
blove
force-pushed
the
blove/docs-content-guards
branch
from
September 8, 2026 15:17
cd436f9 to
38e0463
Compare
Contributor
The description value pattern excluded every quote character, so any `description:` holding a possessive never matched. Nine docs pages declared a description and silently shipped the first-paragraph fallback instead. Capture the value whole and strip only a matched pair of surrounding quotes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`Card` rendered `{icon}` straight into a div, so `icon="rocket"` printed
the word "rocket" above the title. Nothing looked the value up. Remove
the prop, its `.mdx-card-icon` rule, and the four glyph icons the two
interrupt blog posts passed; the cards keep their title and arrow.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nine descriptions ran past META_DESCRIPTION_MAX and were truncated mid-sentence by clampMetaDescription(). Trim each to say the same thing in under 160 characters. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The accuracy audit fixed roughly 160 wrong claims by hand; several of the defect classes render fine and return silently. Walk `content/**` and fail with the offending `path:line` when a page: - passes an `icon` prop to `Card`, which does not accept one; - (docs only) declares no frontmatter `description`, or one long enough that `clampMetaDescription()` truncates it; - gives `Callout` a `type` outside the union, read out of Callout.tsx so the guard cannot drift from the component; - (docs only) uses a contraction. The patterns match no possessive, and the `## What's Next` heading is exempt structurally, not by file list. Each detector also has a unit test over synthetic content, so a rule that stops firing fails rather than passing vacuously. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
blove
force-pushed
the
blove/docs-content-guards
branch
from
September 8, 2026 15:46
38e0463 to
5df08b9
Compare
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Yesterday's accuracy audit fixed roughly 160 wrong claims across 89 docs pages. Several of those defect classes are mechanical: the page still renders, it just renders wrong, and nothing in the build notices. This adds one guard spec that walks the MDX tree and fails with the offending
path:line.The guard —
apps/website/src/lib/docs-content-rules.spec.tsiconprop onCard.Cardrendered{icon}straight into a div with no lookup, soicon="rocket"printed the word "rocket" above the title. Scans all ofcontent/**.description. A page with none falls through to the first-paragraph heuristic and then to the library blurb, so unrelated pages ship identical meta descriptions. The bound isMETA_DESCRIPTION_MAXimported fromsite-metadata, asserted asclampMetaDescription(d) === d, so the rule tracks the code instead of a magic number.Callout typemust be one of the component's union.type="note"renders an empty icon and an unstyled band. The allowed set is parsed out ofCallout.tsx, with a canary assertion so a parse failure fails loudly rather than allowing everything.'spattern is a closed list of pronouns and determiners, and the others end in suffixes (n't,'re,'ve,'ll,'m,'d) no possessive uses.## What's Nextis exempt structurally — a heading test, not a file list. Fenced blocks, inline code spans, and MDX comments are blanked out with line numbers preserved. The current tree needed zero exceptions.Each detector also has a unit test over synthetic content, so a rule that quietly stops firing fails instead of passing vacuously.
Two real defects the guard surfaced
The frontmatter description parser could not read an apostrophe.
FRONTMATTER_DESCRIPTION_PATTERNcaptured[^'"\n]+?, which excluded every quote character, so any description containing a possessive never matched. Nine pages declared a description and silently shipped the first-paragraph fallback. Fixed by capturing the value whole and stripping only a matched pair of surrounding quotes, with a failing-first test indocs.spec.ts.Nine more descriptions ran past the clamp and were truncated mid-sentence by
clampMetaDescription()(META_DESCRIPTION_MAXis 160, not the 180 in the follow-up note). Trimmed each to say the same thing in under 160.Also deleted: the dead
iconprop onCard, its.mdx-card-iconrule, and the four glyph icons the two interrupt blog posts passed. The cards keep their title and arrow.Mutation evidence
Each rule was broken in the real content tree, the spec re-run, and the mutation reverted:
icon="rocket"on a Card inlanggraph/getting-started/introduction.mdxdescription:line deleted fromchat/guides/theming.mdx<Callout type="info">→type="note""The token doesn't apply and you're done."inserted as proseThe
docs.tsparser fix was likewise written failing-first: both newdocs.spec.tstests failed before the pattern change and pass after.Verification
npx vitest run --root apps/website --reporter=dot— 138 files, 1394 tests, all greennpx nx run-many -t lint,test --projects=website --skip-nx-cache— success; lint reports 0 errors (65 pre-existing warnings)GROWTH_FORM_POLICY=growth_v1 npx nx build website— success🤖 Generated with Claude Code