tox.toml

requires = [ "tox>=4.56.3", "tox-uv>=1.35.2" ]
env_list = [
  "3.15",
  "3.14",
  "3.13",
  "3.12",
  "3.11",
  "3.10",
  "pypy3.11",
  "pypy3.10",
  "3.14t",
  "3.15t",
  "docs",
  "fix",
  "pkg_meta",
  "type",
  "warnings"
]
skip_missing_interpreters = true

[env_run_base]
description = { replace = "if", condition = "factor['3.15'] or factor['3.14t'] or factor['3.15t']", then = "run the test suite under {env_name} with the Python coverage gate (no gcov for this interpreter)", else = "run the test suite under {env_name} with the Python and C coverage gates" }
package = "skip"  # we install an instrumented editable build ourselves below
# gcovr (via lxml) has no wheels for 3.15 or the free-threaded builds, and there is
# no gcov on Windows, so pull it in only where the coverage gate actually runs
deps = [
  { replace = "if", condition = "factor.win32 or factor['3.15'] or factor['3.14t'] or factor['3.15t']", then = [], else = [
    "gcovr>=8.6"
  ], extend = true },
]
dependency_groups = [ "test" ]
pass_env = [ "COV_GCOV", "PYTEST_*" ]
commands_pre = [
  [
    "python",
    "-c",
    """\
  import pathlib; d = pathlib.Path(r'{env_dir}', 'cbuild'); [p.unlink() for p in d.rglob('*.gcda')] if d.exists() else \
  None\
  """,
  ],
  [
    "uv",
    "pip",
    "install",
    "--reinstall",
    "--no-deps",
    "--no-build-isolation",
    "--editable",
    "{tox_root}",
    "--config-settings=build-dir={env_dir}{/}cbuild",
    # instrument for C coverage except where gcov/gcovr are unavailable (Windows, 3.15, free-threaded)
    { replace = "if", condition = "factor.win32 or factor['3.15'] or factor['3.14t'] or factor['3.15t']", then = [], else = [
      "--config-settings=setup-args=-Dbuildtype=debug",
      "--config-settings=setup-args=-Db_ndebug=true",
      "--config-settings=setup-args=-Db_coverage=true",
    ], extend = true },
  ],
]
commands = [
  [
    "pytest",
    "--durations",
    "10",
    "--no-cov-on-fail",
    "--cov",
    "turbohtml",
    "--cov",
    "{tox_root}{/}tests",
    "--cov-config",
    "{tox_root}{/}pyproject.toml",
    "--cov-context",
    "test",
    "--cov-report",
    "term-missing:skip-covered",
    "--cov-report",
    "html:{env_tmp_dir}{/}htmlcov",
    # the tests/conformance suites validate a feature against a competitor's or standards body's own suite,
    # vendored as pinned submodules; they only run with those oracles present, in the dedicated `conformance`
    # env (the "🔬 conformance" CI job). Deselect them here so the normal matrix never runs an oracle suite
    # without its oracle -- a missing oracle must error there, not skip silently in the matrix.
    "--ignore={tox_root}{/}tests{/}conformance",
    { replace = "posargs", default = [ "tests" ], extend = true },
  ],
  # enforce 100% C LINE coverage everywhere gcov runs, and 100% BRANCH coverage on
  # every version except 3.10: its pre-PEP-623 PyUnicode_DATA/READ/WRITE macros emit
  # ternaries whose non-compact sides PyUnicode_New objects can never take, so 3.10
  # floors at 97% (gcc counts a few more of these dead branches than llvm). 3.11+
  # collapsed those macros to branchless inline functions.
  { replace = "if", condition = "factor.win32 or factor['3.15'] or factor['3.14t'] or factor['3.15t']", then = [
    "python",
    "-c",
    "print('C coverage gate skipped on this interpreter (no gcov/gcovr)')",
  ], else = [
    "gcovr",
    "{env_dir}{/}cbuild",
    "--root",
    "{tox_root}",
    "--filter",
    "src/turbohtml/.*\\.(c|h)",
    "--gcov-executable",
    "{env:COV_GCOV:xcrun llvm-cov gcov}",
    "--fail-under-line",
    "100",
    "--fail-under-branch",
    { replace = "if", condition = "factor['3.10']", then = "97", else = "100" },
    "--html-details",
    "{env_tmp_dir}{/}c_htmlcov.html",
    "--txt",
    "-",
  ] },
  # free-threaded build only: re-run the thread-safety tests with one thread per core
  # (pytest-run-parallel) to surface data races the single-threaded coverage run hides
  { replace = "if", condition = "factor['3.14t'] or factor['3.15t']", then = [
    "pytest",
    "{tox_root}{/}tests{/}dom{/}test_tree_freethread.py",
    "--no-cov",
    "--parallel-threads=auto",
    "--iterations=20",
  ], else = [ "python", "-c", "print('free-threaded parallel stress skipped (GIL build)')" ] },
]

