Dedup cartridge loader into src/cartridges.js (SonarCloud duplication gate)

SonarCloud flagged 7.1% duplication on new code: the cartridge-walk loader
was repeated across bin/evangeliser.js, test/run_all.js, gui/server.js, and
scripts/validate-cartridges.js. Extract one shared module
(src/cartridges.js: eachCartridgeFile / loadCartridges / verdict) and route
all four readers through it.

Verified (Deno 2.8.3): deno fmt --check, deno lint, deno task test (59/59),
deno task build (1/1 cartridges), CLI + GUI /api/cartridges live probe (6
transitions, all six kinds) — all green.

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

Author: claude

.claude/CLAUDE.md

@@ -80,6 +80,7 @@ JavaScript is allowed only when it is Deno/browser runtime glue or a launcher br
 | `bin/evangeliser.js` | 1 | Deno CLI reading correspondence cartridges (offline fallback) | Replace when AffineScript host CLI is runnable directly |
 | `gui/server.js` | 1 | Local Deno HTTP bridge serving the workspace + cartridge API | Replace when AffineScript-to-Deno/webview bridge is available |
 | `gui/app.js` | 1 | Browser-side event/render bridge for the GUI shell | Replace when AffineScript DOM/TEA bridge can drive this UI directly |
+| `src/cartridges.js` | 1 | Shared Deno cartridge loader (CLI, GUI server, validator, tests) | Replace when AffineScript can host the loader |
 | `scripts/validate-cartridges.js` | 1 | Deno cartridge-schema validator (ajv) | Replace when AffineScript can host the validator |
 | `test/run_all.js` | 1 | Deno cartridge invariant tests | Replace when AffineScript test runner is runnable directly |
 

bin/evangeliser.js

@@ -13,6 +13,8 @@
 // The browser workspace ('just gui') is the primary surface; this CLI is the
 // offline-first fallback.
 
