Skip to content

docs: record the Result-handling convention - #28

Merged
epodivilov merged 1 commit into
mainfrom
docs/result-convention
Jul 22, 2026
Merged

docs: record the Result-handling convention#28
epodivilov merged 1 commit into
mainfrom
docs/result-convention

Conversation

@epodivilov

Copy link
Copy Markdown
Owner

Closes WTK-33.

What changed

  • src/cli/commands/create.ts — the git.removeWorktree call inside the CleanupHandle rollback 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 Result are also discarded at their call sites, all deliberately, and none carry the marker yet:

  • src/application/use-cases/check-for-updates.tswriteUpdateCache inside refreshUpdateCache
  • src/cli/commands/self-update.tswriteUpdateCache after a successful update
  • src/application/use-cases/update-worktrees.tsrunHooks for on-conflict hooks

Out 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).

@epodivilov
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
epodivilov force-pushed the docs/result-convention branch from f26b642 to fd0ca09 Compare July 21, 2026 22:07
@epodivilov
epodivilov merged commit d77bfe2 into main Jul 22, 2026
1 check passed
@epodivilov
epodivilov deleted the docs/result-convention branch July 22, 2026 07:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant