@studious-lms/server 1.23.0 → 1.24.0

package/tests/unit/lib/transcriptPdf.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildTranscriptPdf,
+  isLevelBasedBoundary,
+} from "../../../src/lib/transcriptPdf.js";
+
+describe("isLevelBasedBoundary", () => {
+  it("returns false for empty / invalid payloads", () => {
+    expect(isLevelBasedBoundary(null)).toBe(false);
+    expect(isLevelBasedBoundary("")).toBe(false);
+    expect(isLevelBasedBoundary("not-json")).toBe(false);
+    expect(isLevelBasedBoundary(JSON.stringify({ boundaries: [] }))).toBe(
+      false
+    );
+  });
+
+  it("detects CDC Annex-4 level labels", () => {
+    const structured = JSON.stringify({
+      name: "CDC Levels",
+      boundaries: [
+        { grade: "Advanced", minPercentage: 75, maxPercentage: 100 },
+        { grade: "Proficient", minPercentage: 50, maxPercentage: 74 },
+        { grade: "Basic", minPercentage: 25, maxPercentage: 49 },
+        { grade: "Below Basic", minPercentage: 0, maxPercentage: 24 },
+      ],
+    });
+    expect(isLevelBasedBoundary(structured)).toBe(true);
+  });
+
+  it("returns false for letter-grade scales", () => {
+    const structured = JSON.stringify({
+      name: "AP",
+      boundaries: [
+        { grade: "A", minPercentage: 90, maxPercentage: 100 },
+        { grade: "B", minPercentage: 80, maxPercentage: 89 },
+        { grade: "C", minPercentage: 70, maxPercentage: 79 },
+      ],
+    });
+    expect(isLevelBasedBoundary(structured)).toBe(false);
+  });
+});
+
+describe("buildTranscriptPdf", () => {
+  it("builds a non-empty PDF for letter variant", async () => {
+    const bytes = await buildTranscriptPdf({
+      schoolName: "Kathmandu Pilot School",
+      studentName: "Asha Thapa",
+      studentUsername: "asha.thapa",
+      schoolYear: "2082 BS",
+      variant: "letter",
+      classes: [
+        {
+          className: "Mathematics 5",
+          subject: "Mathematics",
+          section: "A",
+          percentage: 88,
+          gradeLabel: "A",
+          categorySummaries: [
+            { name: "Homework", average: 90 },
+            { name: "Exams", average: 86 },
+          ],
+        },
+      ],
+      attendance: {
+        present: 18,
+        late: 1,
+        absent: 1,
+        total: 20,
+        percent: 95,
+      },
+    });
+    expect(bytes.byteLength).toBeGreaterThan(500);
+    expect(bytes[0]).toBe(0x25); // %PDF
+    expect(String.fromCharCode(bytes[1], bytes[2], bytes[3])).toBe("PDF");
+  });
+
+  it("builds a non-empty PDF for level (Annex-4) variant", async () => {
+    const bytes = await buildTranscriptPdf({
+      schoolName: "Kathmandu Pilot School",
+      studentName: "Bikash Rai",
+      schoolYear: "2082 BS",
+      variant: "level",
+      classes: [
+        {
+          className: "English 3",
+          subject: "English",
+          section: "B",
+          percentage: 72,
+          gradeLabel: "Proficient",
+          categorySummaries: [],
+        },
+        {
+          className: "Science 3",
+          subject: "Science",
+          section: "B",
+          percentage: 40,
+          gradeLabel: "Basic",
+          categorySummaries: [],
+        },
+      ],
+      attendance: {
+        present: 10,
+        late: 0,
+        absent: 2,
+        total: 12,
+        percent: (10 / 12) * 100,
+      },
+    });
+    expect(bytes.byteLength).toBeGreaterThan(500);
+  });
+});

