Skip to content

refactor(format): move IDNA validation out of JsonValidator into Idna - #99

Merged
rawo merged 2 commits into
masterfrom
refactor/94-idna
Nov 6, 2026
Merged

rawo merged 2 commits into
masterfrom
refactor/94-idna

Conversation

@rawo

@rawo rawo commented Nov 6, 2026

Copy link
Copy Markdown
Owner

Summary

Moves the IDNA code out of JsonValidator.kt into a new internal object Idna in src/main/kotlin/org/ktson/Idna.kt. Nothing else changes.

  • Moved: isValidHostname, isValidIdnHostname, idnaMap, isIdnaIgnored, isValidULabel, isAllowedIdnCodePoint, the RFC 5892 contextual rules (satisfiesContextualRules, isJoiningContext, isJoiningTransparent, isJoiningLetter, isVirama), the RFC 5893 Bidi rule (isRtlCodePoint, satisfiesBidiRule) and RFC 3492 Punycode (punycodeDecode, punycodeEncode, punycodeAdapt, punycodeDigit, punycodeChar).
  • Constants moved with them: the companion constants only these functions use: IDNA_*, KATAKANA_MIDDLE_DOT_SCRIPTS, CURSIVE_SCRIPTS, VIRAMA_CODE_POINTS, BIDI_*, PUNYCODE_*, ACE_PREFIX, MAX_LABEL_LENGTH, MAX_HOSTNAME_LENGTH, ZWJ/ZWNJ and REGEX_HOSTNAME_LABEL.
  • Entry points: only Idna.isValidHostname() and Idna.isValidIdnHostname() are visible outside the object. validateFormat, isValidEmailDomain and isValidIdnEmail call them. Everything else stays private.
  • Unchanged: function bodies and comments. The move only changed qualification and visibility. There is no reflection and no mutable state, and the public API is the same.
  • Line counts: JsonValidator.kt goes from 2,662 to 2,222 lines, and Idna.kt has 449.
  • Docs: CLAUDE.md has a new Architecture entry, and its Format Validation section now points to Idna.kt. The Architecture lines in memory/MEMORY.md are updated. There is no CHANGELOG entry because the refactor is internal.