[env.docs]
description = "build the documentation"
package = "wheel"  # co-locate _html.so and _html.pyi so autodoc-typehints finds the stub
dependency_groups = [ "docs" ]
commands_pre = []  # drop the instrumented editable install inherited from env_run_base
commands = [
  [
    "sphinx-build",
    "-d",
    "{env_tmp_dir}{/}docs_tree",
    "docs",
    "{env_tmp_dir}{/}doctest",
    "--color",
    "-b",
    "doctest",
    "-W",
  ],
  [
    "sphinx-build",
    "-d",
    "{env_tmp_dir}{/}docs_tree",
    "docs",
    "{env:READTHEDOCS_OUTPUT:{work_dir}{/}docs_out}/html",
    "--color",
    "-b",
    "html",
    "-W",
    { replace = "posargs", default = [], extend = true },
  ],
  [ "python", "-c", 'print(r"documentation available under file://{work_dir}{/}docs_out{/}html{/}index.html")' ],
]

[env.fix]
description = "format and lint the code base"
skip_install = true
dependency_groups = [ "fix" ]
pass_env = [ "PROGRAMDATA" ]
commands_pre = []  # drop the instrumented editable install inherited from env_run_base
commands = [ [ "pre-commit", "run", "--all-files", "--show-diff-on-failure", { replace = "posargs", extend = true } ] ]

[env.pkg_meta]
description = "check that the package metadata is valid"
skip_install = true
dependency_groups = [ "pkg-meta" ]
commands_pre = []  # uv build does its own isolated build; skip the inherited coverage install
commands = [
  [ "uv", "build", "--sdist", "--wheel", "--out-dir", "{env_tmp_dir}", "." ],
  [ "twine", "check", "{env_tmp_dir}{/}*" ],
  [ "check-wheel-contents", "--no-config", "{env_tmp_dir}" ],
]

[env.type]
description = "run the type checker on the code base"
dependency_groups = [ "type" ]
commands = [ [ "ty", "check", "--output-format", "concise", "--error-on-warning", "src", "tests", "tools" ] ]

[env.warnings]
description = "compile the C extension with -Werror so any -Wall/-Wextra warning fails the build"
package = "skip"  # the throwaway wheel below is the gate; nothing installs it
deps = []  # uv build pulls meson-python/meson/ninja in its own isolated build env
dependency_groups = []  # no test deps; this env only compiles
# CC lets CI pick gcc vs clang; INCLUDE/LIB/LIBPATH forward the MSVC toolchain env that
# msvc-dev-cmd activates for the Windows arm64 cell, which tox would otherwise strip so cl
# compiles with no headers or libs (on x64 meson self-detects MSVC via vswhere and needs none)
pass_env = [ "CC", "INCLUDE", "LIB", "LIBPATH" ]
commands_pre = []  # this env builds with -Werror itself; skip the inherited coverage install
# uv build (the same path users hit) streams every ninja compile line and the warning that
# trips -Werror, and its meson-python backend writes the native file that locates Python on
# every platform — plain `meson setup` cannot find the headers for a uv-managed Windows arm64
# interpreter. buildtype=release is uv build's default, so optimization-only gcc diagnostics
# (-Wmaybe-uninitialized) are in scope. The wheel itself is discarded.
commands = [
  [
    "uv",
    "build",
    "--wheel",
    "--out-dir",
    "{env_tmp_dir}{/}dist",
    "--config-settings=setup-args=-Dwerror=true",
    "{tox_root}",
  ],
]

