[PR #766] [MERGED] fix(reference): retain partial imports for unreadable directories #2226

New issue

Closed

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

bsakaguchi commented

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

Owner

📋 Pull Request Information

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

Base: main ← Head: fix/rea-unreadable-reference-directories-20261006

📝 Commits (1)

e967866 fix(reference): retain partial imports for unreadable directories

📊 Changes

2 files changed (+87 additions, -1 deletions)

View changed files

📝 src/reference/ReferenceSourceReaderEntries.ts (+6 -1)
➕ tests/boundary/filesystem/referenceSourceUnreadableDirectories.test.ts (+81 -0)

📄 Description

Summary

Retain a partial reference-source graph when a child directory cannot be read. This is a self-contained bug fix; no separate issue is linked.

Problem and expected behavior

A source tree with a readable sibling and an unreadable child directory should retain the sibling and one failed directory entry. The reader recorded a directory as read when its parent discovered it, then appended the same path as failed when enumeration returned EACCES. Importing the tree failed graph validation because entry paths were duplicated, losing the entire graph.

Change and scope

Record a directory as read only after its own enumeration and identity checks succeed. A failed enumeration then produces one truthful failed entry. No graph deduplication or permission-failure suppression.

Contract and boundary impact

Semantic owner and earliest changed stage: reference filesystem reader, when recording successful directory enumeration.
CLI and MCP/tool-catalog contract: unchanged schemas; imports retain partial results instead of failing duplicate-entry validation.
Provider, bridge, target-format, or platform compatibility: local filesystem reader. Native POSIX permission proof on macOS arm64.
Evidence, artifact, provenance, or reconstruction contract: failed directory remains unreadable; readable sibling remains hashed.
Process execution, authorization, cleanup, or containment impact: no change to no-follow traversal, directory identity checks or caller exclusions.
Generated metadata (docs/product-catalog.json), package, or installation impact: none.

Evidence and regression coverage

Tests added or updated: real chmod000 child and nested directories, readable sibling retention and readable/empty directory controls.
Base reproduction or other evidence: native reader returns two entries at each denied path on base8238232 (two failures, one readable control). Public importReferenceSource also fails graph validation with entries must be sorted and unique by Unicode code point. After the fix, imports return partial graphs with exactly one unreadable directory and the hashed sibling.
User-visible CLI/MCP output: partial HistoricalSourceGraph rather than duplicate-entry validation failure.
Remaining proof gaps: permission fixtures skip Windows and root UID, where POSIX EACCES cannot establish this proof. Full hosted matrix tracked separately.

For evidence-bearing changes:

Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

npm run test:focused -- tests/boundary/filesystem/referenceSourceUnreadableDirectories.test.ts tests/boundary/filesystem/referenceSourceReader.test.ts tests/boundary/filesystem/referenceSourceImport.test.ts — 23 passed, including actual filesystem permission regressions.
npm run check — 5 tasks successful, 125 existing warnings and zero errors.
npm run check:fast — 2 tasks successful.
git diff --check — passed; SSH signed commit and DCO verified. Node24.18.0, locked Vitest5.0.3/TypeScript7.0.2, reused frozen dependencies.

No external provider behavior changed, so a Hopper/Ghidra/browser workflow is not applicable. Full deterministic coverage remains with hosted CI.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: actual macOS filesystem only; no unrelated provider claim.
Package or release metadata impact: none.
Security, privacy, process, or containment review: existing checks remain before success recording; owned fixture permissions are restored before owned temporary cleanup. No user files or symlink boundaries changed.

AI assistance: implemented and source reviewed with Codex on behalf of @rudycelekli before publication.

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/766 **Author:** [@rudycelekli](https://github.com/rudycelekli) **Created:** 10/6/2026 **Status:** ✅ Merged **Merged:** 10/6/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `fix/rea-unreadable-reference-directories-20261006` --- ### 📝 Commits (1) - [`e967866`](https://github.com/morluto/rea/commit/e967866a049595826f89e1543530f0763fb564f3) fix(reference): retain partial imports for unreadable directories ### 📊 Changes **2 files changed** (+87 additions, -1 deletions) <details> <summary>View changed files</summary> 📝 `src/reference/ReferenceSourceReaderEntries.ts` (+6 -1) ➕ `tests/boundary/filesystem/referenceSourceUnreadableDirectories.test.ts` (+81 -0) </details> ### 📄 Description ## Summary Retain a partial reference-source graph when a child directory cannot be read. This is a self-contained bug fix; no separate issue is linked. ## Problem and expected behavior A source tree with a readable sibling and an unreadable child directory should retain the sibling and one failed directory entry. The reader recorded a directory as read when its parent discovered it, then appended the same path as failed when enumeration returned EACCES. Importing the tree failed graph validation because entry paths were duplicated, losing the entire graph. ## Change and scope Record a directory as read only after its own enumeration and identity checks succeed. A failed enumeration then produces one truthful failed entry. No graph deduplication or permission-failure suppression. ## Contract and boundary impact - Semantic owner and earliest changed stage: reference filesystem reader, when recording successful directory enumeration. - CLI and MCP/tool-catalog contract: unchanged schemas; imports retain partial results instead of failing duplicate-entry validation. - Provider, bridge, target-format, or platform compatibility: local filesystem reader. Native POSIX permission proof on macOS arm64. - Evidence, artifact, provenance, or reconstruction contract: failed directory remains unreadable; readable sibling remains hashed. - Process execution, authorization, cleanup, or containment impact: no change to no-follow traversal, directory identity checks or caller exclusions. - Generated metadata (`docs/product-catalog.json`), package, or installation impact: none. ## Evidence and regression coverage - Tests added or updated: real chmod000 child and nested directories, readable sibling retention and readable/empty directory controls. - Base reproduction or other evidence: native reader returns two entries at each denied path on base8238232 (two failures, one readable control). Public importReferenceSource also fails graph validation with `entries must be sorted and unique by Unicode code point`. After the fix, imports return partial graphs with exactly one unreadable directory and the hashed sibling. - User-visible CLI/MCP output: partial HistoricalSourceGraph rather than duplicate-entry validation failure. - Remaining proof gaps: permission fixtures skip Windows and root UID, where POSIX EACCES cannot establish this proof. Full hosted matrix tracked separately. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run test:focused -- tests/boundary/filesystem/referenceSourceUnreadableDirectories.test.ts tests/boundary/filesystem/referenceSourceReader.test.ts tests/boundary/filesystem/referenceSourceImport.test.ts` — 23 passed, including actual filesystem permission regressions. - `npm run check` — 5 tasks successful, 125 existing warnings and zero errors. - `npm run check:fast` — 2 tasks successful. - `git diff --check` — passed; SSH signed commit and DCO verified. Node24.18.0, locked Vitest5.0.3/TypeScript7.0.2, reused frozen dependencies. No external provider behavior changed, so a Hopper/Ghidra/browser workflow is not applicable. Full deterministic coverage remains with hosted CI. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: actual macOS filesystem only; no unrelated provider claim. - Package or release metadata impact: none. - Security, privacy, process, or containment review: existing checks remain before success recording; owned fixture permissions are restored before owned temporary cleanup. No user files or symlink boundaries changed. AI assistance: implemented and source reviewed with Codex on behalf of @rudycelekli before publication. ## 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:57 +00:00