viparse 0.1.0__tar.gz

viparse-0.1.0/.claude/rules/code-style.md

@@ -0,0 +1,21 @@
+# Rule: code style
+
+Python code in viparse is linted, formatted, and type-checked automatically. The tools are the
+source of truth; this rule states the intent behind them.
+
+## Tooling (enforced by CI and pre-commit)
+
+- **ruff** for both lint and format — do not hand-format around it. Run `scripts/dev.sh lint`.
+- **mypy strict** — `scripts/dev.sh type` must report no errors. Do not weaken strictness or add
+  blanket `# type: ignore`; if an ignore is unavoidable, make it specific (`# type: ignore[code]`)
+  and comment why.
+
+## Conventions
+
+- **Type hints are mandatory.** Every function signature (parameters and return) is annotated.
+  Prefer precise types over `Any`; reach for `typing`/`collections.abc` generics.
+- **English docstrings.** Public modules, classes, and functions have a short docstring, in English,
+  describing behavior — not restating the signature.
+- **English everywhere.** All identifiers, comments, and docstrings are in English. Vietnamese
+  belongs only in test fixtures and data, never in code or prose.
+- **NFC.** Any string literals or fixtures containing Vietnamese text are Unicode NFC.

viparse-0.1.0/.claude/rules/commit-title.md

@@ -0,0 +1,29 @@
+# Rule: commit & PR titles
+
+Every task lands as **one commit = one PR** with a single-line title and **no description body**.
+
+## Format
+
+```
+VIP-<id> <short imperative>
+```
+
+- Start with the Linear task id (`VIP-<id>`), then a short imperative summary.
+- Keep the whole title **≤ 60 characters**.
+- Imperative mood, capitalized, no trailing period. Write "Add", not "Added"/"Adds".
+- **No PR description.** The PR template checklist is the review contract; a body is not required.
+- **No `Co-Authored-By` trailer.**
+
+## Examples
+
+```
+VIP-31 Add minimal PR template
+VIP-33 Add scripts/dev.sh
+```
+
+Not:
+
+```
+Added a PR template.                     # past tense, no VIP id
+VIP-31: add minimal pull request template for the repository   # too long, colon, lowercase
+```

viparse-0.1.0/.claude/rules/review-before-push.md

@@ -0,0 +1,19 @@
+# Rule: review before push
+
+Before pushing a branch and opening its PR, verify every item below. If a task involves real
+code or logic, also run `/code-review` on the working changes and resolve its findings first.
+
+## Checklist
+
+- [ ] **Tests green** — `scripts/dev.sh test` passes locally.
+- [ ] **Type-check clean** — `scripts/dev.sh type` (mypy strict) reports no errors.
+- [ ] **Lint & format** — `scripts/dev.sh lint` passes (ruff check + format).
+- [ ] **Coverage gate met** — coverage stays at or above the `fail_under` threshold.
+- [ ] **No sensitive fixtures** — no secrets, credentials, or private/real documents committed;
+      test fixtures are synthetic or properly licensed.
+- [ ] **NFC-safe** — any emitted or committed text is Unicode NFC (the pre-commit `nfc-check`
+      hook must pass).
+- [ ] **Scope** — the diff matches exactly one `VIP-<id>`; nothing unrelated is bundled in.
+
+Running `scripts/dev.sh` (no argument) covers lint + type-check + test in one go — the same gates
+CI enforces.

