fix(code): explain why doctor has no latest-version answer

[Mason Daugherty (mdrxy)]

dcode doctor now says why it has no latest-version answer — editable install, update checks disabled, a stale cache, or no check ever completed — instead of the blanket unknown (no recent check).

---

The Updates section could render this, which reads as a contradiction:

Updates ✓
├ Update checks: enabled
├ Auto-updates: disabled (editable install)
├ Latest version: unknown (no recent check)
└ Last checked: 3d ago

Both rows read the same checked_at stamp, but get_cached_update_available applies the 24h cache TTL while the Last checked row does not, and that TTL is invisible in the output. The underlying situation is also worth surfacing: an editable install never contacts PyPI at all (startup auto-update, the in-app background worker, and the update command all bail early), so a stamp on disk was written by another install sharing the state directory — or, for a regular install, by a check that has since started failing, since a failed fetch leaves the stamp untouched.

_format_latest_version now names the cause: not checked (editable install), not checked (checks disabled), unknown (cache stale), or unknown (never checked). A cached answer is still reported whenever one exists.

Rows are deliberately not omitted when they are inert. doctor output is meant to be pasted into bug reports and compared line by line between a working and a broken machine, so the same four labels always render and the --json item labels stay stable; the configured [update] values remain visible even on an editable install, where they are exactly what a triager asks about. No new helper and no TTL arithmetic in doctor: a rejected cached answer plus a recorded stamp already distinguishes stale from never checked. Both rows now share a single stamp read, so they cannot straddle a concurrent cache refresh and disagree.

Freshness is read separately rather than inferred, via a new is_update_cache_fresh in the update-check module: a cache can be current and still hold no usable answer (only pre-release pins were recorded, or a pre-release install meets a stable-only payload), which reports as unknown (cache incomplete) so the row never claims an expiry that did not happen. The helper takes the already-read stamp so the file is still read once.

Made by Open SWE

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace