perf(compression/code): avoid a UTF-8 copy per code block in byte-to-char mapping (#3169)

## Description

`CodeStructureHandler._byte_spans_to_char_spans` converts tree-sitter's
byte offsets to character offsets for each compressed code block. Its
ASCII fast path was:

```python
n_bytes = len(content.encode("utf-8"))
if n_bytes == len(content):
    return spans
```

`content.encode("utf-8")` allocates a full UTF-8 byte copy of the whole
code block, which is then discarded — just to compare its length against
`len(content)`. For the common case (ASCII source, byte == char),
`content.isascii()` answers the same question in C with no allocation.

The non-ASCII branch additionally re-encoded **every character** in the
loop (`len(ch.encode("utf-8"))`) to get its UTF-8 width — one small
allocation per character. A character's width (1-4 bytes) is fully
determined by its code point, so it can be derived with `ord(ch)` and no
encoding.

This runs per code block on the compression path, so for code-heavy
traffic the discarded per-block allocation adds up. Output is
byte-for-byte identical.

Benchmark (`_byte_spans_to_char_spans` on a ~20 KB ASCII block, mean of
20000 calls):

```
old (len(encode) == len) : 0.45 us/call  (+ a 20 KB bytes allocation)
new (isascii())          : 0.06 us/call  (~7x faster, no allocation)
```

Correctness was verified by comparing the old and new implementations on
mixed content (`café 🚀 语言` — 2/4/3-byte characters): the remapped span
offsets are identical.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [x] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/compression/handlers/code_handler.py`
(`_byte_spans_to_char_spans`): use `content.isascii()` for the fast-path
check (no UTF-8 allocation), and derive each character's UTF-8 width
from its code point instead of re-encoding it per character.
- `tests/test_compression/test_code_handler.py`: added
`TestByteSpanToCharSpan` — ASCII spans returned unchanged, and non-ASCII
byte offsets (café / rocket / CJK) remapped to the correct character
offsets including the exclusive-end boundary.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality

### Test Output

```text
tests/test_compression/test_code_handler.py  ->  24 passed, 8 skipped (tree-sitter not installed)
uvx ruff@0.16.2 check headroom/compression/handlers/code_handler.py tests/test_compression/test_code_handler.py  ->  All checks passed!
uvx mypy@1.20.2 headroom/compression/handlers/code_handler.py  ->  Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1,
ruff 0.16.2 and mypy 1.20.2 via uvx.
- Exact command / steps: ran the old and new implementations side by
side on ASCII and on mixed non-ASCII content (`café 🚀 语言`) and confirmed
identical remapped span offsets; benchmarked the ASCII path (0.45us ->
0.06us, ~7x, and the new path allocates nothing). Added the regression
test and ran the file.
- Observed result: identical span mapping; the per-block UTF-8
allocation on the ASCII fast path is gone, and the non-ASCII loop no
longer allocates per character.
- Not tested: an end-to-end code-compression request through
`UniversalCompressor`; the static helper is exercised directly with
byte-offset spans, which is exactly what tree-sitter feeds it.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. This is an internal offset-mapping
helper in the code structure handler, not a rollout-channel-gated
runtime feature.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: no. The returned spans are identical
for ASCII and non-ASCII content; only the work done to compute them is
cheaper.
- Kill switch / disable path: N/A.
- Unsafe override required: no.
- Qualification impact: less per-block allocation/CPU when mapping code
spans; identical output.
- Rollback path: revert this PR; the helper returns to encoding the
content for the length check and per-character.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation (N/A:
internal helper, output unchanged)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

Scope is deliberately small and behavior-preserving: `content.isascii()`
is exactly equivalent to "every UTF-8 byte is one character," and the
code-point width table (`<0x80 -> 1`, `<0x800 -> 2`, `<0x10000 -> 3`,
else `4`) matches Python's UTF-8 encoding for every `str` character.
This commit is contained in:
Abhay Singh
2026-09-30 11:28:39 -05:00
committed by GitHub
parent c719d4af55
commit d5e5534b47
2 changed files with 49 additions and 4 deletions
+12 -4
View File
@@ -605,16 +605,24 @@ class CodeStructureHandler(BaseStructureHandler):
returned unchanged. Otherwise a byte->char table is built once
and every span endpoint is remapped.
"""
n_bytes = len(content.encode("utf-8"))
if n_bytes == len(content):
# ASCII fast path: every byte is one character, so tree-sitter's byte
# offsets are already character offsets. ``content.isascii()`` checks
# this in C without allocating, where ``len(content.encode("utf-8"))``
# built (and discarded) a full UTF-8 copy of the content on every code
# block just to compare lengths.
if content.isascii():
return spans
# byte_to_char[b] = index of the character containing byte b;
# byte_to_char[n_bytes] = len(content) so exclusive ends map.
# byte_to_char[n_bytes] = len(content) so exclusive ends map. A
# character's UTF-8 width is derived from its code point (1-4 bytes)
# rather than re-encoding every character individually in the loop.
n_bytes = len(content.encode("utf-8"))
byte_to_char = [0] * (n_bytes + 1)
byte_pos = 0
for char_idx, ch in enumerate(content):
ch_width = len(ch.encode("utf-8"))
cp = ord(ch)
ch_width = 1 if cp < 0x80 else 2 if cp < 0x800 else 3 if cp < 0x10000 else 4
for b in range(byte_pos, byte_pos + ch_width):
byte_to_char[b] = char_idx
byte_pos += ch_width
@@ -353,3 +353,40 @@ class TestTreeSitterContainers:
f"class code preserved {result.preservation_ratio:.0%} — "
"container bodies are leaking into the structural mask"
)
class TestByteSpanToCharSpan:
"""_byte_spans_to_char_spans must map tree-sitter byte offsets to character
offsets. The ASCII fast path returns spans unchanged (byte == char) without
allocating a UTF-8 copy; the non-ASCII path derives each character's width
from its code point instead of re-encoding it."""
def test_ascii_returns_spans_unchanged(self):
from headroom.compression.handlers.code_handler import CodeSpan
spans = [
CodeSpan(start=0, end=5, role="sig", is_structural=True),
CodeSpan(start=6, end=11, role="body", is_structural=False),
]
out = CodeStructureHandler._byte_spans_to_char_spans(spans, "def f():\n pass\n")
assert [(s.start, s.end) for s in out] == [(0, 5), (6, 11)]
def test_non_ascii_remaps_byte_offsets_to_char_offsets(self):
from headroom.compression.handlers.code_handler import CodeSpan
# café (é = 2 bytes), 🚀 (4 bytes), 语言 (3 bytes each).
content = "x = 'café 🚀 语言'\n"
enc = content.encode("utf-8")
# A structural span covering the whole line, plus one covering 'return'-like
# region: give byte offsets and expect character offsets back.
whole = CodeSpan(start=0, end=len(enc), role="body", is_structural=True)
# byte offset of the closing quote vs its character offset
quote_byte = enc.rindex(b"'")
quote_char = content.rindex("'")
marker = CodeSpan(start=quote_byte, end=len(enc), role="sig", is_structural=True)
out = CodeStructureHandler._byte_spans_to_char_spans([whole, marker], content)
assert out[0].start == 0
assert out[0].end == len(content) # exclusive end maps to char length
assert out[1].start == quote_char # byte offset correctly remapped
assert out[1].end == len(content)