# tox cannot resolve a `ref` into a dotted environment name, so the shared body lives in an
# environment with a plain one and both PyPy environments splice it in.
[env._pypy]
description = "shared body of the PyPy environments; not run on its own"
# gcovr reaches cpyext through lxml, which publishes no PyPy wheels, and a cpyext build has no gcov
# to feed it anyway. The C and Python coverage gates both run on the CPython matrix.
deps = []
commands_pre = [
  [
    "uv",
    "pip",
    "install",
    "--reinstall",
    "--no-deps",
    "--no-build-isolation",
    "--editable",
    "{tox_root}",
    "--config-settings=build-dir={env_dir}{/}cbuild",
  ],
]
commands = [
  [
    "pytest",
    "--durations",
    "10",
    "--no-cov",
    "--ignore={tox_root}{/}tests{/}conformance",
    { replace = "posargs", default = [ "tests" ], extend = true },
  ],
]

[env.asan-js]
description = "compile the JS minifier engine standalone and fuzz the corpus under ASan/UBSan (+LSan on Linux)"
package = "skip"
deps = []
dependency_groups = []
commands_pre = []  # no extension install; the engine compiles standalone with the system allocator
commands = [ [ "python", "{tox_root}{/}tools{/}js_sanitize.py" ] ]

[env.bench]
description = "benchmark turbohtml against each competitor isolated in its own uv venv (not run in CI)"
package = "skip"
set_env = { PYTHONPATH = "{tox_root}{/}tools" }
commands = [ [ "python", "-m", "bench", { replace = "posargs", extend = true } ] ]

[env.codspeed]
description = "run the pytest-codspeed hot-path benchmarks (the CodSpeed CI regression gate)"
base_python = [ "3.14" ]
package = "skip"  # commands_pre reinstalls a deterministic LTO editable build; a plain editable package would undo it
deps = []  # drop the gcovr the coverage gate pulls in; the benchmarks never measure coverage
dependency_groups = [ "test" ]  # carries pytest-codspeed, the benchmark fixture, and the meson build backend
commands_pre = [
  # Build a deterministic LTO-only editable extension, not a profile-guided one. PGO regenerates a fresh profile every
  # build, and that profile is not byte-reproducible: across CodSpeed's heterogeneous CPU runners a re-profiled binary
  # flips marginal ops a few percent build-to-build, so the perf gate reports false regressions that mask real ones
  # (spike #478). LTO alone is deterministic and still re-inlines the selector/tokenizer bodies the 1.0 header split
  # moved out of their monolith units, so the gate measures a stable binary. buildtype matches the release wheel; only
  # PGO is dropped. The shipped wheels keep PGO+LTO for max perf -- see tools/pgo_build.py and pyproject's cibuildwheel.
  [
    "uv",
    "pip",
    "install",
    "--reinstall",
    "--no-deps",
    "--no-build-isolation",
    "--editable",
    "{tox_root}",
    "--config-settings=build-dir={env_dir}{/}cbuild",
    "--config-settings=setup-args=-Dbuildtype=release",
    "--config-settings=setup-args=-Db_lto=true",
  ],
]
commands = [
  [ "pytest", "{tox_root}{/}tests{/}benchmarks", "--codspeed", { replace = "posargs", extend = true } ],
]

[env.conformance]
description = "run the vendored-oracle conformance suites in tests/conformance (the '🔬 conformance' CI job, not a per-PR gate)"
package = "skip"  # commands_pre installs a plain release editable build; no coverage instrumentation
deps = []  # no gcovr: this is a pass/fail correctness gate, not a coverage gate (the matrix owns the 100% gate)
dependency_groups = [ "test" ]
pass_env = [ "PYTEST_*" ]
commands_pre = [
  # a plain release build, uninstrumented -- the conformance suites only assert behavior against the oracles
  [
    "uv",
    "pip",
    "install",
    "--reinstall",
    "--no-deps",
    "--no-build-isolation",
    "--editable",
    "{tox_root}",
    "--config-settings=build-dir={env_dir}{/}cbuild",
    "--config-settings=setup-args=-Dbuildtype=release",
  ],
]
# Each tests/conformance/test_*.py validates one feature against a competitor's or standards body's OWN suite,
# vendored as a pinned submodule under tests/conformance/<oracle> (libxml2, unicodetools, qt3tests, parse5,
# DOMPurify, ...) and/or a Node oracle in tools/bench/node. Run them for real with the oracles present: a suite
# whose oracle submodule is absent errors here (never skips) -- that is the point of this env. This is a
# correctness gate, not a coverage gate (no --cov). An empty or absent tests/conformance (no suites on this
# branch yet) is a clean pass, not a failure, so a branch that adds no suite still goes green.
commands = [
  [
    "python",
    "-c",
    """\
  import pathlib, subprocess, sys; suites = sorted(pathlib.Path('tests', 'conformance').glob('test_*.py')); print('no \
  tests/conformance suites present; nothing to run') if not suites else None; raise SystemExit(0 if not suites else \
  subprocess.call([sys.executable, '-m', 'pytest', 'tests/conformance', '--no-cov', '-p', 'no:cacheprovider']))\
  """,
  ],
]