Verification

  • ./gradlew ktlintFormat
  • CI=true ./gradlew test ktlintCheck --rerun-tasks: BUILD SUCCESSFUL, with the official suite required. build/test-results/test/*.xml reports 5,849 tests, 0 failures, 0 errors, 0 skipped, the same count as before.
  • python3 .claude/skills/fix-issue/scripts/test_counts.py: exit 0 (full run 5,849, custom 1,379).

Closes #94

🤖 Generated with Claude Code

Move the internationalized domain name code from JsonValidator.kt into
a new internal object Idna in Idna.kt: isValidHostname,
isValidIdnHostname, the UTS 46 mapping (idnaMap, isIdnaIgnored), the
U-label checks, the RFC 5892 contextual rules, the RFC 5893 Bidi rule,
RFC 3492 Punycode, and the tables and constants only they use
(IDNA_*, KATAKANA_MIDDLE_DOT_SCRIPTS, CURSIVE_SCRIPTS,
VIRAMA_CODE_POINTS, BIDI_*, PUNYCODE_*, ACE_PREFIX, label and hostname
length limits, ZWJ/ZWNJ, REGEX_HOSTNAME_LABEL).

- DDD: IDNA is a subdomain of its own (RFC 3492, 5890-5893), with
  nothing JSON Schema specific in it.
- SRP: its tables change with Unicode versions, not with JSON Schema
  semantics.
- DRY: hostname, idn-hostname, email and idn-email all call the same
  two entry points, Idna.isValidHostname() and Idna.isValidIdnHostname();
  everything else in the object stays private.

Function bodies and comments are unchanged; only qualification and
visibility changed. Behaviour is unchanged and the public API is
untouched. JsonValidator.kt goes from 2,662 to 2,222 lines.

Closes #94

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@rawo rawo added the refactor Restructuring without behaviour change label Nov 6, 2026
@rawo

rawo commented Nov 6, 2026

Copy link
Copy Markdown
Owner Author

Review: #99 (move IDNA into internal object Idna)

Verdict: the pure-move claim holds. I found no blocking or should-fix issues, only three doc nits.

How I verified the pure move

  • Per-declaration comparison. A script (Python) extracted every member declaration, with its leading KDoc or comments, from JsonValidator.kt at origin/master (2f83f64, the merge base) and from Idna.kt at the PR head. It then normalised indentation relative to the declaration, stripped a leading private/internal, and diffed each declaration by name.
    • All 41 declarations in Idna (18 functions, 23 constants) are identical to their originals.
    • None of them still exists in JsonValidator.kt.
    • Nothing was removed from JsonValidator.kt without arriving in Idna, and nothing new was added to it.
  • Line-multiset cross-check. I compared every - line of the JsonValidator.kt diff with every line of Idna.kt, sorted and with leading whitespace stripped. The only differences are:
    • the package line, the object Idna {/} wrapper and the new object KDoc;
    • the 4 rewritten call sites.
  • Build. I ran CI=true ./gradlew test ktlintCheck --rerun-tasks on an exported copy of the PR head, with the official suite at the pinned TEST_SUITE_REF 5b0ee16. Result: 5,849 tests, 0 failures, 0 errors, 0 skipped, and ktlint was clean.

Blocking

None. I checked:

  • Body equivalence, as described above.

  • Call sites. All 4 former callers now go through Idna, with the arguments and surrounding expressions unchanged:

    • validateFormat for FORMAT_HOSTNAME and FORMAT_IDN_HOSTNAME (JsonValidator.kt:1125, :1129);
    • isValidEmailDomain (:1265);
    • isValidIdnEmail (:1284).

    The [...] short-circuit in isValidIdnEmail is untouched. No moved identifier is still referenced in JsonValidator.kt, so nothing it needs was moved away.

  • Visibility and public API.

    • All 41 removed members were private, so JsonValidator's public and Java surface is unchanged.
    • Idna is internal, and only isValidHostname/isValidIdnHostname are non-private. Everything else is private.

Should-fix

None. I checked:

  • Native-image rule. Idna uses no reflection, no ::class, no getResource and no ServiceLoader.
  • Global state. Every top-level val is a read-only setOf(...) or a Regex, and the only vars are function locals.
  • Initialisation order. No property initialiser reads another non-const property. The const vals are inlined, and the functions run only after <clinit>. So the move from the eager companion to lazy object init is safe and has no side effects.
  • Imports.
    • Idna.kt needs none, because it uses java.text.Normalizer fully qualified, as before.
    • The import block of JsonValidator.kt is unchanged, and every import there is still used (FORMAT_HOSTNAME/FORMAT_IDN_HOSTNAME remain in validateFormat).
  • Style.
    • The layout matches UriSyntax.kt: object KDoc, public entry points first, then private helpers, then private constants at the bottom.
    • The KDoc is accurate. Email does reach isValidHostname through isValidEmailDomain, and the hyphen, category, contextual and Bidi rules and the UTS 46 mapping are all in the object.

Nits

  1. CLAUDE.md:60-61. These lines still say JsonValidator "(~90KB)" and that it "Contains all validation logic in a single class".

    • The file is now ~105 KB (107,657 bytes). It was 128 KB before, so the size was already stale.
    • IDNA, like UriSyntax, now lives outside the class.

    Suggest e.g. "(~105KB) ... Contains the validation logic in a single class; format grammars live in UriSyntax and Idna".

  2. memory/MEMORY.md:18. The edited line still says "JsonValidator.kt (~2,220 lines): all validation logic", directly above the new Idna.kt line. Suggest "the validation engine" or "validation logic except the URI and IDNA grammars".

  3. CLAUDE.md:379. The rewritten bullet is 152 characters, while its neighbours wrap at about 100–120. Suggest wrapping after "also used by email and idn-email)".

Out of scope and pre-existing: REGEX_UUID in the companion object sits at column 0 (JsonValidator.kt:2127 on the PR head). This PR doesn't touch it, but it could be fixed in a follow-up.

🤖 Generated with Claude Code

Point the architecture notes at UriSyntax and Idna for the format
grammars, give JsonValidator.kt's current size, and wrap the IDNA
helper bullet to the surrounding width (review of #99).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@rawo
rawo merged commit fdf6c64 into master Nov 6, 2026
1 check passed
@rawo
rawo deleted the refactor/94-idna branch November 6, 2026 10:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

refactor Restructuring without behaviour change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor: move IDNA (hostname, Punycode, contextual and Bidi rules) out of JsonValidator into Idna.kt

1 participant