Skip to content

Clarify JavaScript encoding contracts and strengthen boundary tests - #244

Merged
jmanico merged 1 commit into
mainfrom
docs/issue-243-javascript-contracts
Oct 15, 2026
Merged

jmanico merged 1 commit into
mainfrom
docs/issue-243-javascript-contracts

Conversation

@jmanico

@jmanico jmanico commented Oct 15, 2026 •

Copy link
Copy Markdown
Member

Change

The JavaScript documentation understated output growth and did not clearly define safe insertion boundaries. Clarify the Javadocs, guides, and matching JSP/Jakarta descriptions: preserve complete encoded results, avoid continuing JavaScript escapes or HTML character references, and distinguish nonempty-fragment protection from empty input or an already-started HTML end tag. Explain JSON whole-string embedding separately.

Document that the reported URL is unchanged by forJavaScriptSource and forJavaScriptAttribute, while general/block modes retain their script-letter escaping. Correct the internal XML/shortest-escape claims and describe opening <script tokenizer transitions as well as closing tags.

Strengthen parser regressions to assert the entire script text survives parsing, rather than relying on marker absence. Add empty-input, already-started-end-tag, and opening-script controls. Jsoup 1.23.2 differs from Chrome for mixed-case double-escape starts; the test documents this limitation and uses a lowercase raw negative control.

Related to #243.

Compatibility and validation

No executable encoder logic, emitted encoding, public API, or dependency changes. The patch corrects documentation and test coverage of the existing contract.

  • JDK 17 ./mvnw -B -ntp clean verify: passed all reactor modules, including Javadoc generation; 2,290 Surefire/Failsafe tests, zero failures/errors/skips.
  • python3 scripts/check-taglib-parity.py: passed, 34 source files.
  • python3 -m unittest discover -s scripts/tests: 36 tests passed.
  • python3 -m unittest discover -s compatibility/tests: 17 tests passed against the freshly built artifacts.
  • Packaged-consumer preparation and execution on Java 17 passed against those artifacts.
  • Additional local Chrome 155 checks: 2,124 JavaScript and 177 JSON value roundtrips; 47,232 valid end-tag partition cases; 768 opening-token cases and 64 raw negative controls. Another 768 end-tag candidates already outside the valid insertion context were explicitly excluded, not counted as successes.
  • git diff --check: passed.

The final patch was built in an isolated checkout and verified byte-for-byte against this commit. The Docker/Selenium CI fixture and cross-JDK CI matrix were not run locally; required CI remains the merge gate. Local browser probes used Chrome, not Firefox or Safari.

  • I kept the change scoped and preserved relevant notices.
  • I checked documentation/changelog and tests for any behavior change.
  • This PR contains no credentials or private vulnerability evidence.

@jmanico
jmanico requested a review from jeremylong as a code owner October 15, 2026 16:00
@jmanico
jmanico merged commit ba3aade into main Oct 15, 2026
18 checks passed
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.

1 participant