tq

Appearance

Docs and Release ​

Commands and contracts for docs generation and release validation.

Implementation and distribution model ​

Distribution contract:

  • canonical package index: PyPI
  • canonical package name: tqlint
  • canonical command: tq
  • canonical install flows: uv add, uv tool install, uvx --from tqlint tq

The build backend is maturin targeting the Rust CLI crate. Published artifacts install the compiled tq executable.

Docs generation ​

Reference artifacts are generated by tq-docsgen. CLI and config docs use narrow JSON manifests; rules docs are generated from Rust-owned metadata in tq-rules.

  • cargo run -p tq-docsgen --locked -- generate all
  • cargo run -p tq-docsgen --locked -- generate cli
  • cargo run -p tq-docsgen --locked -- generate config
  • cargo run -p tq-docsgen --locked -- generate rules

These commands regenerate:

  • docs/reference/cli.md
  • docs/reference/configuration.md
  • docs/guide/quickstart.md
  • docs/.vitepress/generated/rules-sidebar.ts
  • docs/reference/rules/index.md and per-rule pages

Docs site build ​

  • mise run docs-bootstrap
  • mise run docs-build

The local docs tasks bootstrap npm dependencies on demand when node_modules/.bin/vitepress is missing.

The docs site build runs the Rust docs generator first through package.json and then builds VitePress.

Repository and release verification ​

Repository-policy and release artifact checks are enforced by tq-release.

  • cargo run -p tq-release --locked -- verify-release-policy --repo-root .
  • cargo package --workspace --locked
  • mise run release-build
  • cargo run -p tq-release --locked -- verify-artifact-contents --dist-dir dist

The release-policy verifier checks workspace versioning policy and the GitHub Actions Dependabot coverage policy together.

The artifact verifier inspects built wheels and sdists for repository-only paths such as scripts/, tests/, docs/, tmp/, and .github/. Wheel installer script locations under .data/scripts/ are allowed because that is where the packaged tq executable lives.

Release artifact shape ​

mise run release-build builds the source distribution plus a wheel for the current host platform.

The CI release wheel matrix builds the source distribution on Linux, then builds publishable wheels for Linux x86_64, macOS x86_64, macOS arm64, and Windows x86_64. The Linux wheel is built explicitly through maturin build --release --locked --compatibility pypi --zig so the platform tag is PyPI-compatible instead of a native linux_* tag. On SemVer tags, a separate CI attestation job promotes those validated build artifacts into the final validated-dist artifact that the publish workflow consumes without rebuilding.

Current artifacts are:

  • wheels:
    • dist/tqlint-<version>-py3-none-manylinux_*.whl
    • dist/tqlint-<version>-py3-none-macosx_*_x86_64.whl
    • dist/tqlint-<version>-py3-none-macosx_*_arm64.whl
    • dist/tqlint-<version>-py3-none-win_amd64.whl
  • source distribution: dist/tqlint-<version>.tar.gz