+import { loadCartridges, verdict } from "../src/cartridges.js"
+
 const KINDS = {
   "cognate": { glyph: "🤝", pedagogy: "transfer directly" },
   "false-friend": { glyph: "🎭", pedagogy: "flag the trap" },
@@ -54,42 +56,6 @@ function parseArgs(argv) {
   return opts
 }
 
-async function loadCartridges(dirUrl) {
-  const out = []
-  async function walk(d) {
-    let entries
-    try {
-      entries = Deno.readDir(d)
-    } catch {
-      return
-    }
-    for await (const e of entries) {
-      const child = new URL(e.name + (e.isDirectory ? "/" : ""), d)
-      if (e.isDirectory) {
-        await walk(child)
-        continue
-      }
-      if (!e.name.endsWith(".cartridge.json")) continue
-      try {
-        const c = JSON.parse(await Deno.readTextFile(child))
-        out.push({
-          cartridge: c.name ?? e.name,
-          transitions: Array.isArray(c.transitions) ? c.transitions : [],
-        })
-      } catch (err) {
-        console.error(`skip ${e.name}: ${err.message}`)
-      }
-    }
-  }
-  await walk(dirUrl)
-  return out
-}
-
-function verdict(strata, name) {
-  const v = (strata ?? []).find((s) => s.stratum === name)
-  return v ? v.holds : null
-}
-
 function render(t) {
   const k = KINDS[t.kind] ?? { glyph: "?", pedagogy: "" }
   const residue = t.residue?.shape ? ` · residue: ${t.residue.shape}` : ""
@@ -119,7 +85,7 @@ async function main() {
 
   const cartridges = await loadCartridges(root)
   let items = cartridges.flatMap((c) =>
-    c.transitions.map((t) => ({ ...t, cartridge: c.cartridge }))
+    (c.transitions ?? []).map((t) => ({ ...t, cartridge: c.name }))
   )
 
   if (opts.kind) items = items.filter((t) => t.kind === opts.kind)

deno.json

@@ -20,7 +20,7 @@
     "semiColons": false,
     "singleQuote": false,
     "proseWrap": "preserve",
-    "include": ["bin/", "gui/", "scripts/", "test/run_all.js", "deno.json"]
+    "include": ["bin/", "gui/", "scripts/", "src/cartridges.js", "test/run_all.js", "deno.json"]
   },
   "lint": {
     "rules": {

gui/server.js

@@ -9,6 +9,8 @@
 //   deno run --allow-read --allow-net gui/server.js [--port N] [--host H] [--open]
 //   (add --allow-env to honour EVANGELISER_GUI_PORT; --allow-run for --open)
 
+import { loadCartridges as loadAll } from "../src/cartridges.js"
+
 const root = new URL("../", import.meta.url)
 
 function argValue(name, fallback) {
@@ -26,36 +28,12 @@ function envPort() {
 
 async function loadCartridges() {
   const dir = new URL("cartridges/", root)
-  const out = []
-  async function walk(d) {
-    let entries
-    try {
-      entries = Deno.readDir(d)
-    } catch {
-      return
-    }
-    for await (const e of entries) {
-      const child = new URL(e.name + (e.isDirectory ? "/" : ""), d)
-      if (e.isDirectory) {
-        await walk(child)
-        continue
-      }
-      if (!e.name.endsWith(".cartridge.json")) continue
-      try {
-        const c = JSON.parse(await Deno.readTextFile(child))
-        out.push({
-          cartridge: c.name ?? e.name,
-          description: c.description ?? "",
-          languages: c.languages ?? [],
-          transitions: Array.isArray(c.transitions) ? c.transitions : [],
-        })
-      } catch (err) {
-        console.error(`skip ${e.name}: ${err.message}`)
-      }
-    }
-  }
-  await walk(dir)
-  return out
+  return (await loadAll(dir)).map((c) => ({
+    cartridge: c.name ?? "(unnamed)",
+    description: c.description ?? "",
+    languages: c.languages ?? [],
+    transitions: Array.isArray(c.transitions) ? c.transitions : [],
+  }))
 }
 
 const contentTypes = {

scripts/validate-cartridges.js

@@ -8,6 +8,7 @@
 // Exits non-zero if any cartridge fails — suitable for CI.
 
 import Ajv2020 from "npm:ajv@8/dist/2020.js"
+import { eachCartridgeFile } from "../src/cartridges.js"
 
 const dir = new URL("../cartridges/", import.meta.url)
 const schema = JSON.parse(
@@ -20,26 +21,17 @@ const validate = new AjvCtor({ allErrors: true, strict: false }).compile(schema)
 let count = 0
 let bad = 0
 
-async function walk(d) {
-  for await (const entry of Deno.readDir(d)) {
-    const child = new URL(entry.name + (entry.isDirectory ? "/" : ""), d)
-    if (entry.isDirectory) {
-      await walk(child)
-      continue
-    }
-    if (!entry.name.endsWith(".cartridge.json")) continue
-    count++
-    const data = JSON.parse(await Deno.readTextFile(child))
-    if (validate(data)) {
-      console.log(`VALID    ${entry.name}  (${data.transitions.length} transitions)`)
-    } else {
-      bad++
-      console.error(`INVALID  ${entry.name}`)
-      console.error(JSON.stringify(validate.errors, null, 2))
-    }
+await eachCartridgeFile(dir, async (url, name) => {
+  count++
+  const data = JSON.parse(await Deno.readTextFile(url))
+  if (validate(data)) {
+    console.log(`VALID    ${name}  (${data.transitions.length} transitions)`)
+  } else {
+    bad++
+    console.error(`INVALID  ${name}`)
+    console.error(JSON.stringify(validate.errors, null, 2))
   }
-}
+})
 
-await walk(dir)
 console.log(`\n${count - bad}/${count} cartridges valid.`)
 Deno.exit(bad ? 1 : 0)

src/cartridges.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MPL-2.0
+// Shared cartridge loader (Deno glue) for the CLI, the GUI server, the schema
+// validator, and the invariant tests. One walk of cartridges/**/*.cartridge.json
+// so the readers do not each re-implement it.
+
+// Invoke `fn(fileUrl, fileName)` for every *.cartridge.json under `rootUrl`.
+export async function eachCartridgeFile(rootUrl, fn) {
+  async function walk(d) {
+    let entries
+    try {
+      entries = Deno.readDir(d)
+    } catch {
+      return
+    }
+    for await (const e of entries) {
+      const child = new URL(e.name + (e.isDirectory ? "/" : ""), d)
+      if (e.isDirectory) {
+        await walk(child)
+        continue
+      }
+      if (!e.name.endsWith(".cartridge.json")) continue
+      await fn(child, e.name)
+    }
+  }
+  await walk(rootUrl)
+}
+
+// Parse every cartridge under `rootUrl`; returns the raw cartridge objects.
+export async function loadCartridges(rootUrl) {
+  const out = []
+  await eachCartridgeFile(rootUrl, async (url, name) => {
+    try {
+      out.push(JSON.parse(await Deno.readTextFile(url)))
+    } catch (err) {
+      console.error(`skip ${name}: ${err.message}`)
+    }
+  })
+  return out
+}
+
+// Whether a correspondence holds at the named stratum (true / false / null).
+export function verdict(strata, name) {
+  const v = (strata ?? []).find((s) => s.stratum === name)
+  return v ? v.holds : null
+}

test/run_all.js

@@ -8,6 +8,8 @@
 //   deno run --allow-read test/run_all.js
 //   deno task test  /  just test
 
+import { loadCartridges, verdict } from "../src/cartridges.js"
+
 const KINDS = [
   "cognate",
   "false-friend",
@@ -30,34 +32,6 @@ function check(label, cond) {
   }
 }
 
-async function loadCartridges(dirUrl) {
-  const out = []
-  async function walk(d) {
-    let entries
-    try {
-      entries = Deno.readDir(d)
-    } catch {
-      return
-    }
-    for await (const e of entries) {
-      const child = new URL(e.name + (e.isDirectory ? "/" : ""), d)
-      if (e.isDirectory) {
-        await walk(child)
-        continue
-      }
-      if (!e.name.endsWith(".cartridge.json")) continue
-      out.push(JSON.parse(await Deno.readTextFile(child)))
-    }
-  }
-  await walk(dirUrl)
-  return out
-}
-
-function verdict(strata, name) {
-  const v = (strata ?? []).find((s) => s.stratum === name)
-  return v ? v.holds : null
-}
-
 const root = new URL("../cartridges/", import.meta.url)
 const cartridges = await loadCartridges(root)