[PR #789] [CLOSED] fix(reference): preserve unsupported import failures #2240

New issue

Closed

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

bsakaguchi commented

2026-10-16 21:16:09 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/789
Author: @kaoru0822-kitauji
Created: 10/6/2026
Status: ❌ Closed

Base: main ← Head: fix/reference-unsupported-import-status

📝 Commits (1)

799d55f fix(reference): preserve unsupported import failures

📊 Changes

8 files changed (+197 additions, -8 deletions)

View changed files

📝 .github/workflows/ci.yml (+1 -0)
📝 docs/javascript-application-workflows.md (+9 -0)
📝 src/application/ReferenceSourceImport.ts (+14 -5)
➕ src/application/ReferenceSourceImportErrors.test.ts (+63 -0)
📝 src/application/ReferenceSourceImportTypes.ts (+6 -1)
📝 src/cli/referenceSourceImportStatus.ts (+6 -1)
📝 src/cliReferenceSourceImportStatus.test.ts (+29 -1)
📝 tests/boundary/cli/referenceSourceImportStatus.test.ts (+69 -0)

📄 Description

Summary

Fixes #787. Preserve the unsupported-reader outcome when historical-source import cannot safely open files without following links, and return actionable platform recovery instead of directory-permission advice.

Problem and expected behavior

On Windows, the reader reports unsupported with “Safe no-follow file opens are unavailable”. The import layer converted this to io, and CLI projection replaced the reason with permission advice. An unavailable capability should remain distinct from an observed I/O failure.

Change and scope

Preserve unsupported and its observed message in the import error mapping.
Project the command's failure as unsupported_provider, with Linux/macOS/WSL recovery.
Recognize that exact command envelope as failed, retaining exit code 1 and error logging.
Document the import limitation and select the compiled CLI regression file in the existing Windows lane.
Reader admission, filesystem operations, cancellation, existing I/O/parse/root mappings and full-output wrapper semantics are unchanged.

Contract and boundary impact

Semantic owner and earliest changed stage: application reader-error conversion.
CLI and MCP/tool-catalog contract: this CLI command gains an accurate failure category; no MCP or canonical error schema changes.
Provider, bridge, target-format, or platform compatibility: no provider or Windows native implementation changes.
Evidence, artifact, provenance, or reconstruction contract: graph schemas and comparison admission are unchanged.
Process execution, authorization, cleanup, or containment impact: none.
Generated metadata, package, or installation impact: none; generated checks pass.

Evidence and regression coverage

On unmodified d2aed17, the new projection/classification/logging cases fail 3 tests, with 39 controls passing. Extracting the existing reader-error expression unchanged for direct testing adds one failing unsupported-mapping case and three passing controls.
Fixed focused tests pass 67 cases, with four capability-dependent CLI cases skipped on Linux. The Windows selection guard passes separately.
The actual local compiled CLI retains exit 1 for missing/file roots and exit 0 for a readable source tree. Pure mapper/projector/logging tests establish the unsupported outcome locally.
The unsupported compiled CLI cases exercise JSON/full-output and logging modes on a host without no-follow support. This PR selects their file in hosted Windows CI; a hosted result is still pending at submission.
The real Windows package reproduction is reported in #787, not independently run in this Linux executor.

Representative new output:

{"error":"Import failed","category":"unsupported_provider","message":"Reference source import is unavailable: Safe no-follow file opens are unavailable. Run the import on Linux or macOS, or in WSL with access to the source tree, then supply the resulting HistoricalSourceGraph."}

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 -- src/application/ReferenceSourceImportErrors.test.ts src/cliReferenceSourceImportStatus.test.ts tests/boundary/cli/referenceSourceImportStatus.test.ts tests/boundary/filesystem/referenceSourceImport.test.ts — 67 passed, 4 skipped; build passed.
npm run test:focused -- tests/process-global/curatedWindowsLane.test.ts — 1 passed.
npm run check — passed; 125 existing warnings, zero errors.
npm run docs:check — passed.
npm run jscpd, npm run scan:todos, git diff --check — passed.
Executed with Node 24.19.0/npm 11.9.0 and the exact locked dependency versions. No real Hopper/Ghidra/browser verification was needed for this error-projection change.

Compatibility, safety, and release

The unavailable import changes from execution_failure to unsupported_provider; callers get the same failed exit status with useful recovery.
No safe-opening restrictions or native controls are relaxed.
No package metadata changes. No real Windows or WSL runtime verification is claimed before hosted execution.
AI-assisted implementation and tests, independently reviewed before publication.

Review checklist

One focused outcome and a conventional title.
Related issue linked.
Regression and failure-path controls included.
Owning documentation updated; generated checks pass.
Representative public output included.
Final diff checked for unrelated changes 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/789 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/6/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/reference-unsupported-import-status` --- ### 📝 Commits (1) - [`799d55f`](https://github.com/morluto/rea/commit/799d55fa0e8fc036956f7fabc2c8bf2effb1b2e9) fix(reference): preserve unsupported import failures ### 📊 Changes **8 files changed** (+197 additions, -8 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/ci.yml` (+1 -0) 📝 `docs/javascript-application-workflows.md` (+9 -0) 📝 `src/application/ReferenceSourceImport.ts` (+14 -5) ➕ `src/application/ReferenceSourceImportErrors.test.ts` (+63 -0) 📝 `src/application/ReferenceSourceImportTypes.ts` (+6 -1) 📝 `src/cli/referenceSourceImportStatus.ts` (+6 -1) 📝 `src/cliReferenceSourceImportStatus.test.ts` (+29 -1) 📝 `tests/boundary/cli/referenceSourceImportStatus.test.ts` (+69 -0) </details> ### 📄 Description ## Summary Fixes #787. Preserve the unsupported-reader outcome when historical-source import cannot safely open files without following links, and return actionable platform recovery instead of directory-permission advice. ## Problem and expected behavior On Windows, the reader reports `unsupported` with “Safe no-follow file opens are unavailable”. The import layer converted this to `io`, and CLI projection replaced the reason with permission advice. An unavailable capability should remain distinct from an observed I/O failure. ## Change and scope - Preserve `unsupported` and its observed message in the import error mapping. - Project the command's failure as `unsupported_provider`, with Linux/macOS/WSL recovery. - Recognize that exact command envelope as failed, retaining exit code 1 and error logging. - Document the import limitation and select the compiled CLI regression file in the existing Windows lane. - Reader admission, filesystem operations, cancellation, existing I/O/parse/root mappings and full-output wrapper semantics are unchanged. ## Contract and boundary impact - Semantic owner and earliest changed stage: application reader-error conversion. - CLI and MCP/tool-catalog contract: this CLI command gains an accurate failure category; no MCP or canonical error schema changes. - Provider, bridge, target-format, or platform compatibility: no provider or Windows native implementation changes. - Evidence, artifact, provenance, or reconstruction contract: graph schemas and comparison admission are unchanged. - Process execution, authorization, cleanup, or containment impact: none. - Generated metadata, package, or installation impact: none; generated checks pass. ## Evidence and regression coverage - On unmodified d2aed17, the new projection/classification/logging cases fail 3 tests, with 39 controls passing. Extracting the existing reader-error expression unchanged for direct testing adds one failing unsupported-mapping case and three passing controls. - Fixed focused tests pass 67 cases, with four capability-dependent CLI cases skipped on Linux. The Windows selection guard passes separately. - The actual local compiled CLI retains exit 1 for missing/file roots and exit 0 for a readable source tree. Pure mapper/projector/logging tests establish the unsupported outcome locally. - The unsupported compiled CLI cases exercise JSON/full-output and logging modes on a host without no-follow support. This PR selects their file in hosted Windows CI; a hosted result is still pending at submission. - The real Windows package reproduction is reported in #787, not independently run in this Linux executor. Representative new output: ```json {"error":"Import failed","category":"unsupported_provider","message":"Reference source import is unavailable: Safe no-follow file opens are unavailable. Run the import on Linux or macOS, or in WSL with access to the source tree, then supply the resulting HistoricalSourceGraph."} ``` - [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 -- src/application/ReferenceSourceImportErrors.test.ts src/cliReferenceSourceImportStatus.test.ts tests/boundary/cli/referenceSourceImportStatus.test.ts tests/boundary/filesystem/referenceSourceImport.test.ts` — 67 passed, 4 skipped; build passed. - `npm run test:focused -- tests/process-global/curatedWindowsLane.test.ts` — 1 passed. - `npm run check` — passed; 125 existing warnings, zero errors. - `npm run docs:check` — passed. - `npm run jscpd`, `npm run scan:todos`, `git diff --check` — passed. - Executed with Node 24.19.0/npm 11.9.0 and the exact locked dependency versions. No real Hopper/Ghidra/browser verification was needed for this error-projection change. ## Compatibility, safety, and release - The unavailable import changes from `execution_failure` to `unsupported_provider`; callers get the same failed exit status with useful recovery. - No safe-opening restrictions or native controls are relaxed. - No package metadata changes. No real Windows or WSL runtime verification is claimed before hosted execution. - AI-assisted implementation and tests, independently reviewed before publication. ## Review checklist - [x] One focused outcome and a conventional title. - [x] Related issue linked. - [x] Regression and failure-path controls included. - [x] Owning documentation updated; generated checks pass. - [x] Representative public output included. - [x] Final diff checked for unrelated changes 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:16:09 +00:00