Display a more helpful error when switching versions and a module or class is not found in the target version

Author: kategengler

app/assets/styles.css

@@ -177,6 +177,7 @@ section.event {
 
 .whoops {
   display: flex;
+  flex-direction: column;
   justify-content: center;
   align-items: center;
   padding: var(--spacing-6);

app/routes/project-version/classes/class.js

@@ -59,8 +59,26 @@ export default class ClassRoute extends Route {
     });
   }
 
-  redirect(model) {
+  redirect(model, transition) {
     if (model.isError) {
+      // Transitioning to the same route, probably only changing version
+      // Could explicitly check by comparing transition.to and transition.from
+      if (transition.to.name === transition?.from?.name) {
+        const projectVersionRouteInfo = transition.to.find(function (item) {
+          return item.params?.project_version;
+        });
+        const attemptedVersion =
+          projectVersionRouteInfo.params?.project_version;
+        const attemptedProject = projectVersionRouteInfo.params?.project;
+        let error = new Error(
+          `We could not find ${transition.to.localName} ${transition.to.params[transition.to.paramNames[0]]} in v${attemptedVersion} of ${attemptedProject}.`,
+        );
+        error.status = 404;
+        error.attemptedProject = attemptedProject;
+        error.attemptedVersion = attemptedVersion;
+        throw error;
+      }
+
       let error = new Error(
         'Error retrieving model in routes/project-version/classes/class',
       );

app/templates/error.hbs

@@ -1,12 +1,20 @@
 <article class="whoops">
   {{#if (eq this.model.status 404)}}
     <h2 class="whoops__title">Ack! 404 friend, you're in the wrong place</h2>
-    <div class="whoops__message">
+    {{#if this.model.attemptedVersion}}
+      <h3>
+        {{this.model.message}} 
+      </h3>
+      <p>
+        Modules, classes, and functions sometimes move around or are renamed across versions.
+        Try the <LinkTo @route="project-version" @models={{array this.model.attemptedProject this.model.attemptedVersion}} data-test-version-index-link>v{{this.model.attemptedVersion}} API docs index.</LinkTo>
+      </p>
+    {{else}}
       <p>
         This page wasn't found. Please try the <LinkTo @route="index">API docs page</LinkTo>.
         If you expected something else to be here, please file a <a href="https://github.com/ember-learn/ember-api-docs/issues/new" target="_blank" rel="noopener noreferrer">ticket</a>.
       </p>
-    </div>
+    {{/if}}
   {{else}}
     <h2 class="whoops__title">
       Whoops! Something went wrong.

tests/acceptance/switch-versions-test.js

@@ -279,4 +279,40 @@ module('Acceptance | version navigation', function (hooks) {
       'navigated to v1.13 class',
     );
   });
+
+  test('switching to a version that is missing a module or class offers a link to the API index for that version', async function (assert) {
+    const versionIndexLinkSelector = '[data-test-version-index-link]';
+    await visit('/ember/6.4/modules/@glimmer%2Ftracking%2Fprimitives%2Fcache');
+    assert.strictEqual(
+      currentURL(),
+      '/ember/6.4/modules/@glimmer%2Ftracking%2Fprimitives%2Fcache',
+    );
+
+    await selectChoose('.ember-power-select-trigger', '3.10');
+
+    assert
+      .dom()
+      .includesText(
+        'We could not find module @glimmer/tracking/primitives/cache in v3.10 of ember.',
+      );
+
+    assert
+      .dom(versionIndexLinkSelector)
+      .includesText('v3.10')
+      .hasAttribute('href', '/ember/3.10');
+
+    await visit('/ember/3.0/classes/Ember.Debug');
+    assert.strictEqual(currentURL(), '/ember/3.0/classes/Ember.Debug');
+
+    await selectChoose('.ember-power-select-trigger', '4.0');
+
+    assert
+      .dom()
+      .includesText('We could not find class Ember.Debug in v4.0 of ember.');
+
+    assert
+      .dom(versionIndexLinkSelector)
+      .includesText('v4.0')
+      .hasAttribute('href', '/ember/4.0');
+  });
 });