chore: get TypeScript to validate programStructure.json for us

support/src/documentationHelpers/generateGitBookSummary.ts

@@ -15,18 +15,8 @@ import fs, { type Dirent } from "fs";
 import path from "path";
 import process from "process";
 
-type ProgramStructure = {
-  readonly courses: readonly {
-    readonly name: string;
-    readonly location: string;
-    readonly modules: readonly {
-      readonly name: string;
-      readonly location: string;
-    }[];
-  }[];
-};
-
-const jsonPath = "programStructure.json";
+import programStructure from "./programStructure.json" with { type: "json" };
+import type { ProgramStructure } from "./programStructure.js";
 
 let rootDir = process.cwd();
 let debug = false;
@@ -88,15 +78,9 @@ const linkLine = (level: number, text: string, filePath: string): string =>
 
 // ---------------- Core ----------------
 function generateSummary(structure: ProgramStructure, rootDir: string): string {
-  if (!structure || !Array.isArray(structure.courses)) {
-    throw new Error("Invalid structure JSON: expected { courses: [...] }");
-  }
-
   const lines = [];
 
   for (const course of structure.courses) {
-    if (!course?.name || !course?.location) continue;
-
     const courseAbs = path.resolve(rootDir, course.location);
     const courseRel = toPosixFromRoot(courseAbs);
     if (debug)
@@ -106,10 +90,7 @@ function generateSummary(structure: ProgramStructure, rootDir: string): string {
     const courseLink = ensureReadmeLink(courseAbs, courseRel);
     lines.push(linkLine(0, course.name, courseLink));
 
-    const modules = Array.isArray(course.modules) ? course.modules : [];
-    for (const module of modules) {
-      if (!module?.name || !module?.location) continue;
-
+    for (const module of course.modules) {
       const modAbs = path.resolve(rootDir, module.location);
       const modRel = toPosixFromRoot(modAbs);
       if (debug)
@@ -184,9 +165,7 @@ function generateSummary(structure: ProgramStructure, rootDir: string): string {
 
 // ---------------- Run ----------------
 try {
-  const raw = fs.readFileSync(jsonPath, "utf8");
-  const structure = JSON.parse(raw) as ProgramStructure;
-  const md = generateSummary(structure, rootDir);
+  const md = generateSummary(programStructure as ProgramStructure, rootDir);
 
   process.stdout.write(md);
 } catch (err: any) {

support/src/documentationHelpers/generateLearningGoals.ts

@@ -15,22 +15,10 @@ import { fileURLToPath } from "url";
 import process from "process";
 import updateFileSection from "./updateFileSection.js";
 
-const scriptDir = dirname(fileURLToPath(import.meta.url));
-
-type Course = {
-  readonly name: string;
-  readonly location: string;
-  readonly modules: readonly {
-    readonly name: string;
-    readonly location: string;
-  }[];
-};
-
-type ProgramStructure = {
-  readonly courses: readonly Course[];
-};
+import programStructure from "./programStructure.json" with { type: "json" };
+import type { Course, ProgramStructure } from "./programStructure.js";
 
-const jsonPath = "programStructure.json";
+const scriptDir = dirname(fileURLToPath(import.meta.url));
 
 function extractLearningGoals(content: string): {
   readonly found: boolean;
@@ -114,13 +102,14 @@ if (!courseName) {
   process.exit(1);
 }
 
-const data = JSON.parse(await readFile(jsonPath, "utf-8")) as ProgramStructure;
-const course = data.courses.find((c) => c.name === courseName);
+const course = (programStructure as ProgramStructure).courses.find(
+  (c) => c.name === courseName,
+);
 
 if (!course) {
   console.log(
     "Course not found in json. Please provide one of:",
-    data.courses.map((c) => c.name).join(", "),
+    programStructure.courses.map((c) => c.name).join(", "),
   );
   process.exit(1);
 }

support/src/documentationHelpers/programStructure.ts

@@ -0,0 +1,14 @@
+export type Module = {
+  readonly name: string;
+  readonly location: string;
+};
+
+export type Course = {
+  readonly name: string;
+  readonly location: string;
+  readonly modules: readonly Module[];
+};
+
+export type ProgramStructure = {
+  readonly courses: readonly Course[];
+};

support/tsconfig.json

@@ -7,6 +7,7 @@
     "outDir": "./dist/",
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
     "strict": true,
     "skipLibCheck": true
   }