[PR #711] [MERGED] docs(hopper): document HopperTargetLease realpath fallback #2190

New issue

Closed

opened 2026-10-16 21:15:28 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:15:28 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/711
Author: @vinay121314
Created: 10/6/2026
Status: ✅ Merged
Merged: 10/6/2026
Merged by: @morluto

Base: main ← Head: patch-1

📝 Commits (2)

6847bc9 docs(hopper): document HopperTargetLease realpath fallback
5624268 docs(hopper): clarify realpath fallback errors

📊 Changes

1 file changed (+7 additions, -0 deletions)

View changed files

📝 src/hopper/HopperTargetLease.ts (+7 -0)

📄 Description

Summary

Fixes #642. Documents why acquireHopperTargetLease falls back from realpath to lexical resolve, and when that fallback is expected, so it no longer reads as a silently swallowed failure.

Problem and expected behavior

src/hopper/HopperTargetLease.ts catches any realpath failure and uses resolve(input.targetPath) without explanation. The #637 silent-catch sweep deferred this because it is fallback-value semantics, but nothing stated when realpath is expected to fail versus when the fallback masks a real problem.

Change and scope

Comment-only change above the realpath(...).catch(...) call stating:

the canonical path only derives the lease key and never authorizes access;
expected failure cases (missing target or path component, ENOENT/ENOTDIR; unreadable component, EACCES; symlink loop, ELOOP);
the cost of the fallback: the key stays deterministic, but symlinked spellings of such a path may take separate leases.

Intentionally not included: debug-level logging of the fallback (the issue's alternative option). Happy to add it if preferred.

Contract and boundary impact

Semantic owner and earliest changed stage: none (comment only)
CLI and MCP/tool-catalog contract: none
Provider, bridge, target-format, or platform compatibility: none
Evidence, artifact, provenance, or reconstruction contract: none
Process execution, authorization, cleanup, or containment impact: none
Generated metadata (docs/product-catalog.json), package, or installation impact: none

Evidence and regression coverage

Tests added or updated: none (no behavior change)
Base reproduction or other evidence: source-derived from src/hopper/HopperTargetLease.ts
User-visible CLI/MCP output (if applicable): not applicable
Remaining proof gaps: none

Validation performed

oxfmt --check src/hopper/HopperTargetLease.ts: all matched files use the correct format

Compatibility, safety, and release

Breaking changes or migration steps: none
Real Hopper/Ghidra, browser, or OS coverage: not applicable
Package or release metadata impact: none
Security, privacy, process, or containment review: none

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/711 **Author:** [@vinay121314](https://github.com/vinay121314) **Created:** 10/6/2026 **Status:** ✅ Merged **Merged:** 10/6/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `patch-1` --- ### 📝 Commits (2) - [`6847bc9`](https://github.com/morluto/rea/commit/6847bc947316e43ff0e0af99ab75752cfabe40dd) docs(hopper): document HopperTargetLease realpath fallback - [`5624268`](https://github.com/morluto/rea/commit/56242682a097ac0db2fa3231135e24f8e26adb56) docs(hopper): clarify realpath fallback errors ### 📊 Changes **1 file changed** (+7 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `src/hopper/HopperTargetLease.ts` (+7 -0) </details> ### 📄 Description ## Summary Fixes #642. Documents why `acquireHopperTargetLease` falls back from `realpath` to lexical `resolve`, and when that fallback is expected, so it no longer reads as a silently swallowed failure. ## Problem and expected behavior `src/hopper/HopperTargetLease.ts` catches any `realpath` failure and uses `resolve(input.targetPath)` without explanation. The #637 silent-catch sweep deferred this because it is fallback-value semantics, but nothing stated when `realpath` is expected to fail versus when the fallback masks a real problem. ## Change and scope Comment-only change above the `realpath(...).catch(...)` call stating: - the canonical path only derives the lease key and never authorizes access; - expected failure cases (missing target or path component, `ENOENT`/`ENOTDIR`; unreadable component, `EACCES`; symlink loop, `ELOOP`); - the cost of the fallback: the key stays deterministic, but symlinked spellings of such a path may take separate leases. Intentionally not included: debug-level logging of the fallback (the issue's alternative option). Happy to add it if preferred. ## Contract and boundary impact - Semantic owner and earliest changed stage: none (comment only) - CLI and MCP/tool-catalog contract: none - Provider, bridge, target-format, or platform compatibility: none - Evidence, artifact, provenance, or reconstruction contract: none - Process execution, authorization, cleanup, or containment impact: none - Generated metadata (`docs/product-catalog.json`), package, or installation impact: none ## Evidence and regression coverage - Tests added or updated: none (no behavior change) - Base reproduction or other evidence: source-derived from `src/hopper/HopperTargetLease.ts` - User-visible CLI/MCP output (if applicable): not applicable - Remaining proof gaps: none ## Validation performed - `oxfmt --check src/hopper/HopperTargetLease.ts`: all matched files use the correct format ## Compatibility, safety, and release - Breaking changes or migration steps: none - Real Hopper/Ghidra, browser, or OS coverage: not applicable - Package or release metadata impact: none - Security, privacy, process, or containment review: none ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:15:28 +00:00