usethis-qa-config-files-sync

name	usethis-qa-config-files-sync
description	Check whether docs/config-files.txt (the machine-readable export) is in-sync with the per-tool tables in docs/about/config-files.md
compatibility	usethis, Python, markdown, documentation
license	MIT
metadata	{"version":"1.0"}

Config Files Documentation Sync Check

The project maintains two representations of per-tool configuration file support:

• docs/config-files.txt — a machine-readable export generated by the export-config-files prek hook
• docs/about/config-files.md — the human-readable documentation page

The txt file is auto-generated from the Python API; the md page is hand-maintained. These can drift out of sync when tools are added, removed, or reconfigured.

Procedure

1. Read docs/config-files.txt. Each line has the form: Tool Name: file1, file2, ... (resolution=<mode>), or for tools with no resolution: Tool Name: file1, file2, ...
2. Read docs/about/config-files.md. For each tool, find the corresponding ### Tool Name section and extract the file names from the | File | Section | markdown table.
3. For each tool in config-files.txt, verify:
   • A matching ### Tool Name section exists in config-files.md.
   • The files listed in config-files.txt (in order) match the file column entries in the markdown table (in order).
4. Report any discrepancies: missing sections, extra sections, or file lists that differ in membership or order.
5. Fix any gaps found by updating docs/about/config-files.md to match docs/config-files.txt.

What counts as a discrepancy

• A tool present in config-files.txt but missing a ### Tool Name section in config-files.md.
• A tool with a ### Tool Name section in config-files.md that is not present in config-files.txt.
• A file listed for a tool in config-files.txt that does not appear in the corresponding markdown table.
• A file in the markdown table that does not appear in config-files.txt for that tool.
• Files present in both but listed in a different order.

Authoritative source

docs/config-files.txt is the authoritative source — it is generated directly from the Python API via the export-config-files prek hook. When a discrepancy exists, update docs/about/config-files.md to match it, not the other way around.

The resolution mode (e.g. resolution=first, resolution=first_content) in config-files.txt provides context for any callout notes in config-files.md; it does not have a required structural equivalent in the markdown table.