[PR #733] [MERGED] fix(target): explain the JavaScript directory analysis route #2201

New issue

Closed

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

bsakaguchi commented

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

Owner

📋 Pull Request Information

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

Base: main ← Head: fix/720-javascript-directory-diagnostics

📝 Commits (1)

962d660 fix(target): explain the JavaScript directory analysis route

📊 Changes

15 files changed (+181 additions, -16 deletions)

View changed files

📝 docs/mcp-prompts.md (+7 -0)
📝 docs/product-catalog.json (+2 -2)
📝 docs/user-visible-errors.csv (+1 -1)
📝 docs/verification/managed-conformance-manifest.json (+2 -2)
📝 skills/reverse-engineer-anything/SKILL.md (+1 -1)
📝 src/application/BinaryTargetResolver.ts (+9 -1)
📝 src/application/Doctor.test.ts (+22 -0)
📝 src/application/Doctor.ts (+31 -0)
📝 src/application/DoctorDiagnostics.ts (+6 -4)
📝 src/contracts/promptContracts.ts (+1 -1)
📝 src/domain/analysisErrorPresentation.ts (+8 -1)
📝 src/domain/analysisErrorProjection.ts (+8 -1)
📝 src/domain/configurationErrors.ts (+9 -2)
➕ tests/boundary/filesystem/targetDiagnostics.test.ts (+71 -0)
📝 tests/boundary/mcp/promptMcp.test.ts (+3 -0)

📄 Description

Summary

Fixes #720. A JavaScript application directory can be analyzed directly, but open_binary previously returned generic path advice and doctor called it configuration drift. Directory admission now names the supported analysis route and doctor distinguishes unsupported_target from filesystem failures.

Problem and expected behavior

For a readable <JS_APP> directory, analyze_javascript_application({input_path: "<JS_APP>"}) and rea analyze <JS_APP> succeed. Opening that directory should explain the narrower file/app-bundle boundary, without implying that the caller must repair a readable path.

Change and scope

Preserve target admission reasons in error projections. Tag the non-app directory constraint, expose detailed host target diagnostics, and update investigate_feature to point directly to JavaScript directory analysis. Native opening remains limited to its existing admitted targets.

Contract and boundary impact

Semantic owner and earliest changed stage: filesystem target admission and shared error projection.
CLI and MCP/tool-catalog contract: additive details.reason/directory constraint; doctor adds unsupported_target; tool inputs and inventory unchanged. Guided prompt text changes.
Provider, bridge, target-format, or platform compatibility: no new provider or format support; macOS app-bundle resolution unchanged.
Evidence, artifact, provenance, or reconstruction contract: unchanged.
Process execution, authorization, cleanup, or containment impact: read-only diagnosis; no engine launch, setup writes, or approval flags.
Generated metadata (docs/product-catalog.json), package, or installation impact: regenerated prompt/skill identity and dependent conformance manifest; no dependency changes.

Evidence and regression coverage

Tests added or updated: directory/missing-path diagnostics, actual Unix permission denial, host diagnostic composition, and advertised MCP prompt guidance; existing bundle and file tests remain passing.
Base reproduction or other evidence: #720 records successful direct analysis versus generic opening/doctor failures. New directory assertions fail against that behavior.
User-visible CLI/MCP output: open_binary returns target_unavailable, details.constraint: "directory_requires_file", and an action naming analyze_javascript_application/rea analyze; doctor target classification is unsupported_target.
Remaining proof gaps: local workflow verification is Linux x64; no local Windows-native or macOS run.

Validation performed

npm run test:focused -- tests/boundary/filesystem/targetDiagnostics.test.ts tests/boundary/filesystem/binaryTarget.test.ts tests/boundary/mcp/promptMcp.test.ts src/application/Doctor.test.ts src/domain/analysisErrorProjection.test.ts — passed (53 tests before the additional permission case).
npm run test:focused -- tests/boundary/filesystem/targetDiagnostics.test.ts — passed, including real filesystem permission denial.
npm run check:fast — passed.
npm run docs:generate and npm run docs:check — passed.
Real pinned-SDK stdio connection — directory opening diagnostic, direct JS analysis, and prompt route passed. Real CLI doctor/analyze on the original evaluation fixture passed.
git diff --check — passed.

Additional local composition review: all four issue branches were merged on a
private temporary branch. The expected #720/#722 overlaps in error remediation
were combined, and shared product/skill/conformance metadata was regenerated
from the combined source contracts. Eight focused test files (54 tests),
npm run check:fast, npm run docs:check, and the real stdio regression
workflows for #719/#720/#722 passed. Public PRs remain independently based on
main; when merging them together, regenerate metadata instead of choosing one
branch's generated digests.

Compatibility, safety, and release

Breaking changes or migration steps: no required input migration; consumers of doctor classifications should accept the new unsupported-target value.
Real Hopper/Ghidra, browser, or OS coverage: Linux filesystem/CLI/MCP tested; no Hopper/Ghidra launch needed or performed.
Package or release metadata impact: generated identities updated; no package/dependency additions.
Security, privacy, process, or containment review: causes remain excluded; caller-selected paths and meaningful failure reasons preserved. Public examples contain placeholders. Build and test commands used two-CPU affinity and a bounded Node heap; real stdio workflows inherited the CPU affinity.

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/733 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/6/2026 **Status:** ✅ Merged **Merged:** 10/6/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `fix/720-javascript-directory-diagnostics` --- ### 📝 Commits (1) - [`962d660`](https://github.com/morluto/rea/commit/962d660a83afdad584ed36a7cb2147cd9b2b3800) fix(target): explain the JavaScript directory analysis route ### 📊 Changes **15 files changed** (+181 additions, -16 deletions) <details> <summary>View changed files</summary> 📝 `docs/mcp-prompts.md` (+7 -0) 📝 `docs/product-catalog.json` (+2 -2) 📝 `docs/user-visible-errors.csv` (+1 -1) 📝 `docs/verification/managed-conformance-manifest.json` (+2 -2) 📝 `skills/reverse-engineer-anything/SKILL.md` (+1 -1) 📝 `src/application/BinaryTargetResolver.ts` (+9 -1) 📝 `src/application/Doctor.test.ts` (+22 -0) 📝 `src/application/Doctor.ts` (+31 -0) 📝 `src/application/DoctorDiagnostics.ts` (+6 -4) 📝 `src/contracts/promptContracts.ts` (+1 -1) 📝 `src/domain/analysisErrorPresentation.ts` (+8 -1) 📝 `src/domain/analysisErrorProjection.ts` (+8 -1) 📝 `src/domain/configurationErrors.ts` (+9 -2) ➕ `tests/boundary/filesystem/targetDiagnostics.test.ts` (+71 -0) 📝 `tests/boundary/mcp/promptMcp.test.ts` (+3 -0) </details> ### 📄 Description ## Summary Fixes #720. A JavaScript application directory can be analyzed directly, but `open_binary` previously returned generic path advice and doctor called it configuration drift. Directory admission now names the supported analysis route and doctor distinguishes `unsupported_target` from filesystem failures. ## Problem and expected behavior For a readable `<JS_APP>` directory, `analyze_javascript_application({input_path: "<JS_APP>"})` and `rea analyze <JS_APP>` succeed. Opening that directory should explain the narrower file/app-bundle boundary, without implying that the caller must repair a readable path. ## Change and scope Preserve target admission reasons in error projections. Tag the non-app directory constraint, expose detailed host target diagnostics, and update `investigate_feature` to point directly to JavaScript directory analysis. Native opening remains limited to its existing admitted targets. ## Contract and boundary impact - Semantic owner and earliest changed stage: filesystem target admission and shared error projection. - CLI and MCP/tool-catalog contract: additive `details.reason`/directory constraint; doctor adds `unsupported_target`; tool inputs and inventory unchanged. Guided prompt text changes. - Provider, bridge, target-format, or platform compatibility: no new provider or format support; macOS app-bundle resolution unchanged. - Evidence, artifact, provenance, or reconstruction contract: unchanged. - Process execution, authorization, cleanup, or containment impact: read-only diagnosis; no engine launch, setup writes, or approval flags. - Generated metadata (`docs/product-catalog.json`), package, or installation impact: regenerated prompt/skill identity and dependent conformance manifest; no dependency changes. ## Evidence and regression coverage - Tests added or updated: directory/missing-path diagnostics, actual Unix permission denial, host diagnostic composition, and advertised MCP prompt guidance; existing bundle and file tests remain passing. - Base reproduction or other evidence: #720 records successful direct analysis versus generic opening/doctor failures. New directory assertions fail against that behavior. - User-visible CLI/MCP output: `open_binary` returns `target_unavailable`, `details.constraint: "directory_requires_file"`, and an action naming `analyze_javascript_application`/`rea analyze`; doctor target classification is `unsupported_target`. - Remaining proof gaps: local workflow verification is Linux x64; no local Windows-native or macOS run. ## Validation performed - `npm run test:focused -- tests/boundary/filesystem/targetDiagnostics.test.ts tests/boundary/filesystem/binaryTarget.test.ts tests/boundary/mcp/promptMcp.test.ts src/application/Doctor.test.ts src/domain/analysisErrorProjection.test.ts` — passed (53 tests before the additional permission case). - `npm run test:focused -- tests/boundary/filesystem/targetDiagnostics.test.ts` — passed, including real filesystem permission denial. - `npm run check:fast` — passed. - `npm run docs:generate` and `npm run docs:check` — passed. - Real pinned-SDK stdio connection — directory opening diagnostic, direct JS analysis, and prompt route passed. Real CLI doctor/analyze on the original evaluation fixture passed. - `git diff --check` — passed. Additional local composition review: all four issue branches were merged on a private temporary branch. The expected #720/#722 overlaps in error remediation were combined, and shared product/skill/conformance metadata was regenerated from the combined source contracts. Eight focused test files (54 tests), `npm run check:fast`, `npm run docs:check`, and the real stdio regression workflows for #719/#720/#722 passed. Public PRs remain independently based on main; when merging them together, regenerate metadata instead of choosing one branch's generated digests. ## Compatibility, safety, and release - Breaking changes or migration steps: no required input migration; consumers of doctor classifications should accept the new unsupported-target value. - Real Hopper/Ghidra, browser, or OS coverage: Linux filesystem/CLI/MCP tested; no Hopper/Ghidra launch needed or performed. - Package or release metadata impact: generated identities updated; no package/dependency additions. - Security, privacy, process, or containment review: causes remain excluded; caller-selected paths and meaningful failure reasons preserved. Public examples contain placeholders. Build and test commands used two-CPU affinity and a bounded Node heap; real stdio workflows inherited the CPU affinity. ## 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:37 +00:00