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. Local and CI release builds consume the exact maturin pin from .github/dev-tools.toml through cargo dev release build-tool-requirements --repo-root .. 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 ​

bash
npm ci --ignore-scripts
npm run docs:build

The docs site build runs the Rust docs generator first through package.json and then builds VitePress. The Node and npm versions are declared in package.json; install them with the environment manager that owns your machine configuration.

Repository and release verification ​

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

  • cargo dev check all --repo-root .
  • cargo dev check --profile full all --repo-root .
  • cargo dev release verify-artifacts --dist-dir dist --profile <expected-profile>

The release-policy verifier checks workspace versioning policy, GitHub Actions Dependabot coverage policy, and release build tool pinning together.

The artifact verifier checks the profile-specific wheel and sdist set, rejects unsupported or native Linux wheel tags, and inspects archives 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 ​

cargo dev check --profile full all includes the local release build, which builds the source distribution plus a wheel for the current host platform. Use cargo dev release build --dry-run --repo-root . to inspect the artifact build commands without changing dist/.

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 read-only CI job validates the complete artifact set before a checkout-free OIDC job attests the same bytes and uploads validated-dist. The checkout-free publish workflow consumes that artifact without rebuilding or executing repository code in its credentialed job.

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