# Inky Rust Rewrite Plan ## Overview Rewrite the Inky HTML-to-email transpiler in Rust and distribute it as: 1. **WASM module** — for JS/Node.js/browser (drop-in replacement for current npm package) 2. **Native shared library** (.so/.dylib/.dll) — for PHP (via FFI), Python (via ctypes), Ruby (via fiddle), and any other language with C FFI support 3. **Rust crate** — for Rust consumers and as the canonical source of truth This eliminates the need for language-specific reimplementations (inky-rb, lorenzo/pinky, etc.) and ensures all consumers produce identical output. --- ## Project Structure ``` inky/ ├── Cargo.toml # Workspace root ├── crates/ │ ├── inky-core/ # Pure Rust transformation library │ │ ├── Cargo.toml │ │ └── src/ │ │ ├── lib.rs # Public API: transform(html) -> html │ │ ├── parser.rs # HTML parsing and component detection │ │ ├── components.rs # Component factory (all transformation rules) │ │ ├── column.rs # Column/grid sizing logic │ │ ├── attrs.rs # Attribute extraction and filtering │ │ └── config.rs # Configuration (column count, tag names) │ │ │ ├── inky-wasm/ # WASM bindings (wasm-bindgen) │ │ ├── Cargo.toml │ │ └── src/ │ │ └── lib.rs # WASM-exported functions │ │ │ └── inky-ffi/ # C FFI bindings (shared library) │ ├── Cargo.toml │ ├── src/ │ │ └── lib.rs # extern "C" exported functions │ └── inky.h # Generated C header (via cbindgen) │ ├── bindings/ │ ├── node/ # npm package wrapper │ │ ├── package.json │ │ └── index.js # JS API wrapping WASM │ │ │ ├── php/ # Composer package wrapper │ │ ├── composer.json │ │ ├── src/ │ │ │ └── Inky.php # PHP FFI wrapper class │ │ ├── tests/ │ │ │ └── InkyTest.php # PHPUnit tests against shared fixtures │ │ └── lib/ # Prebuilt .so/.dylib binaries │ │ │ ├── python/ # PyPI package wrapper │ │ ├── pyproject.toml │ │ ├── src/ │ │ │ └── inky/__init__.py # ctypes wrapper │ │ ├── tests/ │ │ │ └── test_inky.py # pytest tests against shared fixtures │ │ └── lib/ # Prebuilt .so/.dylib binaries │ │ │ └── ruby/ # RubyGems package wrapper │ ├── inky.gemspec │ ├── lib/ │ │ └── inky.rb # fiddle wrapper │ ├── spec/ │ │ └── inky_spec.rb # RSpec tests against shared fixtures │ └── ext/ # Prebuilt .so/.dylib binaries │ ├── tests/ │ ├── fixtures/ # Shared test fixtures (input/output HTML pairs) │ │ ├── components.json # All component test cases │ │ ├── grid.json # All grid test cases │ │ └── parser.json # General parser test cases │ └── integration/ # Cross-language integration tests │ └── .github/ └── workflows/ ├── ci.yml # Test on every push └── release.yml # Build + publish all targets ``` --- ## Phase 1: Rust Core (`inky-core`) The core library is a pure Rust crate with no platform dependencies. It takes an HTML string and returns transformed HTML. ### Public API ```rust pub struct Inky { config: Config, } pub struct Config { pub column_count: u32, // default: 12 pub components: ComponentNames, // customizable tag names } pub struct ComponentNames { pub button: String, // default: "button" pub row: String, // default: "row" pub columns: String, // default: "columns" pub container: String, // default: "container" pub callout: String, // default: "callout" pub inky: String, // default: "inky" pub block_grid: String, // default: "block-grid" pub menu: String, // default: "menu" pub menu_item: String, // default: "item" pub center: String, // default: "center" pub spacer: String, // default: "spacer" pub wrapper: String, // default: "wrapper" pub h_line: String, // default: "h-line" } impl Inky { pub fn new() -> Self; pub fn with_config(config: Config) -> Self; pub fn transform(&self, html: &str) -> String; } // Convenience function pub fn transform(html: &str) -> String; ``` ### Dependencies ```toml [dependencies] scraper = "0.22" # HTML parsing (built on html5ever + selectors) ego-tree = "0.10" # Tree traversal (used by scraper) regex = "1" # Raw tag extraction ``` The `scraper` crate provides CSS selector-based element querying similar to Cheerio/jQuery, making the port straightforward. ### Core Algorithm (mirrors current JS implementation) ``` 1. Extract blocks → replace with ###RAW{i}### placeholders 2. Parse HTML string into DOM tree (scraper::Html) 3. Loop while custom component elements exist in the tree: a. Find first matching component element b. Transform it via component factory → HTML string c. Replace element in tree with transformed HTML 4. Remove data-parsed attributes from
tags 5. Serialize DOM back to HTML string 6. Re-inject raw block content into placeholders 7. Return final HTML string ``` ### Component Transformation Rules Each component maps directly from the current JS implementation: | Component | Input Tag | Output Summary | |-----------|-----------|----------------| | `h-line` | `` | `
 