viparse-0.1.0/.claude/skills/add-encoding/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: add-encoding
+description: Scaffold a legacy Vietnamese encoding table (e.g. TCVN3, VNI, VISCII) plus its golden test, so the normalizer can convert that encoding to Unicode NFC. Use when adding or correcting support for a legacy font/encoding.
+---
+
+# Add a legacy encoding
+
+Legacy Vietnamese documents store text in font-specific encodings (TCVN3 `.VnTime`, VNI
+`VNI-Times`, VISCII, …). The normalization layer maps those bytes/codepoints to correct Unicode
+and enforces **NFC**. This is the product's moat, so correctness is verified by **golden tests**.
+
+Follow these steps.
+
+## 1. Gather an authoritative mapping
+
+- Find a reputable source for the encoding→Unicode mapping (published charset tables, the font's
+  documented layout). Record the source in a comment.
+- Note how the encoding is detected: font name signal from the engine, byte-range heuristics, or an
+  explicit caller hint.
+
+## 2. Add the table
+
+Create `src/viparse/normalize/tables/<encoding>.py` (or the project's table location) as a plain,
+reviewable mapping. Keep it data, not logic — the shared conversion routine consumes any table.
+
+- Map every codepoint the encoding uses, including composed diacritic forms.
+- The conversion output must be normalized to **NFC** by the shared normalizer, not per-table.
+
+## 3. Wire detection
+
+Register the encoding so the normalizer selects it from the engine's raw signals (e.g. font name).
+Do not guess from the file extension.
+
+## 4. Add a golden test
+
+- Add an input fixture in the legacy encoding and an expected Unicode **NFC** output fixture under
+  `tests/` (synthetic text — no sensitive documents).
+- Assert the converted output equals the golden output **and** that it is NFC
+  (`unicodedata.is_normalized("NFC", out)`).
+- Include diacritic-heavy words (e.g. "Việt", "Nguyễn", "Đường") to catch composition bugs.
+
+## 5. Verify
+
+Run `scripts/dev.sh`. Open one PR titled `VIP-<id> Add <encoding> encoding`.
+
+## Checklist
+
+- [ ] Mapping sourced from an authoritative reference (cited in a comment)
+- [ ] Table is data-only; conversion reuses the shared routine
+- [ ] Output enforced to Unicode NFC
+- [ ] Detection wired from engine signals, not the extension
+- [ ] Golden test with diacritic-heavy input asserts exact NFC output
+- [ ] `scripts/dev.sh` passes

viparse-0.1.0/.claude/skills/add-engine/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: add-engine
+description: Scaffold a new viparse extraction Engine — a thin adapter around a well-maintained parse library, plus its test and registry entry. Use when adding support for a new file format or swapping the library behind an existing format.
+---
+
+# Add an extraction engine
+
+An **Engine** is a thin adapter that wraps a well-maintained parse library and returns a
+`RawExtraction` (raw text + font/encoding signals). Engines carry **no Vietnamese logic** — that
+lives in the normalization layer. Heavy engines are lazy-imported behind an extra.
+
+Follow these steps.
+
+## 1. Confirm the library choice
+
+- Pick a **well-maintained** library for the format (recent releases, no open CVEs, active repo).
+  Never hand-write the parser.
+- Decide whether it is heavy (native deps, OCR, LibreOffice). If so, it goes behind an extra
+  (`viparse[<extra>]`) and must be **lazy-imported** inside the engine, never at module top level.
+
+## 2. Scaffold the adapter
+
+Create `src/viparse/extract/<format>.py` with an engine class/callable that:
+
+- Declares which formats (magic-byte signatures) it handles.
+- Lazy-imports its heavy dependency inside the method, raising a clear error that names the extra
+  to install if the import fails.
+- Extracts text and attaches raw signals (e.g. run font names, embedded encoding hints) needed by
+  the normalizer — but performs **no** encoding conversion or NFC itself.
+- Returns a `RawExtraction`.
+
+## 3. Register it
+
+Add the engine to the format→engine registry used by the `route` layer so magic-byte detection can
+select it. Keep detection based on real bytes, not the filename extension.
+
+## 4. Add a test
+
+- Add a small, synthetic fixture under `tests/` (no sensitive or copyrighted documents).
+- Test that the engine is selected for the format and returns the expected raw text and signals.
+- If the dependency is heavy/optional, skip the test cleanly when the extra is not installed.
+
+## 5. Verify
+
+Run `scripts/dev.sh` (lint + type-check + test). Then open one PR titled `VIP-<id> Add <format> engine`.
+
+## Checklist
+
+- [ ] Wraps a maintained library — no hand-written parser
+- [ ] Heavy dependency lazy-imported behind an extra
+- [ ] No Vietnamese/encoding logic in the engine
+- [ ] Registered for magic-byte routing
+- [ ] Synthetic fixture + test, optional-dependency skip handled
+- [ ] `scripts/dev.sh` passes

viparse-0.1.0/.claude/skills/release/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: release
+description: Cut a viparse release — bump the version, update the CHANGELOG, tag, and build the distribution. Use when publishing a new version of the package.
+---
+
+# Cut a release
+
+viparse uses a single source of truth for the version: `src/viparse/__init__.py` (`__version__`),
+read by hatchling at build time. Releases are cut from a green `main`.
+
+Follow these steps.
+
+## 1. Pre-flight
+
+- Ensure `main` is up to date and CI is green.
+- Run `scripts/dev.sh` locally — lint, type-check, and tests must pass.
+- Decide the new version per **SemVer** (MAJOR.MINOR.PATCH) based on what changed since the last tag.
+
+## 2. Bump the version
+
+- Edit `__version__` in `src/viparse/__init__.py` to the new version.
+- This is the only place the version is defined — do not duplicate it in `pyproject.toml`
+  (it is `dynamic`).
+
+## 3. Update the CHANGELOG
+
+- Add a new `## <version> — <YYYY-MM-DD>` section at the top of `CHANGELOG.md`.
+- Group entries under Added / Changed / Fixed / Removed. Summarize user-facing changes; link the
+  relevant `VIP-<id>` tasks. Keep it in English.
+
+## 4. Land the bump
+
+- Open one PR titled `VIP-<id> Release v<version>` with the version bump + CHANGELOG.
+- Merge once CI is green.
+
+## 5. Tag and build
+
+From the merged `main`:
+
+```bash
+git tag -a v<version> -m "v<version>"
+git push origin v<version>
+scripts/dev.sh build          # produces the wheel + sdist in dist/
+```
+
+- Verify the built artifacts carry the new version (`dist/viparse-<version>*`).
+- Publish per the project's distribution process (e.g. PyPI) once configured.
+
+## Checklist
+
+- [ ] `main` green, `scripts/dev.sh` passes
+- [ ] Version bumped only in `src/viparse/__init__.py`, per SemVer
+- [ ] CHANGELOG updated with dated section linking `VIP-<id>`s
+- [ ] Release PR merged on green CI
+- [ ] Annotated tag `v<version>` pushed
+- [ ] Wheel + sdist built and version-verified

viparse-0.1.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns: ["*"]

viparse-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+<!--
+Keep PRs to one task. Title: `VIP-<id> <short imperative>`. No long description needed.
+This checklist is the review contract; delete lines that genuinely do not apply.
+-->
+
+## Checklist
+
+- [ ] One task, one commit — scope matches a single `VIP-<id>`
+- [ ] Acceptance criteria from the spec are met
+- [ ] Output stays Unicode **NFC** (if this touches text handling)
+- [ ] No hand-written parser — engines wrapped behind thin adapters (if this touches extraction)
+- [ ] Lint, type-check, and tests pass locally (`scripts/dev.sh`)
+- [ ] All committed text is in English

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

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,office,pdf]"
+      - name: Lint (ruff)
+        run: bash scripts/dev.sh lint
+      - name: Type-check (mypy)
+        run: bash scripts/dev.sh type
+      - name: Test (pytest + coverage)
+        run: bash scripts/dev.sh test
+
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install project
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+      - name: Audit dependencies (pip-audit)
+        run: |
+          pip install pip-audit
+          pip-audit --progress-spinner off
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+      - name: Validate distribution metadata
+        run: twine check dist/*
+
+  # SBOM is informational and independent of the release artifact, so it lives in its own
+  # job (a transient tooling failure must never gate the build) and runs in a clean env
+  # holding only the package's runtime deps — not build/test tooling.
+  sbom:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Generate SBOM (CycloneDX)
+        continue-on-error: true
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[all]" cyclonedx-bom
+          cyclonedx-py environment --pyproject pyproject.toml --of json -o sbom.json
+      - name: Upload SBOM
+        uses: actions/upload-artifact@v4
+        with:
+          name: sbom
+          path: sbom.json
+          if-no-files-found: warn

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

@@ -0,0 +1,32 @@
+name: Publish
+
+# Publish to PyPI via Trusted Publishing (OIDC) — no API token is stored.
+# Fires when a GitHub Release is published; workflow_dispatch allows a manual
+# run to backfill a release cut before this workflow existed (e.g. v0.1.0).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/viparse
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+      - name: Validate distribution metadata
+        run: twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

viparse-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# Tooling
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+uv.lock
+sbom.json

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

@@ -0,0 +1,32 @@
+# Pre-commit hooks for viparse.
+# Install once with: pre-commit install
+# Run on all files with: pre-commit run --all-files
+minimum_pre_commit_version: "3.5.0"
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+  - repo: local
+    hooks:
+      - id: nfc-check
+        name: Unicode NFC check
+        description: Ensure text files are Unicode NFC-normalized (the viparse invariant).
+        entry: scripts/check_nfc.py
+        language: script
+        types: [text]

viparse-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to viparse are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-07-12
+
+First tagged release. Covers the full M0–M5 feature set (VIP-1 … VIP-59).
+
+### Added
+
+- **Public API** — `viparse.load(source, *, output, encoding, ocr, normalize, max_bytes,
+  cache, chunk, settings)` and lazy `viparse.load_batch(...)`, returning Unicode-**NFC**
+  `Document`s as markdown / text / json.
+- **Layered configuration** — `output` / `encoding` / `ocr` / `normalize` / `max_bytes` resolve
+  from function args → `VIPARSE_*` env vars → a `viparse.toml` file → the built-in defaults. A
+  validating `Settings` (via `load_settings()`) raises `ConfigError` on a bad value.
+- **RAG chunking** — opt-in `chunk=ChunkOptions(max_tokens, overlap_tokens)` splits a document
+  into retrieval-sized, section-aware `Chunk`s (never splitting a table row) with per-chunk
+  `section` / `page` / `sheet` metadata and an ordinal `index`.
+- **Framework integrations** — `to_langchain_documents(doc)` / `to_llamaindex_documents(doc)`
+  map a `Document` (chunk-aware) onto LangChain / LlamaIndex document types, provenance
+  flattened into their `metadata`. Lazy behind `viparse[langchain]` / `viparse[llamaindex]`.
+- **CLI** — `viparse <files> -o md|text|json` (globs, directories, `--out`,
+  `--encoding`/`--ocr`/`--normalize`) and `viparse doctor` (engine + binary availability).
+- **Extraction engines** — DOCX, XLSX, digital PDF, scanned PDF via OCR (`viparse[ocr]`),
+  and legacy binary `.doc`/`.xls` via LibreOffice — all thin adapters behind extras so the
+  `core` install stays dependency-free.
+- **Vietnamese normalization (the moat)** — legacy **TCVN3 / VNI / VISCII** → Unicode NFC,
+  with font-signal detection, opt-in content-based detection (`encoding="auto"`), and text
+  cleanup. Output is always NFC.
+- **Structured output** — headings, GFM tables, and a versioned JSON schema
+  (`viparse.SCHEMA_VERSION`).
+- **Untrusted-input safety** — configurable file-size limit, zip-decompression-bomb guard,
+  and per-engine process timeouts (`UnsafeInput`).
+- **Caching** — content-hash `MemoryCache` / `DiskCache` to skip re-parsing unchanged files.
+- **Parallel batch** — `load_batch(..., workers=N)` with bounded concurrency and per-source
+  error isolation.
+
+[Unreleased]: https://github.com/minhtridinh-kayden/viparse/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/minhtridinh-kayden/viparse/releases/tag/v0.1.0

viparse-0.1.0/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository.
+
+## What viparse is
+
+A Vietnamese-first document loader for RAG. It turns Vietnamese documents (including legacy
+TCVN3/VNI/VISCII fonts, scanned PDFs, and old `.doc`/`.xls`) into clean Unicode **NFC**
+Markdown/JSON, ready to push into a vector DB.
+
+The differentiator (the moat) is the **Vietnamese normalization layer**: detect & convert legacy
+encodings to Unicode and enforce NFC. Generic loaders parse the file but emit garbled diacritics
+or wrong normalization; viparse fixes exactly that.
+
+## Golden rules
+
+These are non-negotiable. They override convenience.
+
+1. **Never hand-write a parser.** Wrap a well-maintained engine behind a thin adapter. If an engine
+   gets a CVE or is abandoned, swap the adapter — don't reinvent it.
+2. **Always NFC.** Output is Unicode NFC by default. Normalization is the product; never ship text
+   that isn't consistently normalized.
+3. **Thin adapters.** Engines only extract and attach raw signals. No Vietnamese logic leaks into
+   an engine; that belongs in the normalization layer.
+4. **Heavy engines are lazy.** OCR, LibreOffice, and other heavy dependencies are lazy-imported
+   behind extras (`viparse[ocr]`, `viparse[office]`). `core` must import with stdlib-only deps.
+5. **Every task has acceptance criteria.** A task is done only when its criteria (from the spec)
+   are met and verified by a test.
+
+## Architecture
+
+The pipeline has four layers; each communicates through intermediate types so they stay decoupled
+and independently testable:
+
+```
+viparse.load("file") -> list[Document]
+
+  route      detect real format via magic bytes (not the extension); pick an engine
+  extract    Engine adapter -> RawExtraction (raw text + font/encoding signals)
+  normalize  Normalizer     -> NormalizedDoc  (legacy encoding -> Unicode, NFC, cleanup)
+  structure  Renderer       -> Document       (text | markdown | json, + metadata)
+```
+
+- **Engines** (`extract`) are thin adapters wrapping well-maintained parse libraries. They carry
+  no Vietnamese logic — they only extract and attach raw signals (e.g. run font name).
+- **Normalizers** (`normalize`) own the Vietnamese layer (the moat).
+- **Renderers** (`structure`) produce the RAG-ready output and metadata.
+
+Heavy dependencies (OCR, LibreOffice) are **lazy-imported** behind extras so `core` stays light.
+
+## Repository layout
+
+```
+docs/specs/      Spec map: README + SPEC-0 .. SPEC-8 (source of truth for scope)
+docs/ops/        Linear <-> GitHub workflow mapping
+src/viparse/     Package source (added incrementally per spec)
+tests/           Test suite + golden fixtures
+```
+
+Specs are the source of truth for scope. Before implementing, read the relevant
+`docs/specs/SPEC-*.md`.
+
+## Commands
+
+> The Python toolchain is added in SPEC-0 (E0.6) and SPEC-5 (packaging). Until then, these are the
+> intended entry points.
+
+```bash
+# Setup (once the package exists)
+pip install -e ".[all]"      # editable install with every extra
+
+# Quality gates
+ruff check .                 # lint
+ruff format .                # format
+mypy src                     # type-check (strict)
+pytest                       # tests
+pytest --cov=viparse         # tests with coverage
+
+# CLI
+viparse <file> -o md|text|json
+viparse doctor               # list available engines per installed extras
+```
+
+## Workflow
+
+- Hierarchy: **SPEC -> Epic -> Task**. In Linear, an epic is an issue and a **task is a sub-issue**
+  (team key `VIP`). Sub-issues are created just-in-time per epic.
+- **One task = one branch = one commit = one PR.** PR/commit title: `VIP-<id> <short imperative>`,
+  no description.
+- All committed artifacts (docs, comments, identifiers, commit titles) are in **English**.

viparse-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing to viparse
+
+viparse is built one task at a time. Every change traces back to a task in Linear (team key
+`VIP`) and lands as a single, self-contained pull request.
+
+## One task = one branch = one commit = one PR
+
+- **Branch:** `vip-<id>-<short-slug>` — the Linear task id plus a short kebab-case slug.
+  Examples: `vip-31-add-minimal-pr-template`, `vip-33-add-scripts-dev-sh`.
+  (Linear also suggests this name on each task under "Copy git branch name".)
+- **Commit / PR title:** `VIP-<id> <short imperative>` — e.g. `VIP-31 Add minimal PR template`.
+  No PR description is required; the checklist in the PR template is the review contract.
+- Keep the PR scoped to its one task. If you discover unrelated work, open a new task for it.
+
+## Before you push
+
+Run the local quality gates — the same ones CI enforces:
+
+```bash
+scripts/dev.sh        # lint (ruff) + type-check (mypy) + tests (pytest + coverage) + build
+```
+
+## House rules
+
+- All committed artifacts — docs, comments, identifiers, commit and PR titles — are in **English**.
+- Output text is Unicode **NFC**. Never ship text that is not consistently normalized.
+- Never hand-write a parser: wrap a well-maintained engine behind a thin adapter.
+- Read the relevant `docs/specs/SPEC-*.md` before implementing; the specs are the source of truth
+  for scope and acceptance criteria.