docs: fix the last drifted claims, and make usage-line drift impossible - #1
Merged
Conversation
The audit's remaining findings, plus a structural fix so this class stops
recurring.
CONSOLE TRANSCRIPTS THE CODE CANNOT PRODUCE
docs/commands/README.md promises "Output shown in `console` blocks is
real output from the command, not an illustration." Three blocks were
not:
- getting-started.md showed `feed sync stopped: complete`. sync.py
rewrites a surviving "complete" to TIME_BUDGET_EXHAUSTED before the
summary prints, precisely so a truncated run cannot look finished —
so that string never reaches a terminal. Now `feed exhausted`.
- troubleshooting.md showed a 503 as `[error] HTTP 503 from <url>:
Service Unavailable` followed by `re-run with -v for the full
traceback`. Both lines are wrong: `_advice_for_http` prints
"DeviantArt is having trouble (HTTP 503 Service Unavailable)", and
for a 5xx `offer_traceback` is False so the second line never
appears at all — and where it does appear it says "re-run with -v to
see the request that failed". Replaced with the real two lines,
captured by stubbing a 503.
- auth.md showed `[error] refresh failed: HTTP 401 ...`. The string
"refresh failed" does not exist anywhere in dacli/. The real message
names the refresh token and tells you to run `da auth`.
USAGE LINES — and the reason they drifted unnoticed
Three were stale: `da daily` had gained `--json`, `da search user` had
gained `--json`, and `da sync watched` had gained a mutually exclusive
group, so argparse prints `[--user USER | --via-feed]` where the doc
still showed `[--user USER] [--via-feed]`.
tools/check_doc_flags.py already walks the parser, but it only ever
compared the flag *tables*. The `usage:` line above each table — the part
a reader copies verbatim — was checked by nothing. It is now: every
`usage: da ...` block in docs/ is resolved to its subparser and compared
against `format_usage()`, whitespace-normalised and first line only,
since argparse wraps to terminal width. 31 usage lines now verified
alongside the 67 flag rows.
The check earned its place immediately: I had fixed two usage lines by
hand from the audit's list, and it found a third I had missed
(`da search user`). Negative control confirmed — reverting one drifted
line takes the count from 0 problems to 1.
Two bugs in my own addition, both caught before pushing: I inserted the
call after the loop that prints `problems`, so usage findings were
counted but never displayed; and the summary line still said
"flag-table problem(s)" for what are now documentation problems
generally.
ADR 0007 had drifted past its own refactor: "thirteen command handlers"
(that is the top-level subcommand count; there are 29 handlers) and "the
largest module is 848 lines" (sync.py is ~1,200, and it is the walk plus
its checkpointing — not usefully divisible, which is worth saying rather
than quoting a number that will drift again).
Verified: ruff, mypy, doc references, doc flags + usage lines, codespell
all clean; lychee 194 OK / 0 errors with fragments; 868 tests pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The audit's remaining findings, plus a structural fix so this class stops
recurring.
CONSOLE TRANSCRIPTS THE CODE CANNOT PRODUCE
docs/commands/README.md promises "Output shown in
consoleblocks isreal output from the command, not an illustration." Three blocks were
not:
feed sync stopped: complete. sync.pyrewrites a surviving "complete" to TIME_BUDGET_EXHAUSTED before the
summary prints, precisely so a truncated run cannot look finished —
so that string never reaches a terminal. Now
feed exhausted.[error] HTTP 503 from <url>: Service Unavailablefollowed byre-run with -v for the full traceback. Both lines are wrong:_advice_for_httpprints"DeviantArt is having trouble (HTTP 503 Service Unavailable)", and
for a 5xx
offer_tracebackis False so the second line neverappears at all — and where it does appear it says "re-run with -v to
see the request that failed". Replaced with the real two lines,
captured by stubbing a 503.
[error] refresh failed: HTTP 401 .... The string"refresh failed" does not exist anywhere in dacli/. The real message
names the refresh token and tells you to run
da auth.USAGE LINES — and the reason they drifted unnoticed
Three were stale:
da dailyhad gained--json,da search userhadgained
--json, andda sync watchedhad gained a mutually exclusivegroup, so argparse prints
[--user USER | --via-feed]where the docstill showed
[--user USER] [--via-feed].tools/check_doc_flags.py already walks the parser, but it only ever
compared the flag tables. The
usage:line above each table — the parta reader copies verbatim — was checked by nothing. It is now: every
usage: da ...block in docs/ is resolved to its subparser and comparedagainst
format_usage(), whitespace-normalised and first line only,since argparse wraps to terminal width. 31 usage lines now verified
alongside the 67 flag rows.
The check earned its place immediately: I had fixed two usage lines by
hand from the audit's list, and it found a third I had missed
(
da search user). Negative control confirmed — reverting one driftedline takes the count from 0 problems to 1.
Two bugs in my own addition, both caught before pushing: I inserted the
call after the loop that prints
problems, so usage findings werecounted but never displayed; and the summary line still said
"flag-table problem(s)" for what are now documentation problems
generally.
ADR 0007 had drifted past its own refactor: "thirteen command handlers"
(that is the top-level subcommand count; there are 29 handlers) and "the
largest module is 848 lines" (sync.py is ~1,200, and it is the walk plus
its checkpointing — not usefully divisible, which is worth saying rather
than quoting a number that will drift again).
Verified: ruff, mypy, doc references, doc flags + usage lines, codespell
all clean; lychee 194 OK / 0 errors with fragments; 868 tests pass.