[PR #575] [MERGED] fix(javascript): prefer package entrypoints over directory indexes #2076

New issue

Closed

opened 2026-10-16 21:13:59 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:13:59 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/575
Author: @kaoru0822-kitauji
Created: 10/5/2026
Status: ✅ Merged
Merged: 10/5/2026
Merged by: @morluto

Base: main ← Head: fix/javascript-package-entrypoint-precedence

📝 Commits (1)

c9e21b6 fix(javascript): prefer package entrypoints over directory indexes

📊 Changes

3 files changed (+384 additions, -42 deletions)

View changed files

📝 src/application/JavaScriptArtifactPathResolution.test.ts (+143 -0)
📝 src/application/JavaScriptArtifactPathResolution.ts (+99 -42)
➕ tests/boundary/filesystem/javascriptPackagePrecedence.test.ts (+142 -0)

📄 Description

Summary

Resolve declared JavaScript package entrypoints before directory index fallbacks. A package containing both main: "actual.cjs" and index.js currently produces a high-confidence graph edge to index.js, while Node resolves actual.cjs.

Found during a repository audit; no existing issue describes this ordering error.

Change and scope

Preserve direct-file priority, then inspect admissible package metadata before directory indexes.
Apply package exports to bare package requests; relative directory requests use legacy main/index loading.
Try a legacy main target's files/index first, then the package-root index fallback.
Preserve main: ".", missing legacy-main fallback, cycle diagnostics when no fallback exists, and artifact-container isolation.
Keep malformed or unreadable metadata explicit and avoid substituting an index for a missing exports target.

The existing recursive artifact-package lookup remains as a compatibility heuristic after legacy file/index fallbacks are exhausted. This is a bounded precedence correction; parity with Node is established for the fixture cases rather than claimed for every loader feature.

Problem and evidence

Real filesystem fixtures compare REA's reconstructed require edges against Node's require.resolve. The matrix covers declared main and exports, bare versus relative requests, self-directory main, missing legacy main, nested-directory indexes, root-index fallback, and cycles with a root index. The expected ordering follows the CommonJS loader algorithm.

On unchanged base 52bf709bcefb17ab07e1f9c47c5fadf5eca9bd4e, the final regression matrix has 12 failures and 29 passing controls. The corrected matrix passes. Independent re-review also verified relative missing exports and foreign-container behavior.

Contract and boundary impact

Semantic owner: application-layer artifact-local path resolution, shared by CLI and MCP graph construction.
Public schemas and tool inventory: unchanged; resolved target identities and derived Evidence change where the old target was wrong.
Provider/format/platform support: unchanged.
Evidence: preserves explicit unavailable/rejected outcomes and source citations; avoids confident edges to an unrelated index.
Execution, authorization, filesystem containment, and cleanup: unchanged; production resolution remains inert over the inventoried file map.
Generated metadata/package dependencies: unchanged.

Validation performed

Path-resolution unit tests plus 13 real-filesystem Node-oracle cases: 41 passed.
Those suites plus JavaScript artifact reconstruction: 52 passed.
Independent re-review: clear after adding relative/bare and nested-directory controls.
npm run check:ci: all seven static tasks passed.
npm run docs:check: passed; TypeDoc reported 202 existing warnings and no errors.
npm run verify:package: Linux package/install, CLI, and MCP verifier passed.
npm pack --dry-run --json: passed.
git diff --check: passed.
npm run check:pr: static stages passed; final rebased full suite reported 1,812 passed, 40 failed, and 1 skipped. All 40 failures in the same seven native bridge suites reproduce on unchanged 52bf709. This environment rejects Unix-domain socket listeners with EPERM, causing startup failures/timeouts. No tests or permission checks were relaxed.

Compatibility and release

No schema migration. Node v24.19.0 was used for the real resolution oracle; target modules were not executed for graph construction. No real Hopper/Ghidra verification was performed because native providers are unchanged. Broader conditional-export, package-subpath, and loader-equivalence work remains outside this change.

Review checklist

Focused Conventional Commit outcome.
Baseline regressions reproduced.
Node-backed positive and fallback controls.
Container and unavailable-outcome behavior preserved.
Independent findings addressed and re-reviewed.
Final checks performed on the current main base.

_{🔄 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/575 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/5/2026 **Status:** ✅ Merged **Merged:** 10/5/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `fix/javascript-package-entrypoint-precedence` --- ### 📝 Commits (1) - [`c9e21b6`](https://github.com/morluto/rea/commit/c9e21b67c64a56fd74761f1c4abafb1d71164080) fix(javascript): prefer package entrypoints over directory indexes ### 📊 Changes **3 files changed** (+384 additions, -42 deletions) <details> <summary>View changed files</summary> 📝 `src/application/JavaScriptArtifactPathResolution.test.ts` (+143 -0) 📝 `src/application/JavaScriptArtifactPathResolution.ts` (+99 -42) ➕ `tests/boundary/filesystem/javascriptPackagePrecedence.test.ts` (+142 -0) </details> ### 📄 Description ## Summary Resolve declared JavaScript package entrypoints before directory index fallbacks. A package containing both `main: "actual.cjs"` and `index.js` currently produces a high-confidence graph edge to `index.js`, while Node resolves `actual.cjs`. Found during a repository audit; no existing issue describes this ordering error. ## Change and scope - Preserve direct-file priority, then inspect admissible package metadata before directory indexes. - Apply package exports to bare package requests; relative directory requests use legacy main/index loading. - Try a legacy main target's files/index first, then the package-root index fallback. - Preserve `main: "."`, missing legacy-main fallback, cycle diagnostics when no fallback exists, and artifact-container isolation. - Keep malformed or unreadable metadata explicit and avoid substituting an index for a missing exports target. The existing recursive artifact-package lookup remains as a compatibility heuristic after legacy file/index fallbacks are exhausted. This is a bounded precedence correction; parity with Node is established for the fixture cases rather than claimed for every loader feature. ## Problem and evidence Real filesystem fixtures compare REA's reconstructed require edges against Node's `require.resolve`. The matrix covers declared main and exports, bare versus relative requests, self-directory main, missing legacy main, nested-directory indexes, root-index fallback, and cycles with a root index. The expected ordering follows the [CommonJS loader algorithm](https://nodejs.org/api/modules.html#all-together). On unchanged base `52bf709bcefb17ab07e1f9c47c5fadf5eca9bd4e`, the final regression matrix has 12 failures and 29 passing controls. The corrected matrix passes. Independent re-review also verified relative missing exports and foreign-container behavior. ## Contract and boundary impact - Semantic owner: application-layer artifact-local path resolution, shared by CLI and MCP graph construction. - Public schemas and tool inventory: unchanged; resolved target identities and derived Evidence change where the old target was wrong. - Provider/format/platform support: unchanged. - Evidence: preserves explicit unavailable/rejected outcomes and source citations; avoids confident edges to an unrelated index. - Execution, authorization, filesystem containment, and cleanup: unchanged; production resolution remains inert over the inventoried file map. - Generated metadata/package dependencies: unchanged. ## Validation performed - Path-resolution unit tests plus 13 real-filesystem Node-oracle cases: 41 passed. - Those suites plus JavaScript artifact reconstruction: 52 passed. - Independent re-review: clear after adding relative/bare and nested-directory controls. - `npm run check:ci`: all seven static tasks passed. - `npm run docs:check`: passed; TypeDoc reported 202 existing warnings and no errors. - `npm run verify:package`: Linux package/install, CLI, and MCP verifier passed. - `npm pack --dry-run --json`: passed. - `git diff --check`: passed. - `npm run check:pr`: static stages passed; final rebased full suite reported 1,812 passed, 40 failed, and 1 skipped. All 40 failures in the same seven native bridge suites reproduce on unchanged `52bf709`. This environment rejects Unix-domain socket listeners with `EPERM`, causing startup failures/timeouts. No tests or permission checks were relaxed. ## Compatibility and release No schema migration. Node v24.19.0 was used for the real resolution oracle; target modules were not executed for graph construction. No real Hopper/Ghidra verification was performed because native providers are unchanged. Broader conditional-export, package-subpath, and loader-equivalence work remains outside this change. ## Review checklist - [x] Focused Conventional Commit outcome. - [x] Baseline regressions reproduced. - [x] Node-backed positive and fallback controls. - [x] Container and unavailable-outcome behavior preserved. - [x] Independent findings addressed and re-reviewed. - [x] Final checks performed on the current main base. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:13:59 +00:00