Setup
Prerequisites¶
- Python 3.13 (GIL only) or 3.14+ — see Supported runtimes
- mise — installs the pinned dev toolchain and runs tasks
- uv — dependency and environment manager
First steps¶
git clone https://github.com/jr2804/parsecraft.git
cd parsecraft
mise dev # uv sync -U --dev --all-groups --extra web
mise test # pytest with the 100% coverage gate
mise dev is idempotent; re-run it after dependency changes. mise install
provisions the dev toolchain (ruff, ty, rumdl, codespell, pyreorder, and the
optional AI tooling). See Tech stack.
Tasks¶
| Task | Runs | Purpose |
|---|---|---|
mise dev |
uv sync -U --dev --all-groups --extra web |
Install dependencies (heavy extras never enter the dev/CI venv) |
mise test |
uv run python .config/mise/scripts/run_tests.py (pytest under coverage) |
Tests with the 100% coverage gate |
mise lint |
ruff check src/ tests/ --fix |
Lint and autofix |
mise lint-check |
ruff check src/ tests/ --no-cache |
Verify lint cleanliness (the gate arm) |
mise typecheck |
ty check src/ tests/ |
Static type checking |
mise spell |
codespell src/ tests/ |
Spell check |
mise format |
pyreorder + ruff format + import sort |
Format Python |
mise format-md |
rumdl fmt |
Lint and format Markdown |
mise docs |
uv run --link-mode=copy zensical build |
Build the docs site |
mise all |
format-check + smoke + test + typecheck + lint-check + spell + actionlint + docs |
Full quality gate |
mise clean |
remove build artifacts | Clean build/, dist/, caches |
mise lint and mise format-md rewrite files in place. Run them before
committing; a clean tree is expected after a full mise all.
mise all only runs the checking arms (format-check, lint-check): a
non-canonical tree fails the gate instead of being silently fixed into a false
green. mise test writes its coverage data to a per-process file and deletes it
when the run passes; when the gate fails it keeps .coverage.<pid> and
.htmlcov_<pid> and prints the report command, so a coverage failure can be
diagnosed after the fact instead of only seen.
Project layout¶
parsecraft/
├── src/parsecraft/
│ ├── adapters/ # input adapters (Markdown → IR)
│ ├── assets/ # pinned model-asset cache and downloads
│ ├── backends/ # backend protocol and registry
│ ├── cli/ # Typer app and commands
│ ├── config/ # layered configuration engine
│ └── ir/ # canonical IR and Markdown projection
├── tests/ # pytest suite (100% coverage gate)
├── docs/ # Zensical documentation site
├── examples/
│ └── third_party_backend/
├── scripts/
├── .config/mise/ # task and tool configuration
└── .github/workflows/ # CI and release
Pre-commit¶
pre-commit install
pre-commit run --all-files
The hooks run a subset of the quality gate on every commit.
Template¶
The repository is generated from
copier-uv-plus; answers live in
.copier-answers.yml. Run copier update to pull template changes.
When a just-published version looks missing¶
Two caching layers can make a fresh release look absent, and both read like a real problem rather than a stale read:
- PyPI's summary endpoint lags.
https://pypi.org/pypi/parsecraft/json->info.versioncan still report the previous release minutes after a publish. Check the version-specific endpoint instead (https://pypi.org/pypi/parsecraft/<version>/json, which lists the wheel and sdist), or the tag + GitHub release. uv's resolver cache can refuse it.uv lockmay answer "only parsecraft[docling]<=is available" , which reads like a dependency conflict in the new release. It is a stale index read: the two wheels were byte-identical apart from theVersion:line in their METADATA, so metadata cannot be the cause.uv lock --refreshresolves it.UV_NO_CACHE=1is the sledgehammer when the cache is more broadly suspect.
Both are consumer-visible (a downstream project hit both on the same release),
so reach for the version-specific endpoint and --refresh before reporting a
release as broken or missing.