[env.dev]
description = "dev environment with all dependencies at {envdir}"
package = "editable"
dependency_groups = [ "dev" ]
commands = [ [ "uv", "pip", "list", "--format=columns" ], [ "python", "-c", 'print(r"{env_python}")' ] ]

[env.docs-linkcheck]
description = "check every external link in the documentation resolves (network-bound; run on demand, not a per-PR gate)"
package = "wheel"
dependency_groups = [ "docs" ]
commands_pre = []
commands = [
  [
    "sphinx-build",
    "-d",
    "{env_tmp_dir}{/}docs_tree",
    "docs",
    "{env_tmp_dir}{/}linkcheck",
    "--color",
    "-b",
    "linkcheck",
  ],
]

[env.fuzz]
description = "coverage-guided/mutation deep fuzz of every harness under ASan/UBSan (scheduled/manual, not a PR gate)"
deps = []  # override the base env's gcovr; this env instruments for ASan, not coverage
dependency_groups = [ "test" ]
set_env = { CC = "clang" }
commands_pre = [
  [
    "uv",
    "pip",
    "install",
    "--reinstall",
    "--no-deps",
    "--no-build-isolation",
    "--editable",
    "{tox_root}",
    "--config-settings=build-dir={env_dir}{/}cbuild",
    "--config-settings=setup-args=-Dc_args=-fsanitize=address,undefined",
    "--config-settings=setup-args=-Dc_link_args=-fsanitize=address,undefined",
    "--config-settings=setup-args=-Dbuildtype=debugoptimized",
  ],
]
commands = [
  [
    "python",
    "{tox_root}{/}tools{/}fuzz{/}fuzz.py",
    "--mode",
    "deep",
    { replace = "posargs", default = [ "--minutes", "2" ], extend = true },
  ],
]

[env.fuzz-smoke]
description = "replay the benign fuzz seed corpus through every harness under ASan/UBSan (the fast per-PR gate)"
deps = []  # override the base env's gcovr; this env instruments for ASan, not coverage
dependency_groups = [ "test" ]  # carries the meson-python build backend the no-build-isolation install below needs
set_env = { CC = "clang" }
commands_pre = [
  # build the extension with the sanitizers so the in-process harness faults on a C memory error. b_sanitize trips
  # meson's linker capability check for an extension module on macOS, so pass the flag through c_args/c_link_args, which
  # the driver's ASan-runtime preload then arms; buildtype matches the tsan env's instrumented build.
  [
    "uv",
    "pip",
    "install",
    "--reinstall",
    "--no-deps",
    "--no-build-isolation",
    "--editable",
    "{tox_root}",
    "--config-settings=build-dir={env_dir}{/}cbuild",
    "--config-settings=setup-args=-Dc_args=-fsanitize=address,undefined",
    "--config-settings=setup-args=-Dc_link_args=-fsanitize=address,undefined",
    "--config-settings=setup-args=-Dbuildtype=debugoptimized",
  ],
]
commands = [ [ "python", "{tox_root}{/}tools{/}fuzz{/}fuzz.py", "--mode", "smoke" ] ]

