Todo list¶

Every pending item this project tracks, collected from the {todo} admonitions left in the documentation pages and in the docstrings autodoc renders. Each entry links back to where it is written, which is next to the code or the prose it acts on.

Most wait on an upstream release: the ticket named in an item is what closes it.

Todo

Once the docs group requires a click-extra release newer than 10.2.0, one whose prep_path returns a replaced sys.stdout as-is, drop click_extra_run_capture from docs/conf.py. Once the runtime floor reaches that release too, reword the paragraph above: - then returns the live sys.stdout whenever something replaced it.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/github/outputs.py:docstring of repomatic.github.outputs.write_text_output, line 7.)

Todo

Swap the two reusable-workflow lanes in release.yaml to GitHub’s $/ self-repository syntax, and drop their suppression, once actionlint accepts the form: it rejects $/ as a malformed ref today, per rhysd/actionlint#711 and rhysd/actionlint#732. The publish-pypi step keeps ./ either way, since $/ resolves against the workflow’s own commit rather than the release commit it checks out.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/github/workflow_sync.py:docstring of repomatic.github.workflow_sync, line 27.)

Todo

Drop the py-walk dependency and parse .gitignore with wcmatch, already imported here for globbing, once it reads gitignore files natively: facelessuser/wcmatch#226. Pick another parser first if pacha/py-walk#11 ends with py-walk retired: sly, its only dependency, already is.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/file_inventory.py:docstring of repomatic.file_inventory, line 14.)

Todo

Stop excluding Zsh once shfmt formats those constructs: mvdan/sh#1203. Give the shellcheck registry entry a file list of its own in the same change, which keeps the Zsh files out.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/file_inventory.py:docstring of repomatic.file_inventory.FileInventory.shfmt_files, line 19.)

Todo

Delete this pruning pass once uv prunes stale exclude-newer-package entries natively: uv#18792.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/deps/cooldown.py:docstring of repomatic.deps.cooldown.UvSettings.prune, line 3.)

Todo

Delete this module once mdformat-toc can express the exclusion in the ToC marker itself, through hukkin/mdformat-toc#17 or hukkin/mdformat-toc#20.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/awesome_toc.py:docstring of repomatic.awesome_toc, line 19.)

Todo

Compare the clcache keys of two builds on one image, then state what changes them.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/nuitka.md, line 116.)

Todo

Collapse the job’s two Ruff steps, check then format, into one invocation once Ruff unifies linting and formatting behind a single command: astral-sh/ruff#8232. The autopep8 step goes the same way once Ruff wraps long comments: astral-sh/ruff#7414.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/workflows.md, line 130.)

Todo

Once the Nuitka pin moves to a release carrying Nuitka/Nuitka@381a18f17, delete the ccache.conf base_dir write of prepare_compile_cache(), then move this entry to Upstreamed from repomatic. Keep the install into the project virtualenv: the fix keeps the original include paths on Windows.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream.md, line 213.)

Todo

Once MyST-Parser renders an {eval-rst} block into the page’s own document, delete this entry. The rehome_moved_nodes hook of click_extra.sphinx tracks the same release in click-extra. Keep test_pickled_pages_carry_no_build_environment in tests/test_sphinx_crossrefs.py: it shows whether the upstream change holds.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream.md, line 245.)

Todo

Once Sphinx publishes no viewcode page for an unused module under a parallel read, delete this entry. The drop_unused_viewcode_modules hook of click_extra.sphinx tracks the same fix in click-extra.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream.md, line 251.)

Todo

Once the minimum-release-age cooldown lets repomatic run mdformat resolve markdown-it-py 4.3.0, which carries the fix for executablebooks/markdown-it-py#445, run the reproducer from hukkin/mdformat#599 through it. Then update this entry and A known mdformat defect to match the result. With markdown-it-py main at 9aa1aae, which differs from 4.3.0 by its release commit alone, a bare mdformat 1.0.0 keeps every character of that reproducer: it writes \* as * and & as &, as it does in link text. A code span in the alt text makes it stop on Could not format instead: markdown-it-py now keeps the span, while mdformat’s own renderer still drops it, as hukkin/mdformat#414 tracks.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream.md, line 275.)

Todo

When sync-tool-versions moves the mdformat-web pin past 0.2.0, run the reproducer from hukkin/mdformat-web#8 through repomatic run mdformat. Then update this entry to match the result.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream.md, line 283.)

Todo

Drop the [tool.X] translation layer for each tool that grows native pyproject.toml support, as lychee already has. The standing upstream requests, all still unshipped: actionlint#623, biome#9239, gitleaks#2066, zizmor#322. The same request for shfmt (sh#1268) was declined. Nuitka#3909 shipped in 4.2, but only for --project builds, which take their entry points from the project configuration. repomatic names one entry point per build on the command line, so the nuitka bridge stays.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/tool-runner.md, line 13.)

Todo

Build lint-prose, run by lint.yaml over Markdown, docstrings, comments and .claude/: em dashes, Latin abbreviations, the AI-writing tropes as a bundled word list, Unicode decoration, sentence length, sentence-case headings, unbackticked versions, the spelling of proper nouns like “GitHub Actions”, and the owner/repo#N link-text form. It retires about 3,000 words of prose rules. Settle the link-text rule first: it is broken in 135 places, so either the rule or the pages change before the check lands.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 42.)

Todo

Build a local gate command that runs CI’s checks in order with the pinned registry tools: formatters in verify mode against a worktree copy, a bare run mypy, lint-changelog, lint-deps, the workflow linters when a workflow changed, the typos and biome smoke runs, and a fresh uvx --from . resolution with the cooldown hint: parsed. It retires step 2 of repomatic-ship and steps 3 and 5 of babysit-ci, about 3,000 words. Its name is open: the naming table reserves the verb prefixes.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 46.)

