antlrope 1.0.0__tar.gz

antlrope-1.0.0/.clang-format

@@ -0,0 +1,12 @@
+# C++ formatting for cpp/ (run `pixi run format-cpp`). Matches the code's
+# existing LLVM-ish style (attached braces, right-aligned pointers, 80 columns)
+# with a 4-space indent, and puts one argument per line for any call or
+# declaration whose arguments do not fit on a single line.
+BasedOnStyle: LLVM
+IndentWidth: 4
+AccessModifierOffset: -4
+ColumnLimit: 80
+BinPackArguments: false
+BinPackParameters: false
+# The existing code separates trailing comments with two spaces.
+SpacesBeforeTrailingComments: 2

antlrope-1.0.0/.claude/CLAUDE.md

@@ -0,0 +1,112 @@
+# antlr-pyfacade — project context
+
+A fast, C++-accelerated ANTLR runtime for Python with **no per-grammar C/C++
+compilation by the user**. It drives the official ANTLR4 C++ runtime from the
+serialized ATN that the stock `-Dlanguage=Python3` ANTLR tool already emits, and
+hands Python a single bulk, filtered int32 event stream instead of a per-node
+parse-tree walk. Users generate a parser with the normal ANTLR tool, install this
+package, generate a small facade, and write a pure-Python event listener.
+
+## Layout
+
+- `src/antlr_pyfacade/` — the Python package (src/ layout).
+  - `specs.py` — `load_specs(LexerCls, ParserCls)` / `load_lexer_spec` read ATN +
+    metadata off the stock-generated Python lexer/parser classes; the
+    grammar-agnostic bridge.
+  - `base.py` — `FacadeListener` (base of every generated facade) and its
+    `drive()` method: introspects which callbacks a subclass overrides, builds
+    native rule/token masks, runs the event loop. Also `Chunk` and the
+    `walk_parallel` thread-pool driver.
+  - `chunking.py` — the chunkers that produce `Chunk`s for `walk_parallel`:
+    `split_on_token` / `split_between_tokens` (token), `split_on_pattern` /
+    `chunk_by_pattern` (regex), `chunk_by_rule` (grammar rule), `stream_on_token` /
+    `stream_on_pattern` (bounded-memory streaming), and `lex`.
+  - `location.py` — `SourceMap` (char offset ↔ line/column).
+  - `generate.py` — the `antlr-pyfacade` console script; emits a
+    `<Grammar>EventListener` base class from a generated parser module.
+- `cpp/` — the nanobind extension sources (`binding.cpp`, `events.h`); module
+  name `_native`.
+- `vendor/antlr4-cpp/` — vendored ANTLR4 C++ runtime sources. **BSD-3-Clause**,
+  kept separate from the package's own Apache-2.0 license. See its `UPDATING.md`
+  before refreshing the snapshot.
+- `examples/json/`, `examples/predicate/` — end-to-end examples that double as
+  test fixtures.
+- `tests/`, `docs/` (Zensical site, config in `zensical.toml`).
+
+## Event stream
+
+Records are `(kind, payload, start, stop)` int32, decoded via
+`struct.iter_unpack("<4i", raw)`. `kind`: `0=ENTER_RULE, 1=EXIT_RULE,
+2=TERMINAL, 3=ERROR`. `payload` is the rule index or token type. Token text is
+recovered Python-side by slicing `text[start:stop + 1]` — no strings cross the
+boundary. Only overridden rules/tokens are emitted (native filtering).
+
+## Dev workflow (pixi)
+
+```sh
+pixi install            # solve + build the editable extension
+pixi run build          # rebuild _native after editing cpp/ or vendor/ (cmake)
+pixi run test           # pytest suite
+pixi run example        # JSON reconstruction example
+pixi run docs-build     # build the docs site into site/
+pixi run stubgen        # regenerate _native.pyi after binding API changes
+pixi run gen-json       # regenerate the JSON example parser (gen env, needs JDK)
+pixi run gen-facade     # regenerate the JSON facade
+```
+
+Environments: `default` (Python build + test, no JDK), `gen` (openjdk + ANTLR
+tool, isolated), `docs` (Zensical, no default feature), `recipe` (rattler-build).
+The editable install uses `no-build-isolation`, so cmake/ninja must be on PATH —
+they come from the pixi env.
+
+## Build
+
+scikit-build-core + nanobind + CMake. `editable.rebuild = false` — imports never
+invoke the toolchain (so the package imports from any interpreter, even an
+unactivated IDE prefix); after editing `cpp/` or `vendor/`, recompile explicitly
+with `pixi run build` (a cmake build+install via `scripts/build_native.py`).
+`wheel.packages = ["src/antlr_pyfacade"]`. Extension built with `STABLE_ABI` (abi3
+only materializes on CPython 3.12+; older build per-version).
+`MACOSX_DEPLOYMENT_TARGET = 11.0`. Minimum Python is **3.10** — use modern typing
+(`list[...]`, `X | None`, `collections.abc` over `typing`).
+
+Version is single-sourced in `src/antlr_pyfacade/VERSION` (pyproject reads it
+dynamically; `antlr_pyfacade.__version__` reads it via `importlib.resources`). The
+compiled `_native` module has a checked-in stub `src/antlr_pyfacade/_native.pyi`
+(IDEs/type-checkers can't follow the editable redirector) — after changing the
+binding's public interface, run `pixi run stubgen` (it re-applies the hand edits
+automatically via `scripts/stubgen.py`).
+
+## Known limitation
+
+The pure-ATN interpreter **cannot evaluate target-language semantic predicates
+(`{...}?`) or embedded actions (`{...}`)** — predicates are treated as true.
+Grammars depending on them won't parse correctly. This is pinned by
+`tests/test_predicate_limitation.py` and documented loudly; keep it that way.
+
+## Conventions
+
+- Default branch is `dev`.
+- Bump the patch in `src/antlr_pyfacade/VERSION` and add a `CHANGELOG.md` entry on
+  every commit that changes runtime behavior or user-facing docs (`README`,
+  `docs/`); build/test/tooling-only changes don't bump. See `CONTRIBUTING.md`.
+- Hand-authored `.py`/`.cpp` files carry the Apache-2.0 header; docstrings use
+  mkdocstrings/Markdown style (single backticks, Google-style sections) — no
+  reStructuredText roles or `::` directives. Cross-references are
+  `[title][antlr_pyfacade.Symbol]` with a **plain** title — never backtick the
+  title. `` [`title`][ref] `` renders the title as inline code, which hides that
+  it's a clickable link. (Backticks remain correct for inline code that is *not* a
+  cross-reference.)
+- Package license is **Apache-2.0**; the vendored runtime under `vendor/` stays
+  **BSD-3-Clause** — never relicense vendored code.
+- Public docs (README, `docs/`) compare only against alternatives the reader
+  actually has (the official `antlr4-python3-runtime`). No internal research
+  context, no testbed names.
+- Dev/build details live in `CONTRIBUTING.md`, not the README.
+- `docs/llms.txt` is a hand-written LLM summary published verbatim at the doc-site
+  root (`/llms.txt`) for coding agents. It is not generated and `docs-build` won't
+  flag it as stale, so keep it in sync when the public API (`__all__`), the
+  generate→facade→`walk` workflow, install steps, or the doc page set / `site_url`
+  change. (It lives in `docs/`, so updating it bumps the version.)
+- Never commit `.idea/`. Only commit when explicitly asked; never push without
+  asking; never skip git hooks.