` | | `columns` | `` | `[expander]
[content]
` | | `row` | `` | `[content]
` | | `button` | `", "expected": "
Button
" }, { "name": "creates a spacer with default size", "input": "", "expected": "
 
" } ] } ``` ### Test Runners Each binding loads the same JSON fixtures and asserts identical output: - **Rust:** `cargo test` — loads fixtures, runs through `inky_core::transform()` - **Node.js:** `npm test` — loads fixtures, runs through WASM binding - **PHP:** `phpunit` — loads fixtures, runs through FFI binding - **Python:** `pytest` — loads fixtures, runs through ctypes binding - **Ruby:** `rspec` — loads fixtures, runs through fiddle binding - **Go:** `go test` — loads fixtures, runs through cgo binding --- ## Phase 9: CI/CD and Release Pipeline ### GitHub Actions Workflow ```yaml # .github/workflows/release.yml # Triggered on version tags (v2.0.0, etc.) jobs: test: # Run cargo test on all platforms strategy: matrix: os: [ubuntu-latest, macos-latest, windows-latest] build-wasm: # wasm-pack build → upload artifact # Publish to npm build-native: # Cross-compile shared libraries for all targets: # - x86_64-unknown-linux-gnu → libinky.so # - aarch64-unknown-linux-gnu → libinky.so # - x86_64-apple-darwin → libinky.dylib # - aarch64-apple-darwin → libinky.dylib # - x86_64-pc-windows-msvc → inky.dll # Package into GitHub release # Publish to crates.io test-bindings: # For each language binding: # 1. Copy prebuilt native library into binding's lib/ directory # 2. Run language-specific test suite against shared JSON fixtures # 3. Verify output matches Rust core exactly publish: # After all tests pass: # - npm: publish WASM-based Node.js package # - Packagist: publish PHP Composer package with native binaries # - PyPI: publish Python package with native binaries # - RubyGems: publish gem with native binaries # - crates.io: publish Rust crate # - Go: tag release in foundation/inky-go (binaries committed to repo) ``` ### Versioning - All crates, npm package, and Composer package share the same version number - Start at **v2.0.0** to signal the rewrite (current JS version is 1.4.2) --- ## Migration Path for Existing Users ### npm (JS/Node.js) The v2.0.0 npm package maintains backward compatibility: ```javascript // This still works exactly as before const { Inky } = require('inky'); const inky = new Inky(); const html = inky.releaseTheKraken(input); // New simpler API also available const { transform } = require('inky'); const html = transform(input); ``` Breaking changes: - Gulp stream integration removed (Gulp usage has declined significantly) - Cheerio options no longer accepted (Rust uses its own HTML parser) - Minimum Node.js version: 16+ (for WASM support) ### PHP For users of `lorenzo/pinky` or `twigphp/inky-extra`: ```php // Before (pinky) $html = Pinky\transformString($body)->saveHTML(); // After (foundation/inky) $html = \Foundation\Inky\Inky::convert($body); ``` ### Python ```python # Before (no official package existed) # After from inky import transform html = transform('Hello') ``` ### Ruby ```ruby # Before (inky-rb) # require 'inky' # Inky::Core.new.release_the_kraken(html) # After require 'inky' html = Inky.transform('Hello') ``` ### Go ```go // New — no previous Go support existed import "github.com/foundation/inky-go" html := inky.Transform("Hello") ``` ### Other Languages Any language with C FFI support can use the shared library directly without an official binding — the C API is just 3 functions (`inky_transform`, `inky_transform_with_columns`, `inky_free`). --- ## Implementation Order ### Stage 1: Core (do this first — everything else depends on it) | Step | Task | Scope | |------|------|-------| | 1 | Set up Cargo workspace with three crates (`inky-core`, `inky-wasm`, `inky-ffi`) | Scaffolding | | 2 | Implement `inky-core` with `scraper` crate | ~500-600 lines of Rust | | 3 | Port all 52 test cases to JSON fixtures | Test data extraction | | 4 | Write Rust tests against fixtures, achieve parity with JS | Testing | ### Stage 2: Distribution targets (can be done in parallel) | Step | Task | Scope | |------|------|-------| | 5 | Build `inky-wasm` with wasm-bindgen | ~30 lines | | 6 | Build `inky-ffi` with cbindgen | ~40 lines | ### Stage 3: Language bindings (can all be done in parallel) | Step | Task | Scope | |------|------|-------| | 7 | Create Node.js wrapper package (WASM) | ~50 lines | | 8 | Create PHP Composer package (FFI) | ~60 lines | | 9 | Create Python PyPI package (ctypes) | ~40 lines | | 10 | Create Ruby gem (fiddle) | ~40 lines | | 11 | Create Go module in separate repo (cgo) | ~50 lines | ### Stage 4: Ship it | Step | Task | Scope | |------|------|-------| | 12 | Set up CI: test Rust + all bindings on all platforms | CI config | | 13 | Set up release pipeline: cross-compile + publish to all registries | CD config | | 14 | Write migration guide for each language | Documentation | | 15 | Publish v2.0.0 to npm, crates.io, Packagist, PyPI, RubyGems | Release | | 16 | Archive `foundation/inky-rb` with pointer to new gem | Cleanup | | 17 | Re-enable Dependabot security updates (disabled during 1.x→2.x transition) | Cleanup |