feat(schema): add v2 Span model + line/col→byte-offset helper

Author: rahlk

codeanalyzer/schema/py_schema.py

@@ -22,7 +22,7 @@
 from __future__ import annotations
 import inspect
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 import gzip
 
 from pydantic import BaseModel
@@ -168,6 +168,29 @@ def build(self):
     return cls
 
 
+def byte_offsets(source: str, start_line: int, start_col: int,
+                 end_line: int, end_col: int) -> Tuple[int, int]:
+    """Convert (1-based line, 0-based col) ast positions to utf-8 byte offsets
+    into `source`. `col` is a character offset within the line (ast semantics);
+    we re-encode the line prefix to bytes so multibyte chars are handled."""
+    lines = source.splitlines(keepends=True)
+    def offset(line: int, col: int) -> int:
+        prefix_bytes = len("".join(lines[: line - 1]).encode("utf-8"))
+        col_bytes = len(lines[line - 1][:col].encode("utf-8")) if line - 1 < len(lines) else 0
+        return prefix_bytes + col_bytes
+    return offset(start_line, start_col), offset(end_line, end_col)
+
+
+@builder
+@msgpk
+class Span(BaseModel):
+    """Where a node lives in source. `start`/`end` are [line, col] (1-based line,
+    0-based col, ast semantics); `bytes` are utf-8 offsets into module.source."""
+    start: Tuple[int, int]
+    end: Tuple[int, int]
+    bytes: Tuple[int, int]
+
+
 @builder
 @msgpk
 class PyImport(BaseModel):

test/test_v2_source_spans.py

@@ -0,0 +1,14 @@
+from codeanalyzer.schema.py_schema import byte_offsets
+
+
+def test_byte_offsets_slice_source_exactly():
+    source = "def f():\n    return 1\n"
+    # `return 1` is line 2, cols 4..12 (0-based, end exclusive per ast end_col_offset)
+    lo, hi = byte_offsets(source, 2, 4, 2, 12)
+    assert source.encode("utf-8")[lo:hi].decode("utf-8") == "return 1"
+
+
+def test_byte_offsets_multibyte_safe():
+    source = "x = 'é'\ny = 2\n"  # 'é' is 2 bytes in utf-8
+    lo, hi = byte_offsets(source, 2, 0, 2, 5)
+    assert source.encode("utf-8")[lo:hi].decode("utf-8") == "y = 2"