Skip to content

Complete rewrite#12

Merged
mark-dropbear merged 10 commits intomainfrom
rewrite
Feb 26, 2026
Merged

Complete rewrite#12
mark-dropbear merged 10 commits intomainfrom
rewrite

Conversation

@mark-dropbear
Copy link
Contributor

Moving away from a strict Punycode.js port to an implementation that is more idomatic Dart from the ground up.

@gemini-code-assist
Copy link
Contributor

Summary of Changes

Hello @mark-dropbear, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a comprehensive overhaul of the Punycoder package, transitioning to a native Dart implementation that prioritizes compliance, performance, and a more intuitive API. The changes streamline how developers interact with Punycode, offering clearer distinctions between basic string conversions and complex Internationalized Domain Name (IDNA) operations, while also introducing robust validation and mixed-case support.

Highlights

  • Complete Rewrite: The package has undergone a complete, ground-up rewrite, moving from a Punycode.js port to an idiomatic Dart implementation.
  • API Restructuring: The API has been significantly refactored, separating raw Punycode encoding/decoding from IDNA domain and email handling. The PunycodeCodec.simple() constructor was removed, and dedicated top-level functions (domainToAscii, emailToAscii, etc.) were introduced for IDNA operations.
  • Enhanced Compliance & Features: The new implementation offers full RFC 3492 compliance, including support for mixed-case annotation (RFC 3429 Appendix A), official errata fixes, and IDNA2003 separator recognition. Strict IDNA validation is now enforced by default but can be configured.
  • Improved Codebase: The internal implementation now uses StringBuffer and Unicode-aware Runes for efficient processing, and a comprehensive suite of unit and integration tests ensures platform parity across Dart VM and Web.
Changelog
  • CHANGELOG.md
    • Updated to version 0.3.0, detailing breaking changes and new features.
  • README.md
    • Updated to reflect the new architecture, features, and usage examples.
  • analysis_options.yaml
    • Updated linter rules and strict language settings for improved code quality.
  • doc/api/__404error.html
    • Updated version number and minor HTML formatting.
  • doc/api/index.html
    • Updated package description, features, usage examples, and version number.
  • doc/api/index.json
    • Updated API index to reflect new classes, functions, and descriptions.
  • doc/api/punycoder/PunycodeCodec-class-sidebar.html
    • Removed reference to PunycodeCodec.simple() constructor.
  • doc/api/punycoder/PunycodeCodec-class.html
    • Updated class description and removed simple() constructor documentation.
  • doc/api/punycoder/PunycodeCodec/PunycodeCodec.html
    • Updated constructor description and implementation to reflect simplified initialization.
  • doc/api/punycoder/PunycodeCodec/decoder.html
    • Updated decoder property implementation to directly return PunycodeDecoder instance.
  • doc/api/punycoder/PunycodeCodec/encoder.html
    • Updated encoder property implementation to directly return PunycodeEncoder instance.
  • doc/api/punycoder/PunycodeDecoder-class-sidebar.html
    • Added sidebar entries for PunycodeDecoder constructor and removed toUnicode method.
  • doc/api/punycoder/PunycodeDecoder-class.html
    • Updated class description, added constructor documentation, and removed toUnicode method documentation.
  • doc/api/punycoder/PunycodeDecoder/PunycodeDecoder.html
    • Added new file for PunycodeDecoder constructor documentation.
  • doc/api/punycoder/PunycodeDecoder/convert.html
    • Updated convert method implementation details.
  • doc/api/punycoder/PunycodeEncoder-class-sidebar.html
    • Added sidebar entries for PunycodeEncoder constructor and encodeBasic method, removed toAscii method.
  • doc/api/punycoder/PunycodeEncoder-class.html
    • Updated class description, added constructor documentation, and removed toAscii method documentation.
  • doc/api/punycoder/PunycodeEncoder/PunycodeEncoder.html
    • Added new file for PunycodeEncoder constructor documentation.
  • doc/api/punycoder/PunycodeEncoder/convert.html
    • Updated convert method implementation details.
  • doc/api/punycoder/PunycodeEncoder/encodeBasic.html
    • Added new file for encodeBasic method documentation.
  • doc/api/punycoder/domainToAscii.html
    • Added new file for domainToAscii function documentation.
  • doc/api/punycoder/domainToUnicode.html
    • Added new file for domainToUnicode function documentation.
  • doc/api/punycoder/emailToAscii.html
    • Added new file for emailToAscii function documentation.
  • doc/api/punycoder/emailToUnicode.html
    • Added new file for emailToUnicode function documentation.
  • doc/api/punycoder/index.html
    • Updated library description and added new functions and constants to the overview.
  • doc/api/punycoder/punycode-constant.html
    • Added new file for punycode constant documentation.
  • doc/api/punycoder/punycoder-library-sidebar.html
    • Updated sidebar to include new classes, constants, and functions.
  • doc/api/search.html
    • Updated version number in the footer.
  • doc/api/static-assets/styles.css
    • Updated CSS for breadcrumbs and search bar styling.
  • example/punycoder_example.dart
    • Updated usage examples to reflect the new API and demonstrate mixed-case preservation.
  • lib/punycoder.dart
    • Rewritten to define the main PunycodeCodec and punycode constant, and to export new src files.
  • lib/src/codec.dart
    • Removed as its functionality was integrated into lib/punycoder.dart and new encoder/decoder files.
  • lib/src/constants.dart
    • Added new file to define Punycode bootstrap constants.
  • lib/src/decoder.dart
    • Removed as its functionality was replaced by lib/src/punycode_decoder.dart.
  • lib/src/encoder.dart
    • Removed as its functionality was replaced by lib/src/punycode_encoder.dart.
  • lib/src/idna.dart
    • Added new file containing IDNA-specific domain and email handling functions with validation logic.
  • lib/src/punycode_decoder.dart
    • Added new implementation of the Punycode decoder, including mixed-case annotation support.
  • lib/src/punycode_encoder.dart
    • Added new implementation of the Punycode encoder, including mixed-case annotation support.
  • lib/src/punycode_helper.dart
    • Removed as its utility functions were refactored into lib/src/utils.dart and directly into encoder/decoder classes.
  • lib/src/utils.dart
    • Added new utility functions for Punycode operations, including digit encoding/decoding and bias adaptation.
  • pubspec.yaml
    • Updated package version to 0.3.0 and revised dev dependencies.
  • test/decoder_test.dart
    • Updated tests to use the new PunycodeDecoder and removed references to simpleCodec.
  • test/encoder_test.dart
    • Updated tests to use the new PunycodeEncoder and removed references to simpleCodec.
  • test/idna_test.dart
    • Added new tests for IDNA domain and email functions, including validation scenarios.
  • test/punycoder_test.dart
    • Added new integration tests for the PunycodeCodec to ensure overall functionality.
  • test/utils_test.dart
    • Added new tests for utility functions in lib/src/utils.dart.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link
