Merge pull request #2 from lucasbellesi/codex/java-foundations-mvp

Add Java educational track through advanced modules

Author: lucasbellesi

.github/workflows/cpp-build.yml

@@ -31,6 +31,12 @@ jobs:
         with:
           dotnet-version: "8.0.x"
 
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: "temurin"
+          java-version: "21"
+
       - name: Install clang-format
         run: |
           sudo apt update
@@ -71,6 +77,12 @@ jobs:
         with:
           dotnet-version: "8.0.x"
 
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: "temurin"
+          java-version: "21"
+
       - name: Install g++
         run: |
           sudo apt update
@@ -111,6 +123,12 @@ jobs:
         with:
           dotnet-version: "8.0.x"
 
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: "temurin"
+          java-version: "21"
+
       - name: Setup MSYS2
         uses: msys2/setup-msys2@v2
         with:

CONCEPT_INDEX.md

@@ -9,6 +9,7 @@ Thank you for contributing to this repository.
 - Use clear English for all text, comments, and instructions.
 - Maintain cross-platform compatibility (Windows MSYS2 + Linux).
 - Keep Node-based tooling simple and explicit when touching the TypeScript track.
+- Keep Java modules on plain `javac`/`java` until the track intentionally adopts build tooling.
 
 ## Workflow
 
@@ -52,12 +53,13 @@ For large changes, you can run one language at a time before the full check:
 
 - `python scripts/automation.py check-exercise-output-contracts --language python`
 - `python scripts/automation.py check-exercise-output-contracts --language go`
+- `python scripts/automation.py check-exercise-output-contracts --language java`
 - `python scripts/automation.py check-exercise-output-contracts --language typescript`
 - `python scripts/automation.py check-exercise-output-contracts --language cpp`
 - `python scripts/automation.py check-exercise-output-contracts --language csharp`
 
 These smoke checks also compile standalone C# exercises by generating temporary validation projects during the check.
-TypeScript checks restore Node dependencies from `package-lock.json`, compile with `tsc`, and execute the emitted JavaScript with `node`.
+TypeScript checks restore Node dependencies from `package-lock.json`, compile with `tsc`, and execute the emitted JavaScript with `node`. Java checks compile single-file programs with Java 21 using `javac` and run them with `java`.
 
 The public PowerShell and Bash scripts are thin wrappers over the shared Python automation core in `scripts/automation.py`. Curriculum validation and smoke target metadata live in `scripts/automation_manifest.json`.
 The artifact cleanup command removes generated build outputs, reports, temporary binaries, and exercise report files while keeping restored dependencies such as `node_modules`.
@@ -82,7 +84,7 @@ Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md)
   - `## Checkpoint`
 - Every project or assessment checkpoint should include:
   - `README.md`
-  - runnable entrypoint (`main.cs` + `.csproj`, `main.go`, `main.py`, or `main.ts`)
+  - runnable entrypoint (`main.cs` + `.csproj`, `main.go`, `Main.java`, `main.py`, or `main.ts`)
   - the same learner goal, input/output shape, and acceptance expectations as the corresponding C++ checkpoint
   - required `## Learning Metadata` before `## Quick Run` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Learning Focus`
   - recommended `## Cross-Language Notes` before `## What To Check`
@@ -97,6 +99,7 @@ Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md)
 - Avoid external dependencies and test frameworks for C++ modules.
 - Avoid external dependencies and test frameworks for non-C++ checkpoints.
 - Keep the TypeScript track on plain Node console programs; do not introduce browser, DOM, or framework dependencies.
+- Keep the Java track on package-free single-file programs; do not introduce Maven, Gradle, or `src/main/java` until the curriculum intentionally adds build tooling.
 - Keep examples aligned with C++17.
 - Keep documentation in English and keep path names consistent with folder names.
 - Keep parity planning updated in `LANGUAGE_PARITY_MATRIX.md` when adding modules or checkpoints to non-C++ tracks.