package/tests/unit/services/attendanceMerge.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildExcusalLocks,
+  mergeAttendanceUpdateWithLocks,
+} from "../../../src/services/attendanceMerge.js";
+
+describe("buildExcusalLocks", () => {
+  it("maps excusal students to locks and prefers first excusal per student", () => {
+    const locks = buildExcusalLocks(
+      [
+        {
+          id: "ex-1",
+          reason: "ILLNESS",
+          students: [{ studentId: "s1" }, { studentId: "s2" }],
+        },
+        {
+          id: "ex-2",
+          reason: "FAMILY",
+          students: [{ studentId: "s1" }],
+        },
+      ],
+      ["s1", "s2", "s3"]
+    );
+
+    expect(locks).toEqual([
+      { studentId: "s1", excusalId: "ex-1", reason: "ILLNESS", note: undefined },
+      { studentId: "s2", excusalId: "ex-1", reason: "ILLNESS", note: undefined },
+    ]);
+  });
+});
+
+describe("mergeAttendanceUpdateWithLocks", () => {
+  it("forces locked students to EXCUSED and strips them from other lists", () => {
+    const merged = mergeAttendanceUpdateWithLocks({
+      present: [
+        { id: "s1", username: "a" },
+        { id: "s2", username: "b" },
+      ],
+      late: [{ id: "s3", username: "c" }],
+      absent: [{ id: "s4", username: "d" }],
+      excused: [{ id: "s5", username: "e" }],
+      locks: [
+        { studentId: "s2", excusalId: "ex-1", reason: "ILLNESS" },
+        { studentId: "s4", excusalId: "ex-2", reason: "FAMILY" },
+      ],
+      updatedById: "teacher-1",
+    });
+
+    expect(merged.presentIds).toEqual(["s1"]);
+    expect(merged.lateIds).toEqual(["s3"]);
+    expect(merged.absentIds).toEqual([]);
+    expect(merged.excusedIds.sort()).toEqual(["s2", "s4", "s5"].sort());
+    expect(merged.lockedStudentIds.sort()).toEqual(["s2", "s4"].sort());
+
+    const byStudent = new Map(merged.records.map((r) => [r.studentId, r]));
+    expect(byStudent.get("s2")).toMatchObject({
+      status: "EXCUSED",
+      excusedByExcusalId: "ex-1",
+      updatedById: "teacher-1",
+    });
+    expect(byStudent.get("s4")).toMatchObject({
+      status: "EXCUSED",
+      excusedByExcusalId: "ex-2",
+    });
+    expect(byStudent.get("s5")).toMatchObject({
+      status: "EXCUSED",
+      excusedByExcusalId: null,
+    });
+    expect(byStudent.get("s1")?.status).toBe("PRESENT");
+    expect(byStudent.get("s3")?.status).toBe("LATE");
+  });
+
+  it("applies excusal locks even when teacher marks the student present", () => {
+    const merged = mergeAttendanceUpdateWithLocks({
+      present: [{ id: "s1", username: "a" }],
+      late: [],
+      absent: [],
+      locks: [{ studentId: "s1", excusalId: "ex-9" }],
+    });
+
+    expect(merged.presentIds).toEqual([]);
+    expect(merged.records).toEqual([
+      expect.objectContaining({
+        studentId: "s1",
+        status: "EXCUSED",
+        excusedByExcusalId: "ex-9",
+      }),
+    ]);
+  });
+});

package/tests/unit/services/attendanceRate.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { computeAttendanceRate } from "../../../src/services/attendanceRate.js";
+
+describe("computeAttendanceRate", () => {
+  it("returns null percent with no records", () => {
+    expect(computeAttendanceRate([])).toEqual({
+      present: 0,
+      late: 0,
+      absent: 0,
+      total: 0,
+      percent: null,
+    });
+  });
+
+  it("counts late toward attendance rate", () => {
+    const result = computeAttendanceRate([
+      { status: "PRESENT" },
+      { status: "PRESENT" },
+      { status: "LATE" },
+      { status: "ABSENT" },
+    ]);
+    expect(result).toEqual({
+      present: 2,
+      late: 1,
+      absent: 1,
+      total: 4,
+      percent: 75,
+    });
+  });
+
+  it("is 100% when never absent", () => {
+    const result = computeAttendanceRate([
+      { status: "PRESENT" },
+      { status: "LATE" },
+    ]);
+    expect(result.percent).toBe(100);
+  });
+});

package/tests/unit/services/attendanceStats.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import {
+  computeAttendancePercentage,
+  computeAttendancePercentageFromStatuses,
+  tallyAttendanceStatuses,
+} from "../../../src/services/attendanceStats.js";
+
+describe("attendanceStats", () => {
+  it("tallies each attendance status", () => {
+    expect(
+      tallyAttendanceStatuses([
+        "PRESENT",
+        "LATE",
+        "ABSENT",
+        "EXCUSED",
+        "PRESENT",
+      ])
+    ).toEqual({
+      present: 2,
+      late: 1,
+      absent: 1,
+      excused: 1,
+    });
+  });
+
+  it("excludes excused from attendance percentage denominator and numerator", () => {
+    // 2 present + 1 late + 1 absent + 3 excused => (2+1)/(2+1+1) = 75%
+    const percentage = computeAttendancePercentageFromStatuses([
+      "PRESENT",
+      "PRESENT",
+      "LATE",
+      "ABSENT",
+      "EXCUSED",
+      "EXCUSED",
+      "EXCUSED",
+    ]);
+    expect(percentage).toBeCloseTo(75);
+  });
+
+  it("returns null when only excused records exist", () => {
+    expect(
+      computeAttendancePercentageFromStatuses(["EXCUSED", "EXCUSED"])
+    ).toBeNull();
+    expect(
+      computeAttendancePercentage({ present: 0, late: 0, absent: 0 })
+    ).toBeNull();
+  });
+
+  it("treats late as present for attendance rate", () => {
+    expect(
+      computeAttendancePercentage({ present: 1, late: 1, absent: 2 })
+    ).toBeCloseTo(50);
+  });
+});