development

Now writing the page.

Development

Relevant source files

• README.md
• tests/test_repodocs.py
• .github/workflows/ci.yml

Running the test suite

RepoDocs' entire test suite lives in a single file, tests/test_repodocs.py, and is exposed to pytest through one entry point: test_repodocs() at the bottom of the file, which simply calls selftest() (tests/test_repodocs.py:589-590). selftest() is a long, linear function (tests/test_repodocs.py:44-586) that exercises the library modules directly — repodocs.plan, repodocs.render, repodocs.citations, repodocs.generate, repodocs.gitlinks, repodocs.publish, repodocs.scan, repodocs.translate, and repodocs.cli — using tempfile.TemporaryDirectory() fixtures rather than mocks, so most assertions run against real files on disk (tests/test_repodocs.py:1-26).

Contributors run the suite with:

uv run --extra test pytest -q

as documented in the README's Development section (README.md:135-138). The --extra test flag pulls in the test dependency group defined in pyproject.toml (pytest itself) before invoking it. Sources: README.md:L135-L138, tests/test_repodocs.py:L589-L590

What the suite covers

selftest() walks through the pipeline stages in order, each in its own tempfile.TemporaryDirectory() block:

Area	Example assertions
Planning	plan_pages produces expected slugs (overview, installation, architecture, development, changelog); validate_pages drops bad slugs, non-dict entries, and duplicates (tests/test_repodocs.py:55-76)
Plan caching	llm_plan reuses plan.json when the fingerprint is unchanged and never caches a fallback plan after the backend fails (tests/test_repodocs.py:102-127)
Graph digest	graph_digest returns "" when graphify-out/graph.json is absent or corrupt, and a compact prompt block when present (tests/test_repodocs.py:129-149)
Generation decisions	decide_page / generate_decision skip-vs-regenerate logic and hash memoization across pages (tests/test_repodocs.py:89-100, 151-165)
HTML build	build_html embeds page titles/markdown, excludes index.md, and fails via SystemExit (not a raw traceback) on empty output or vendoring network failure (tests/test_repodocs.py:167-191)
Citations	CITATION_RE, citation_error, citation_problems, and requires_evidence reject reversed ranges, out-of-bounds line numbers, path mismatches, and traversal (tests/test_repodocs.py:534-565)
GitHub/wiki linking	_github_slug, rewrite_citation_links (including HTML-escaping to block injected attributes), wiki_remote_url (tests/test_repodocs.py:193-210, 389-393)
Publishing	stage_publish / stage_wiki staging, secret-pattern scanning via staged_secret_findings, branch-safety guard publish_branch_safe, and symlink-escape rejection (tests/test_repodocs.py:299-387)
Wiki push	publish_wiki_push against a local bare git remote covering WikiNotInitialized, no-op push, a normal commit/push, and a rejected pre-receive hook (tests/test_repodocs.py:395-468)
Setup	setup_install fresh/identical/differs/force-overwrite behavior (tests/test_repodocs.py:469-485)
Path safety	safe_repo_file rejects traversal, absolute paths, NUL bytes, and symlink escapes (tests/test_repodocs.py:488-504)
Scan self-ingestion	scan() never includes repo-docs/, graphify-out/, or the configured output dir in src_files, and drops symlink escapes (tests/test_repodocs.py:513-532)
XSS/viewer wiring	The built HTML viewer sanitizes markdown with DOMPurify, loads purify.min.js before use, and runs Mermaid in securityLevel: "strict" (tests/test_repodocs.py:567-579)

Sources: tests/test_repodocs.py:L44-L586

Continuous integration

CI is defined in .github/workflows/ci.yml and runs on every push to main and on pull requests, with concurrency set to cancel superseded runs on the same ref (.github/workflows/ci.yml:1-13). The test job runs on ubuntu-latest across a matrix of Python 3.10, 3.12, and 3.13 (.github/workflows/ci.yml:16-21) and executes, per Python version:

uvx --from . repodocs --version      # smoke-test the package installs and the CLI runs
uv run --extra test pytest -q        # the test suite
uvx ruff@0.15.22 check .             # lint
python3 scripts/check_module_size.py # module-size guard

(.github/workflows/ci.yml:22-31). The CI badge in the README links to this workflow's Actions page (README.md:6). Sources: .github/workflows/ci.yml:L1-L31, README.md:L6-L6

Related documentation

The README's Development section points contributors to CONTRIBUTING.md for contribution guidelines and SECURITY.md for reporting vulnerabilities (README.md:137-138); this page does not repeat their content since it was not part of the candidate files reviewed here. Sources: README.md:L135-L138