Release v0.1.8

Author: nshkrdotcom

.github/workflows/elixir.yaml

@@ -150,3 +150,32 @@ jobs:
     # Step: Execute the tests.
     - name: Run tests
       run: mix test
+
+  windows_test:
+    runs-on: windows-latest
+    name: Windows Test on OTP ${{matrix.otp}} / Elixir ${{matrix.elixir}}
+    strategy:
+      matrix:
+        otp: ['27.3.3']
+        elixir: ['1.18.3']
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Set up Elixir
+        uses: erlef/setup-beam@v1
+        with:
+          otp-version: ${{matrix.otp}}
+          elixir-version: ${{matrix.elixir}}
+
+      - name: Install dependencies
+        run: mix deps.get
+
+      - name: Compile without warnings
+        run: mix compile --warnings-as-errors
+
+      - name: Run tests
+        run: mix test

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.8] - 2025-10-27
+
+### Added
+- **HTML metadata**: `HtmlHandlers.extract_html_content/2` now returns byte counts alongside grapheme totals so every caller gets accurate offsets without recomputing (#6).
+- **Examples**: New `html_metadata_examples.exs` and `windows_ci_examples.exs` scripts document the metadata workflow and Windows CI parity (#6, #7).
+
+### Fixed
+- **Syntax normalization**: Layer 3 consumes the shared metadata directly, removing duplicated byte math around HTML quoting (#6).
+
+### CI
+- **Windows coverage**: Introduced a `windows-latest` PowerShell job to the GitHub Actions matrix to run `mix deps.get`, `mix compile --warnings-as-errors`, and `mix test`, ensuring CRLF regressions are caught ahead of releases (#7).
+
 ## [0.1.7] - 2025-10-27
 
 ### Fixed
@@ -328,7 +340,8 @@ This is a **100% rewrite** - all previous code has been replaced with the new la
 - Minimal memory overhead (< 8KB for repairs)
 - All operations pass performance thresholds
 
-[Unreleased]: https://github.com/nshkrdotcom/json_remedy/compare/v0.1.7...HEAD
+[Unreleased]: https://github.com/nshkrdotcom/json_remedy/compare/v0.1.8...HEAD
+[0.1.8]: https://github.com/nshkrdotcom/json_remedy/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/nshkrdotcom/json_remedy/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/nshkrdotcom/json_remedy/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/nshkrdotcom/json_remedy/compare/v0.1.4...v0.1.5

README.md

@@ -97,6 +97,7 @@ Runs **before** the main layer pipeline to handle complex patterns that would ot
   - DOCTYPE declarations, comments, void elements
   - Self-closing tags, nested structures
   - Proper escaping of quotes, newlines, special chars
+  - Byte + grapheme metadata for consumer slices *(v0.1.8)*
 
 #### 🔧 **Hardcoded Patterns** *(ported from [json_repair](https://github.com/mangiucugna/json_repair) Python library)*
 Layer 3 includes battle-tested cleanup patterns for edge cases commonly found in LLM output:
@@ -158,7 +159,7 @@ Add JsonRemedy to your `mix.exs`:
 ```elixir
 def deps do
   [
-    {:json_remedy, "~> 0.1.7"}
+    {:json_remedy, "~> 0.1.8"}
   ]
 end
 ```
@@ -302,6 +303,15 @@ Demonstrates handling of unquoted HTML content in JSON values (common when APIs
 
 This example showcases the HTML detection and quoting capabilities added in v0.1.5, which handle real-world scenarios where API endpoints return HTML error pages instead of JSON.
 
+### 🧮 **HTML Metadata Examples** ✨ *NEW in v0.1.8*
+```bash
+mix run examples/html_metadata_examples.exs
+```
+Inspect the metadata returned when quoting HTML fragments:
+- Grapheme vs byte counts for emoji-rich HTML bodies
+- Byte-accurate offsets from non-zero starting positions
+- Guidance for integrating the metadata into downstream pipelines
+
 ### 🌍 **Real-World Scenarios**
 ```bash
 mix run examples/real_world_scenarios.exs
@@ -336,6 +346,15 @@ Verify reliability under load:
 - Large array processing
 - Memory usage stability
 
+### 🪟 **Windows CI Examples** ✨ *NEW in v0.1.8*
+```bash
+mix run examples/windows_ci_examples.exs
+```
+Validate the cross-platform pipeline:
+- Confirms the GitHub Actions workflow includes a Windows runner
+- Lists the PowerShell commands executed in CI
+- Helps contributors mirror the job locally when debugging CRLF issues
+
 ### 📊 **Example Output**
 
 Here's what you'll see when running the real-world scenarios:
@@ -1012,6 +1031,9 @@ mix dialyzer                    # Type analysis
 mix format --check-formatted    # Code formatting
 mix test.coverage               # Coverage analysis
 
+# Windows CI parity (PowerShell)
+mix run examples/windows_ci_examples.exs
+
 # Benchmarking
 mix run bench/comprehensive_benchmark.exs
 mix run bench/memory_profile.exs

examples/html_metadata_examples.exs

@@ -0,0 +1,57 @@
+# HTML Metadata Examples for JsonRemedy
+#
+# Demonstrates the new metadata returned by HtmlHandlers.extract_html_content/2
+# so that consumers can rely on both grapheme and byte measurements.
+#
+# Run with: mix run examples/html_metadata_examples.exs
+
+defmodule HtmlMetadataExamples do
+  @moduledoc """
+  Shows how to inspect the grapheme and byte counts returned when JsonRemedy
+  wraps unquoted HTML fragments. Useful when integrating with systems that need
+  byte-accurate slicing (e.g., Windows CRLF payloads or emoji-rich HTML).
+  """
+
+  alias JsonRemedy.Layer3.HtmlHandlers
+
+  def run_all_examples do
+    IO.puts("=== JsonRemedy HTML Metadata Examples ===\n")
+
+    example_1_multibyte_html_metadata()
+    example_2_offset_html_metadata()
+
+    IO.puts("\n=== Completed HTML metadata examples! ===")
+  end
+
+  defp example_1_multibyte_html_metadata do
+    IO.puts("Example 1: Metadata for multi-byte HTML fragment")
+    IO.puts("==============================================")
+
+    fragment = "<div>café 🚀</div>,\"next\""
+
+    {html, graphemes, bytes} = HtmlHandlers.extract_html_content(fragment, 0)
+
+    IO.puts("Extracted HTML: #{html}")
+    IO.puts("Graphemes consumed: #{graphemes}")
+    IO.puts("Bytes consumed: #{bytes}")
+    IO.puts("Byte/Grapheme delta: #{bytes - graphemes}")
+    IO.puts("\n" <> String.duplicate("-", 80) <> "\n")
+  end
+
+  defp example_2_offset_html_metadata do
+    IO.puts("Example 2: Metadata from non-zero starting offset")
+    IO.puts("===============================================")
+
+    payload = ~s({"body":<section data-info="café 🚀">Line</section>,"ok":true})
+    start_position = String.length(~s({"body":))
+
+    {html, graphemes, bytes} = HtmlHandlers.extract_html_content(payload, start_position)
+
+    IO.puts("Extracted HTML: #{html}")
+    IO.puts("Graphemes consumed from offset #{start_position}: #{graphemes}")
+    IO.puts("Bytes consumed from offset #{start_position}: #{bytes}")
+    IO.puts("\n" <> String.duplicate("-", 80) <> "\n")
+  end
+end
+
+HtmlMetadataExamples.run_all_examples()

examples/windows_ci_examples.exs

@@ -0,0 +1,61 @@
+# Windows CI Examples for JsonRemedy
+#
+# Highlights the new Windows job in the GitHub Actions matrix and how to
+# reproduce the steps locally on a Windows machine.
+#
+# Run with: mix run examples/windows_ci_examples.exs
+
+defmodule WindowsCIExamples do
+  @moduledoc """
+  Useful helpers for verifying JsonRemedy's Windows CI coverage:
+  - Confirms the workflow includes a `windows-latest` runner with PowerShell.
+  - Prints the exact commands the CI executes so contributors can mirror them.
+  """
+
+  @workflow_path ".github/workflows/elixir.yaml"
+
+  def run_all_examples do
+    IO.puts("=== JsonRemedy Windows CI Examples ===\n")
+
+    example_1_verify_windows_job()
+    example_2_windows_reproduction_steps()
+
+    IO.puts("\n=== Finished Windows CI examples! ===")
+  end
+
+  defp example_1_verify_windows_job do
+    IO.puts("Example 1: Verify Windows job exists in CI workflow")
+    IO.puts("===================================================")
+
+    workflow = File.read!(@workflow_path)
+    windows_job_present = String.contains?(workflow, "runs-on: windows-latest")
+    uses_pwsh = String.contains?(workflow, "shell: pwsh")
+
+    IO.puts("Windows runner configured? #{windows_job_present}")
+    IO.puts("PowerShell shell configured? #{uses_pwsh}")
+    IO.puts("\n" <> String.duplicate("-", 80) <> "\n")
+  end
+
+  defp example_2_windows_reproduction_steps do
+    IO.puts("Example 2: Commands executed on the Windows runner")
+    IO.puts("==================================================")
+
+    commands = [
+      "mix deps.get",
+      "mix compile --warnings-as-errors",
+      "mix test"
+    ]
+
+    Enum.each(commands, fn command ->
+      IO.puts("pwsh> #{command}")
+    end)
+
+    IO.puts(
+      "\nTip: Run the commands above inside a PowerShell session after installing Elixir via asdf or the official installer."
+    )
+
+    IO.puts("\n" <> String.duplicate("-", 80) <> "\n")
+  end
+end
+
+WindowsCIExamples.run_all_examples()

lib/json_remedy/layer3/character_parsers.ex

@@ -233,7 +233,8 @@ defmodule JsonRemedy.Layer3.CharacterParsers do
       char == "<" and state.expecting == :value and
           HtmlHandlers.is_html_start?(content, state.position) ->
         # Start of HTML content - quote it
-        {html_iolist, chars_consumed, repairs} = HtmlHandlers.process_html_iolist(content, state)
+        {html_iolist, chars_consumed, _bytes_consumed, repairs} =
+          HtmlHandlers.process_html_iolist(content, state)
 
         %{
           state
@@ -373,7 +374,8 @@ defmodule JsonRemedy.Layer3.CharacterParsers do
       char == "<" and state.expecting == :value and
           HtmlHandlers.is_html_start?(content, state.position) ->
         # Start of HTML content - quote it
-        {html_string, chars_consumed, repairs} = HtmlHandlers.process_html_string(content, state)
+        {html_string, chars_consumed, _bytes_consumed, repairs} =
+          HtmlHandlers.process_html_string(content, state)
 
         %{
           state

lib/json_remedy/layer3/html_handlers.ex

@@ -37,18 +37,30 @@ defmodule JsonRemedy.Layer3.HtmlHandlers do
 
   @doc """
   Extract HTML content starting from position until we hit a JSON structural delimiter.
-  Returns {html_content, chars_consumed}.
+  Returns {html_content, chars_consumed, bytes_consumed}.
 
   Strategy: Track HTML tag depth. Only stop at JSON delimiters when:
   - We're at HTML tag depth 0 (all tags closed)
   - We're at JSON depth 0 (no nested JSON-like braces)
   - We're not inside an HTML tag marker (between < and >)
   """
-  @spec extract_html_content(String.t(), non_neg_integer()) :: {String.t(), non_neg_integer()}
+  @spec extract_html_content(String.t(), non_neg_integer()) ::
+          {String.t(), non_neg_integer(), non_neg_integer()}
   def extract_html_content(content, start_position) do
     extract_html_content_recursive(content, start_position, start_position, 0, 0, false)
   end
 
+  defp finalize_html_result(content, start_pos, stop_pos) do
+    length = stop_pos - start_pos
+    raw_html = String.slice(content, start_pos, length)
+    trimmed_html = String.trim_trailing(raw_html)
+
+    chars_consumed = max(length, 0)
+    bytes_consumed = if length <= 0, do: 0, else: byte_size(raw_html)
+
+    {trimmed_html, chars_consumed, bytes_consumed}
+  end
+
   # Helper to find end of HTML comment
   defp find_comment_end(content, start_pos) do
     case :binary.match(content, "-->", scope: {start_pos, byte_size(content) - start_pos}) do
@@ -96,11 +108,11 @@ defmodule JsonRemedy.Layer3.HtmlHandlers do
          html_depth,
          inside_tag_marker
        ) do
-    if current_pos >= String.length(content) do
+    content_length = String.length(content)
+
+    if current_pos >= content_length do
       # Reached end of content
-      html = String.slice(content, start_pos..-1//1)
-      chars = String.length(html)
-      {String.trim_trailing(html), chars}
+      finalize_html_result(content, start_pos, content_length)
     else
       char = String.at(content, current_pos)
 
@@ -181,9 +193,7 @@ defmodule JsonRemedy.Layer3.HtmlHandlers do
 
         # Stop at JSON delimiters ONLY when all HTML tags are closed
         char in [",", "}", "]"] and json_depth == 0 and html_depth <= 0 and not inside_tag_marker ->
-          html = String.slice(content, start_pos..(current_pos - 1))
-          chars = current_pos - start_pos
-          {String.trim_trailing(html), chars}
+          finalize_html_result(content, start_pos, current_pos)
 
         # Track JSON-like depth (for data attributes with JSON)
         char == "{" and not inside_tag_marker ->
@@ -275,25 +285,27 @@ defmodule JsonRemedy.Layer3.HtmlHandlers do
 
   @doc """
   Process HTML content for IO list version.
-  Returns {html_iolist, chars_consumed, repairs}.
+  Returns {html_iolist, chars_consumed, bytes_consumed, repairs}.
   """
-  @spec process_html_iolist(String.t(), map()) :: {iodata(), non_neg_integer(), list()}
+  @spec process_html_iolist(String.t(), map()) ::
+          {iodata(), non_neg_integer(), non_neg_integer(), list()}
   def process_html_iolist(content, state) do
-    {html, chars_consumed} = extract_html_content(content, state.position)
+    {html, chars_consumed, bytes_consumed} = extract_html_content(content, state.position)
     {quoted_html, repairs} = quote_html_content(html, state.position)
 
-    {quoted_html, chars_consumed, repairs}
+    {quoted_html, chars_consumed, bytes_consumed, repairs}
   end
 
   @doc """
   Process HTML content for regular string version.
-  Returns {html_string, chars_consumed, repairs}.
+  Returns {html_string, chars_consumed, bytes_consumed, repairs}.
   """
-  @spec process_html_string(String.t(), map()) :: {String.t(), non_neg_integer(), list()}
+  @spec process_html_string(String.t(), map()) ::
+          {String.t(), non_neg_integer(), non_neg_integer(), list()}
   def process_html_string(content, state) do
-    {html, chars_consumed} = extract_html_content(content, state.position)
+    {html, chars_consumed, bytes_consumed} = extract_html_content(content, state.position)
     {quoted_html, repairs} = quote_html_content(html, state.position)
 
-    {quoted_html, chars_consumed, repairs}
+    {quoted_html, chars_consumed, bytes_consumed, repairs}
   end
 end

lib/json_remedy/layer3/syntax_normalization.ex

@@ -806,25 +806,18 @@ defmodule JsonRemedy.Layer3.SyntaxNormalization do
           HtmlHandlers.is_html_start?(<<char::utf8, rest::binary>>, 0) ->
         # Start of HTML content - quote it
         fragment = <<char::utf8, rest::binary>>
-        {html_content, chars_consumed} = HtmlHandlers.extract_html_content(fragment, 0)
+
+        {html_content, chars_consumed, bytes_consumed} =
+          HtmlHandlers.extract_html_content(fragment, 0)
 
         {quoted_html, html_repairs} = HtmlHandlers.quote_html_content(html_content, pos)
 
-        consumed_fragment = String.slice(fragment, 0, chars_consumed)
-        bytes_consumed = byte_size(consumed_fragment)
-        bytes_for_rest = max(bytes_consumed - byte_size(<<char::utf8>>), 0)
+        fragment_size = byte_size(fragment)
 
         remaining =
-          if bytes_for_rest <= 0 do
-            rest
-          else
-            rest_size = byte_size(rest)
-
-            if bytes_for_rest >= rest_size do
-              <<>>
-            else
-              binary_part(rest, bytes_for_rest, rest_size - bytes_for_rest)
-            end
+          cond do
+            bytes_consumed >= fragment_size -> <<>>
+            true -> binary_part(fragment, bytes_consumed, fragment_size - bytes_consumed)
           end
 
         normalize_syntax_binary_simple(

mix.exs

@@ -1,7 +1,7 @@
 defmodule JsonRemedy.MixProject do
   use Mix.Project
 
-  @version "0.1.7"
+  @version "0.1.8"
   @source_url "https://github.com/nshkrdotcom/json_remedy"
 
   def project do