[dmccoystephenson]

Summary

• Five characterization tests are added to ProjectJsonReaderWriterImplTest. They cover ProjectJsonReaderWriterImpl branches that no test exercised before:
  • readJson on a missing file returns an empty list and does not create the file
  • readJson on a zero-byte file returns an empty list. This is the file.length() == 0 branch, which readJson_WhenNoProjectsWritten_ShouldReturnEmptyList never reaches because setUp writes [] first
  • readJson on malformed JSON throws Failed to read projects from JSON file, with the IOException as the cause
  • writeJson throws Failed to create directory for projects file: <path> when the parent path is a regular file, and that file is left untouched
  • writeJson throws Failed to write projects to JSON file, with the IOException as the cause, when the target path is a directory
• Each new test builds its own ProjectJsonReaderWriterImpl against a @TempDir path, the same way the existing writeJson_WhenParentDirectoryIsMissing_ShouldCreateIt does. The shared test-projects.json is never touched.
• Only tests are changed; production code is not.

No tracking issue: the gap was found during a Stage B (unit-test expansion) cycle. The only open issue, #27 (REST controller endpoints), stays deferred for the reason recorded on it on 2026-10-19: it needs a new web dependency in build.gradle and undecided endpoint, port and bind-address choices.

Test plan

• ./gradlew test -Dorg.gradle.java.home=/usr/lib/jvm/java-21-openjdk-amd64 passes: 178 tests ran, 0 failures, 0 errors, 0 skipped. ProjectJsonReaderWriterImplTest went from 7 to 12 tests. Counts were summed from build/test-results/test/*.xml.
• CI (CI Pipeline, Build and Test) is green on the PR head

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[github-actions]

Test Results

178 tests  +5   178 ✅ +5   2s ⏱️ ±0s
 24 suites ±0     0 💤 ±0 
 24 files   ±0     0 ❌ ±0 

Results for commit 08f19ff. ± Comparison against base commit b6d3d21.

♻️ This comment has been updated with latest results.

[dmccoystephenson]

Self-review rubric (posted as a plain comment; no independent reviewer is implied):

• Scope: PASS. One file is modified, src/test/java/com/preponderous/parpt/repo/ProjectJsonReaderWriterImplTest.java: +88 lines of tests plus two imports (java.io.IOException, java.nio.file.Files). No production code, formatting or renames are touched.
• Tests-new: PASS (not applicable). No public method is added. All five additions are tests.
• Tests-fix: not applicable. This is a characterization-only cycle with no bug fix to stash. Where a test pins a branch, it is constructed so that the branch matters. For example, removing the file.length() == 0 guard would hand a zero-byte file to Jackson, which throws on empty input, so readJson_WhenFileIsEmpty_ShouldReturnEmptyList would fail. That claim is reasoned, not run.
• Sibling structure: PASS. The new tests follow the existing methodName_ShouldExpectedBehavior naming and the Arrange/Act/Assert comments. Each one builds its own ProjectJsonReaderWriterImpl against a @TempDir path, like writeJson_WhenParentDirectoryIsMissing_ShouldCreateIt.
• Sibling renames: not applicable. Nothing is renamed.
• Docs: PASS. The change is test-only. README.md and CONTRIBUTING.md describe no behaviour this changes, and ./gradlew test is still the documented test command.
• Issue resolution: not applicable. No Closes reference is made; the PR body records that Add controller endpoints to create, retrieve, update and delete projects #27 stays deferred.
• Manual validation: PASS. Locally, ./gradlew test on JDK 21 ran 178 tests (0 failures, 0 errors, 0 skipped; ProjectJsonReaderWriterImplTest 7 → 12), and ./gradlew build succeeded. On the PR head, test, build (21) and Test Results are green. The first build (21) run failed only in Validate Gradle wrapper with connect ETIMEDOUT 104.16.72.101:443, a network fault in a step this diff cannot affect. It passed when re-run through an empty commit.
• Shell command tests: not applicable. No @ShellComponent is changed.
• Round-trip coverage: not applicable. No Project field is added.
• I/O behind an interface: not applicable. No production I/O code is added.

Notes:

• src/test/java/com/preponderous/parpt/repo/ProjectJsonReaderWriterImplTest.java (writeJson_WhenParentPathIsAFile_ShouldThrowNamingTheDirectory): the test relies on POSIX semantics, where mkdirs() fails when a path component is a regular file. That holds on the Linux CI runners. It does not depend on file permissions, so it also holds when the tests are run as root.
• The exact-message assertions (Failed to read projects from JSON file and the two others) tie the tests to the current wording. The repo already does this elsewhere (Project not found: Missing in ProjectRepositoryTest), so it is consistent rather than new coupling.

Verdict: ready to merge. Only test code is added, it is green locally and in CI, and no do-not-auto-merge path is modified.

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson