Program Summary (#2590)

* add program rows

* fix existing tests

* add some tests for programsummary

* fix some types

* make req_tree more flexible

* remove some ts-expect-error

Author: ChristopherChudzicki

frontends/api/package.json

@@ -32,6 +32,7 @@
   "dependencies": {
     "@mitodl/mitxonline-api-axios": "^2025.10.21",
     "@tanstack/react-query": "^5.66.0",
-    "axios": "^1.12.2"
+    "axios": "^1.12.2",
+    "tiny-invariant": "^1.3.3"
   }
 }

frontends/api/src/mitxonline/test-utils/factories/index.ts

@@ -4,5 +4,14 @@ import * as programs from "./programs"
 import * as courses from "./courses"
 import * as organizations from "./organization"
 import * as user from "./user"
+import * as requirements from "./requirements"
 
-export { mitx as enrollment, programs, courses, organizations, user, pages }
+export {
+  mitx as enrollment,
+  programs,
+  courses,
+  organizations,
+  user,
+  pages,
+  requirements,
+}

frontends/api/src/mitxonline/test-utils/factories/pages.ts

@@ -279,32 +279,7 @@ const programPageItem: PartialFactory<ProgramPageItem> = (override) => {
           electives: [],
         },
       },
-      req_tree: [
-        {
-          data: {
-            node_type: "operator",
-            operator: "all_of",
-            operator_value: null,
-            program: faker.number.int(),
-            course: null,
-            title: "Required Courses",
-            elective_flag: false,
-          },
-          id: 1,
-        },
-        {
-          data: {
-            node_type: "operator",
-            operator: "min_number_of",
-            operator_value: "2",
-            program: faker.number.int(),
-            course: null,
-            title: "Elective Courses",
-            elective_flag: true,
-          },
-          id: 2,
-        },
-      ],
+      req_tree: [],
       page: {
         feature_image_src: faker.image.url({
           width: 1134,

frontends/api/src/mitxonline/test-utils/factories/requirements.ts

@@ -0,0 +1,139 @@
+import type {
+  V2ProgramRequirement,
+  V2ProgramRequirementData,
+} from "@mitodl/mitxonline-api-axios/v2"
+import { V2ProgramRequirementDataNodeTypeEnum } from "@mitodl/mitxonline-api-axios/v2"
+
+import { faker } from "@faker-js/faker/locale/en"
+import { UniqueEnforcer } from "enforce-unique"
+import invariant from "tiny-invariant"
+
+const uniqueNodeId = new UniqueEnforcer()
+const uniqueProgramId = new UniqueEnforcer()
+
+type NodeConstructorOpts = {
+  id?: number | null
+  data?: Partial<V2ProgramRequirementData>
+}
+
+/**
+ * Build req_tree data for tests:
+ *
+ * ```ts
+ * const root = new RequirementTreeBuilder()
+ * const required = root.addOperator({ operator: "all_of" })
+ * const elective = root.addOperator({ operator: "min_number_of", operator_value: "2" })
+ *
+ * required // Two required courses
+ *   .addCourse()
+ *   .addCourse()
+ *
+ * elective // Three elective courses, two of which must be completed
+ *   .addCourse()
+ *   .addCourse()
+ *   .addCourse()
+ *
+ * const req_tree = root.serialize()
+ * ```
+ *
+ */
+class RequirementTreeBuilder implements V2ProgramRequirement {
+  children: RequirementTreeBuilder[] | undefined
+  data: V2ProgramRequirementData
+  id: number
+  #root: RequirementTreeBuilder
+
+  constructor({ id, data }: NodeConstructorOpts = {}) {
+    this.id = id ?? uniqueNodeId.enforce(faker.number.int)
+    this.data = {
+      // @ts-expect-error Root node is not actually exposed in the API
+      node_type: "program_root",
+      course: null,
+      required_program: null,
+      program: uniqueProgramId.enforce(faker.number.int),
+      title: null,
+      operator: null,
+      operator_value: null,
+      elective_flag: false,
+      ...data,
+    }
+    this.#root = this
+  }
+
+  addChild(node: RequirementTreeBuilder) {
+    node.#root = this.#root
+    if (!this.children) {
+      this.children = []
+    }
+    this.children.push(node)
+  }
+
+  addCourse({
+    course,
+  }: Pick<Partial<V2ProgramRequirement["data"]>, "course"> = {}) {
+    const data: V2ProgramRequirementData = {
+      node_type: V2ProgramRequirementDataNodeTypeEnum.Course,
+      course: course ?? uniqueProgramId.enforce(faker.number.int),
+      program: this.#root.data.program,
+      required_program: null,
+      title: null,
+      operator: null,
+      operator_value: null,
+      elective_flag: false,
+    }
+    const courseNode = new RequirementTreeBuilder({ data })
+    this.addChild(courseNode)
+    return courseNode
+  }
+  addOperator(opts: {
+    operator: "min_number_of" | "all_of"
+    operator_value?: string
+  }) {
+    invariant(opts.operator, "operator is required")
+    if (opts.operator === "min_number_of") {
+      invariant(
+        opts.operator_value &&
+          !isNaN(Number(opts.operator_value)) &&
+          Number(opts.operator_value) > 0,
+        "operator_value is required and must be a positive number when operator is min_number_of",
+      )
+    }
+    const data: V2ProgramRequirementData = {
+      ...opts,
+      node_type: V2ProgramRequirementDataNodeTypeEnum.Operator,
+      course: null,
+      required_program: null,
+      program: this.#root.data.program,
+      title: null,
+      elective_flag: opts.operator === "min_number_of" ? true : false,
+    }
+    const operatorNode = new RequirementTreeBuilder({ data })
+    this.addChild(operatorNode)
+    return operatorNode
+  }
+
+  addProgram(opts: { program?: number; title?: string } = {}) {
+    const programId = opts.program ?? uniqueProgramId.enforce(faker.number.int)
+    const data: V2ProgramRequirementData = {
+      node_type: "program",
+      course: null,
+      program: this.#root.data.program,
+      required_program: programId,
+      title: null,
+      operator: null,
+      operator_value: null,
+      elective_flag: false,
+    }
+    const programNode = new RequirementTreeBuilder({ data })
+    this.addChild(programNode)
+    return programNode
+  }
+
+  serialize(): V2ProgramRequirement {
+    const node = { id: this.id, data: this.data }
+    const children = this.children?.map((child) => child.serialize())
+    return children ? { ...node, children } : node
+  }
+}
+
+export { RequirementTreeBuilder }