CONTRIBUTING.md

@@ -1,74 +1,77 @@
 # Language Parity Matrix
 
-This matrix tracks module and checkpoint parity across C++, C#, Go, Python, and TypeScript.
+This matrix tracks module and checkpoint parity across C++, C#, Go, Java, Python, and TypeScript.
 
 - Canonical order is defined by the C++ track.
 - C++, C#, Go, Python, and TypeScript now reach module and checkpoint parity through `04-expert`.
+- Java currently tracks `01-foundations`, `02-core`, all `03-advanced` modules and checkpoints, and the first `04-expert` module as a Java 21 MVP.
 - Status labels:
   - `Done`: module implemented with example, exercises, and README.
   - `Planned`: module not implemented yet, already queued in order.
 
 ## Foundations (`01-foundations`)
 
-| Module | C++ | C# | Go | Python | TypeScript |
-| --- | --- | --- | --- | --- | --- |
-| types-and-io | Done | Done | Done | Done | Done |
-| operators-and-expressions | Done | Done | Done | Done | Done |
-| control-flow | Done | Done | Done | Done | Done |
-| functions | Done | Done | Done | Done | Done |
-| arrays-and-vectors | Done | Done | Done | Done | Done |
-| strings | Done | Done | Done | Done | Done |
-| scope-and-lifetime-basics | Done | Done | Done | Done | Done |
-| formatted-output-and-iomanip | Done | Done | Done | Done | Done |
+| Module | C++ | C# | Go | Java | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- | --- |
+| types-and-io | Done | Done | Done | Done | Done | Done |
+| operators-and-expressions | Done | Done | Done | Done | Done | Done |
+| control-flow | Done | Done | Done | Done | Done | Done |
+| functions | Done | Done | Done | Done | Done | Done |
+| arrays-and-vectors | Done | Done | Done | Done | Done | Done |
+| strings | Done | Done | Done | Done | Done | Done |
+| scope-and-lifetime-basics | Done | Done | Done | Done | Done | Done |
+| formatted-output-and-iomanip | Done | Done | Done | Done | Done | Done |
 
 ## Core (`02-core`)
 
 Current parity progress in non-C++ tracks:
 
 - C#: `6/6` modules complete
 - Go: `6/6` modules complete
+- Java: `6/6` modules complete
 - Python: `6/6` modules complete
 - TypeScript: `6/6` modules complete
 
-| Order | Module | C++ | C# | Go | Python | TypeScript |
-| --- | --- | --- | --- | --- | --- | --- |
-| 1 | input-validation | Done | Done | Done | Done | Done |
-| 2 | algorithms-basics | Done | Done | Done | Done | Done |
-| 3 | file-io-basics | Done | Done | Done | Done | Done |
-| 4 | sorting-and-searching | Done | Done | Done | Done | Done |
-| 5 | maps-and-frequency-counting | Done | Done | Done | Done | Done |
-| 6 | error-handling-and-defensive-programming | Done | Done | Done | Done | Done |
+| Order | Module | C++ | C# | Go | Java | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | input-validation | Done | Done | Done | Done | Done | Done |
+| 2 | algorithms-basics | Done | Done | Done | Done | Done | Done |
+| 3 | file-io-basics | Done | Done | Done | Done | Done | Done |
+| 4 | sorting-and-searching | Done | Done | Done | Done | Done | Done |
+| 5 | maps-and-frequency-counting | Done | Done | Done | Done | Done | Done |
+| 6 | error-handling-and-defensive-programming | Done | Done | Done | Done | Done | Done |
 
 ## Advanced and Expert
 
 Current parity progress in non-C++ tracks:
 
 - C#: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
 - Go: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
+- Java: `5/5` modules complete in `03-advanced`, `1/5` in `04-expert`
 - Python: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
 - TypeScript: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
 
 ### Advanced (`03-advanced`) - Current Expansion Queue
 
-| Order | Module | C++ | C# | Go | Python | TypeScript |
-| --- | --- | --- | --- | --- | --- | --- |
-| 1 | structs-and-classes | Done | Done | Done | Done | Done |
-| 2 | constructors-and-invariants | Done | Done | Done | Done | Done |
-| 3 | copy-and-move-semantics | Done | Done | Done | Done | Done |
-| 4 | inheritance-and-polymorphism | Done | Done | Done | Done | Done |
-| 5 | templates-basics | Done | Done | Done | Done | Done |
+| Order | Module | C++ | C# | Go | Java | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | structs-and-classes | Done | Done | Done | Done | Done | Done |
+| 2 | constructors-and-invariants | Done | Done | Done | Done | Done | Done |
+| 3 | copy-and-move-semantics | Done | Done | Done | Done | Done | Done |
+| 4 | inheritance-and-polymorphism | Done | Done | Done | Done | Done | Done |
+| 5 | templates-basics | Done | Done | Done | Done | Done | Done |
 
-`04-expert` projects and assessments are now implemented across all active non-C++ tracks.
+`04-expert` projects and assessments are now implemented across all active non-Java tracks.
 
 ### Expert (`04-expert`)
 
-| Order | Module | C++ | C# | Go | Python | TypeScript |
-| --- | --- | --- | --- | --- | --- | --- |
-| 1 | memory-management-and-raii | Done | Done | Done | Done | Done |
-| 2 | smart-pointers-in-depth | Done | Done | Done | Done | Done |
-| 3 | concurrency-basics | Done | Done | Done | Done | Done |
-| 4 | performance-and-profiling-basics | Done | Done | Done | Done | Done |
-| 5 | modularization-and-build-structure | Done | Done | Done | Done | Done |
+| Order | Module | C++ | C# | Go | Java | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | memory-management-and-raii | Done | Done | Done | Done | Done | Done |
+| 2 | smart-pointers-in-depth | Done | Done | Done | Planned | Done | Done |
+| 3 | concurrency-basics | Done | Done | Done | Planned | Done | Done |
+| 4 | performance-and-profiling-basics | Done | Done | Done | Planned | Done | Done |
+| 5 | modularization-and-build-structure | Done | Done | Done | Planned | Done | Done |
 
 ## Checkpoint Parity
 
@@ -79,18 +82,18 @@ Status labels:
 
 ### Projects
 
-| Checkpoint | C++ | C# | Go | Python | TypeScript |
-| --- | --- | --- | --- | --- | --- |
-| 01-foundations | Done | Done | Done | Done | Done |
-| 02-core | Done | Done | Done | Done | Done |
-| 03-advanced | Done | Done | Done | Done | Done |
-| 04-expert | Done | Done | Done | Done | Done |
+| Checkpoint | C++ | C# | Go | Java | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- | --- |
+| 01-foundations | Done | Done | Done | Done | Done | Done |
+| 02-core | Done | Done | Done | Done | Done | Done |
+| 03-advanced | Done | Done | Done | Done | Done | Done |
+| 04-expert | Done | Done | Done | Planned | Done | Done |
 
 ### Assessments
 
-| Checkpoint | C++ | C# | Go | Python | TypeScript |
-| --- | --- | --- | --- | --- | --- |
-| 01-foundations | Done | Done | Done | Done | Done |
-| 02-core | Done | Done | Done | Done | Done |
-| 03-advanced | Done | Done | Done | Done | Done |
-| 04-expert | Done | Done | Done | Done | Done |
+| Checkpoint | C++ | C# | Go | Java | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- | --- |
+| 01-foundations | Done | Done | Done | Done | Done | Done |
+| 02-core | Done | Done | Done | Done | Done | Done |
+| 03-advanced | Done | Done | Done | Done | Done | Done |
+| 04-expert | Done | Done | Done | Planned | Done | Done |

LANGUAGE_PARITY_MATRIX.md

@@ -4,7 +4,7 @@
 
 This repository teaches programming through small runnable examples and focused exercises.
 
-- Five active language tracks: C++, C#, Go, Python, and TypeScript.
+- Six active language tracks: C++, C#, Go, Java, Python, and TypeScript.
 - Shared concept naming across tracks for easier comparison.
 - Each module follows the same shape: `README.md`, `example/main.*`, and two exercises.
 - Each implemented level ends with a project and an assessment checkpoint.
@@ -19,6 +19,7 @@ For the full local pipeline, install:
 - Go
 - .NET 8 SDK
 - Node LTS with `npm`
+- Java 21 JDK
 
 If you only want to learn one track, follow that track README first because language-specific prerequisites differ.
 
@@ -30,10 +31,12 @@ If you only want to learn one track, follow that track README first because lang
    - [C++ Guide](languages/cpp/README.md)
    - [C# Guide](languages/csharp/README.md)
    - [Go Guide](languages/go/README.md)
+   - [Java Guide](languages/java/README.md)
    - [Python Guide](languages/python/README.md)
    - [TypeScript Guide](languages/typescript/README.md)
 2. Start at the first roadmap for that track:
    - C++: [00-setup](languages/cpp/00-setup/README.md), then `01-foundations`
+   - Java: `01-foundations`, then `02-core`, `03-advanced`, and the available `04-expert` modules
    - C#, Go, Python, TypeScript: `01-foundations`
 3. Run one module example.
 4. Solve `exercises/01` and `exercises/02` in that module.
@@ -53,6 +56,7 @@ If you only want to learn one track, follow that track README first because lang
 | C++ | 00-setup, 01-foundations, 02-core, 03-advanced, 04-expert | Foundations, Core, Advanced, Expert, projects, assessments | Most complete and primary track |
 | C# | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
 | Go | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
+| Java | 01-foundations, 02-core, 03-advanced, 04-expert partial | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 1/5 expert modules, 3/4 projects, 3/4 assessments | Java 21 MVP complete through advanced checkpoints plus first expert module |
 | Python | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
 | TypeScript | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
 
@@ -80,6 +84,13 @@ dotnet run --project languages/csharp/01-foundations/types-and-io/example/types-
 go run languages/go/01-foundations/types-and-io/example/main.go
 ~~~
 
+### Java
+
+~~~bash
+javac -d build/java languages/java/01-foundations/types-and-io/example/Main.java
+java -cp build/java Main
+~~~
+
 ### Python
 
 ~~~bash
@@ -105,6 +116,7 @@ learn-programming-languages-with-examples/
     cpp/
     csharp/
     go/
+    java/
     python/
     typescript/
 ~~~
@@ -133,7 +145,7 @@ A standardized `## Learning Metadata` block is required before `## Quick Run` fo
 Checkpoint artifacts under `languages/<language>/projects/*` and `languages/<language>/assessments/*` should mirror the corresponding C++ checkpoint style:
 
 - `README.md`
-- runnable entrypoint (`main.cpp` in C++, `main.cs` + `.csproj` in C#, `main.go` in Go, `main.py` in Python, or `main.ts` in TypeScript)
+- runnable entrypoint (`main.cpp` in C++, `main.cs` + `.csproj` in C#, `main.go` in Go, `main.py` in Python, `Main.java` in Java, or `main.ts` in TypeScript)
 - same learner goal, input/output shape, and acceptance expectations as the C++ version
 
 ## Example Commenting Standard
@@ -160,7 +172,7 @@ bash ./scripts/verify-repo.sh
 bash ./scripts/lint.sh
 ~~~
 
-`verify-repo` validates curriculum structure, the blocking education-quality gate, output contracts, and compiled-language builds. `lint` validates formatting and static checks for C++, Python, Go, C#, and TypeScript.
+`verify-repo` validates curriculum structure, the blocking education-quality gate, output contracts, and compiled-language builds. `lint` validates formatting and static checks for C++, Python, Go, C#, Java, and TypeScript.
 
 Use narrower commands only when you want a faster loop on one area:
 
@@ -198,15 +210,15 @@ bash ./scripts/clean-artifacts.sh
 bash ./scripts/verify-repo.sh
 ~~~
 
-GitHub Actions validates links, README structure, module completeness, checkpoint completeness, documentation sync, compiled-language builds, multi-language smoke checks, and Linux lint checks for C++, Python, Go, C#, and TypeScript.
+GitHub Actions validates links, README structure, module completeness, checkpoint completeness, documentation sync, compiled-language builds, multi-language smoke checks, and Linux lint checks for C++, Python, Go, C#, Java, and TypeScript.
 
 The public PowerShell and Bash scripts remain the supported entrypoints, but they now delegate to a shared Python automation core under `scripts/automation.py` backed by `scripts/automation_manifest.json`.
 
 Use `clean-artifacts` when you want to remove generated build outputs, reports, temporary binaries, and exercise report files without removing dependencies such as `node_modules`.
 
-The multi-language smoke scripts also compile standalone C# exercises by generating temporary validation projects during the check and compile TypeScript programs before executing their smoke targets.
+The multi-language smoke scripts also compile standalone C# exercises by generating temporary validation projects during the check and compile TypeScript programs before executing their smoke targets, and compile Java single-file programs with Java 21.
 
-Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md) to keep entry examples pedagogically consistent during reviews. The education audit command is advisory and writes markdown/json findings without failing CI.
+Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md) to keep entry examples pedagogically consistent during reviews. The education audit command writes markdown/json findings; `verify-repo` fails on blocking findings, while oversized-example findings remain advisory unless you opt into strict mode.
 Use [EDUCATIONAL_ANTI_PATTERN_BACKLOG.md](EDUCATIONAL_ANTI_PATTERN_BACKLOG.md) for the prioritized anti-pattern vs corrected-example expansion plan.
 
 `verify-repo` now fails on blocking education-quality findings: low example-comment ratio, missing output explanation markers, or boilerplate comments. Oversized example findings remain advisory. When you want the stricter local cleanup mode that also fails on oversized examples, run:
@@ -220,7 +232,7 @@ Documentation sync also validates that [CONCEPT_INDEX.md](CONCEPT_INDEX.md) cove
 For long exercise-contract runs, you can scope by language:
 
 ~~~bash
-python scripts/automation.py check-exercise-output-contracts --language typescript
+python scripts/automation.py check-exercise-output-contracts --language java
 ~~~
 
 ## Contributing

README.md

@@ -2,13 +2,21 @@
 
 This plan assumes 5 study days per week, 60-90 minutes per day.
 
+This is the canonical study plan because the C++ track is the primary complete reference. Learners using C#, Go, Python, TypeScript, or Java can follow the same weekly concept order by opening the matching language guide and concept paths from [CONCEPT_INDEX.md](CONCEPT_INDEX.md). Java currently has complete foundations, core, advanced modules and checkpoints, plus the first expert module.
+
 ## How To Use This Plan
 
 1. Follow modules in order.
 2. For each module: read `README.md`, run `example/main.cpp`, solve `exercises/01.cpp` and `exercises/02.cpp`.
 3. Mark progress in `languages/cpp/CHECKLIST.md`.
 4. Use level capstones to combine concepts.
 
+For another language, replace the C++ file names with that track's entrypoint convention:
+
+- Java: `example/Main.java`, `exercises/Exercise01.java`, `exercises/Exercise02.java`
+- C#: project-based examples with `.csproj`, exercises as `01.cs` and `02.cs`
+- Go, Python, TypeScript: `example/main.*`, `exercises/01.*`, `exercises/02.*`
+
 ## Week 1 - Foundations Basics
 
 Modules: