test(core): make the README usage example compile-checked

[evanofficial]

Closes #5.

What

The README "Usage example" (a hand-written MemoryBlockDevice + main() that formats, writes /HELLO.TXT, lists, and reads it back) wasn't compiled or run by anything, so it could silently bit-rot as the API evolves.

Adds ReadmeExampleTest mirroring that exact flow — format → open() → writeFile("/HELLO.TXT", …) → list("/") → readFile(…) — and asserts the round-tripped bytes equal "hello fat12". Uses the existing InMemoryBlockDevice fixture at the README's 1.44 MB floppy geometry (2880 × 512-byte sectors) instead of redefining a device (approach 1 from the issue — test-backs-the-README).

README accuracy

The snippet matches the current public API verbatim — the test passed unchanged — so no code in the README needed updating. I added a single line noting the example is backed by ReadmeExampleTest so future readers (and editors) know it's load-bearing.

Testing

./gradlew :core:test green.

Summary by CodeRabbit

• Documentation

  • Updated the README usage example notes to clarify that the snippet is automatically verified during builds.

• Tests

  • Added an automated end-to-end test that executes the README usage example, formats a FAT12 volume, writes and reads HELLO.TXT, and asserts the contents and expected size match exactly.

[coderabbitai]

Warning

.coderabbit.yaml has a parsing error

The CodeRabbit configuration file in this repository has a parsing error and default settings were used instead. Please fix the error(s) in the configuration file. You can initialize chat with CodeRabbit to get help with the configuration file.

💥 Parsing errors (1)

Validation error: Too big: expected string to have <=250 characters at "tone_instructions"

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 79dc958d-85bd-42a8-bb8d-10fd791edc88

📥 Commits

Reviewing files that changed from the base of the PR and between ee752e3 and 25e589a.

📒 Files selected for processing (1)

• core/src/test/kotlin/com/ams/fat12ex/core/ReadmeExampleTest.kt

🚧 Files skipped from review as they are similar to previous changes (1)

• core/src/test/kotlin/com/ams/fat12ex/core/ReadmeExampleTest.kt

---

📝 Walkthrough

Walkthrough

Adds ReadmeExampleTest, which runs the README FAT12 usage flow as a build-verified round trip, and updates README.md to note that the example is covered by the test.

Changes

README Example Test

Layer / File(s)	Summary
ReadmeExampleTest and README note core/src/test/kotlin/com/ams/fat12ex/core/ReadmeExampleTest.kt, README.md	Adds ReadmeExampleTest to format, write, list, read, and close a 1.44MB FAT12 in-memory volume, asserting Fat12Result.Ok and matching file contents, and updates the README usage example to state that the snippet is exercised by this test.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐇 I hopped through the README, then back again,
With ReadmeExampleTest to keep code in the den.
I wrote HELLO.TXT, then read it with glee,
And the bytes came home just as they should be.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a test-backed compile check for the README usage example.
Linked Issues check	✅ Passed	The PR satisfies issue #5 by testing the README round-trip flow, asserting the payload bytes, and updating the README note.
Out of Scope Changes check	✅ Passed	The changes stay within scope, limited to the README note and the new test that verifies the documented flow.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch test/readme-roundtrip

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@core/src/test/kotlin/com/ams/fat12ex/core/ReadmeExampleTest.kt`:
- Around line 4-6: The README round-trip test is only checking decoded text, not
the raw bytes, so update ReadmeExampleTest to compare the returned payload bytes
directly against the original payload in the read/write round-trip assertion.
Use the existing ReadmeExampleTest assertions around the Fat12Result.Ok value
and replace the String-based check with a byte-for-byte comparison, keeping the
test focused on the raw payload contract.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3bfd8a9a-89a2-4f9a-b0cf-aedff7c7228d

📥 Commits

Reviewing files that changed from the base of the PR and between d5f998f and ee752e3.

📒 Files selected for processing (2)

• README.md
• core/src/test/kotlin/com/ams/fat12ex/core/ReadmeExampleTest.kt