tox.toml

requires = [ "tox>=4.64.7", "tox-uv>=1.36.1" ]
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_*" ]
# Pin the hash seed so set iteration order is fixed across runs. Without it every CI process draws a
# fresh seed, and a test whose path through the C core depends on set ordering then exercises a
# branch on some runs and not others. The C branch gate wants every branch every run, and llvm-cov
# (the macOS cells) counts branches gcc does not, so such a branch flakes only on macOS -- one cell,
# rotating by interpreter, green on rerun. A fixed seed makes the gate reproducible.
set_env = { PYTHONHASHSEED = "0" }
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",
    # tests/fuzz_build checks the operation limit only the sanitizer fuzz build compiles in; fuzz-smoke runs it
    "--ignore={tox_root}{/}tests{/}fuzz_build",
    { 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" },
    "--json",
    "{env_tmp_dir}{/}c_coverage.json",
    "--html-details",
    "{env_tmp_dir}{/}c_htmlcov.html",
    "--txt-metric",
    "branch",
    "--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",
    "{tox_root}{/}tests{/}clean{/}test_linkify.py::test_linker_is_reusable_across_concurrent_callbacks",
    "--no-cov",
    "--parallel-threads=auto",
    "--iterations=20",
  ], else = [
    "python",
    "-c",
    "print('free-threaded parallel stress skipped (GIL build)')"
  ] },
]
commands_post = [
  [
    "python",
    "-c",
    """
from pathlib import Path
from typing import Final
import json
import sys

report: Final = Path(r'{env_tmp_dir}/c_coverage.json')
if sys.platform == 'darwin' and report.is_file():
    print(json.dumps([
        dict(file=source['file'], lines=[
            line for line in source['lines'] if 521 <= line['line_number'] <= 524
        ])
        for source in json.loads(report.read_text())['files']
        if source['file'].endswith('css/minify/css_grammar.h')
    ], indent=2))
    """,
  ],
]

[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 } ]

[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.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",
    "--ignore={tox_root}{/}tests{/}fuzz_build",
    { 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.atheris]
description = "verify public consumers and native rejection against released Linux Atheris"
base_python = [ "3.14" ]
package = "skip"
deps = [
  "atheris==3.1",
  "html5lib>=1.1",
  "markdown-it-py>=4.2",
  "meson>=1.12.1",
  "meson-python>=0.22.1",
  "ninja>=1.13.2",
  "pytest>=9.1.1",
  "tinycss2>=1.5.1",
  "typing-extensions>=4.16",
]
dependency_groups = []
set_env = { PYTHONPATH = "{tox_root}/tools", PYTHONHASHSEED = "0", CC = "clang", CXX = "clang++", CFLAGS = "-fsanitize=fuzzer-no-link --coverage" }
platform = "linux"
commands_pre = [
  [ "npm", "ci", "--ignore-scripts", "--prefix", "{tox_root}/tools/bench/node" ],
  [
    "uv",
    "pip",
    "install",
    "--reinstall",
    "--no-deps",
    "--no-build-isolation",
    "--editable",
    "{tox_root}",
    "--config-settings=build-dir={env_dir}{/}cbuild",
    "--config-settings=setup-args=-Dbuildtype=debug",
    "--config-settings=compile-args=-j2"
  ],
]
commands = [
  [
    "env",
    "CC=gcc",
    "CXX=g++",
    "python",
    "-m",
    "pytest",
    "{tox_root}/tests/atheris",
    "--confcutdir={tox_root}/tests/atheris",
    "--basetemp={env_tmp_dir}/native",
  ]
]
allowlist_externals = [ "env", "npm" ]

[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",
  ],
  # the phone oracle is the vendored python-phonenumbers checkout, so the suite compares against the pinned release
  [ "uv", "pip", "install", "--no-deps", "{tox_root}{/}tests{/}conformance{/}python-phonenumbers{/}python" ],
]
# 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" ]
pass_env = [ "FUZZ_RNG_SEED" ]
# tox draws a fresh hash seed per run unless set_env pins it, and the XML duplicate-attribute hash salts from it, so a
# find on a hash-dependent path would not replay; fuzz.py logs the seed at the start of each pass
set_env = { CC = "clang", PYTHONHASHSEED = "0" }
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 -DTH_OPERATION_LIMIT=100000",
    "--config-settings=setup-args=-Dc_link_args=-fsanitize=address,undefined",
    "--config-settings=setup-args=-Dbuildtype=debugoptimized",
    "--config-settings=setup-args=-Dfuzzing=true",
  ],
]
commands = [
  [
    "python",
    "{tox_root}{/}tools{/}fuzz{/}fuzz.py",
    "--mode",
    "deep",
    { replace = "posargs", default = [ "--minutes", "2" ], extend = true },
  ],
]

[env.fuzz-amplify]
description = "score super-linear time and output growth: the regression list (per-PR gate) or a shape search"
package = "skip"  # commands_pre installs a plain release build: timing an instrumented build measures the instrumentation
deps = []  # override the base env's gcovr; this env measures time, not coverage
dependency_groups = [ "test" ]  # carries the meson-python build backend the no-build-isolation install below needs
pass_env = [ "FUZZ_RNG_SEED" ]
set_env = { PYTHONHASHSEED = "0" }
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=-Dbuildtype=release",
  ],
]
commands = [
  [
    "python",
    "{tox_root}{/}tools{/}fuzz{/}amplify.py",
    { replace = "posargs", default = [ "regressions" ], extend = true },
  ],
]

[env.fuzz-oracle]
description = """\
  run the sanitizer wrong-output oracles (independent re-parse, random Policy, URL scheme) under ASan/UBSan\
  """
# dharma's xss.dg grammar generates seed payloads; six and webencodings are what the vendored html5lib-python imports
deps = [ "dharma>=1.3.2", "six>=1.17", "webencodings>=0.6.1" ]
dependency_groups = [ "test" ]
pass_env = [ "FUZZ_RNG_SEED" ]
# the independent re-parser is the vendored html5lib-python, imported from its checkout: its setup.py needs the
# pkg_resources module current setuptools no longer ships, so it cannot be installed
set_env = { CC = "clang", PYTHONHASHSEED = "0", PYTHONPATH = "{tox_root}{/}tools{/}html5lib-python" }
commands_pre = [
  # the WPT seeds are a sparse checkout fuzz.py makes itself; a plain update skips them (update = none in .gitmodules)
  [
    "git",
    "-C",
    "{tox_root}",
    "submodule",
    "update",
    "--init",
    "--depth",
    "1",
    "tools/html5lib-python",
    "tests/conformance/DOMPurify",
    "tools/fuzz-data/h5sc",
    "tools/fuzz-data/google-fuzzing",
  ],
  [
    "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 -DTH_OPERATION_LIMIT=100000",
    "--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",
    "oracle",
    { replace = "posargs", default = [ "--minutes", "2" ], extend = true },
  ],
]
allowlist_externals = [ "git" ]

[env.fuzz-reachability]
description = "fail when a ClusterFuzzLite coverage run leaves a harness's target functions unexecuted"
package = "skip"  # commands_pre installs a plain release build; the coverage data comes from the CFLite run
deps = []  # override the base env's gcovr; the coverage data is Python coverage.py output
dependency_groups = [ "test" ]  # carries coverage and the libraries the registry's targets import
set_env = { PYTHONPATH = "{tox_root}{/}tools" }
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=-Dbuildtype=release",
  ],
]
commands = [ [ "python", "-m", "fuzz.reachability", { replace = "posargs", extend = true } ] ]

