Skip to content

fix: authored-link normalization JSX range matching - #124

Closed
mvvmm wants to merge 3 commits into
mainfrom
fix/authored-link-normalization-jsx-ranges
Closed

fix: authored-link normalization JSX range matching#124
mvvmm wants to merge 3 commits into
mainfrom
fix/authored-link-normalization-jsx-ranges

Conversation

@mvvmm

@mvvmm mvvmm commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

What & why

Bumping @cloudflare/nimbus-docs to 0.13.1 in cloudflare-docs fails at astro check with Nimbus authored-link normalization failed ... ambiguous JSX range — 364 of 9309 MDX files crash.

Root cause: staticHrefOffsets re-parses each JSX element's raw text as TSX and matches the TypeScript-computed node range against satteri's mdast position. TypeScript's JsxElement.getEnd() includes trailing trivia (and even the wrapper's );), so the end offset drifts and the lookup misses → "ambiguous JSX range". The same raw text also isn't always valid JSX: code blocks inside JSX elements can contain { (interpreted by TS as a JSX expression) and blockquote markers (> ) span the element's raw slice.

Changes:

  • Match JSX elements by start offset instead of full rangegetStart() is precise and unique; the drifting getEnd() was the failure.
  • Skip elements without href attributes before the TS round-trip — staticHrefOffsets only ever emits insertions for href-like attributes, so parsing is unnecessary (and crash-prone) otherwise.
  • Reconcile attributes by name instead of index — when TS can't parse a mangled attribute (e.g. blockquote markers), skip it rather than failing the whole source.

Verified: full scan of cloudflare-docs docs/partials/changelog goes from 364 failures to 0. Three regression tests added.

Checklist

  • A maintainer approved this work (lgtm+ on my issue or discussion), or I'm on the team
  • Correct tier (framework / starter / registry) per the boundary test
  • Edited packages/nimbus-starter-source/, not the templates branch
  • Changeset added (create-nimbus-docs changeset if the starter changed)
  • pnpm typecheck, pnpm -r test, and pnpm templates:check all green

@mvvmm mvvmm added the pr preview Publish a pkg.pr.new preview for this PR label Sep 8, 2026
@github-actions github-actions Bot removed the pr preview Publish a pkg.pr.new preview for this PR label Sep 8, 2026
@pkg-pr-new

pkg-pr-new Bot commented Sep 8, 2026

Copy link
Copy Markdown
pnpm add https://pkg.pr.new/@cloudflare/create-nimbus-docs@124
pnpm add https://pkg.pr.new/@cloudflare/nimbus-docs@124

commit: c83cfdf

// The TypeScript parse could not reconcile this attribute with the
// mdast node (for example, the raw slice spans blockquote markers that
// are not valid JSX). Skip it rather than failing the whole source.
continue;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we only normalize href on native elements? If a native html cannot be read, might be worth returning an error instead of skipping it.

@mvvmm mvvmm added the pr preview Publish a pkg.pr.new preview for this PR label Sep 8, 2026
@github-actions github-actions Bot removed the pr preview Publish a pkg.pr.new preview for this PR label Sep 8, 2026
@MohamedH1998

Copy link
Copy Markdown
Collaborator

Closing this as it's resolved by #138

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants