docs: record the Result-handling convention - #28
Merged
Conversation
epodivilov
marked this pull request as ready for review
July 21, 2026 22:04
Port calls return Result and every one must be checked. The single deliberate exception — best-effort worktree rollback in the create cleanup handler — now carries an "// ignored: <reason>" marker so review can tell intent from oversight. Mechanical enforcement was considered and deferred: Biome 2.x GritQL has no type information, so a syntactic rule would need a hand-maintained list of ~42 port method names, and adding a second type-aware linter is disproportionate for a bug class with no live instances.
epodivilov
force-pushed
the
docs/result-convention
branch
from
July 21, 2026 22:07
f26b642 to
fd0ca09
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes WTK-33.
What changed
src/cli/commands/create.ts— thegit.removeWorktreecall inside theCleanupHandlerollback callback now carries an// ignored: <reason>comment. Comment only, no behavior change.CLAUDE.md— new "Result handling" subsection under Conventions: Results from port calls must be checked, deliberate exceptions are marked// ignored: <reason>, and mechanical enforcement is deferred.Decision
No enforcement tooling is being adopted. Biome 2.x GritQL carries no type information, so a syntactic rule would have to match on a hand-maintained list of ~42 port method names and would drift as ports change. Adding a second, type-aware linter to the toolchain is disproportionate for a bug class that currently has zero live instances. The convention is enforced by review, and the
// ignored:marker exists so review can distinguish intent from oversight.Scan
A fresh scan (statement-position port calls, plus assigned-but-never-checked Result variables) finds the create rollback as the only discarded port Result in
src/.Three use-case level functions that return
Resultare also discarded at their call sites, all deliberately, and none carry the marker yet:src/application/use-cases/check-for-updates.ts—writeUpdateCacheinsiderefreshUpdateCachesrc/cli/commands/self-update.ts—writeUpdateCacheafter a successful updatesrc/application/use-cases/update-worktrees.ts—runHooksfor on-conflict hooksOut of scope here; worth a follow-up if the marker should cover use-case Results too.
Checks
pnpm typecheck,pnpm lint,pnpm test— all pass (513 tests, 0 failures).