antlrope-1.0.0/.gitattributes

@@ -0,0 +1,7 @@
+# Check out text files with LF everywhere (overrides Windows autocrlf): tests
+# and the streaming chunkers treat file contents verbatim, so CRLF working
+# copies would shift every character offset the fixtures assert.
+* text=auto eol=lf
+
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff

antlrope-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: ci
+
+# Run the test suite, and a memory-safety pass with AddressSanitizer. The ASan
+# leg builds the extension (and a C++ harness) with -fsanitize=address — it is
+# what would have caught the DFA-edge heap overflow that normal builds missed.
+
+# Runs on every branch push so work on any feature/dev branch is validated.
+# (Same-repo branch pushes are covered here; re-add a `pull_request:` trigger if
+# the project starts taking pull requests from forks.)
+on:
+  push:
+    branches: ["**"]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.1
+        with:
+          environments: default
+          cache: true
+      - run: pixi run build
+      # Run the suite under coverage (only src/ is measured); the summary lands in
+      # the job log and the HTML/JSON artifacts in .coverage/.
+      - run: pixi run coverage
+      # Smoke-test the worked examples end to end (both OSes), so a runtime change
+      # that breaks them — or their checked-in generated parsers/facades — is caught.
+      - name: Examples
+        run: |
+          pixi run example
+          pixi run example-schema
+
+  # The pixi workspace covers linux/macOS only, but wheels.yml ships Windows
+  # (amd64) wheels — so run the suite on Windows via a plain pip build: MSVC on
+  # the runner compiles the extension, scikit-build-core pulls cmake/ninja from
+  # PyPI. This is what validates the Windows wheels beyond an import smoke test.
+  test-windows:
+    name: tests (windows-latest)
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      # 3.14 matches the pixi dev env, so version-sensitive argparse help
+      # rendering (tests/test_cli_docs.py compares against the committed
+      # reference) agrees. The 3.12 abi3 floor is covered by cibuildwheel's
+      # per-wheel import test.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Build and install
+        run: pip install . pytest
+      # Run from the repo (tests/ + examples/ fixtures), against the installed
+      # package (no src layout conflict: the extension lives in site-packages).
+      - name: Test
+        run: python -m pytest tests -q
+
+  asan:
+    name: addresssanitizer (linux)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.1
+        with:
+          environments: default
+          cache: true
+      # Portable C++ harness over the example grammars (also runnable on macOS).
+      - name: ASan C++ harness
+        run: pixi run asan-test
+      # Full pytest suite under ASan — covers the nanobind binding too (Linux).
+      - name: pytest under ASan
+        run: pixi run asan-pytest

