feat(core): add isOk / getOrNull / getOrThrow to Fat12Result

[evanofficial]

Closes #3.

What

Adds idiomatic Kotlin convenience accessors to the sealed Fat12Result<T> so callers can branch on success without an exhaustive when or an is Fat12Result.Ok cast every time.

val Fat12Result<*>.isOk: Boolean
val Fat12Result<*>.isError: Boolean
fun <T> Fat12Result<T>.getOrNull(): T?
fun <T> Fat12Result<T>.getOrThrow(): T   // throws IllegalStateException describing a non-Ok result

(isError is a small addition beyond the issue's list — the inverse reads better than !result.isOk at call sites. Happy to drop it if you'd rather keep the surface minimal.)

Changes

• Extensions added to Fat12Result.kt; existing sealed subclasses unchanged (additive, non-breaking).
• Fat12ResultAccessorsTest: Ok returns the value for all three accessors; NotFound / DiskFull return false/null and getOrThrow() throws. Also covers an Ok(null) so getOrThrow returning a null value is distinguished from an error.

Testing

./gradlew :core:test green.

Summary by CodeRabbit

• New Features

  • Added convenient result-handling helpers to check success vs. error states.
  • Added safe value retrieval (getOrNull) and strict retrieval that throws on errors (getOrThrow).
  • Standardized the string representation for the disk-full error for more consistent messaging.

• Tests

  • Added coverage for the new helpers across success, non-success (including disk-full and not-found), and null payload scenarios, including exception behavior and message content.

[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: 1a671dd4-7f6c-4fdb-9d9e-5f0cba7549a9

📥 Commits

Reviewing files that changed from the base of the PR and between ee8e80f and ab4a008.

📒 Files selected for processing (2)

• core/src/main/kotlin/com/ams/fat12ex/core/Fat12Result.kt
• core/src/test/kotlin/com/ams/fat12ex/core/Fat12ResultAccessorsTest.kt

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

• core/src/test/kotlin/com/ams/fat12ex/core/Fat12ResultAccessorsTest.kt
• core/src/main/kotlin/com/ams/fat12ex/core/Fat12Result.kt

---

📝 Walkthrough

Walkthrough

Adds isOk, isError, getOrNull(), and getOrThrow() helpers to Fat12Result, makes DiskFull stringify stably, and adds JUnit 5 coverage for Ok, NotFound, DiskFull, and nullable values.

Changes

Fat12Result Accessors

Layer / File(s)	Summary
DiskFull string output core/src/main/kotlin/com/ams/fat12ex/core/Fat12Result.kt	Fat12Result.DiskFull now overrides toString() to return DiskFull.
Extension helpers and tests core/src/main/kotlin/com/ams/fat12ex/core/Fat12Result.kt, core/src/test/kotlin/com/ams/fat12ex/core/Fat12ResultAccessorsTest.kt	Adds isOk/isError, getOrNull(), and getOrThrow() on Fat12Result, with tests covering Ok, NotFound, DiskFull, nullable payloads, and thrown exception text.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop hop, the result is clear,
Ok or error, now easy to steer.
DiskFull says its name out loud,
Tests skip and hop right through the crowd.
Happy ears and steady paws!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.86% 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 clearly and concisely describes the main change: adding Fat12Result convenience accessors.
Linked Issues check	✅ Passed	The PR adds isOk, getOrNull(), and getOrThrow(), keeps changes additive, and includes tests for Ok and non-Ok cases.
Out of Scope Changes check	✅ Passed	The DiskFull toString override and message-focused tests support the new accessor behavior and are not unrelated changes.

✨ 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 feat/fat12result-accessors

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

core/src/test/kotlin/com/ams/fat12ex/core/Fat12ResultAccessorsTest.kt (1)

29-45: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Assert the thrown message, not just the exception type.

Lines 35 and 44 currently prove that getOrThrow() throws, but they do not lock in the new “describe the non-Ok outcome” behavior from the PR contract. A message assertion here would prevent that detail from regressing silently.

Proposed test update

     fun notFound_isNotOk_getOrNull_null_getOrThrow_throws() {
         val result: Fat12Result<String> = Fat12Result.NotFound("/MISSING.TXT")
         assertFalse(result.isOk)
         assertTrue(result.isError)
         assertNull(result.getOrNull())
-        assertThrows<IllegalStateException> { result.getOrThrow() }
+        val ex = assertThrows<IllegalStateException> { result.getOrThrow() }
+        assertTrue(ex.message?.contains("NotFound(path=/MISSING.TXT)") == true)
     }
@@
     fun diskFull_isNotOk_getOrNull_null_getOrThrow_throws() {
         val result: Fat12Result<Unit> = Fat12Result.DiskFull
         assertFalse(result.isOk)
         assertTrue(result.isError)
         assertNull(result.getOrNull())
-        assertThrows<IllegalStateException> { result.getOrThrow() }
+        val ex = assertThrows<IllegalStateException> { result.getOrThrow() }
+        assertTrue(ex.message?.contains("DiskFull") == true)
     }

🤖 Prompt for 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.

In `@core/src/test/kotlin/com/ams/fat12ex/core/Fat12ResultAccessorsTest.kt` around
lines 29 - 45, The `Fat12ResultAccessorsTest` cases for
`notFound_isNotOk_getOrNull_null_getOrThrow_throws` and
`diskFull_isNotOk_getOrNull_null_getOrThrow_throws` only verify that
`getOrThrow()` throws `IllegalStateException`; update them to also assert the
thrown exception message so the new non-Ok description contract is covered. Use
the existing `Fat12Result.NotFound`, `Fat12Result.DiskFull`, and `getOrThrow()`
assertions to capture the exception and check its message content, not just the
type.

🤖 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/main/kotlin/com/ams/fat12ex/core/Fat12Result.kt`:
- Around line 35-38: Update Fat12Result.getOrThrow() so the failure message
renders a stable, human-readable description for singleton object variants like
Fat12Result.DiskFull instead of relying on $this. Keep the Ok branch unchanged,
and in the else/error path detect the object-style sealed cases in Fat12Result
and map them to explicit names/messages so getOrThrow() always produces a
predictable error string.

---

Nitpick comments:
In `@core/src/test/kotlin/com/ams/fat12ex/core/Fat12ResultAccessorsTest.kt`:
- Around line 29-45: The `Fat12ResultAccessorsTest` cases for
`notFound_isNotOk_getOrNull_null_getOrThrow_throws` and
`diskFull_isNotOk_getOrNull_null_getOrThrow_throws` only verify that
`getOrThrow()` throws `IllegalStateException`; update them to also assert the
thrown exception message so the new non-Ok description contract is covered. Use
the existing `Fat12Result.NotFound`, `Fat12Result.DiskFull`, and `getOrThrow()`
assertions to capture the exception and check its message content, not just the
type.

🪄 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: 8e404b81-c743-41d2-9bb9-e23e21658c00

📥 Commits

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

📒 Files selected for processing (2)

• core/src/main/kotlin/com/ams/fat12ex/core/Fat12Result.kt
• core/src/test/kotlin/com/ams/fat12ex/core/Fat12ResultAccessorsTest.kt