morluto/rea

Fork 0

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

[PR #6496] [MERGED] docs(ci): add a repeatable static analysis example #7369

New issue

Closed

opened 2026-11-01 21:47:21 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:47:21 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6496
Author: @gongfpp
Created: 10/23/2026
Status: ✅ Merged
Merged: 10/23/2026
Merged by: @baron

Base: main ← Head: docs/ci-analysis-example-6335

📝 Commits (3)

2c58c8d docs(ci): add a repeatable static analysis example
da1fc65 fix(ci): isolate example reports and repair the guide link
c19648f chore: sync upstream Node security baseline

📊 Changes

4 files changed (+394 additions, -0 deletions)

View changed files

➕ docs/ci-analysis.md (+90 -0)
📝 docs/cli.md (+2 -0)
➕ examples/github-actions/rea-analysis.yml (+60 -0)
➕ tests/boundary/cli/githubActionsExample.test.ts (+242 -0)

📄 Description

Summary

Fixes #6335. Add a copyable GitHub Actions example and linked guide for static analysis with the existing REA CLI, preserving both reports and the original analysis exit status.

Problem and expected behavior

The CLI documentation did not provide a complete noninteractive workflow from a known build artifact to downloadable machine-readable results. A failed analysis must not become a green job merely to upload its diagnostics; successful execution must not be presented as complete coverage.

Change and scope

Add a manually triggered Ubuntu example: pinned Node 24.22.1, published rea-agents@6.7.0, SHA-pinned actions, a small generated application, and retained JSON/stderr/exit-code files.
Install into the runner's temporary directory with lifecycle scripts disabled. Analyze the generated application as inert text; its JavaScript deliberately throws if executed.
Keep the original analysis exit status and use always() for uploading available reports. Explain missing input, unsupported input, partial results, prerequisites, privacy, and dependency-lock limitations.
Add regression coverage that executes the checked-in YAML build/analysis scripts against the real compiled CLI, not a fabricated tool response.

Follow the contribution scope.
Unresolved scope, authority, side effects, or required verification block
integration. Link the required maintainer scope decision for new providers or
capabilities involving target execution, injection, mutation, or protection
recovery; ordinary fixes within existing boundaries may state "not applicable".
Draft PRs may leave the scope decision pending and the readiness and merge checklists
unchecked. Maintainers can help resolve open questions.

Contract and boundary impact

Semantic owner and earliest changed stage: documentation/example at the existing CLI invocation boundary; no production analysis code changes.
Contribution scope fit and linked maintainer decision: not applicable; this documents an existing static operation and introduces no provider, target-execution capability, injection, mutation, or protection recovery.
CLI and MCP/tool-catalog contract: unchanged; original CLI output and exit codes are retained without filtering.
Provider, bridge, target-format, or platform compatibility: example targets Ubuntu 24.04/Bash and an existing JavaScript application directory or ASAR, not all providers or operating systems.
Evidence, artifact, provenance, or reconstruction contract: unchanged; the guide distinguishes process success from incomplete Evidence and preserves errors/limitations.
Target selection, authority, upstream behavior, and cleanup details (if applicable): caller-selected, authorized artifacts only; explicit manual trigger; no privileged untrusted-PR trigger. The demonstration build creates owned files. REA does not execute the analyzed application. Temporary tooling and reports remain job-owned.
Generated metadata (docs/public/product-catalog.json), package, or installation impact (CI generates and validates ignored catalogs and skills/; edit authored instructions in .agents/skills/reverse-engineer-anything/ and never commit build outputs): no package/dependency/metadata changes in REA; example installs the published package separately. Generated outputs are not committed.

Expected effects (check known effects; use documentation-only on its own).
Unchecked items do not establish absence; leave uncertainties visible.

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.

These checked effects describe intentionally executing the example: checkout/npm, reviewed Bash build commands, the existing CLI/parser process, generated files/reports, and artifact upload. They do not mean execution/injection of the analyzed application, target-memory changes, or new REA execution authority. The workflow requests only contents: read; no user-supplied secret is required.

Evidence and regression coverage

Tests added or updated: seven tests cover trigger/permissions/action pinning, the published workflow link, isolated report/upload behavior, four actual compiled-CLI cases (success, partial, missing and unsupported input), and a pre-analysis build failure with stale workspace reports. POSIX shell cases do not claim Windows coverage.
Base reproduction or other evidence: source-derived absence of a complete workflow example; no production bug claim. Separately executed the exact install/build/analysis commands with the published 6.7.0 package under Node 24.18.0 in isolated temporary workspaces.
User-visible CLI/MCP output (if applicable): observed public CLI results below; original report files remain unfiltered.
Remaining proof gaps: other providers/hosts were not verified. Hosted Ubuntu validation covers the published CLI success, missing-input and pre-analysis build-failure paths; partial/unsupported cases were verified with the current source-built CLI and previously with published 6.7.0 on macOS. A repeat four-case local published-package trial on Node 24.22.1 timed out during npm installation before analysis; it is not counted as a pass. Policy-skipped upstream CI lanes are not claimed as executed.

Input	Original exit	Retained JSON
Generated valid application	0	`ok: true`, `statistics.parse_failures: 0`
Application with invalid JavaScript	0	`ok: true`, `statistics.parse_failures: 1`, incomplete-coverage limitation
Missing application directory	1	`ok: false`, `error.category: invalid_input`
Single source file, not an application container	1	`ok: false`, `error.category: unsupported_target`

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

Current head: c19648fc23947930941398a59f2fb0a6e57471a6, incorporating upstream 28a33cae8f8d4de8e11f7a266ff0d756432ab092 (including its patched-Node requirement and the upstream HTTP MCP test fix). The PR delta remains four example/documentation/regression files; no independent runtime or dependency fix is mixed into it.

On macOS with Node 24.22.1 and npm 11.16.0:

npm run test:focused -- tests/boundary/cli/githubActionsExample.test.ts tests/boundary/mcp/streamableHttpMcp.test.ts src/domain/runtimeVersion.test.ts — 31 tests passed (7 example, 2 HTTP MCP, 22 runtime-version).
npm run check:fast — typecheck/lint passed.
npm run docs:check — generated documentation/metadata/license checks and 9 README tests passed.
npm run docs:build — VitePress build passed; the guide links directly to the repository-hosted YAML.
git diff --check and normal commit/push hooks passed.

Upstream CI run 39921898246 completed successfully for this exact head, including all eight test shards, Portable tests and CI required. PR readiness/title checks passed. Skipped optional lanes are not counted as coverage.

Real GitHub-hosted Ubuntu verification

A fork-only verification run derives its install/build/analysis/upload steps from this head's checked-in example, on Ubuntu 24.04 / Node 24.22.1 / published REA 6.7.0. Validation-only changes seed stale workspace reports, inject the two intentional failures, add assertions and give concurrent uploads distinct names. This extra verification workflow is not part of the upstream PR.

Case	Observed job result	Report/upload evidence
Complete application	Success	Fresh-directory assertions and upload succeeded; downloaded artifact contains original JSON/stderr/exit-code, `ok: true`, exit 0 and zero parse failures.
Missing application	Failure at analysis, as intended	Fresh-directory assertions and upload succeeded; downloaded artifact contains `ok: false`, `invalid_input` and exit 1.
Build fails before analysis	Failure at build with exit 42, as intended	Analysis skipped; assertion verified a fresh empty report directory despite stale workspace files. Upload warned that no files were found, and no stale artifact was published.

The verification run's overall failure is intentional: injected errors must remain red. Both available artifacts were downloaded and their exact three-file contents and exit codes checked. No build-failure artifact exists.

Historical supporting evidence: the exact published-6.7.0 install/build/analysis commands previously passed all four table cases on macOS / Node 24.18.0; the previous head's combined CLI suites passed 52 tests. Those historical results are not substituted for the current-head checks above. An initial cold compiled-CLI case hit the existing 30-second deadline; reusing the repository's worker-scoped compilation-cache fixture fixed that setup issue without widening the timeout or masking a failure.

Compatibility, safety, and release

Breaking changes or migration steps: none; copy the example to your own default branch and substitute a reviewed build/artifact path when needed.
Real Hopper/Ghidra, browser, or OS coverage: not applicable to this static operation; source-built CLI execution is macOS and the published CLI was verified on hosted Ubuntu 24.04 / Node 24.22.1 as detailed above. No claim for other providers/hosts.
Package or release metadata impact: none. The example pins REA/Node/action revisions, but does not claim every transitive npm dependency is locked; the guide explains using a committed lock and npm ci for that requirement.
Security, privacy, process, or containment review: least-privileged manual workflow; no pull_request_target, no secret inference, no artifact execution, no automatic provider fallback, no filtering away failures. Reports can contain caller-selected/source-derived data, so authorization and artifact access/retention are documented. Runner cancellation/loss can prevent upload.

Author readiness

Human owner: @gongfpp

AI-assisted contribution. The human owner has dictated the initial readiness declarations.

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/6496 **Author:** [@gongfpp](https://github.com/gongfpp) **Created:** 10/23/2026 **Status:** ✅ Merged **Merged:** 10/23/2026 **Merged by:** [@baron](https://github.com/baron) **Base:** `main` ← **Head:** `docs/ci-analysis-example-6335` --- ### 📝 Commits (3) - [`2c58c8d`](https://github.com/morluto/rea/commit/2c58c8d5fecea0f4eb0ea05a3a3bdca386b0056e) docs(ci): add a repeatable static analysis example - [`da1fc65`](https://github.com/morluto/rea/commit/da1fc65e80b11d58e21bdd4bcd34905954b97f2b) fix(ci): isolate example reports and repair the guide link - [`c19648f`](https://github.com/morluto/rea/commit/c19648fc23947930941398a59f2fb0a6e57471a6) chore: sync upstream Node security baseline ### 📊 Changes **4 files changed** (+394 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `docs/ci-analysis.md` (+90 -0) 📝 `docs/cli.md` (+2 -0) ➕ `examples/github-actions/rea-analysis.yml` (+60 -0) ➕ `tests/boundary/cli/githubActionsExample.test.ts` (+242 -0) </details> ### 📄 Description ## Summary Fixes #6335. Add a copyable GitHub Actions example and linked guide for static analysis with the existing REA CLI, preserving both reports and the original analysis exit status. ## Problem and expected behavior The CLI documentation did not provide a complete noninteractive workflow from a known build artifact to downloadable machine-readable results. A failed analysis must not become a green job merely to upload its diagnostics; successful execution must not be presented as complete coverage. ## Change and scope - Add a manually triggered Ubuntu example: pinned Node 24.22.1, published `rea-agents@6.7.0`, SHA-pinned actions, a small generated application, and retained JSON/stderr/exit-code files. - Install into the runner's temporary directory with lifecycle scripts disabled. Analyze the generated application as inert text; its JavaScript deliberately throws if executed. - Keep the original analysis exit status and use `always()` for uploading available reports. Explain missing input, unsupported input, partial results, prerequisites, privacy, and dependency-lock limitations. - Add regression coverage that executes the checked-in YAML build/analysis scripts against the real compiled CLI, not a fabricated tool response. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Unresolved scope, authority, side effects, or required verification block integration. Link the required maintainer scope decision for new providers or capabilities involving target execution, injection, mutation, or protection recovery; ordinary fixes within existing boundaries may state "not applicable". Draft PRs may leave the scope decision pending and the readiness and merge checklists unchecked. Maintainers can help resolve open questions. ## Contract and boundary impact - Semantic owner and earliest changed stage: documentation/example at the existing CLI invocation boundary; no production analysis code changes. - Contribution scope fit and linked maintainer decision: not applicable; this documents an existing static operation and introduces no provider, target-execution capability, injection, mutation, or protection recovery. - CLI and MCP/tool-catalog contract: unchanged; original CLI output and exit codes are retained without filtering. - Provider, bridge, target-format, or platform compatibility: example targets Ubuntu 24.04/Bash and an existing JavaScript application directory or ASAR, not all providers or operating systems. - Evidence, artifact, provenance, or reconstruction contract: unchanged; the guide distinguishes process success from incomplete Evidence and preserves errors/limitations. - Target selection, authority, upstream behavior, and cleanup details (if applicable): caller-selected, authorized artifacts only; explicit manual trigger; no privileged untrusted-PR trigger. The demonstration build creates owned files. REA does not execute the analyzed application. Temporary tooling and reports remain job-owned. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact (CI generates and validates ignored catalogs and `skills/`; edit authored instructions in `.agents/skills/reverse-engineer-anything/` and never commit build outputs): no package/dependency/metadata changes in REA; example installs the published package separately. Generated outputs are not committed. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [x] Read existing files or captured data. - [x] Launch or attach to a process. - [x] Inject instrumentation or run scripts/code. - [x] Change process memory, registers, files, or configuration. - [x] 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. These checked effects describe intentionally executing the example: checkout/npm, reviewed Bash build commands, the existing CLI/parser process, generated files/reports, and artifact upload. They do **not** mean execution/injection of the analyzed application, target-memory changes, or new REA execution authority. The workflow requests only `contents: read`; no user-supplied secret is required. ## Evidence and regression coverage - Tests added or updated: seven tests cover trigger/permissions/action pinning, the published workflow link, isolated report/upload behavior, four actual compiled-CLI cases (success, partial, missing and unsupported input), and a pre-analysis build failure with stale workspace reports. POSIX shell cases do not claim Windows coverage. - Base reproduction or other evidence: source-derived absence of a complete workflow example; no production bug claim. Separately executed the exact install/build/analysis commands with the published 6.7.0 package under Node 24.18.0 in isolated temporary workspaces. - User-visible CLI/MCP output (if applicable): observed public CLI results below; original report files remain unfiltered. - Remaining proof gaps: other providers/hosts were not verified. Hosted Ubuntu validation covers the published CLI success, missing-input and pre-analysis build-failure paths; partial/unsupported cases were verified with the current source-built CLI and previously with published 6.7.0 on macOS. A repeat four-case local published-package trial on Node 24.22.1 timed out during npm installation before analysis; it is not counted as a pass. Policy-skipped upstream CI lanes are not claimed as executed. | Input | Original exit | Retained JSON | | --- | --- | --- | | Generated valid application | 0 | `ok: true`, `statistics.parse_failures: 0` | | Application with invalid JavaScript | 0 | `ok: true`, `statistics.parse_failures: 1`, incomplete-coverage limitation | | Missing application directory | 1 | `ok: false`, `error.category: invalid_input` | | Single source file, not an application container | 1 | `ok: false`, `error.category: unsupported_target` | 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 Current head: `c19648fc23947930941398a59f2fb0a6e57471a6`, incorporating upstream `28a33cae8f8d4de8e11f7a266ff0d756432ab092` (including its patched-Node requirement and the upstream HTTP MCP test fix). The PR delta remains four example/documentation/regression files; no independent runtime or dependency fix is mixed into it. On macOS with Node 24.22.1 and npm 11.16.0: - `npm run test:focused -- tests/boundary/cli/githubActionsExample.test.ts tests/boundary/mcp/streamableHttpMcp.test.ts src/domain/runtimeVersion.test.ts` — 31 tests passed (7 example, 2 HTTP MCP, 22 runtime-version). - `npm run check:fast` — typecheck/lint passed. - `npm run docs:check` — generated documentation/metadata/license checks and 9 README tests passed. - `npm run docs:build` — VitePress build passed; the guide links directly to the repository-hosted YAML. - `git diff --check` and normal commit/push hooks passed. [Upstream CI run 39921898246](https://github.com/morluto/rea/actions/runs/39921898246) completed successfully for this exact head, including all eight test shards, Portable tests and CI required. PR readiness/title checks passed. Skipped optional lanes are not counted as coverage. ### Real GitHub-hosted Ubuntu verification A [fork-only verification run](https://github.com/gongfpp/rea/actions/runs/39922553442) derives its install/build/analysis/upload steps from this head's checked-in example, on Ubuntu 24.04 / Node 24.22.1 / published REA 6.7.0. Validation-only changes seed stale workspace reports, inject the two intentional failures, add assertions and give concurrent uploads distinct names. This extra verification workflow is not part of the upstream PR. | Case | Observed job result | Report/upload evidence | | --- | --- | --- | | Complete application | Success | Fresh-directory assertions and upload succeeded; downloaded artifact contains original JSON/stderr/exit-code, `ok: true`, exit 0 and zero parse failures. | | Missing application | Failure at analysis, as intended | Fresh-directory assertions and upload succeeded; downloaded artifact contains `ok: false`, `invalid_input` and exit 1. | | Build fails before analysis | Failure at build with exit 42, as intended | Analysis skipped; assertion verified a fresh empty report directory despite stale workspace files. Upload warned that no files were found, and no stale artifact was published. | The verification run's overall `failure` is intentional: injected errors must remain red. Both available artifacts were downloaded and their exact three-file contents and exit codes checked. No build-failure artifact exists. Historical supporting evidence: the exact published-6.7.0 install/build/analysis commands previously passed all four table cases on macOS / Node 24.18.0; the previous head's combined CLI suites passed 52 tests. Those historical results are not substituted for the current-head checks above. An initial cold compiled-CLI case hit the existing 30-second deadline; reusing the repository's worker-scoped compilation-cache fixture fixed that setup issue without widening the timeout or masking a failure. ## Compatibility, safety, and release - Breaking changes or migration steps: none; copy the example to your own default branch and substitute a reviewed build/artifact path when needed. - Real Hopper/Ghidra, browser, or OS coverage: not applicable to this static operation; source-built CLI execution is macOS and the published CLI was verified on hosted Ubuntu 24.04 / Node 24.22.1 as detailed above. No claim for other providers/hosts. - Package or release metadata impact: none. The example pins REA/Node/action revisions, but does not claim every transitive npm dependency is locked; the guide explains using a committed lock and `npm ci` for that requirement. - Security, privacy, process, or containment review: least-privileged manual workflow; no `pull_request_target`, no secret inference, no artifact execution, no automatic provider fallback, no filtering away failures. Reports can contain caller-selected/source-derived data, so authorization and artifact access/retention are documented. Runner cancellation/loss can prevent upload. ## Author readiness Human owner: @gongfpp AI-assisted contribution. The human owner has dictated the initial readiness declarations. - [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-11-01 21:47:21 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-11-03 00:29:32 +00:00

[GH-ISSUE #5653] [Tracker] New issue intake by area (October 2026) #3423

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

No description provided.

Rows
Columns