[env.regen]
description = "regenerate the generated C tables (entities, tag atoms)"
skip_install = true
commands_pre = []
commands = [
  [
    "python",
    "{tox_root}{/}tools{/}generate_html_entities.py",
    "{tox_root}{/}src{/}turbohtml{/}_c{/}data{/}html_entities.h",
  ],
  [ "python", "{tox_root}{/}tools{/}generate_tags.py", "{tox_root}{/}src{/}turbohtml{/}_c{/}data{/}tag_atom.h" ],
  [ "python", "{tox_root}{/}tools{/}generate_attrs.py", "{tox_root}{/}src{/}turbohtml{/}_c{/}data{/}attr_atom.h" ],
  [ "python", "{tox_root}{/}tools{/}generate_tlds.py", "{tox_root}{/}src{/}turbohtml{/}_c{/}data{/}tld_table.h" ],
  [ "python", "{tox_root}{/}tools{/}generate_psl.py", "{tox_root}{/}src{/}turbohtml{/}_c{/}data{/}psl_table.h" ],
  [ "python", "{tox_root}{/}tools{/}generate_idna.py", "{tox_root}{/}src{/}turbohtml{/}_c{/}data{/}idna_table.h" ],
  [
    "python",
    "{tox_root}{/}tools{/}generate_normalize.py",
    "{tox_root}{/}src{/}turbohtml{/}_c{/}data{/}normalize_table.h",
  ],
  [
    "python",
    "{tox_root}{/}tools{/}generate_css_colors.py",
    "{tox_root}{/}src{/}turbohtml{/}_c{/}data{/}css_colors.h"
  ],
  [
    "python",
    "{tox_root}{/}tools{/}generate_encoding_tables.py",
    "{tox_root}{/}src{/}turbohtml{/}_c{/}data{/}encoding_tables.h",
  ],
]

[env.release]
description = "cut a release; pass the version as a positional argument"
skip_install = true
dependency_groups = [ "release" ]
pass_env = [ "GH_TOKEN" ]
commands_pre = []
commands = [ [ "python", "{tox_root}{/}tasks{/}release.py", "--version", "{posargs}" ] ]

[env.tsan]
description = "detect data races with ThreadSanitizer; run inside ghcr.io/nascheme/cpython-tsan:3.14t"
# the no-GIL TSan interpreter is the container's own python, not a uv-managed one
base_python = [ "python3.14t" ]
package = "skip"
dependency_groups = [ "test" ]
# let meson autodetect the container's TSan-capable compiler (the one CPython was built with); do not force CC=clang
set_env = { UV_PYTHON_PREFERENCE = "only-system", TSAN_OPTIONS = "halt_on_error=0 allocator_may_return_null=1 suppressions={tox_root}{/}tools{/}tsan-suppressions.txt" }
commands_pre = [
  # build the extension with TSan instrumentation against the container's TSan interpreter
  [
    "uv",
    "pip",
    "install",
    "--reinstall",
    "--no-deps",
    "--no-build-isolation",
    "--editable",
    "{tox_root}",
    "--config-settings=build-dir={env_dir}{/}cbuild",
    "--config-settings=setup-args=-Db_sanitize=thread",
    "--config-settings=setup-args=-Dbuildtype=debugoptimized",
  ],
]
commands = [
  [
    "pytest",
    "-s",                                                 # let TSan reports reach the console; pytest otherwise captures them
    "--no-cov",
    "--parallel-threads=auto",
    "--iterations=20",
    "{tox_root}{/}tests{/}dom{/}test_tree_freethread.py",
  ],
]

[env."pypy3.10"]
description = "run the test suite under PyPy 3.10 through cpyext"
base_python = [ "pypy3.10" ]
deps = { replace = "ref", of = [ "env", "_pypy", "deps" ] }
commands_pre = [ { replace = "ref", of = [ "env", "_pypy", "commands_pre" ], extend = true } ]
commands = [ { replace = "ref", of = [ "env", "_pypy", "commands" ], extend = true } ]

[env."pypy3.11"]
description = "run the test suite under PyPy 3.11 through cpyext"
base_python = [ "pypy3.11" ]
deps = { replace = "ref", of = [ "env", "_pypy", "deps" ] }
commands_pre = [ { replace = "ref", of = [ "env", "_pypy", "commands_pre" ], extend = true } ]
commands = [ { replace = "ref", of = [ "env", "_pypy", "commands" ], extend = true } ]