Feat/graphql challenge map readme/tests update

[CarlyAThomas]

Checklist:

• I have read freeCodeCamp's contribution guidelines.
• My pull request has a descriptive title (not a vague title like Update index.md)

Summary

This PR extends the work merged in #574 by:

• Adding README documentation for generating challengeMap.json and recommending a weekly refresh.
• Updating challenge map tests to run against the real challengeMap.json (when present) to validate that FCC Proper output is digestible by Classroom.
• Keeping synthetic tests to validate core transformation logic independent of real data.
• Ensuring the real-map tests fail with a clear message when the map is missing.

Co-authored-by: Newton Chung <NewtonLC@users.noreply.github.com>

Why keep both synthetic and real-map tests?

Synthetic tests validate the transformation logic in isolation (stable, deterministic).
Real-map tests validate that the actual FCC Proper map format is compatible with Classroom. This is important since the upstream map can change over time.

This aligns with the feedback:

“Tests should run against the actual challengeMap.json from FCC Proper … If the file does not exist, the test should fail and tell the user to generate it.”

New real-map test descriptions

1. loads a non-empty challenge map
   Confirms challengeMap.json exists, parses, and has entries. Prevents downstream logic from running on empty or missing data.

2. builds dashboard data using the first valid map entry
   Verifies the map’s real structure can be transformed into the expected nested dashboard shape.

3. skips unknown challenge IDs
   Ensures the logic ignores unknown/missing IDs safely (no crashes or mis-grouping).

4. resolves multiple students against the current map
   Validates per-student transformation with real map data and the expected output shape.

Fail example (missing map):

npm run test:challenge-map

> @freecodecamp/classroom@0.0.0 test:challenge-map
> jest __tests__/utils/challengeMapUtils.test.js

info  - Loaded env from ../classroom/.env
  console.log
    [challengeMapUtils.test] Missing challenge map
      Missing challenge map path: ../classroom/data/challengeMap.json
      Current working directory: ../classroom
      Resolved map path: ../classroom/data/challengeMap.json
      To generate the challengeMap.json please run:
          node scripts/build-challenge-map-graphql.mjs
    
      Tests that rely on the challenge map will fail until the map is generated.

      at Object.log (__tests__/utils/challengeMapUtils.test.js:19:11)

 FAIL  __tests__/utils/challengeMapUtils.test.js
  challengeMapUtils (real challengeMap.json)
    ✕ challengeMap.json must exist to run real-map tests (1 ms)
  challengeMapUtils (synthetic map)
    buildStudentDashboardData
      ✓ should transform flat challenge array into nested certification structure (1 ms)
      ✓ should use first superblock as canonical certification
      ✓ should use first block as canonical block (1 ms)
      ✓ should nest challenges under correct certification and block
      ✓ should include challengeName from map
      ✓ should skip unknown challenge IDs
      ✓ should handle empty challenge array
      ✓ should handle multiple challenges in different certifications
      ✓ should preserve original challenge data properties
      ✓ should include challenges that are only in legacy certifications (-22) (1 ms)
      ✓ should use first superblock even if legacy when both versions exist
    resolveAllStudentsToDashboardFormat
      ✓ should transform multiple students data
      ✓ should include certifications for each student (1 ms)
      ✓ should handle empty student data object
      ✓ should handle null student data
      ✓ should handle undefined student data
      ✓ should handle non-object student data (1 ms)
      ✓ should use provided curriculumMap parameter
      ✓ should process students independently
      ✓ should handle student with no completed challenges (1 ms)
      ✓ should preserve email case sensitivity
    integration scenarios
      ✓ should handle real-world scenario with multiple students and certifications
      ✓ should track challenges from multiple superblocks correctly (1 ms)

  ● challengeMapUtils (real challengeMap.json) › challengeMap.json must exist to run real-map tests

    Missing data/challengeMap.json. Run: node scripts/build-challenge-map-graphql.mjs

      121 |     test('challengeMap.json must exist to run real-map tests', () => {
      122 |       expect(true).toBe(true);
    > 123 |       throw new Error(
          |             ^
      124 |         'Missing data/challengeMap.json. Run: node scripts/build-challenge-map-graphql.mjs'
      125 |       );
      126 |     });

      at Object.<anonymous> (__tests__/utils/challengeMapUtils.test.js:123:13)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 23 passed, 24 total
Snapshots:   0 total
Time:        0.292 s, estimated 1 s
Ran all test suites matching /__tests__\/utils\/challengeMapUtils.test.js/i.

Pass example (map generated):

npm run test:challenge-map

> @freecodecamp/classroom@0.0.0 test:challenge-map
> jest __tests__/utils/challengeMapUtils.test.js

info  - Loaded env from ../classroom/.env
  console.log
    [challengeMapUtils.test] Using challenge map: ../classroom/data/challengeMap.json

      at Object.log (__tests__/utils/challengeMapUtils.test.js:109:11)

  console.log
    [challengeMapUtils.test] Challenge map entries: 12847

      at Object.log (__tests__/utils/challengeMapUtils.test.js:115:11)

 PASS  __tests__/utils/challengeMapUtils.test.js
  challengeMapUtils (real challengeMap.json)
    ✓ loads a non-empty challenge map (2 ms)
    ✓ builds dashboard data using the first valid map entry (3 ms)
    ✓ skips unknown challenge IDs
    ✓ resolves multiple students against the current map (7 ms)
  challengeMapUtils (synthetic map)
    buildStudentDashboardData
      ✓ should transform flat challenge array into nested certification structure (1 ms)
      ✓ should use first superblock as canonical certification
      ✓ should use first block as canonical block
      ✓ should nest challenges under correct certification and block
      ✓ should include challengeName from map
      ✓ should skip unknown challenge IDs
      ✓ should handle empty challenge array (1 ms)
      ✓ should handle multiple challenges in different certifications
      ✓ should preserve original challenge data properties
      ✓ should include challenges that are only in legacy certifications (-22)
      ✓ should use first superblock even if legacy when both versions exist (1 ms)
    resolveAllStudentsToDashboardFormat
      ✓ should transform multiple students data
      ✓ should include certifications for each student
      ✓ should handle empty student data object
      ✓ should handle null student data (1 ms)
      ✓ should handle undefined student data
      ✓ should handle non-object student data
      ✓ should use provided curriculumMap parameter
      ✓ should process students independently
      ✓ should handle student with no completed challenges
      ✓ should preserve email case sensitivity
    integration scenarios
      ✓ should handle real-world scenario with multiple students and certifications (1 ms)
      ✓ should track challenges from multiple superblocks correctly

Test Suites: 1 passed, 1 total
Tests:       27 passed, 27 total
Snapshots:   0 total
Time:        0.519 s, estimated 1 s
Ran all test suites matching /__tests__\/utils\/challengeMapUtils.test.js/i.

Testing:

npm run test:challenge-map

Testing / CI Note

Local dev: If challengeMap.json is missing, the real‑map suite fails with a clear error and guidance to run node scripts/build-challenge-map-graphql.mjs.
CI: When CI=true and the map is missing, the real‑map suite is skipped to keep the pipeline green. Synthetic tests still run.

[NewtonLC]

I tested this out in a Windows environment and originally, upon running node scripts/build-challenge-map-graphql.mjs, there was an issue with the pathing of the challenge map. I updated the file path to use the fileURLToPath() function and it should now work on all machines!

Aside from that, this PR looks ready for review.