Todo

Build lint-commits on pull request and push ranges, with --range for the gate: subject length and shape, [changelog] as the only bracket prefix, the skip-ci tokens, the body cap, a #N that resolves to a real issue, and forbidden trailers from a [tool.repomatic] list. It retires about 900 words across the commit-message rules and two skills.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 50.)

Todo

Build lint-docs for Sphinx repositories, as its own command or as lint-repo checks gated on is_sphinx: html_logo beside the logo pair, ogp_image outside _static, the exec-directives flag, a suppressed myst.xref_missing, the html_baseurl slash, uncommented suppress, nitpick and linkcheck entries, an extension missing from the docs group, a setting equal to its Sphinx default, an automodule on a guide page, bare markers, an orphan .rst and the toctree shape. It retires about 3,500 words of the sphinx-docs agent and half of sphinx-docs-sync; title-octicons is the first row built.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 54.)

Todo

Add the lint-deps warnings the review tables of repomatic-deps still describe in prose: an accreted floor comment, a weak-comment phrase, an exemption for a package no longer declared, an uncommented exemption, and a marker that contradicts its rationale. About 300 words.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 58.)

Todo

Add the lint-repo checks that the filename, uv-flag, YAML and ordering rules still state in prose: filename case and short extensions, a symlinked .gitignore, bumpversion ignore_missing_files, a CI-only flag in addopts, a bare uv run or uvx without --no-progress or --frozen outside the documented job, apt in place of apt-get, a version literal in no recognized shape, a YAML comment block over 8 lines, a stale *-probe.yaml, the awesome topics, jobs ordered by needs level, and every job id present in docs/workflows.md. About 900 words.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 62.)

Todo

Add the hygiene tests the code-style rules still state in prose: every Python comment ends with a period, no Google docstring section, a minimal __init__.py, no MyST markup in a Click command docstring, every Config field documented, the example-data denylist, and the docs/workflows.md version samples equal to the latest tag. About 250 words.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 66.)

Todo

Give six skills their mechanical half as a command or a registry entry: lint-translations for the parity checks of translation-sync, an upstream-page state audit for upstream-audit, a signal table for awesome-triage, sync-milestones for github-housekeeping, scan-virustotal --report plus the vendor templates as data for av-false-positive, init --check, the upstream-norms discovery and log-anchor resolution of file-bug-report, and resvg in the tool registry for brand-assets. About 4,000 words, one item at a time.

(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 70.)

Todo

Drop the YAML-block fixup in the mdformat post-process callback once executablebooks/mdformat-myst#49 merges upstream. See _DIRECTIVE_YAML_OPTIONS_RE for the shape it repairs.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry, line 21.)

Todo

Drop the colon-fence fixup in the same callback once mdformat-myst ships colon-fence support, via either executablebooks/mdformat-myst#36 or executablebooks/mdformat-myst#48. See _ESCAPED_COLON_FENCE_RE for the shape it repairs.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry, line 28.)

Todo

Once lychee ships 0.25.0, the release expected to carry lycheeverse/lychee#2250, run the {#id} reproduction from lycheeverse/lychee#2249 through repomatic run lychee, and report the result there, as that comment commits to. The file:// docs-fragment entry in [tool.lychee] stays either way: lychee reads the Markdown source, which holds neither MyST (target)= labels nor the anchors directives generate at build time.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry, line 38.)

Todo

Move those integrity checks to __post_init__ if the registry ever becomes user-configurable: a test only covers the specs shipped here.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry.BinarySpec, line 16.)

Todo

Move those integrity checks to __post_init__ if the registry ever becomes user-configurable: a test only covers the specs shipped here.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry.ToolSpec, line 10.)

Todo

Give the mdformat entry a config_flag="--config" once mdformat accepts an explicit config path, so it stops relying on discovery from the working directory: hukkin/mdformat#432 and hukkin/mdformat#562.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry.TOOL_REGISTRY, line 7.)

Todo

Declare the exemption once, instead of splicing it onto every frozen command line, as soon as uv grows a configuration or environment knob for --exclude-newer-package: astral-sh/uv#20995. Glob exemptions (astral-sh/uv#20788) and pin-based bypasses (astral-sh/uv#19864, astral-sh/uv#18921) could settle it too.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/release/self_pin.py:docstring of repomatic.release.self_pin.cooldown_exemption, line 28.)

Todo

Carry the creation day as a non-accruing attribute beside commit and release, so no star reading can collide with it, and let repomatic.metrics.chart.render_chart() read a by-age origin from it. This is a store schema change: it adds a metric value that every consumer’s own store-shape test enumerates, so it lands with a note to downstream repositories rather than silently.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/metrics/store.py:docstring of repomatic.metrics.store.Source.rank, line 24.)

Todo

Widen the JSON branch beyond an iterable of dict[str, str] and a flat dict[str, str], the two shapes it asserts on today, when a metadata key needs a richer one.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/metadata/output.py:docstring of repomatic.metadata.output.format_github_value, line 21.)

Todo

Review the octicon of each page against the 81 icons that sphinx-design 0.8.0 adds to the 328 of 0.7.0, through executablebooks/sphinx-design#309, like agent, ai-model and flowchart. Adopt a new icon only once the docs dependencies of every site that takes it require sphinx-design>=0.8: 0.7.0 reports an error on an icon it does not know, and renders the role as plain text.

(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/lint_repo/site.py:docstring of repomatic.lint_repo.site.OcticonRegistry, line 8.)