latexwalker 0.1.0__tar.gz

latexwalker-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install deps
+        run: uv sync --dev --locked
+
+      - name: Ruff lint
+        run: uv run ruff check . --output-format=github
+
+      - name: Ruff format
+        run: uv run ruff format . --check
+
+      - name: basedpyright
+        run: uv run basedpyright
+
+      - name: Pytest
+        run: uv run pytest -v

latexwalker-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Deploy documentation
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install deps
+        run: uv sync --no-dev --group docs --locked
+
+      - name: Build site
+        run: uv run sphinx-build -W --keep-going -b html docs docs/_build/html
+
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    name: Deploy docs
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

latexwalker-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package
+        run: uv publish

latexwalker-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+src/*/_version.py
+
+# Virtual environments
+.venv
+
+# Cache
+.pytest_cache/
+.ruff_cache/
+
+# Docs
+docs/_build/
+
+# Local
+.vscode/

latexwalker-0.1.0/.opencode/opencode.jsonc

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+    },
+  },
+}

latexwalker-0.1.0/.opencode/skills/context7-usage/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: context7-usage
+description: Use Context7 to retrieve version-specific official documentation and examples for external libraries before implementing unfamiliar, version-sensitive, or API-dependent code.
+---
+
+# Context7 usage
+
+Use Context7 to verify third-party library APIs, configuration, migration paths,
+and version-specific behavior. Prefer official documentation and primary project
+sources over memory, search snippets, or guessed APIs.
+
+## When to use
+
+Use Context7 when a task depends on:
+
+- An unfamiliar library, framework, tool, or package API.
+- Version-sensitive behavior, deprecations, or migration guidance.
+- Exact constructor arguments, configuration keys, return types, or exception
+  behavior.
+- Integration patterns for external dependencies such as msgspec, pytest, or
+  colorlog.
+- A dependency addition or upgrade being considered.
+- An implementation detail that cannot be established from this repository's code,
+  tests, type information, or lockfile.
+
+Do not use Context7 when:
+
+- The answer is already established by local code, tests, type stubs, or project
+  documentation.
+- The task is internal refactoring with no external API dependency.
+- The task is about repository conventions; follow `AGENTS.md`,
+  `ARCHITECTURE.md`, and `CONTRIBUTING.md` instead.
+- You need current public information unrelated to a software-library API.
+
+## Workflow
+
+1. Read local usage first.
+   - Inspect imports, wrapper abstractions, configuration, and tests.
+   - Identify the installed package name and locked version before researching.
+   - Reuse an established project pattern when one exists.
+
+2. Resolve the library.
+   - Search Context7 using the package or project name.
+   - Select the official or canonical documentation source.
+   - Prefer a source matching the installed major and minor version.
+
+3. Query narrowly.
+   - Ask about one API surface at a time.
+   - Include the exact symbol, feature, or behavior being implemented.
+   - Request examples only when they clarify the required integration.
+
+4. Apply the result conservatively.
+   - Adapt documented patterns to local abstractions and architecture.
+   - Do not copy examples blindly; preserve local types, error handling, and test
+     conventions.
+   - Do not introduce a dependency or upgrade solely because an example uses it.
+
+5. Verify locally.
+   - Confirm the result with type checking and focused tests.
+   - Run the required project checks from `AGENTS.md` before completion.
+
+## Query patterns
+
+Use concise, concrete queries.
+
+```text
+msgspec Struct tagged union decode validation
+pytest anyio async fixture scope
+colorlog ColoredFormatter format reset log_color
+```
+
+For version-sensitive behavior, include the known version:
+
+```text
+msgspec 0.x Struct omit_defaults JSON schema
+```
+
+Avoid broad queries such as:
+
+```text
+how does msgspec work
+best Python serialization library
+show me all msgspec features
+```
+
+## Source selection
+
+- Prefer official project documentation, official API references, and maintained
+  upstream repositories.
+- Prefer the package's canonical source over third-party tutorials or blog posts.
+- If Context7 returns multiple candidate libraries, verify the package identity
+  against the repository dependency manifest and imports before using one.
+- Treat documentation for a different major version as potentially incompatible.
+- If the installed version cannot be identified, state that uncertainty and avoid
+  relying on version-specific claims.
+
+## Dependency decisions
+
+Context7 research does not authorize a dependency change.
+
+Before proposing a new, removed, or upgraded dependency:
+
+- Check whether the standard library or an existing dependency solves the problem.
+- Identify the exact package, version policy, license, type support, maintenance
+  status, and transitive-dependency impact.
+- Record alternatives considered in the plan.
+- Obtain explicit approval before running `uv add`, removing a package, or changing
+  a version constraint.
+
+## Reporting
+
+When Context7 materially informed an implementation plan or code change, report:
+
+- The library and version investigated.
+- The API or behavior verified.
+- The local files or tests that use the result.
+- Any version uncertainty, caveat, or deviation from the documented example.
+
+Keep the report brief. Do not paste long documentation excerpts when a concise
+statement and local verification result are sufficient.
+
+## Boundaries
+
+- Context7 is evidence for external APIs, not a replacement for repository context.
+- `AGENTS.md` controls code style, validation, dependencies, logging, and tests.
+- `ARCHITECTURE.md` controls system boundaries, contracts, and invariants.
+- `CONTRIBUTING.md` controls branches, commits, rebases, and review workflow.
+- When Context7 conflicts with local project conventions, preserve local conventions
+  unless the task explicitly changes them.

latexwalker-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-added-large-files
+
+  - repo: local
+    hooks:
+      - id: lint
+        name: lint
+        entry: just lint
+        language: system
+        types_or: [python, pyi]
+        pass_filenames: true
+
+      - id: format
+        name: format
+        entry: just format
+        language: system
+        types_or: [python, pyi]
+        pass_filenames: true
+
+      - id: typecheck
+        name: typecheck
+        entry: just typecheck
+        language: system
+        types_or: [python, pyi]
+        pass_filenames: false
+        stages: [pre-push]
+
+      - id: test
+        name: test
+        entry: just test
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

latexwalker-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

latexwalker-0.1.0/AGENTS.md

@@ -0,0 +1,165 @@
+# AGENTS
+
+## Important files
+
+Read:
+
+- [README](/README.md) to understand the purpose of the project.
+- [ARCHITECTURE](/ARCHITECTURE.md) to grasp the structure and conventions.
+- [CONTRIBUTING](/CONTRIBUTING.md) for contribution guidelines.
+
+## Commands
+
+- Use `just` as a task runner (see `just --summary` for the list of all tasks).
+- Run `just lintcheck <paths>` to check linting.
+- Run `just formatcheck <paths>` to check formatting.
+- Run auto-fix before trying to fix issues manually:
+  `just format <paths>` (format fix), `just lint <paths>` (linting fix).
+- Run `just typecheck <paths>` for static type-checking on selected files.
+- Run `just test <pytest args>` for tests.
+- Use `just check` to run all checks on the whole codebase.
+
+You can use lightweight `just lint[check]` and `just format[check]` frequently.
+Prefer focused `just typecheck` and `just test` over `just check`, for faster feedback.
+To consider the task done, `just check` must pass without errors.
+
+## Dependencies
+
+- Prefer the standard library and existing project dependencies before adding a new package; add a new dependency only when absolutely necessary.
+- Use `uv add <package>` or `uv add --group <group> <package>` to modify
+  dependencies. Do not edit the lockfile manually.
+- Commit the dependency manifest and lockfile together whenever dependencies change.
+- Pin or constrain versions only when compatibility, reproducibility, or a known
+  upstream regression requires it; otherwise follow the project's existing
+  version policy.
+
+## Code style
+
+- The code is written in Python 3.12.
+- All code must be linted and formatted before commit.
+- Depend on abstractions, not concrete backends; benefit from polymorphism.
+
+### Typing rules
+
+- Fully-type the code; Annotate all functions and methods.
+- Never use `typing.Any`; Never suppress diagnostics.
+- Use structural typing via `typing.Protocol` instead of `abc.ABC`.
+- If you need to add a base class, use `abc.ABC` alongside (not instead of) `typing.Protocol`.
+- Use Python 3.12+ style generics.
+- Run `just typecheck <paths>` for static type-checking (`basedpyright` strict).
+
+When working with poorly typed third-party stubs never give up on types --
+reason through them step-by-step.
+
+### Patterns
+
+#### Control flow
+
+- Prefer early returns over deeply nested conditionals.
+- Prefer `match` when branching on a closed set of variants; use `if` only for
+  predicates.
+- Prefer comprehensions for simple transformations; use named functions when the
+  transformation needs more than one clause.
+- Prefer iterators and generators for streaming data; materialize collections only
+  when indexing, reuse, or batching requires it.
+
+#### Function interfaces
+
+- Use keyword-only arguments for parameters whose meaning is unclear at call sites.
+- Represent optional values explicitly with `T | None`; validate or narrow them
+  immediately at the boundary where they are consumed.
+- Prefer `Sequence[T]`, `Mapping[K, V]`, `Iterable[T]`, and `Collection[T]` in input
+  annotations unless mutation or a concrete operation requires `list` or `dict`.
+- Accept the narrowest appropriate abstract collection type in inputs; return a
+  concrete immutable collection from public APIs when practical.
+- Prefer returning new values over mutating inputs or shared state; permit in-place
+  mutation only when the function contract explicitly promises it.
+- Never use mutable default arguments; use `None` and construct the value inside the
+  function.
+
+#### Models and states
+
+- Use `default_factory` for mutable dataclass fields.
+- Use `msgspec.Struct` for schemas, serialization and where performance is crucial;
+  keep decoding and validation at system boundaries.
+- Use `Enum` or discriminated union types for closed sets of states; do not represent
+  states with magic strings.
+- Use `StrEnum` only when a string representation is part of a public boundary.
+- Keep models that cross a boundary immutable unless mutation is essential to their
+  purpose.
+
+#### Type narrowing
+
+- Use `TypeIs` helper functions to narrow complex unions.
+- Keep narrowing functions small, deterministic, and named as predicates.
+- Use `typing.cast` only when the type equivalence is known and cannot be expressed
+  through normal narrowing.
+
+#### Errors
+
+- Catch only exceptions that can be handled meaningfully; keep `try` blocks minimal.
+- Raise specific, contextual exceptions; chain external failures with
+  `raise ... from exc`.
+- Keep error reporting at the boundary responsible for recovery or user-visible output.
+- Make retries explicit and limited. Retry only transient, idempotent operations.
+- Use exponential backoff with jitter for retryable external failures.
+- Do not retry validation errors, malformed input, or authorization failures.
+- For error logging, follow the [logging conventions](#logging) below.
+
+#### Resources and I/O
+
+- Use `pathlib.Path` for filesystem paths. Do not pass paths as raw strings internally.
+- Use `contextlib` context managers for resources with explicit lifetimes.
+- Close resources deterministically, including clients, files, streams, and database
+  sessions.
+- Keep filesystem, network, database, and model calls at explicit boundaries.
+
+#### Imports and modules
+
+- Keep imports at module scope; use local imports only to avoid an import cycle or
+  defer an optional or expensive dependency.
+- Keep modules focused on one cohesive concern. Split a module before it becomes a
+  catch-all for unrelated helpers.
+- Avoid `utils`, `common`, and `helpers` modules. Name modules after the capability
+  they provide.
+- Keep public exports explicit with `__all__` only for deliberately curated package APIs.
+
+## Comment style
+
+Your code shall read like prose, even without comments:
+
+- Use PEP 257 one-line docstrings.
+- Module-level docstrings should describe the module's purpose, not its contents.
+- If something (e.g. module, class, function) cannot be explained with a
+  one-line docstring, refactor or split it instead.
+- Comments explain _why_, not _what_.
+- If you feel the need to explain _what_ the code does, refactor it instead.
+- If comment or docstring restates the obvious, remove it.
+
+## Logging
+
+- Use the standard `logging` package and create one module-level logger:
+  `logger = logging.getLogger(__name__)`.
+- Configure handlers, levels, and `colorlog` formatters only at application entry
+  points. Never configure logging in imported modules.
+- Use the format `%(log_color)s%(levelname)-8s%(reset)s %(name)s: %(message)s`;
+  prefer a short package-relative module name when configuring the formatter.
+- Keep messages brief, lower-case, and action-oriented:
+  `logger.info("parsed 12 formula")`.
+- Use lazy `%s` formatting for values:
+  `logger.debug("processing %s", path)`.
+- Log identifiers and concise counts, not complete document contents, prompts, graph
+  payloads, secrets, or personal data.
+- Use `DEBUG` for diagnostics, `INFO` for meaningful progress, `WARNING` for handled
+  anomalies, and `ERROR` for operations that fail.
+- Use `logger.exception("failed to parse %s", path)` only inside an `except` block
+  when the current layer owns reporting or recovery.
+- Do not log an exception and re-raise it unless this layer adds actionable context
+  or terminates the operation.
+
+## Testing
+
+- Keep tests under `tests/`.
+- Keep tests in Arrange–Act–Assert order, with one behavioral reason to fail per test.
+- Test observable behavior and domain invariants, not private implementation details.
+- Prefer parametrized tests for equivalent cases with different inputs and outputs.

latexwalker-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,108 @@
+# ARCHITECTURE
+
+This document describes `latexwalker` library boundaries.
+Keep it current when changing the project architecture.
+
+## System
+
+`latexwalker` is a library for parsing LaTeX source into a syntax tree and
+normalizing its formatting. Parsing and normalization are separate concerns:
+the parser produces a lossless view of the source (every node carries the
+exact region it was built from), and the normalizer re-emits it in canonical
+form.
+
+## Project layout
+
+```text
+src/latexwalker/
+├── __init__.py     # curated public API surface
+├── _version.py     # generated by hatch-vcs; do not edit
+├── errors.py       # LatexWalkerError hierarchy and ParseError context
+├── source.py       # SourcePoint / SourceSpan schemas and SourceMap offset index
+├── tokens.py       # TokenType vocabulary and immutable Token schema
+├── lexer.py        # streaming tokenizer over raw text
+├── nodes.py        # frozen syntax tree schemas (Document root + Content union)
+├── parser.py       # recursive-descent parser assembling documents
+├── traverse.py     # structural traversal over any node kind
+├── rules.py        # normalization rule-set schemas and YAML decoding
+├── zones.py        # preserve / math / text classification of source regions
+├── rewrite.py      # rule set fused into a single-pass rewriting automaton
+├── normalize.py    # public canonicalization entry point
+└── resources/
+    └── rules.yaml
+```
+
+## Pipeline
+
+1. **Lexing** (`lexer.tokenize`) converts a `SourceMap`-backed text into a
+   stream of `Token`s ending with an end-of-input sentinel. Whitespace runs
+   become `WHITESPACE` or, when they contain two or more newlines,
+   `PARAGRAPH_BREAK`. Comments run to the end of their line. Macro values
+   exclude the leading backslash.
+2. **Parsing** (`parser.parse_document`) consumes tokens recursively into a
+   `Document` of frozen nodes. Each construct (groups, macros with attached
+   arguments, environments, math regions) declares the closers it owns, so
+   errors point at precise spans via `ParseError`. Nesting beyond a fixed
+   depth bound also fails with `ParseError`; the bound is chosen low enough
+   that nested parses never approach the interpreter's own stack limit.
+3. **Traversal** (`traverse.walk`, `traverse.iter_children`) visits trees
+   structurally; unknown future node kinds fall through safely.
+4. **Re-emission** currently means lossless extraction through spans
+   (`Document.source_of`); canonical formatting will build on the same node
+   contracts.
+5. **Normalization** (`normalize.normalize`) reduces plain text toward its
+   canonical form. `zones.classify` first fences off what must never change
+   (comments, verbatim-family environments) and labels math regions; the
+   rewriteable zones then pass through `rewrite.CompiledRuleSet`, a rule
+   set fused into a single alternation so one regex scan serves any rule
+   count. Rule sets are strict msgspec schemas (`rules.RuleSet`) decoded
+   from YAML; the packaged `resources/rules.yaml` supplies defaults and
+   is the stage's only filesystem access.
+
+## Lexer decisions
+
+The lexer keys on raw characters instead of TeX's line-based
+canonicalization. These behaviors are deliberate and pinned by tests:
+
+- Control sequences never span lines: scanning stops at the newline, which is
+  emitted as its own whitespace token.
+- A backslash followed by LF fails with `ParseError`; a backslash followed by
+  CR forms a control-symbol macro whose name is the CR character.
+- Comments extend through any trailing CR of a CRLF terminator before ending
+  at the LF.
+- Paragraph breaks are detected by counting raw LF characters (two or more)
+  in a whitespace run; blank lines built from CR alone stay whitespace.
+
+## Boundaries
+
+### Core
+
+- Tokenizing and parsing raw LaTeX text into a syntax tree.
+- The core does not read from or write to the filesystem.
+
+### Normalization
+
+- Works on plain strings, independent of parser node types, so it runs
+  before lexing or over extracted spans equally well.
+- Rules are user-authored pattern/canonical pairs; scoping (`any`,
+  `math`, `text`) declares where a rewrite is render-equivalent.
+- The packaged default rule set is the package's only filesystem read.
+
+### API
+
+- The public surface is whatever `src/latexwalker/__init__.py` exports;
+  submodules remain importable but are not covered by stability promises.
+- Callers pass in source text and receive a `Document`; internal node types
+  are deliberately exported so downstream code can match on them.
+- All errors derive from `LatexWalkerError`.
+
+## Data contracts
+
+- Schemas crossing a system boundary are defined with `msgspec.Struct`s;
+  decoding and validation happen at those boundaries only.
+- Every schema class is `frozen=True, kw_only=True`, configured once on the
+  shared base classes.
+- Boundary schemas reject unknown keys; the rule-set schema additionally
+  requires a `version` of at least 1 and non-empty patterns.
+- Trees are immutable after construction; positions are 1-based lines and
+  0-based columns.