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.

[utsab]

Can you add some explanation about the purpose of the Challenge Map? Why does does Classroom App need it? How is it consumed/transformed?

[CarlyAThomas]

I added additional notation in the readme about the purpose of the Challenge Map and how it works so that the functionality is not lost going forward as well as specifics in the file itself and the Utils file explaining how the breakdown works so that if anyone addresses the functions in the future they have context.

[utsab]

Why do we need to check for both cases mapEntry.certification AND mapEntry.superblocks? Are we not sure what the actual property name is? Is the property name sometimes "certification" and at other times "superblocks"? Same question for "block" vs. "blocks" -- is it sometimes one vs. the other?

[CarlyAThomas]

Short answer: that code was dead and has been removed. It was a transition artifact — the build script originally wrote singular fields (certification, block), then was updated to write arrays (superblocks, blocks). The conditional mapEntry.certification || (mapEntry.superblocks || [])[0] was the bridge during that migration and was never cleaned up. Now that the build script always emits arrays, we replaced the whole inline expression with getCanonicalChallengeMapLocation(mapEntry) from challengeMapHelpers.js, which only reads from the arrays. I removed the additional code as it is no longer needed and it makes the code much simpler and straightforward.

[utsab]

2nd time this code is duplicated. Can we prevent the code duplication?

[CarlyAThomas]

I created a util/challengeMapHelpers.js file to consolidate the duplicated logic. This now uses the util/challengeMapHelpers.js file.

[utsab]

This code gets duplicated below. Is there a way to prevent the duplication of this code?

[CarlyAThomas]

This now uses the util/challengeMapHelpers.js file.