Contributor

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

Choose a reason for hiding this comment

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

Code Review

This is an excellent and comprehensive rewrite of the package. The new structure is much more idiomatic for Dart, separating the core Punycode logic from the IDNA-specific helpers for domains and emails. The code is now more modular, readable, and strictly follows the RFC specifications, including support for mixed-case annotations and errata fixes. The addition of extensive linter rules and platform-aware constants further improves the quality and robustness of the codebase. I've found a few minor areas for improvement, mainly concerning error handling and a small bug in domain validation, which are detailed in the comments.

mark-dropbear and others added 4 commits February 26, 2026 15:51
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: mark-dropbear <76698672+mark-dropbear@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: mark-dropbear <76698672+mark-dropbear@users.noreply.github.com>
@mark-dropbear
Copy link
Contributor Author

/gemini review

Copy link
Contributor

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

Choose a reason for hiding this comment

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

Code Review

This is a fantastic and thorough rewrite of the library. The move to a more idiomatic Dart structure with clear separation of concerns (raw Punycode vs. IDNA helpers) is a huge improvement in terms of API design and maintainability. The code is well-structured, the new test suite is comprehensive, and the documentation is clear. I've only found a couple of minor inconsistencies in error handling, where a generic Exception is thrown instead of the more specific FormatException, and a small redundancy in constant definitions. I've left a few suggestions to address these. Overall, excellent work on this major refactoring!

mark-dropbear and others added 3 commits February 26, 2026 16:09
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: mark-dropbear <76698672+mark-dropbear@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: mark-dropbear <76698672+mark-dropbear@users.noreply.github.com>
@mark-dropbear
Copy link
Contributor Author

/gemini review

Copy link
Contributor

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

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 represents a significant and high-quality rewrite of the library. The move to a more idiomatic Dart implementation from the ground up is very successful. The code is now much more modular, readable, and robust, with clear separation of concerns for encoding, decoding, IDNA handling, and utilities. The addition of full RFC compliance, including mixed-case support and errata fixes, is a major improvement. The expanded and reorganized test suite also adds a great deal of confidence in the new implementation. Overall, this is an excellent update. I have one minor suggestion to improve error handling consistency.

@mark-dropbear mark-dropbear merged commit 0a8985d into main Feb 26, 2026
1 check 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