[env.fuzz-release-diff]
description = "compare HEAD with the latest PyPI release on generated inputs (a local triage aid, not a CI gate)"
package = "skip"  # commands_pre installs a plain release build to compare with the release wheel
deps = []  # override the base env's gcovr; this env compares outputs, not coverage
dependency_groups = [ "test" ]  # carries the meson-python build backend the no-build-isolation install below needs
pass_env = [ "FUZZ_RNG_SEED" ]
set_env = { PYTHONHASHSEED = "0" }
commands_pre = [
  [ "git", "-C", "{tox_root}", "submodule", "update", "--init", "--depth", "1", "tests/html5lib-tests" ],
  [
    "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",
  ],
]
commands = [
  [
    "python",
    "{tox_root}{/}tools{/}fuzz{/}fuzz.py",
    "--mode",
    "release-diff",
    { replace = "posargs", default = [ "--minutes", "2" ], extend = true },
  ],
]
allowlist_externals = [ "git" ]

[env.fuzz-round-trip]
description = "run the round-trip, minifier-semantics, entry-point and source-span oracles under ASan/UBSan"
deps = []  # override the base env's gcovr; this env instruments for ASan, not coverage
dependency_groups = [ "test" ]  # carries markdown-it-py, the Markdown reader the to_markdown oracle re-reads with
pass_env = [ "FUZZ_RNG_SEED" ]
set_env = { CC = "clang", PYTHONHASHSEED = "0" }
commands_pre = [
  # the HTML seeds come from html5lib-tests; the JS identifier oracle needs `npm ci` in tools/bench/node
  [ "git", "-C", "{tox_root}", "submodule", "update", "--init", "--depth", "1", "tests/html5lib-tests" ],
  [
    "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 -DTH_OPERATION_LIMIT=100000",
    "--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",
    "round-trip",
    { replace = "posargs", default = [ "--minutes", "2" ], extend = true },
  ],
]
allowlist_externals = [ "git" ]

[env.fuzz-smoke]
description = "replay past fuzz finds and the seed corpus through every harness under ASan/UBSan (the 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", PYTHONHASHSEED = "0" }
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. The operation
  # limit is the XPath opLimit libxslt's own fuzzer sets (libxslt tests/fuzz/fuzz.c), applied to each counter.
  [
    "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 -DTH_OPERATION_LIMIT=100000",
    "--config-settings=setup-args=-Dc_link_args=-fsanitize=address,undefined",
    "--config-settings=setup-args=-Dbuildtype=debugoptimized",
    "--config-settings=setup-args=-Dfuzzing=true",
  ],
]
commands = [ [ "python", "{tox_root}{/}tools{/}fuzz{/}fuzz.py", "--mode", "smoke" ] ]

[env.preprocess-identity]
description = "check that the fuzz-only branches leave the production build's preprocessed C byte-identical"
skip_install = true
deps = [ "meson>=1.12.1", "ninja>=1.13.2" ]
dependency_groups = []
commands_pre = []  # the check configures its own production build and compiles nothing
commands = [ [ "python", "{tox_root}{/}tools{/}preprocess_identity.py" ] ]
commands_post = []  # drop the base env's C coverage report

[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_phone.py", "{tox_root}{/}src{/}turbohtml{/}_c{/}data{/}phone_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.scalar]
description = "run the test suite against the portable SWAR scan loops that TH_FORCE_SCALAR selects over NEON and SSE2"
base_python = [ "3.14" ]
package = "skip"  # commands_pre installs the forced-scalar editable build
# no gcovr: the SIMD build owns the coverage gate, this run diffs the scalar arms against the same expectations
deps = []
dependency_groups = [ "test" ]
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=-Dbuildtype=release",
    "--config-settings=setup-args=-Dforce_scalar=true",
  ],
]
commands = [
  [
    "pytest",
    "--no-cov",
    "--ignore={tox_root}{/}tests{/}conformance",
    "--ignore={tox_root}{/}tests{/}fuzz_build",
    { replace = "posargs", default = [ "tests" ], extend = true },
  ],
]
commands_post = []  # drop the base env's C coverage report

[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 = [
  [
    # let TSan reports reach the console; pytest otherwise captures them
    "pytest",
    "-s",
    "--no-cov",
    "--parallel-threads=auto",
    "--iterations=20",
    "{tox_root}{/}tests{/}dom{/}test_tree_freethread.py",
    "{tox_root}{/}tests{/}clean{/}test_linkify.py::test_linker_is_reusable_across_concurrent_callbacks",
  ],
]