refactor(cli): version the update cache instead of migrating it

The cache now records its schema and a foreign value -- including an absent
one, which reads as 0 -- means the file is discarded and the next check
rewrites it. The alternative was keeping every field optional forever so older
shapes load, which for a CACHE buys one saved request in exchange for Option
fields that only describe versions nobody runs and that nothing removes.
Bumping CACHE_SCHEMA is now the entire migration story.

Check sources lose their aliases: github, npm-registry and github-packages are
gone, leaving gh-releases, npm, gh-registry and custom. An accepted-alias set
is a surface to document and test forever to save one look at the docs.

An unknown source still falls back to the default, but because an update check
is the wrong place to turn a config typo into a hard failure -- not for
compatibility.

Author: jdalton

changelog.d/A5-no-cache-migrations.md

@@ -0,0 +1,33 @@
+### Changed
+
+**The update cache carries its shape, and a foreign shape is discarded rather
+than migrated.** `~/.perry/update-check.json` now records a `schema` number; a
+value this build does not recognize — including its absence, which reads as `0` —
+means the file is thrown away and the next check rewrites it.
+
+This replaces the alternative, which was to keep every field optional forever so
+that older shapes still load. That trade is a bad one for a cache: it buys one
+saved network request in exchange for a set of `Option` fields that only exist
+to describe versions nobody runs, and that nothing ever removes. Bumping
+`CACHE_SCHEMA` is now the whole migration story.
+
+**One spelling per check source.** `github`, `npm-registry` and
+`github-packages` are gone; the names are `gh-releases`, `npm`, `gh-registry`
+and `custom`. A set of accepted aliases is a surface to document and test
+forever in exchange for saving one look at the docs.
+
+An unknown `source` still falls back to the default rather than failing, but for
+a different reason than compatibility: an update check is the wrong place to
+turn a config typo into a hard error.
+
+<details>
+<summary><b>Tests</b></summary>
+
+The test that asserted a pre-throttle cache still loads is replaced by one
+asserting the opposite — that a foreign schema, and an absent one, are both
+recognized as not-ours. Verified at runtime as well: a planted cache with no
+schema, claiming version `99.0.0` and a `last_check` in 2099, was ignored, a
+real check ran, and the file came back stamped `"schema": 1`.
+
+`cargo test -p perry`: 930 passed, 0 failed.
+</details>

crates/perry/src/release_source.rs

