Skip to content

Conversation

@corylanou
Copy link
Member

Summary

This PR fixes non-deterministic JSON output when marshaling hype documents. Previously, rendering the same hype document multiple times would produce different JSON due to non-deterministic map iteration order.

Changes

  • document.go: Copy and marshal snippet maps to ensure deterministic key ordering
  • snippet.go: Create new maps to leverage Go's json package automatic lexicographic key sorting
  • element.go: Convert syncx.Map attributes to regular map for deterministic attribute ordering
  • parser.go: Convert syncx.Map vars to regular map using Range() for deterministic variable ordering

Testing

Added comprehensive JSON determinism tests to document_test.go:

  • Test_Document_JSON_Determinism: Tests basic documents, docs with attributes, code snippets, and complex documents (10 runs each)
  • Test_Document_JSON_Determinism_WithExecution: Tests determinism after document execution
  • Test_Document_JSON_Determinism_RealWorld: Real-world scenario with multiple features
  • Test_Parser_JSON_Determinism: Tests Parser JSON marshaling determinism
  • Test_Element_JSON_Determinism: Tests Element JSON marshaling determinism
  • Test_Snippets_JSON_Determinism: Tests Snippets JSON marshaling determinism
  • Benchmark_Document_JSON_Marshal: Performance benchmark

All tests pass ✅

Result

JSON output is now deterministic and predictable - rendering the same hype document multiple times will always produce identical JSON.

This change ensures that JSON marshaling of hype documents produces
deterministic, predictable output across multiple renders of the same content.

Changes:
- Document.MarshalJSON(): Copy and marshal snippet maps to ensure
  deterministic key ordering
- Snippets.MarshalJSON(): Create new maps to leverage Go's json package
  automatic lexicographic key sorting
- Element.JSONMap(): Convert syncx.Map attributes to regular map to ensure
  deterministic attribute ordering in JSON output
- Parser.MarshalJSON(): Convert syncx.Map vars to regular map using Range()
  to ensure deterministic variable ordering

Testing:
- Added comprehensive JSON determinism tests to document_test.go:
  - Test_Document_JSON_Determinism: Basic document JSON determinism (10 runs)
  - Test_Document_JSON_Determinism_WithExecution: Determinism after execution
  - Test_Document_JSON_Determinism_RealWorld: Real-world scenario testing
  - Test_Parser_JSON_Determinism: Parser marshaling determinism
  - Test_Element_JSON_Determinism: Element marshaling determinism
  - Test_Snippets_JSON_Determinism: Snippets marshaling determinism
  - Benchmark_Document_JSON_Marshal: Performance benchmark

All tests pass, confirming JSON output is now deterministic.

Fixes: Non-deterministic JSON output when regenerating hype documents
@cursor
Copy link

cursor bot commented Nov 4, 2025

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on December 12.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

@corylanou corylanou merged commit 3ac83a1 into main Nov 4, 2025
@corylanou corylanou deleted the claude/fix-hype-json-output-011CUoYdjQQucerK6d1X9DZB branch November 4, 2025 22:34
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.

3 participants