Skip to content

Fix RangeError when stripping @docImport directives with non-ASCII characters and CRLF - #4289

Open
wyrindev wants to merge 3 commits into
dart-lang:mainfrom
wyrindev:fix/strip-doc-imports-range-error
Open

wyrindev wants to merge 3 commits into
dart-lang:mainfrom
wyrindev:fix/strip-doc-imports-range-error

Conversation

@wyrindev

Copy link
Copy Markdown

Fixes #4180

Description

This PR fixes an unhandled RangeError during comment precaching when stripping @docImport directives in documentation comments containing non-ASCII characters (e.g. em-dash — or emojis) and CRLF line endings.

  • Defensive bounds clamping: Clamped substring slice bounds (safeStart and safeEnd) to [0, content.length] in DocumentationComment._stripDocImports so that string offset drift never causes a fatal RangeError.
  • Precache error diagnostics: Added a try-catch block around processComment() in DocumentationComment.precacheLocalDocs that logs the affected element location (location) and full identifier (fullyQualifiedName) with logWarning before rethrowing, avoiding opaque ParallelWaitError failures during batch doc precaching.
  • Regression test: Added test_docImport_withNonAsciiAndCrlf in test/documentation_comment_test.dart (stress testing with 30 accumulated lines of comments containing em-dashes and CRLF line endings) to verify that doc imports are stripped cleanly without error.
  • Changelog: Added an entry under ## 9.0.10-wip in CHANGELOG.md.

Verification

  • Formatted via dart format.
  • Analyzed via dart analyze (0 issues).
  • Ran all 50 tests in test/documentation_comment_test.dart (50/50 passed).

  • I’ve reviewed the contributor guide and applied the relevant portions to this PR.
Contribution guidelines:

Many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

Note: The Dart team is trialing Gemini Code Assist. Don't take its comments as final Dart team feedback. Use the suggestions if they're helpful; otherwise, wait for a human reviewer.

- Clamp substring range bounds in DocumentationComment._stripDocImports to avoid RangeError on offset drift.
- Log element location and exception details when precaching local docs fails.
- Add regression test for doc imports with non-ASCII characters and CRLF line endings.
- Update CHANGELOG.md.

Fixes dart-lang#4180
- Accumulate 30 lines of comments with non-ASCII em-dashes and CRLF.
- Assert that comment text is preserved and @DocImport is removed without RangeError.

Related to dart-lang#4180
@google-cla

google-cla Bot commented Sep 29, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Code Review

This pull request fixes an unhandled RangeError that occurs during comment precaching when stripping @docImport directives containing non-ASCII characters or CRLF line endings. It resolves this by clamping the substring offsets to safe bounds within the content length. Additionally, it wraps the local documentation precaching in a try-catch block to log warnings with element location and exception details upon failure, and adds a test case to verify the fix. There are no review comments, so I have no feedback to provide.

@wyrindev
wyrindev marked this pull request as ready for review September 29, 2026 11:05
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.

Pana Dartdoc Crashing

1 participant