morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #4692] [CLOSED] fix(apple): retain unread inventory files as unavailable components #6360

New issue

Closed

opened 2026-10-31 01:13:50 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:13:50 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4692
Author: @rodricksz4h5
Created: 10/17/2026
Status: ❌ Closed

Base: main ← Head: fix/apple-unread-components

📝 Commits (2)

1df1a0d fix(apple): retain unread inventory files as unavailable components
a5a3811 fix(apple): keep symlinks out of unavailable components

📊 Changes

3 files changed (+126 additions, -6 deletions)

View changed files

📝 docs/apple-application-analysis.md (+5 -0)
📝 src/domain/apple/appleApplication.ts (+32 -6)
📝 tests/boundary/filesystem/appleApplication.test.ts (+89 -0)

📄 Description

Summary

Fixes #4688

The Apple application graph dropped any inventory file without a content identity, such as an encrypted IPA member, and still reported complete-within-inventory coverage with no limitation. Such files are now listed in unavailable_components, coverage becomes partial, and a limitation states that component absence is unknown. This matches what the Android and HarmonyOS projections already do (#2603).

Problem and expected behavior

Trigger: an IPA whose Payload/Fixture.app/libentry.dylib is an encrypted ZIP member. inspect-artifact keeps it with artifact_id: null, hash_status: unavailable, encrypted: true. projectAppleApplication mapped a null identity to an undefined component and filtered it out, so the path disappeared from the result while coverage still said complete. AGENTS.md asks that omission and uncertainty be preserved and that unknown identity stay unknown rather than become absence.

Change and scope

src/domain/apple/appleApplication.ts: uses the shared unavailableComponents / unavailableComponentSchema from mobileApplicationGraphProjection.ts (already used by Android and HarmonyOS). Symlinks are left out: they never carry content identity and are already reported by path in symlinks. Unread entries go through the same attributeComponents rule as readable ones: AppleDouble sidecars are excluded, and for directory, ZIP and DMG roots only entries inside an application root are kept, with the rest added to the existing unattributed count. Coverage is partial when any unavailable component remains. The limitation text is the same as Android's.
docs/apple-application-analysis.md: documents unavailable_components and the coverage effect.
Not included: no hash, format or byte interpretation is invented for unread content, and nothing is decrypted.

Follow the contribution scope.
Scope decision: not applicable (ordinary fix within existing boundaries).

Contract and boundary impact

Semantic owner and earliest changed stage: Apple application projection (src/domain/apple/appleApplication.ts); the inventory producer is unchanged.
Contribution scope fit and linked maintainer decision: not applicable.
CLI and MCP/tool-catalog contract: project_apple_application_graph / project-apple-application-graph output gains unavailable_components (always present, empty when every file was read). The output schema is derived from the domain schema.
Provider, bridge, target-format, or platform compatibility: none.
Evidence, artifact, provenance, or reconstruction contract: projection_id hashes the whole result, so Apple projection IDs change with the new field, as the Android ones did in #2603.
Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable.
Generated metadata (docs/public/product-catalog.json), package, or installation impact: catalog output schema changes through the domain schema; nothing generated is committed.

Expected 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

Tests added or updated, in tests/boundary/filesystem/appleApplication.test.ts (real ZIP, real inventory_artifact, real projection service):
- retains an encrypted IPA native library as unknown component evidence: fails with appleApplication.ts reverted to main (expected undefined to deeply equal [ ObjectContaining{…} ]).
- keeps symlinks out of unavailable components: a ZIP symlink entry leaves coverage complete.
- applies application-root and sidecar rules to unread entries: in a .zip root, an unread file inside Fixture.app is listed, an unread AppleDouble sidecar is not, and an unread file outside the root is counted in the unattributed limitation.
Base reproduction or other evidence (executed): the issue's script through the public CLI (node scripts/rea.mjs inspect-artifact → project-apple-application-graph), readable vs encrypted member.

Main 0ec48266:

{"encrypted":false,"native_paths":["Payload/Fixture.app/libentry.dylib"],"unavailable":[],"coverage":{"status":"complete-within-inventory","inventory_complete":true},"unread_notice":[]}
{"encrypted":true,"native_paths":[],"unavailable":[],"path_in_result":false,"coverage":{"status":"complete-within-inventory","inventory_complete":true},"unread_notice":[]}

This PR:

{"encrypted":false,"native_paths":["Payload/Fixture.app/libentry.dylib"],"unavailable":[],"coverage":{"status":"complete-within-inventory","inventory_complete":true},"unread_notice":[]}
{"encrypted":true,"native_paths":[],"unavailable":["Payload/Fixture.app/libentry.dylib encrypted=true id=null"],"path_in_result":true,"coverage":{"status":"partial","inventory_complete":true},"unread_notice":["Some inventoried occurrences have no authenticated content identity. Their paths and limitations are retained in unavailable_components; component absence is unknown."]}

User-visible CLI/MCP output: above.
Remaining proof gaps: only the encrypted-ZIP-member cause of unavailable identity was exercised; unreadable files in a macOS .app directory take the same code path but were not run. MCP was covered by the existing mobileApplicationGraphMcp test, not a new Apple-specific one.

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

Windows 11, Node 24.18.0, npm 11.16.0. The source checkout has no Windows native addon, so run-exclusive wrappers could not run; I ran their turbo tasks and vitest directly. The Apple boundary file was also run on Linux (node:24.18.0-bookworm, fresh npm ci).

turbo run typecheck lint (check:fast) — pass
turbo run typecheck lint:built format:check knip metadata:check + npm run verify:architecture-guards (check) — pass
turbo run docs:check:built — pass
Linux, vitest run tests/boundary/filesystem/appleApplication.test.ts — 10 passed, including the macOS .app directory test with a real symlink
Windows, vitest run on tests/boundary/filesystem/appleApplication.test.ts, src/domain/apple/appleApplication.test.ts, tests/boundary/filesystem/android/application.test.ts, tests/boundary/filesystem/harmony/application.test.ts, tests/boundary/mcp/mobileApplicationGraphMcp.test.ts, src/contracts/toolEffects.test.ts, tests/acceptance/applications/mobileFrameworkConventions.test.ts, tests/acceptance/tools/mobileGraphExamples.test.ts — all pass except projects a macOS .app directory inventory with nested bundle roles (EPERM creating a symlink on Windows; fails the same on main)
src/artifacts/inventory/ArtifactOccurrenceIdentity.test.ts — 2 mode-755 tests fail on Windows, the same on main; unrelated

Compatibility, safety, and release

Breaking changes or migration steps: additive output field; Apple projection_id values change.
Real Hopper/Ghidra, browser, or OS coverage: not applicable (no provider involved).
Package or release metadata impact: none.
Security, privacy, process, or containment review: none; read-only projection of existing Evidence.

Author readiness

Human owner: @rodricksz4h5

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

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.
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/4692 **Author:** [@rodricksz4h5](https://github.com/rodricksz4h5) **Created:** 10/17/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/apple-unread-components` --- ### 📝 Commits (2) - [`1df1a0d`](https://github.com/morluto/rea/commit/1df1a0d3a3636cb83dec80e0ed17fb79bcb0ef61) fix(apple): retain unread inventory files as unavailable components - [`a5a3811`](https://github.com/morluto/rea/commit/a5a38118f341aec8a8808e6fa11d550cf17ebc18) fix(apple): keep symlinks out of unavailable components ### 📊 Changes **3 files changed** (+126 additions, -6 deletions) <details> <summary>View changed files</summary> 📝 `docs/apple-application-analysis.md` (+5 -0) 📝 `src/domain/apple/appleApplication.ts` (+32 -6) 📝 `tests/boundary/filesystem/appleApplication.test.ts` (+89 -0) </details> ### 📄 Description ## Summary Fixes #4688 The Apple application graph dropped any inventory file without a content identity, such as an encrypted IPA member, and still reported `complete-within-inventory` coverage with no limitation. Such files are now listed in `unavailable_components`, coverage becomes `partial`, and a limitation states that component absence is unknown. This matches what the Android and HarmonyOS projections already do (#2603). ## Problem and expected behavior Trigger: an IPA whose `Payload/Fixture.app/libentry.dylib` is an encrypted ZIP member. `inspect-artifact` keeps it with `artifact_id: null`, `hash_status: unavailable`, `encrypted: true`. `projectAppleApplication` mapped a null identity to an undefined component and filtered it out, so the path disappeared from the result while coverage still said complete. AGENTS.md asks that omission and uncertainty be preserved and that unknown identity stay unknown rather than become absence. ## Change and scope - `src/domain/apple/appleApplication.ts`: uses the shared `unavailableComponents` / `unavailableComponentSchema` from `mobileApplicationGraphProjection.ts` (already used by Android and HarmonyOS). Symlinks are left out: they never carry content identity and are already reported by path in `symlinks`. Unread entries go through the same `attributeComponents` rule as readable ones: AppleDouble sidecars are excluded, and for directory, ZIP and DMG roots only entries inside an application root are kept, with the rest added to the existing unattributed count. Coverage is `partial` when any unavailable component remains. The limitation text is the same as Android's. - `docs/apple-application-analysis.md`: documents `unavailable_components` and the coverage effect. - Not included: no hash, format or byte interpretation is invented for unread content, and nothing is decrypted. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Scope decision: not applicable (ordinary fix within existing boundaries). ## Contract and boundary impact - Semantic owner and earliest changed stage: Apple application projection (`src/domain/apple/appleApplication.ts`); the inventory producer is unchanged. - Contribution scope fit and linked maintainer decision: not applicable. - CLI and MCP/tool-catalog contract: `project_apple_application_graph` / `project-apple-application-graph` output gains `unavailable_components` (always present, empty when every file was read). The output schema is derived from the domain schema. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: `projection_id` hashes the whole result, so Apple projection IDs change with the new field, as the Android ones did in #2603. - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: catalog output schema changes through the domain schema; nothing generated is committed. Expected 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 - Tests added or updated, in `tests/boundary/filesystem/appleApplication.test.ts` (real ZIP, real `inventory_artifact`, real projection service): - `retains an encrypted IPA native library as unknown component evidence`: fails with `appleApplication.ts` reverted to main (`expected undefined to deeply equal [ ObjectContaining{…} ]`). - `keeps symlinks out of unavailable components`: a ZIP symlink entry leaves coverage complete. - `applies application-root and sidecar rules to unread entries`: in a `.zip` root, an unread file inside `Fixture.app` is listed, an unread AppleDouble sidecar is not, and an unread file outside the root is counted in the unattributed limitation. - Base reproduction or other evidence (executed): the issue's script through the public CLI (`node scripts/rea.mjs inspect-artifact` → `project-apple-application-graph`), readable vs encrypted member. Main `0ec48266`: ```json {"encrypted":false,"native_paths":["Payload/Fixture.app/libentry.dylib"],"unavailable":[],"coverage":{"status":"complete-within-inventory","inventory_complete":true},"unread_notice":[]} {"encrypted":true,"native_paths":[],"unavailable":[],"path_in_result":false,"coverage":{"status":"complete-within-inventory","inventory_complete":true},"unread_notice":[]} ``` This PR: ```json {"encrypted":false,"native_paths":["Payload/Fixture.app/libentry.dylib"],"unavailable":[],"coverage":{"status":"complete-within-inventory","inventory_complete":true},"unread_notice":[]} {"encrypted":true,"native_paths":[],"unavailable":["Payload/Fixture.app/libentry.dylib encrypted=true id=null"],"path_in_result":true,"coverage":{"status":"partial","inventory_complete":true},"unread_notice":["Some inventoried occurrences have no authenticated content identity. Their paths and limitations are retained in unavailable_components; component absence is unknown."]} ``` - User-visible CLI/MCP output: above. - Remaining proof gaps: only the encrypted-ZIP-member cause of unavailable identity was exercised; unreadable files in a macOS `.app` directory take the same code path but were not run. MCP was covered by the existing `mobileApplicationGraphMcp` test, not a new Apple-specific one. 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 Windows 11, Node 24.18.0, npm 11.16.0. The source checkout has no Windows native addon, so `run-exclusive` wrappers could not run; I ran their turbo tasks and vitest directly. The Apple boundary file was also run on Linux (`node:24.18.0-bookworm`, fresh `npm ci`). - `turbo run typecheck lint` (`check:fast`) — pass - `turbo run typecheck lint:built format:check knip metadata:check` + `npm run verify:architecture-guards` (`check`) — pass - `turbo run docs:check:built` — pass - Linux, `vitest run tests/boundary/filesystem/appleApplication.test.ts` — 10 passed, including the macOS `.app` directory test with a real symlink - Windows, `vitest run` on `tests/boundary/filesystem/appleApplication.test.ts`, `src/domain/apple/appleApplication.test.ts`, `tests/boundary/filesystem/android/application.test.ts`, `tests/boundary/filesystem/harmony/application.test.ts`, `tests/boundary/mcp/mobileApplicationGraphMcp.test.ts`, `src/contracts/toolEffects.test.ts`, `tests/acceptance/applications/mobileFrameworkConventions.test.ts`, `tests/acceptance/tools/mobileGraphExamples.test.ts` — all pass except `projects a macOS .app directory inventory with nested bundle roles` (`EPERM` creating a symlink on Windows; fails the same on main) - `src/artifacts/inventory/ArtifactOccurrenceIdentity.test.ts` — 2 mode-755 tests fail on Windows, the same on main; unrelated ## Compatibility, safety, and release - Breaking changes or migration steps: additive output field; Apple `projection_id` values change. - Real Hopper/Ghidra, browser, or OS coverage: not applicable (no provider involved). - Package or release metadata impact: none. - Security, privacy, process, or containment review: none; read-only projection of existing Evidence. ## Author readiness Human owner: @rodricksz4h5 - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## 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. - [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:13:50 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-11-01 21:46:55 +00:00

[PR #6360] [MERGED] fix(javascript): report path data records as route candidates #7306

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#6360

No description provided.

Rows
Columns