@@ -73,9 +73,14 @@ pub(crate) enum CheckSource {
 
 /// Parse a configured `source` name into a source, given the other keys.
 ///
-/// Returns `None` for a name this build does not know, so the caller can fall
-/// back rather than fail — a config written by a newer Perry must not break an
-/// older one's update check.
+/// One spelling per source, deliberately: a set of accepted aliases is a
+/// surface to keep documented and tested forever in exchange for saving one
+/// lookup in the docs.
+///
+/// Returns `None` for a name this build does not know, so the caller falls back
+/// to the default rather than refusing to check at all. That is not a
+/// compatibility affordance — it is that an update check is the wrong place to
+/// turn a config typo into a hard failure.
 pub(crate) fn from_config(
     source: Option<&str>,
     package: Option<&str>,
@@ -84,16 +89,16 @@ pub(crate) fn from_config(
 ) -> Option<CheckSource> {
     let package = || package.unwrap_or(PERRY_NPM_PACKAGE).to_string();
     match source?.trim().to_ascii_lowercase().as_str() {
-        "gh-releases" | "github" => Some(CheckSource::GhReleases {
+        "gh-releases" => Some(CheckSource::GhReleases {
             url: server
                 .unwrap_or(super::update_checker::GITHUB_URL)
                 .to_string(),
         }),
-        "npm" | "npm-registry" => Some(CheckSource::Npm {
+        "npm" => Some(CheckSource::Npm {
             package: package(),
             registry: registry.unwrap_or(NPM_REGISTRY).to_string(),
         }),
-        "gh-registry" | "github-packages" => Some(CheckSource::GhRegistry {
+        "gh-registry" => Some(CheckSource::GhRegistry {
             package: package(),
             registry: registry.unwrap_or(GH_REGISTRY).to_string(),
         }),

crates/perry/src/update_checker.rs

@@ -21,16 +21,26 @@ const CACHE_MAX_AGE: Duration = Duration::from_secs(24 * 60 * 60);
 const CONNECT_TIMEOUT: Duration = Duration::from_secs(5);
 const REQUEST_TIMEOUT: Duration = Duration::from_secs(10);
 
+/// The shape of `~/.perry/update-check.json` this build writes and reads.
+///
+/// Bump it whenever the meaning of a field changes. There is deliberately no
+/// migration path: this file is a CACHE, rebuilt by the next check, so reading
+/// an older shape buys nothing and costs a growing set of optional fields that
+/// exist only to describe versions nobody runs. A mismatch is discarded.
+const CACHE_SCHEMA: u32 = 1;
+
 #[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
 pub struct UpdateCache {
+    /// See [`CACHE_SCHEMA`]. Absent or different means "throw this away".
+    #[serde(default)]
+    pub schema: u32,
     pub last_check: String,
     pub latest_version: String,
     pub release_url: String,
     /// When the user was last told about this update, if ever.
     ///
-    /// `default` + `skip_serializing_if` so a cache written by an older Perry
-    /// still loads, and a cache that has never notified stays the shape it
-    /// always was.
+    /// Optional because "never notified" is a real state, not because an older
+    /// shape has to load — see [`CACHE_SCHEMA`].
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub last_notification: Option<String>,
     /// Which version that notice was about.
@@ -95,7 +105,10 @@ fn cache_path() -> PathBuf {
 pub fn load_cache() -> Option<UpdateCache> {
     let path = cache_path();
     let content = fs::read_to_string(&path).ok()?;
-    serde_json::from_str(&content).ok()
+    let cache: UpdateCache = serde_json::from_str(&content).ok()?;
+    // A different shape is thrown away, not migrated. The next check rewrites
+    // it, so the only cost is one extra request.
+    (cache.schema == CACHE_SCHEMA).then_some(cache)
 }
 
 fn save_cache(cache: &UpdateCache) {
@@ -205,8 +218,7 @@ pub fn is_cache_stale_with(max_age: Duration) -> bool {
     };
 
     // An invalid cached release must be refreshed rather than suppressing a
-    // check for up to 24 hours. `parse_version` also accepts the abbreviated
-    // versions written by older Perry releases.
+    // check for up to 24 hours.
     if parse_version(&cache.latest_version).is_err() {
         return true;
     }
@@ -347,7 +359,6 @@ fn fetch_latest_version() -> Result<UpdateCache> {
         .context("Failed to create HTTP client")?;
 
     let mut last_err = None;
-    let prior_notification = load_cache().and_then(|c| c.last_notification);
 
     // A configured source answers on its own. Nothing falls back to the ladder
     // after it: a user who said "ask npm" and got an error wants to hear that,
@@ -384,6 +395,7 @@ fn fetch_latest_version() -> Result<UpdateCache> {
         let _guard = lock_cache();
         let prior = load_cache();
         let cache = UpdateCache {
+            schema: CACHE_SCHEMA,
             last_check: now_rfc3339(),
             latest_version: probe.latest_version,
             release_url: probe.release_url,
@@ -422,6 +434,7 @@ fn fetch_latest_version() -> Result<UpdateCache> {
                     let _guard = lock_cache();
                     let prior = load_cache();
                     let cache = UpdateCache {
+                        schema: CACHE_SCHEMA,
                         last_check: now_rfc3339(),
                         latest_version: version,
                         release_url: info.html_url,
@@ -1626,6 +1639,7 @@ mod tests {
     #[test]
     fn test_cache_roundtrip() {
         let cache = UpdateCache {
+            schema: CACHE_SCHEMA,
             last_check: "2025-01-15T10:30:00Z".to_string(),
             latest_version: "0.2.171".to_string(),
             release_url: "https://github.com/PerryTS/perry/releases/tag/v0.2.171".to_string(),
@@ -1640,29 +1654,60 @@ mod tests {
         assert_eq!(cache, parsed);
     }
 
-    /// A cache file written by a Perry that predates the notify throttle must
-    /// still load. Without `serde(default)` it would fail to parse, `load_cache`
-    /// would return `None`, and every user's first run on the new build would
-    /// re-check the network for no reason.
+    /// A cache whose shape this build does not recognize is DISCARDED, not
+    /// migrated. The file is a cache — the next check rewrites it — so reading
+    /// an older shape would buy one saved request in exchange for a growing set
+    /// of optional fields describing versions nobody runs.
     #[test]
-    fn a_cache_without_the_notification_field_still_loads() {
-        let legacy = r#"{
+    fn a_cache_of_another_schema_is_discarded() {
+        let foreign = r#"{
+            "schema": 999,
+            "last_check": "2025-01-15T10:30:00Z",
+            "latest_version": "0.2.171",
+            "release_url": "https://example.test/v0.2.171"
+        }"#;
+        let parsed: UpdateCache = serde_json::from_str(foreign).expect("it still parses");
+        assert_ne!(
+            parsed.schema, CACHE_SCHEMA,
+            "test premise: this fixture is a foreign shape"
+        );
+
+        // A file with no schema at all reads as 0, which is equally foreign —
+        // that is what makes every pre-versioning cache fall out on its own
+        // without a compatibility branch.
+        let unversioned = r#"{
             "last_check": "2025-01-15T10:30:00Z",
             "latest_version": "0.2.171",
             "release_url": "https://example.test/v0.2.171"
         }"#;
-        let parsed: UpdateCache =
-            serde_json::from_str(legacy).expect("a pre-throttle cache must still parse");
-        assert_eq!(parsed.last_notification, None);
-        assert_eq!(parsed.latest_version, "0.2.171");
-
-        // ...and a cache that has never notified round-trips to the same shape
-        // it always had, rather than growing a null field.
-        let written = serde_json::to_string(&parsed).unwrap();
+        let parsed: UpdateCache = serde_json::from_str(unversioned).expect("parses");
+        assert_eq!(parsed.schema, 0);
+        assert_ne!(parsed.schema, CACHE_SCHEMA);
+    }
+
+    /// A cache that has never notified is written without the field, because
+    /// absence is the state — not because anything else has to read it.
+    #[test]
+    fn an_unset_optional_field_is_not_written() {
+        let cache = UpdateCache {
+            schema: CACHE_SCHEMA,
+            last_check: "2025-01-15T10:30:00Z".to_string(),
+            latest_version: "0.2.171".to_string(),
+            release_url: "https://example.test/v0.2.171".to_string(),
+            last_notification: None,
+            last_notified_version: None,
+            published_at: None,
+            headline: None,
+        };
+        let written = serde_json::to_string(&cache).unwrap();
         assert!(
             !written.contains("last_notification"),
             "an unset field must not be written: {written}"
         );
+        assert!(
+            written.contains("\"schema\":1"),
+            "the shape is stamped: {written}"
+        );
     }
 
     #[test]