[PR #2907] [CLOSED] fix(reference): reconcile excluded symlink identities #5488

Closed
opened 2026-10-31 01:07:02 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2907
Author: @Adkid-Zephyr
Created: 10/13/2026
Status: ❌ Closed

Base: main ← Head: fix/reference-excluded-symlink


📝 Commits (10+)

  • 62ec3db fix(reference): retain links to excluded source paths
  • 1786fdd fix(reference): require exact excluded symlink targets
  • b1f097b fix(reference): preserve excluded directory coverage
  • 3da27cf fix(reference): distinguish omitted paths from escape facts
  • 333e32c Merge remote-tracking branch 'origin/main' into fix/reference-excluded-symlink
  • 3cd5f6c fix(reference): preserve specific exclusion identity
  • 162fd65 fix(reference): validate exclusion kinds and index ancestors
  • 49da456 Merge remote-tracking branch 'origin/main' into fix/reference-excluded-symlink
  • 4d3e6d9 fix(reference): compare exclusion kinds by filesystem spelling
  • 8bac307 Merge remote-tracking branch 'origin/main' into fix/reference-excluded-symlink

📊 Changes

5 files changed (+291 additions, -41 deletions)

View changed files

📝 src/domain/referenceSourceGraph.test.ts (+139 -0)
📝 src/domain/referenceSourceGraph.ts (+36 -26)
➕ src/domain/referenceSourcePathIdentity.test.ts (+40 -0)
📝 src/domain/referenceSourcePathIdentity.ts (+46 -13)
📝 tests/boundary/filesystem/referenceSourceImport.test.ts (+30 -2)

📄 Description

Summary

Fixes #2651. Thanks to @coygeek for the original report.

Validate excluded symlink targets without conflating distinct filesystem spellings or repeatedly walking and normalizing long path prefixes. Current main supplies the exclusion-kind metadata and missing-target handling; this PR preserves those behaviors and completes graph consistency and identity checks.

Problem and expected behavior

A source tree may contain an excluded directory café and a different file cafe\u0301. Their recorded filesystem identities must not be conflated when checking entry kinds. Symbolic-reference lookup can still use an unambiguous Unicode fallback.

An internal target must also agree with the recorded facts: an escape is not an omission, an excluded file cannot establish subtree coverage, and directory evidence cannot contradict an inventoried file at the same exact path. Unknown kind remains unknown.

Change and scope

  • Compare exclusion/inventory kinds by exact recorded spelling.
  • Match recorded prefixes through lazy exact/canonical component indexes. Normalize each query once and retain unknown identity when a prefix is ambiguous.
  • Validate every applicable excluded prefix: only directory evidence covers descendants; exact omissions keep their existing meaning. Escape facts never supply internal-target coverage.
  • Skip exclusion lookup for already-inventoried targets. Remove the superseded parent-walking API and preserve upstream missing-target, literal-path, and exclusion-kind behavior.

Contract and boundary impact

  • Semantic owners: historical-source graph validation and reference-path identity.
  • Contribution scope: ordinary static source-import correctness; no new provider or capability requiring a separate scope decision.
  • CLI/MCP: the current-main graph shape and exclusion-kind schema remain unchanged. New checks reject contradictory graph facts while preserving valid imported source metadata and partial inventories.
  • Evidence: exact source spellings, exclusion reasons/patterns, hashes, and unknowns remain preserved. Existing graph commitments are not rewritten.
  • Platform coverage: macOS source/CLI tests; Linux filename-coexistence fixture is included for CI. No real analysis engine or paid API is involved.

Expected operation effects:

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

The original source-import failure and later review findings were reproduced before their corrections. Coverage includes distinct NFC/NFD filesystem names, exact kind conflicts, unknown kind, legacy omissions, directory descendants, escapes, mixed exclusion kinds, sibling boundaries, and source preservation.

A small 128-component query made 128 normalization calls with the original parent walker and one with the component index. This is a resource-work regression, not an end-to-end latency, token, CPU, or memory improvement claim.

  • 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

Pinned Node 24.18.0 / npm 11.16.0; head 1092f12d includes main 500e3239 and preserves maintainer commits:

  • All 26 reference-source suites through npm run test:focused — 139 passed, 3 skipped. One skip is the new Linux filesystem-coexistence test; its platform-independent graph regression passed locally.
  • npm run check — passed, including architecture guards.
  • npm run docs:check — passed, including 5 consistency tests.
  • npm run verify:test-discovery — 1,244 files discovered exactly once.
  • git diff --check — passed.

The eight suites implicated in the preceding CI run were also rerun after incorporating upstream #3080 and the README-fact isolation fix: 117 passed (injected IDA protocol fixture, no real provider). The full suite and actual Linux coexistence case remain for current-head CI. Local test results do not claim CI or maintainer approval.

Compatibility, safety, and release

No new graph field relative to current main, provider, package entrypoint, or installation behavior. Static import remains read-only. Tests use self-created fixtures. Main's general exclusion-kind and missing-target behavior is retained rather than replaced by the earlier narrower representation.

Implementation, regression tests, conflict resolution, and self-review were assisted by OpenAI Codex.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • 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 coverage.
  • 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/2907 **Author:** [@Adkid-Zephyr](https://github.com/Adkid-Zephyr) **Created:** 10/13/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/reference-excluded-symlink` --- ### 📝 Commits (10+) - [`62ec3db`](https://github.com/morluto/rea/commit/62ec3db8bd5a071e28ca8058274fc2d695f06fc3) fix(reference): retain links to excluded source paths - [`1786fdd`](https://github.com/morluto/rea/commit/1786fdd0019ee35ddc697e1996236875711e00a4) fix(reference): require exact excluded symlink targets - [`b1f097b`](https://github.com/morluto/rea/commit/b1f097bcc2a96dc918fea83037ee07ded5e528f7) fix(reference): preserve excluded directory coverage - [`3da27cf`](https://github.com/morluto/rea/commit/3da27cf4fc977e130ff71a78cbd16a5be40be7ad) fix(reference): distinguish omitted paths from escape facts - [`333e32c`](https://github.com/morluto/rea/commit/333e32c4f927ddb329eacf4056ecda15e6d08ae6) Merge remote-tracking branch 'origin/main' into fix/reference-excluded-symlink - [`3cd5f6c`](https://github.com/morluto/rea/commit/3cd5f6c2790770f3daba3fa0180219b8f803eaa0) fix(reference): preserve specific exclusion identity - [`162fd65`](https://github.com/morluto/rea/commit/162fd6537e78b07b5c15684d61c171540ec0a58c) fix(reference): validate exclusion kinds and index ancestors - [`49da456`](https://github.com/morluto/rea/commit/49da456b905fc5cb983535440ad82b076a34cf54) Merge remote-tracking branch 'origin/main' into fix/reference-excluded-symlink - [`4d3e6d9`](https://github.com/morluto/rea/commit/4d3e6d98fdfe4a306b708fa5ed3ae9b1f75e8dfa) fix(reference): compare exclusion kinds by filesystem spelling - [`8bac307`](https://github.com/morluto/rea/commit/8bac3070e10de1666268e9e461abecb9fc0024e3) Merge remote-tracking branch 'origin/main' into fix/reference-excluded-symlink ### 📊 Changes **5 files changed** (+291 additions, -41 deletions) <details> <summary>View changed files</summary> 📝 `src/domain/referenceSourceGraph.test.ts` (+139 -0) 📝 `src/domain/referenceSourceGraph.ts` (+36 -26) ➕ `src/domain/referenceSourcePathIdentity.test.ts` (+40 -0) 📝 `src/domain/referenceSourcePathIdentity.ts` (+46 -13) 📝 `tests/boundary/filesystem/referenceSourceImport.test.ts` (+30 -2) </details> ### 📄 Description ## Summary Fixes #2651. Thanks to @coygeek for the original report. Validate excluded symlink targets without conflating distinct filesystem spellings or repeatedly walking and normalizing long path prefixes. Current main supplies the exclusion-kind metadata and missing-target handling; this PR preserves those behaviors and completes graph consistency and identity checks. ## Problem and expected behavior A source tree may contain an excluded directory `café` and a different file `cafe\u0301`. Their recorded filesystem identities must not be conflated when checking entry kinds. Symbolic-reference lookup can still use an unambiguous Unicode fallback. An internal target must also agree with the recorded facts: an escape is not an omission, an excluded file cannot establish subtree coverage, and directory evidence cannot contradict an inventoried file at the same exact path. Unknown kind remains unknown. ## Change and scope - Compare exclusion/inventory kinds by exact recorded spelling. - Match recorded prefixes through lazy exact/canonical component indexes. Normalize each query once and retain unknown identity when a prefix is ambiguous. - Validate every applicable excluded prefix: only directory evidence covers descendants; exact omissions keep their existing meaning. Escape facts never supply internal-target coverage. - Skip exclusion lookup for already-inventoried targets. Remove the superseded parent-walking API and preserve upstream missing-target, literal-path, and exclusion-kind behavior. ## Contract and boundary impact - Semantic owners: historical-source graph validation and reference-path identity. - Contribution scope: ordinary static source-import correctness; no new provider or capability requiring a separate scope decision. - CLI/MCP: the current-main graph shape and exclusion-kind schema remain unchanged. New checks reject contradictory graph facts while preserving valid imported source metadata and partial inventories. - Evidence: exact source spellings, exclusion reasons/patterns, hashes, and unknowns remain preserved. Existing graph commitments are not rewritten. - Platform coverage: macOS source/CLI tests; Linux filename-coexistence fixture is included for CI. No real analysis engine or paid API is involved. Expected operation effects: - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage The original source-import failure and later review findings were reproduced before their corrections. Coverage includes distinct NFC/NFD filesystem names, exact kind conflicts, unknown kind, legacy omissions, directory descendants, escapes, mixed exclusion kinds, sibling boundaries, and source preservation. A small 128-component query made 128 normalization calls with the original parent walker and one with the component index. This is a resource-work regression, not an end-to-end latency, token, CPU, or memory improvement claim. - [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 Pinned Node 24.18.0 / npm 11.16.0; head `1092f12d` includes main `500e3239` and preserves maintainer commits: - All 26 reference-source suites through `npm run test:focused` — **139 passed, 3 skipped**. One skip is the new Linux filesystem-coexistence test; its platform-independent graph regression passed locally. - `npm run check` — passed, including architecture guards. - `npm run docs:check` — passed, including 5 consistency tests. - `npm run verify:test-discovery` — 1,244 files discovered exactly once. - `git diff --check` — passed. The eight suites implicated in the preceding CI run were also rerun after incorporating upstream #3080 and the README-fact isolation fix: **117 passed** (injected IDA protocol fixture, no real provider). The full suite and actual Linux coexistence case remain for current-head CI. Local test results do not claim CI or maintainer approval. ## Compatibility, safety, and release No new graph field relative to current main, provider, package entrypoint, or installation behavior. Static import remains read-only. Tests use self-created fixtures. Main's general exclusion-kind and missing-target behavior is retained rather than replaced by the earlier narrower representation. Implementation, regression tests, conflict resolution, and self-review were assisted by OpenAI Codex. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [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 coverage. - [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-31 01:07:02 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#5488
No description provided.