Fix "value.join is not a function": normalize the index instead of asserting it

Selecting Leia Organa, Palpatine, Qui-Gon Jinn, Darth Maul, Mace Windu, Kit
Fisto, Luminara Unduli or any of the other records where `masters` or
`apprentices` is a bare string took the whole page down: the detail panel
called .join on a string. The source is hand-maintained community JSON and the
same field is not always the same type — masters is an array on 7 records and a
string on 8, apprentices likewise, homeworld is a string except Greedo's two,
cybernetics is a string except Darth Maul's list, and born is a number of years
except Boba Fett's "Shortly after the Battle of Naboo".

The real mistake was believing a TypeScript interface. `as Character` on parsed
JSON asserts a shape the compiler then stops checking and the runtime never
had; it moved the lie somewhere nothing would catch it. Every record now goes
through normalize(), which coerces each field to one shape — list fields are
always arrays and never undefined, text fields are strings or absent, and the
years arrive display-ready (BBY/ABY, or the source's own prose where it had no
number). The UI stops guessing: no optional chaining on lists, no formatYear.

scripts/check-index.mjs runs that normalizer over the live document and asserts
the result, wired into checks.yml. It needs the network and will fail the job
if the source is down — the trade for catching the next shape change in CI
rather than in a browser. It passes on all 87 records today.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnPtsHsXzbApqMpY6k4Pm9

Author: dwang-CXDO

.github/workflows/checks.yml

@@ -37,3 +37,16 @@ jobs:
 
       - name: Typecheck
         run: npm run typecheck
+
+      # The character index is hand-maintained community JSON whose field TYPES
+      # are not stable — `masters` is an array on some records and a bare string
+      # on others, which took the detail panel down with "value.join is not a
+      # function" before the API layer started coercing them. tsc cannot catch
+      # that: an interface is erased at build time and says nothing about what
+      # actually arrives. So this runs the real normalizer over the live
+      # document. It needs the network, and a source outage will fail the job —
+      # that is the trade for catching the next shape change here rather than in
+      # somebody's browser.
+      - name: Character index shape
+        if: '!cancelled()'
+        run: npm run check:index

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@netsapiens/horizon-starwars-app",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": true,
   "description": "Horizon federated app: browse Star Wars characters and adopt one as your avatar. A Module Federation remote loaded by the Horizon host.",
   "author": "dwang",
@@ -9,7 +9,8 @@
     "start": "webpack serve --mode development",
     "build": "webpack --mode production",
     "verify": "horizon-verify-bundle ./dist",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "check:index": "node --experimental-strip-types scripts/check-index.mjs"
   },
   "dependencies": {
     "@netsapiens/horizon-sdk": "^0.2.11",

package.json

@@ -0,0 +1,110 @@
+/**
+ * Shape test for the live character index.
+ *
+ * The source is hand-maintained community JSON, so a field's TYPE is not
+ * stable: `masters` is an array on some records and a bare string on others,
+ * `homeworld` is a string except where it is a list. A TypeScript interface
+ * asserts nothing about that at runtime — it is erased — so this runs the real
+ * `normalize` over the real document and checks what comes out.
+ *
+ * It caught nothing when it was written, because it was written after the
+ * page had already crashed on `value.join is not a function`. It exists so
+ * the next shape change at the source fails a build instead of a browser.
+ *
+ * Needs the network. Run with: npm run check:index
+ */
+import { normalize } from '../src/api/starwarsApi.ts';
+
+const INDEX_URL =
+  'https://raw.githubusercontent.com/akabab/starwars-api/master/api/all.json';
+
+const LIST_FIELDS = [
+  'affiliations',
+  'formerAffiliations',
+  'masters',
+  'apprentices',
+  'equipment',
+];
+const TEXT_FIELDS = [
+  'name',
+  'image',
+  'wiki',
+  'gender',
+  'species',
+  'homeworld',
+  'born',
+  'bornLocation',
+  'died',
+  'diedLocation',
+  'cybernetics',
+  'class',
+  'model',
+  'manufacturer',
+  'haystack',
+];
+const NUMBER_FIELDS = ['id', 'height', 'mass'];
+
+const response = await fetch(INDEX_URL);
+if (!response.ok) {
+  console.error(`Could not fetch the index: ${response.status}`);
+  process.exit(1);
+}
+
+const raw = await response.json();
+const problems = [];
+
+if (!Array.isArray(raw) || raw.length === 0) {
+  console.error('The index is not a non-empty list');
+  process.exit(1);
+}
+
+const characters = raw.map(normalize).filter(Boolean);
+
+for (const character of characters) {
+  const where = `#${character.id} ${character.name}`;
+
+  for (const field of LIST_FIELDS) {
+    const value = character[field];
+    if (!Array.isArray(value)) {
+      problems.push(`${where}: ${field} is ${typeof value}, expected an array`);
+    } else if (value.some((entry) => typeof entry !== 'string')) {
+      problems.push(`${where}: ${field} holds a non-string entry`);
+    }
+  }
+
+  for (const field of TEXT_FIELDS) {
+    const value = character[field];
+    if (value !== undefined && typeof value !== 'string') {
+      problems.push(`${where}: ${field} is ${typeof value}, expected a string`);
+    }
+  }
+
+  for (const field of NUMBER_FIELDS) {
+    const value = character[field];
+    if (value !== undefined && typeof value !== 'number') {
+      problems.push(`${where}: ${field} is ${typeof value}, expected a number`);
+    }
+  }
+}
+
+const dropped = raw.length - characters.length;
+
+if (problems.length) {
+  console.error(`FAIL — ${problems.length} shape problem(s):`);
+  problems.slice(0, 20).forEach((problem) => console.error(`  ${problem}`));
+  process.exit(1);
+}
+
+// A source that suddenly drops most of its records still "passes" every type
+// check above, so assert the roster is there at all.
+if (characters.length < 50) {
+  console.error(
+    `FAIL — only ${characters.length} usable characters; the source has changed shape.`,
+  );
+  process.exit(1);
+}
+
+console.log(
+  `PASS — ${characters.length} characters normalize cleanly` +
+    (dropped ? ` (${dropped} raw record(s) dropped as unusable)` : ''),
+);