antlrope-1.0.0/.github/workflows/docs-deploy.yml

@@ -0,0 +1,33 @@
+name: docs
+
+# Deploy the versioned documentation site to gh-pages when a release tag is
+# pushed (the same trigger that publishes wheels to PyPI), or on demand via
+# workflow_dispatch. `pixi run docs-deploy` runs mike, which builds the site
+# with zensical and commits it to gh-pages under the release's major.minor
+# with the `latest` alias — patch releases overwrite their minor in place.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write # mike pushes to the gh-pages branch
+
+jobs:
+  deploy:
+    name: deploy versioned docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # mike needs the gh-pages branch history
+      - uses: prefix-dev/setup-pixi@v0.8.1
+        with:
+          environments: docs
+          cache: true
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - run: pixi run docs-deploy

antlrope-1.0.0/.github/workflows/wheels.yml

@@ -0,0 +1,69 @@
+name: wheels
+
+# Build wheels and an sdist on pushes to main (no publish), and publish to PyPI
+# when a version tag is pushed. Development happens on `dev`, which is covered by
+# the lighter `ci` workflow; the full multi-platform wheel build only runs once
+# work lands on main. cibuildwheel compiles the vendored ANTLR C++ runtime for
+# each platform/CPython; scikit-build-core fetches cmake/ninja.
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build_wheels:
+    name: wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # ubuntu-latest = manylinux x86_64; ubuntu-24.04-arm = native manylinux
+        # aarch64 (free ARM runner, no QEMU); macos-15-intel = x86_64 (the last
+        # free Intel image — macos-13 was retired and its jobs queue forever);
+        # macos-14 = arm64; windows-latest = amd64. cibuildwheel infers the
+        # wheel arch from the runner.
+        os:
+          [ubuntu-latest, ubuntu-24.04-arm, macos-15-intel, macos-14, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21
+        env:
+          MACOSX_DEPLOYMENT_TARGET: "11.0"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        run: pipx run build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: publish to PyPI
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    # Only on a version tag. Uses Trusted Publishing (OIDC) — configure the
+    # publisher on PyPI; no API token secret required.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

antlrope-1.0.0/.gitignore

@@ -0,0 +1,41 @@
+# Build artifacts
+/build/
+# Standalone build dir for scripts/bench_runtime_patches.py (runtime-patch A/B/C)
+/build-bench/
+/dist/
+# rattler-build output (the recipe-build task)
+/output/
+# Coverage artifacts (pixi run coverage): data file, HTML site, JSON report
+/.coverage/
+# Zensical documentation site output
+/site/
+/.zensical/
+*.so
+*.pyd
+*.egg-info/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+# AddressSanitizer build dirs (scripts/asan_pytest.py, scripts/asan_harness.py)
+/build-asan/
+/tests/asan/build/
+
+# ANTLR tool side outputs (the gen-* tasks): token maps and IDE/TestRig
+# interpreter data the examples never use (no ANTLR flag suppresses them).
+examples/*/generated/*.tokens
+examples/*/generated/*.interp
+
+# Editors
+.idea/
+.vscode/
+.DS_Store
+
+# Claude Code local settings (CLAUDE.md is committed; local overrides are not)
+.claude/settings.local.json
+
+# Env
+.venv/
+.pixi/
+# pixi environments
+.pixi/*
+!.pixi/config.toml

antlrope-1.0.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and from 1.0 the project
+follows semantic versioning (see the version policy in
+[CONTRIBUTING.md](CONTRIBUTING.md)).
+
+## [1.0.0] - 2026-07-08
+
+First stable release. **Antlrope** is a fast, C++-accelerated ANTLR runtime for
+Python: it drives the official ANTLR4 C++ runtime's ATN interpreter directly from
+the serialized ATN that the stock `-Dlanguage=Python3` ANTLR tool already emits —
+no per-grammar codegen, nothing to compile — and delivers the parse to Python as
+one bulk, filtered event stream instead of a per-node tree walk (typically 10–20×
+the official pure-Python runtime). The public API — `FacadeListener` and its
+generated `<Grammar>EventListener` facades, `walk` / `walk_parallel`, the chunking
+and streaming family, and the `antlrope` command group — is stable as of this
+release.
+
+Final pre-release polish (over the 0.x history below):
+
+### Changed
+- The CLI prints a clean one-line error (exit status 2) for bad input — an
+  unimportable module, a module that is not a generated parser, an unreadable or
+  unwritable file — instead of a Python traceback.
+- `FacadeListener.rule_name` now raises `IndexError` for any out-of-range rule
+  index; previously a negative index silently wrapped from the end.
+
+### Added
+- Release engineering: complete PyPI metadata (development-status classifier,
+  documentation/changelog/issue URLs), a documented release procedure
+  ([RELEASING.md](RELEASING.md)), automated versioned-docs deployment on release
+  tags, and a Windows CI job running the full test suite (Windows wheels were
+  previously only import-smoke-tested).
+
+## 0.x development history
+
+The 0.x versions (0.1.0 2026-05-31 through 0.2.28 2026-06-28) were development
+builds, never published to PyPI. Condensed highlights, roughly in order:
+
+- **Engine** (0.1.0): the bulk filtered event stream over a vendored ANTLR4 C++
+  runtime — parse in C++, cross into Python once with `(kind, payload, start,
+  stop)` int32 records, filter unsubscribed rules/tokens natively; GIL released
+  during the parse; `py.typed` + a checked-in `_native` stub. Two runtime patches
+  written for upstream: lock-free DFA-edge reads and per-DFA write locks (shared
+  specs scale across threads instead of running slower than serial). A
+  heap-buffer-overflow in the patched DFA-edge cache was found and fixed under
+  AddressSanitizer, which the CI now runs routinely.
+- **Facade**: generated `<Grammar>EventListener` classes with per-rule callbacks,
+  token-type constants (symbolic plus ANTLR's positional `T__n` literal names),
+  and baked-in lexer/parser — `listener.walk(text)` needs no class arguments.
+  `walk_parallel` parses chunks across cores as a lazy, order-preserving iterator.
+  Consumer helpers grew in: `depth` / `rule_stack` / `current_rule`, `text`,
+  `token_name` / `rule_name`, `line_col` / `span` / `sourcename`, collected
+  `syntax_errors` (now `ParseError` exceptions), and the
+  `enterEveryRule` / `exitEveryRule` hooks.
+- **Chunking family**: token-aware `split_on_token` / `split_between_tokens` over
+  a C++ `lex` pass; regex `split_on_pattern` / `chunk_by_pattern`; structural
+  `chunk_by_rule`; and bounded-memory streaming counterparts `stream_on_token`,
+  `stream_on_pattern`, and `stream_by_rule` (which fails loudly on malformed
+  record sequences). All yield positioned `Chunk`s with optional `sourcename`;
+  `trim=False` preserves whitespace terminators.
+- **API consolidation**: the chunkers and spec handling moved onto
+  `FacadeListener`; the low-level layer (event buffers, native specs, typing
+  protocols, the `cached=` option) went private, leaving a seven-name public
+  surface plus a `clear_cache()` escape hatch.
+- **CLI**: grew from a single generator command into the `antlrope` command group
+  — `gen` (with a deterministic origin header), `regen` and `up-to-date`
+  (regenerate / staleness-check from that header), `check` (flag semantic
+  predicates and embedded actions the ATN interpreter cannot run), and `rules` /
+  `tokens` introspection.
+- **Packaging**: renamed from `antlr-pyfacade` to **antlrope** (0.2.0); Python
+  floor raised to 3.12 so a single Stable-ABI (`cp312-abi3`) wheel per platform
+  covers 3.12+ (Linux x86_64/aarch64, macOS x86_64/arm64, Windows amd64).
+- **Docs**: the zensical + mkdocstrings site (user guide, examples, glossary,
+  generated API and CLI references), an LLM-oriented `llms.txt`, and the SystemRDL
+  benchmark: ~21× the pure-Python runtime and ~8× the speedy-antlr accelerator
+  end-to-end on a 2.6 MB input, at lower peak memory.

antlrope-1.0.0/CMakeLists.txt

@@ -0,0 +1,54 @@
+cmake_minimum_required(VERSION 3.21)
+project(antlrope LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# The ANTLR4 C++ runtime sources are vendored into the repo (see
+# vendor/antlr4-cpp/UPDATING.md). Self-contained so the sdist builds with no
+# external checkout. Override with -DANTLR4_CPP_SRC=... only for development.
+set(ANTLR4_CPP_SRC "${CMAKE_CURRENT_SOURCE_DIR}/vendor/antlr4-cpp/src"
+    CACHE PATH "Path to ANTLR4 C++ runtime src directory")
+
+if (NOT EXISTS "${ANTLR4_CPP_SRC}/ParserInterpreter.cpp")
+  message(FATAL_ERROR "ANTLR4_CPP_SRC does not point at the C++ runtime src: ${ANTLR4_CPP_SRC}")
+endif()
+
+file(GLOB antlr4_runtime_SRC
+  "${ANTLR4_CPP_SRC}/*.cpp"
+  "${ANTLR4_CPP_SRC}/atn/*.cpp"
+  "${ANTLR4_CPP_SRC}/dfa/*.cpp"
+  "${ANTLR4_CPP_SRC}/internal/*.cpp"
+  "${ANTLR4_CPP_SRC}/misc/*.cpp"
+  "${ANTLR4_CPP_SRC}/support/*.cpp"
+  "${ANTLR4_CPP_SRC}/tree/*.cpp"
+  "${ANTLR4_CPP_SRC}/tree/pattern/*.cpp"
+  "${ANTLR4_CPP_SRC}/tree/xpath/*.cpp"
+)
+
+# Request the Stable ABI (Limited API) component too, so nanobind's STABLE_ABI
+# can build an abi3 extension. scikit-build-core sets SKBUILD_SABI_COMPONENT to
+# "Development.SABIModule" when [tool.scikit-build] wheel.py-api is configured
+# (the wheel builds); it is empty for a plain local cmake build (pixi run build),
+# which then produces a normal version-specific extension. Without this component
+# nanobind silently falls back to a full-ABI build and the wheel is mis-tagged.
+find_package(Python 3.12 REQUIRED
+  COMPONENTS Interpreter Development.Module ${SKBUILD_SABI_COMPONENT})
+find_package(nanobind CONFIG REQUIRED)
+find_package(Threads REQUIRED)
+
+nanobind_add_module(_native STABLE_ABI
+  cpp/binding.cpp
+  ${antlr4_runtime_SRC}
+)
+
+target_compile_definitions(_native PRIVATE ANTLR4CPP_STATIC)
+target_include_directories(_native PRIVATE
+  "${ANTLR4_CPP_SRC}"
+  "${ANTLR4_CPP_SRC}/tree/pattern"
+  "${ANTLR4_CPP_SRC}/tree/xpath"
+)
+target_link_libraries(_native PRIVATE Threads::Threads)
+
+install(TARGETS _native LIBRARY DESTINATION antlrope)

antlrope-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,154 @@
+# Contributing
+
+Thanks for your interest in improving `antlrope`. This page covers the
+local development setup; for what the package does and how to use it, see the
+[README](README.md) and the [docs](docs/index.md).
+
+## Development environment
+
+This project uses [pixi](https://pixi.sh). The toolchain (C++ compiler, CMake,
+Ninja, nanobind, scikit-build-core) comes from the pixi environment, so the
+editable `editable.rebuild` hook always finds a persistent CMake on `PATH`.
+
+```sh
+pixi install            # solve + build the editable extension
+pixi run build          # rebuild the _native C++ extension after editing C++
+pixi run test           # run the pytest suite
+pixi run example        # run the JSON reconstruction example
+pixi run docs-serve     # preview the docs site at http://localhost:8000
+pixi run docs-build     # build the static docs site into site/
+```
+
+## Environments
+
+- **default** — Python build + test toolchain (no JDK); `pixi run test` lives here.
+- **gen** — adds `openjdk` + the ANTLR tool, isolated from the runtime envs.
+  Regenerate the example from the grammar with `pixi run gen-json` (re-runs the
+  ANTLR Python target on `examples/json/JSON.g4`) and `pixi run gen-facade`.
+- **docs** — [Zensical](https://zensical.org) static site generator, isolated
+  with no default feature so building the docs pulls neither the JDK nor the C++
+  toolchain. Configured by `zensical.toml`; output goes to `site/` (gitignored).
+
+## The native extension and its type stub
+
+The C++ engine is the nanobind module `antlrope._native`, built from
+`cpp/binding.cpp` against the vendored runtime. The C++ rarely changes, so it is
+**not** rebuilt on import (`editable.rebuild = false`). After editing anything
+under `cpp/` or `vendor/antlr4-cpp/`, recompile explicitly:
+
+```sh
+pixi run build      # incremental cmake build + install (scripts/build_native.py)
+```
+
+Then `pixi run test` runs against the fresh build. Because import never invokes
+the build toolchain, the package imports fine from any interpreter — including an
+IDE that points at `.pixi/envs/default` without activating it (e.g. PyCharm using
+the env prefix as a plain interpreter); no `cmake` on `PATH` is required.
+
+`_native` is a compiled module loaded through scikit-build-core's editable
+redirector, which IDEs and type checkers cannot follow. A checked-in stub,
+`src/antlrope/_native.pyi`, gives them the interface (and the `py.typed`
+marker advertises the package as typed). If you change the **public interface** of
+`cpp/binding.cpp` — add or rename a class, method, or function, or change a
+signature — rebuild, then regenerate the stub:
+
+```sh
+pixi run build
+pixi run stubgen
+```
+
+`pixi run stubgen` runs `scripts/stubgen.py`, which invokes nanobind's stubgen and
+then re-applies the edits nanobind cannot infer — the license header and the
+`parse_events` / `lex` return types — so the committed stub is produced directly.
+To change those edits, edit `scripts/stubgen.py`, not the `.pyi`.
+
+## Naming the product
+
+In prose, the product is **Antlrope** (capitalized). Render it **bold on the first
+mention in a page or section** and plain capitalized (`Antlrope`) afterwards. Reserve
+the lowercase, backticked `` `antlrope` `` form for the literal Python module
+(`from antlrope import …`), the CLI command (`antlrope gen`), or the package id in an
+install command (`pip install antlrope`). Headings, the site/README title, URLs, the
+logo wordmark, and code stay lowercase.
+
+## Docstrings
+
+Docstrings are rendered into the API docs by mkdocstrings, which resolves
+cross-references written as `[title][path.to.symbol]` (e.g.
+`[walk_parallel][antlrope.FacadeListener.walk_parallel]`).
+
+**Do not wrap the cross-reference title in backticks.** Write `[title][ref]`, not
+`` [`title`][ref] ``. Backticks render the title as inline code, which visually
+hides that the text is a clickable link — the reference still resolves, but
+readers can't tell it's a link. Plain `[title][ref]` renders as a normal styled
+link. Backticks are still correct for inline code that is *not* a cross-reference
+(a parameter or type name with no `][ref]` after it).
+
+## `llms.txt`
+
+`docs/llms.txt` is a hand-written, LLM-oriented summary of the library (install, the
+generate → facade → `walk` workflow, the listener model, the public API, and doc
+links), published verbatim at the doc-site root (`/llms.txt`) for coding agents — see
+[llmstxt.org](https://llmstxt.org/). It is **not generated**, so keep it in sync when
+any of these change: the public API (`__all__`), the workflow or listener model,
+install instructions, the supported Python/platform versions, or the doc page set and
+`site_url` (its doc links are absolute). It is excluded from the rendered docs — no
+nav, search, or sitemap — so `pixi run docs-build` will **not** flag it as stale.
+
+## CLI reference
+
+The command reference in `docs/reference/cli.md` (the region between the
+`gen-cli-help` markers) is **generated from the live `antlrope --help` output** by
+`scripts/gen_cli_docs.py`. After any change to the CLI (`antlrope.cli` — a command's
+arguments or help text, or adding/renaming a subcommand), regenerate it:
+
+```sh
+pixi run gen-cli-docs
+```
+
+The prose outside the markers (the intro and the origin-header section) is hand-written.
+`tests/test_cli_docs.py` runs `gen-cli-docs --check`, so `pixi run test` fails if the
+committed doc has drifted from the CLI.
+
+## Version
+
+The version lives in one place: `src/antlrope/VERSION`. The build reads it
+(scikit-build-core's regex metadata provider) so the wheel and its
+`importlib.metadata` follow it, and `antlrope.__version__` reads the same
+file via `importlib.resources`. The conda recipe is the exception: it tracks the
+*published* release it packages, not the dev version, so it pins its own value
+(bumped per release).
+
+**Policy: bump the patch on every commit that changes runtime behavior or
+user-facing docs.** Edit `VERSION` in the same commit that touches the runtime
+(`src/`, `cpp/`, `vendor/antlr4-cpp/`) or the external docs (`README.md`,
+`docs/`). Build-only, test-only, or dev-tooling changes (pixi/CMake config,
+`scripts/`, `CONTRIBUTING.md`, CI) don't need a bump. When you bump, add a matching
+entry to [CHANGELOG.md](CHANGELOG.md). Bumping the file is enough for the version
+itself — `__version__` reflects it immediately; run `pixi install` to refresh the
+installed package metadata too.
+
+## Vendored runtime
+
+The vendored ANTLR C++ runtime is built from `vendor/antlr4-cpp/`; see
+`vendor/antlr4-cpp/UPDATING.md` to refresh the snapshot.
+
+## Before submitting
+
+- If you changed C++ (`cpp/` or `vendor/antlr4-cpp/`), run `pixi run build` first.
+- If you changed `cpp/`, run `pixi run format-cpp` (clang-format; config in
+  `.clang-format` — one argument per line when a call/declaration doesn't fit).
+- Run `pixi run test` and make sure the suite is green.
+- If you changed `cpp/binding.cpp`'s public interface, run `pixi run stubgen` (it
+  re-applies the hand edits automatically).
+- If you changed the CLI (`antlrope.cli`), run `pixi run gen-cli-docs` to regenerate
+  the `docs/reference/cli.md` command reference (`pixi run test` fails if it's stale).
+- If you changed the docs, confirm `pixi run docs-build` succeeds.
+- If you changed the public API, the workflow, or the doc page set, update
+  `docs/llms.txt` to match (it's hand-maintained and not flagged by `docs-build`).
+
+## Releasing
+
+Releases are cut from `main` via a `vX.Y.Z` tag; see [RELEASING.md](RELEASING.md)
+for the full procedure (CHANGELOG, version bump, wheels/PyPI, docs deploy,
+conda-forge).