Skip to content

Development

Setup

uv sync --group dev --group docs

Project structure

  • src/mcp_zen_of_languages/ core package
  • languages/ per-language analyzers and detectors
  • analyzers/ shared pipeline and registry logic
  • rules/ zen principle models
  • docs/ documentation site

Checks

uv run ruff check
uv run ruff format --check
uv run ty check src
uv run pytest
uv run python scripts/check_docs_contrast.py --build --mode check
uv run python scripts/check_content_quality.py

Developer tasks (Poe)

All scripts/*.py helpers are available through Poe tasks in pyproject.toml.

uv run poe check_docs_links
uv run poe check_orphan_docs
uv run poe check_content_quality
uv run poe generate_cli_docs
uv run poe generate_mcp_tools_docs
uv run poe export_svg_assets

Use uv run poe (without a task) to list all available developer tasks.

Tasks are now documented with Poe help text, so discovery is much nicer:

uv run poe --help
uv run poe --help check_docs_assets

When defining or reviewing tasks, you can use either inline-table notation or a dedicated task table:

check_docs_assets = { cmd = "python scripts/check_docs_assets.py", help = "Validate docs asset, CSS, JS, and SVG quality gates" }

[tool.poe.tasks.check_docs_assets]
cmd = "python scripts/check_docs_assets.py"
help = "Validate docs asset, CSS, JS, and SVG quality gates"

Poe also supports configuring the uv executor globally or per task. See the official guidance for details and examples:

Pre-commit

pre-commit install --hook-type pre-commit --hook-type pre-push
pre-commit run --all-files
pre-commit run --hook-stage pre-push --all-files

Debugging tips

  • Use uv run pytest -k <pattern> -xvs for focused tests.
  • Run uv run zensical serve -f mkdocs.yml to preview docs locally.

Don't skip pre-commit

Pushing without running pre-commit run --all-files will likely trigger CI failures. The hooks check linting, docs links, orphan pages, Sphinx role leaks, and docs contrast.

Docs-from-code model

Technical references are generated from source code and docstrings:

  • CLI reference from cli.py (scripts/generate_cli_docs.py)
  • MCP tools reference from server.py (scripts/generate_mcp_tools_docs.py)
  • Config reference from AnalyzerConfig (scripts/generate_config_docs.py)
  • API pages from mkdocstrings ::: declarations in docs/api/*.md

Narrative pages (README, docs home, onboarding flow, philosophy) stay human-authored Markdown. Keep duplicated strategic messaging in snippet blocks and include them with --8<--.

Contrast policy (WCAG AA)

  • Documentation styles must satisfy WCAG AA contrast checks for both caligo-light and caligo-dark.
  • The contrast audit runs in pre-commit and CI via scripts/check_docs_contrast.py.
  • Allowed exceptions must be added to scripts/docs_contrast_config.json with explicit selector scope.
  • Prefer token updates first in docs/stylesheets/tokens/palette.css and docs/stylesheets/tokens/semantic.css, then targeted selector overrides in component modules as needed.