Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 21 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,17 @@ Arc-specific static CI quality gate and integration-pattern validator for wallet
[![Release](https://img.shields.io/github/v/release/tanka420/arcready?include_prereleases&label=release)](https://github.com/tanka420/arcready/releases)
![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)
![Node.js](https://img.shields.io/badge/Node.js-22%2B-green)
![npm](https://img.shields.io/badge/npm-arcready%400.3.0-blue)
![npm](https://img.shields.io/badge/npm-arcready%400.4.0-blue)
![Backend](https://img.shields.io/badge/backend-not_required-lightgrey)

ArcReady helps developers catch common Arc integration mistakes before release. It is a developer-side early warning layer for static checks in local workflows and CI.

> ArcReady is an independent open-source project. It is not an official Circle or Arc product.

> Release boundary: the install and Action examples below deliberately run the
> published `arcready@0.3.0` release. The main branch contains later, unreleased
> rule and runtime changes. In particular, v0.3.0 still runs
> `wallet/NO_ETH_GAS_LABEL` as a default critical rule, while current main
> exposes it only as default-excluded, deprecated `info` advice. Use the
> versioned release notes for v0.3.0 behavior and the current rule catalog for
> main-branch behavior.
> Release boundary: npm `latest` is the reviewed `arcready@0.4.0` package. The
> current stable Action tag remains `tanka420/arcready@v0.3.0` until the staged
> v0.4.0 Action proof and immutable tag checkpoints complete. The v0.3 Action
> wrapper can run the new package by setting `arcready-version: "0.4.0"`.

## What It Is

Expand All @@ -34,20 +31,20 @@ It reports findings in terminal, JSON, Markdown, or HTML formats and can fail CI
## Quick Demo

```powershell
npx --yes arcready@0.3.0 init
npx --yes arcready@0.3.0 scan
npx --yes arcready@0.4.0 init
npx --yes arcready@0.4.0 scan
```

CI-oriented Markdown report:

```powershell
npx --yes arcready@0.3.0 scan --format markdown --out arcready-report.md
npx --yes arcready@0.4.0 scan --format markdown --out arcready-report.md
```

Shortened example output:

```text
ArcReady v0.3.0
ArcReady v0.4.0
Project: my-arc-app
Score: 75
Status: fail
Expand Down Expand Up @@ -78,13 +75,13 @@ patterns, not universal Arc compatibility or runtime verification.
Run without installing:

```powershell
npx --yes arcready@0.3.0 scan
npx --yes arcready@0.4.0 scan
```

Create a config file:

```powershell
npx --yes arcready@0.3.0 init
npx --yes arcready@0.4.0 init
```

Install locally:
Expand Down Expand Up @@ -117,17 +114,18 @@ jobs:

- uses: tanka420/arcready@v0.3.0
with:
arcready-version: "0.4.0"
fail-on: critical
```

The action runs the published npm CLI and defaults to `arcready@0.3.0`. You can pin or override the CLI package version:

The `v0.3.0` Action tag therefore runs v0.3.0 package behavior, not unreleased
main-branch behavior.
The stable `v0.3.0` Action wrapper defaults to npm package v0.3.0, so the example
pins its package input to the published v0.4.0 release. The repository Action
candidate defaults to v0.4.0, but no `v0.4.0` Action tag is claimed until the
separate exact-SHA proof and tag checkpoints complete.

```yaml
with:
arcready-version: "0.3.0"
arcready-version: "0.4.0"
```

See [docs/github-action.md](docs/github-action.md) for inputs, artifact behavior, and external usage notes.
Expand Down Expand Up @@ -184,10 +182,10 @@ Supported formats:
- HTML

```powershell
npx --yes arcready@0.3.0 scan --format terminal
npx --yes arcready@0.3.0 scan --format json --out arcready-report.json
npx --yes arcready@0.3.0 scan --format markdown --out arcready-report.md
npx --yes arcready@0.3.0 scan --format html --out arcready-report.html
npx --yes arcready@0.4.0 scan --format terminal
npx --yes arcready@0.4.0 scan --format json --out arcready-report.json
npx --yes arcready@0.4.0 scan --format markdown --out arcready-report.md
npx --yes arcready@0.4.0 scan --format html --out arcready-report.html
```

Generated report folders such as `.arcready/` and `reports/` are ignored by git.
Expand Down
2 changes: 1 addition & 1 deletion action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ inputs:
arcready-version:
description: "ArcReady npm package version to run"
required: false
default: "0.3.0"
default: "0.4.0"
working-directory:
description: "Directory to scan"
required: false
Expand Down
84 changes: 56 additions & 28 deletions docs/exec-plans/active/R01.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# R01 — Coordinated ArcReady v0.4.0 Release

Status: Validated — E1 candidate pending commit and PR approval
Status: Validated — E2A candidate pending commit and PR approval

Risk class: R3 distribution and external contract

Expand All @@ -16,24 +16,21 @@ Last reviewed: 2026-08-20

### Problem

The public npm package and exact GitHub Action release remain on v0.3.0, while
main contains the merged C04–C12 rule hardening, bounded analyzers, experimental
canonical JSON output, dependency, default-selection, and remediation changes.
The current repository README must distinguish those surfaces because a user
following its pinned v0.3.0 commands does not receive current main behavior.
The reviewed npm package is now published as `arcready@0.4.0`, but the stable
GitHub Action tag remains `v0.3.0` and defaults to the old npm package. E2 must
move the Action default to 0.4.0 without claiming a tag before its exact-SHA
external proof completes.

The mismatch is directly harmful for C12: npm v0.3.0 runs
`wallet/NO_ETH_GAS_LABEL` as a default critical rule, while merged main
default-excludes it as deprecated `info` advice after measured real-repository
false positives.
The boundary matters for C12: the stable v0.3 Action still selects the old
default-critical gas-label rule unless the caller explicitly overrides
`arcready-version` to 0.4.0.

### Why now

The [A02 adoption audit](../../research/A02.md) found zero default findings in
eight pinned repositories with the merged post-C12 package. The
[A03 distribution audit](../../research/A03.md) proved that npm `latest` and the
`v0.3.0` Action cannot reproduce that result because they still deliver the
older release.
eight pinned repositories with the merged post-C12 package. E1 then published
and independently verified that package as npm 0.4.0. The remaining distribution
gap is the stable v0.3 Action wrapper's default package selection.

### Product value

Expand Down Expand Up @@ -71,14 +68,14 @@ Verified on 2026-08-20:

| Boundary | Evidence |
| --------------------- | ------------------------------------------------------------------- |
| npm latest | `arcready@0.3.0`, published 2026-06-13T17:07:22.227Z |
| npm package source | `gitHead` `108759757d047236cab19272c3246bacc3261f1a` |
| npm latest | `arcready@0.4.0`, published 2026-08-20T09:31:45.690Z |
| npm package source | `gitHead` `be945efd2fb6d6ec625d9aa28ebdfc3cae7e91af` |
| Git release tag | `v0.3.0` resolves to `e4a1244e5363bafee2dcf7446467e7f6fabe921e` |
| Frozen E1 base | `4b7ee02901f5313b8bd33e1e22de69b1b4e2d620` |
| Change size | 184 files, 61,169 insertions, 1,162 deletions from tag to base |
| File deletion | no deleted path in the tag-to-main diff |
| Published package | 7 entries, 18,109-byte tarball, 79,982 bytes unpacked |
| E1 candidate package | 10 entries, 92,141-byte tarball, 436,925 bytes unpacked |
| Published package | 10 entries, 92,141-byte tarball, 436,925 bytes unpacked |
| Published integrity | Exact SHA-1 and SHA-512 recorded in the npm checklist |
| Runtime dependencies | `@solidity-parser/parser@0.20.2`, `typescript@5.9.3` |
| Dependency licenses | parser MIT with no declared dependency; TypeScript Apache-2.0 |
| Dependency Node floor | TypeScript >=14.17; ArcReady >=22 |
Expand All @@ -95,11 +92,12 @@ Resolved before E1 implementation:
- the E1 base is frozen at that exact merge SHA, and later runtime changes are
excluded unless the cumulative release inventory is reset.

Remaining before E1 publication:
E1 publication is complete. Remaining for E2:

- npm authentication and package-owner authorization;
- exact GitHub release permissions and tag protection state;
- exact candidate review, full gate, merge, and registry dry-run evidence.
- E2A exact-head CI and merge;
- E2B exact-E2A-SHA external proof before tag approval;
- exact GitHub release permissions and tag protection state before later tag
and GitHub Release checkpoints.

Any new runtime-affecting main change resets the release base and requires a new
cumulative inventory.
Expand Down Expand Up @@ -374,7 +372,10 @@ analyzer semantics.

### Final independent review

Pending for the exact E1 package candidate and exact E2A Action/tag candidate.
E1 passed with `APPROVE — 0 blocker / 0 major / 0 minor` on its exact reviewed
candidate. E2A passed with `APPROVE — 0 blocker / 0 major / 0 minor` on the
exact 10-file staged bundle whose SHA-256 is
`fd4797234d5114996bbf745b2f70cbd5764ff1c44c51181d53d951c4e9a8dafa`.
Corrections that change only E3 closeout prose do not require a new full
analyzer review; any package or Action execution change does.

Expand All @@ -390,6 +391,10 @@ rerun the full gate if it changes anything beyond the external reference,
structural assertion, and release evidence. Do not substitute historical
per-milestone gates for the cumulative release gate.

E2A passed this gate on 2026-08-20: fixture validation, all 42 package test files
and 2,704 tests, six workflow tests, lint, build, and installed-package smoke
completed successfully.

### Additional release-candidate checks

- `npm whoami` and package-owner verification immediately before publish;
Expand Down Expand Up @@ -430,11 +435,13 @@ Progress:
- [x] targeted validation passed
- [x] E1 final independent review passed
- [x] E1 full validation passed
- [ ] E1 exact-head CI passed and merged
- [ ] npm 0.4.0 explicitly approved, published, and verified
- [ ] E2A Action candidate reviewed, validated, and merged
- [ ] E2A transitive build-input equality with E1 passed
- [ ] E2A rebuilt package entry hashes equal E1 registry artifact
- [x] E1 exact-head CI passed and merged
- [x] npm 0.4.0 explicitly approved, published, and verified
- [x] E2A local Action vertical slice and registry consumer probe passed
- [x] E2A Action candidate reviewed and full validation passed
- [ ] E2A exact-head CI passed and merged
- [x] E2A transitive build-input equality with E1 passed
- [x] E2A rebuilt package entry hashes equal E1 registry artifact
- [ ] E2B exact-SHA external smoke passed
- [ ] v0.4.0 tag explicitly approved and created at E2A SHA
- [ ] E3A tagged external Action smoke passed on its exact merge SHA
Expand Down Expand Up @@ -516,3 +523,24 @@ Pending.
package tests, six workflow tests, lint, build, and installed-package smoke.
Ignored local adoption artifacts were quarantined outside the repository for
lint and restored afterward; they are not candidate inputs.
- 2026-08-20: PR #75 merged E1 as
`be945efd2fb6d6ec625d9aa28ebdfc3cae7e91af`; four exact-head checks and five
post-merge workflows passed on the expected SHAs.
- 2026-08-20: Published npm `arcready@0.4.0` with registry `gitHead`
`be945efd2fb6d6ec625d9aa28ebdfc3cae7e91af`, SHA-1
`936ed9a88a47273690782072488ee52e761c37c1`, and the reviewed SHA-512. The
registry tarball's ten entry hashes matched E1, and clean-install terminal,
default C12, legacy JSON, and JSON v2 probes passed.
- 2026-08-20: Began E2A from E1 merge `be945efd`; changed only the Action
default, structural assertions, current public distribution docs/examples,
and E1 evidence. All declared transitive package inputs remained
byte-identical to E1. The E2A rebuild reproduced all ten registry entry hashes
and the exact tarball SHA-1; local good/bad Action command probes returned
pass/zero and expected fail/three-critical behavior with all reports created.
- 2026-08-20: Final independent E2A review approved the exact 27,766-byte,
10-file staged bundle with SHA-256
`fd4797234d5114996bbf745b2f70cbd5764ff1c44c51181d53d951c4e9a8dafa` at
`0 blocker / 0 major / 0 minor`. `corepack pnpm verify:full` then passed fixture
validation, 42 package test files with 2,704 tests, six workflow tests, lint,
build, and installed-package smoke. Ignored audit artifacts were quarantined
for lint and restored afterward; they are not candidate inputs.
30 changes: 20 additions & 10 deletions docs/github-action.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,21 +27,26 @@ jobs:

- uses: tanka420/arcready@v0.3.0
with:
arcready-version: "0.4.0"
fail-on: critical
```

`v0.3.0` is the current GitHub Action-ready release and includes rule quality hardening. The action runs the published npm CLI package, and the default CLI version is `0.3.0`. You can override the CLI package version with `arcready-version`.
`v0.3.0` remains the current stable GitHub Action tag until the v0.4.0 exact-SHA
proof and immutable tag checkpoints complete. That wrapper defaults to npm
package v0.3.0, so current examples set `arcready-version: "0.4.0"`. The
repository Action candidate defaults to the published npm v0.4.0 package; it is
not a claim that the `v0.4.0` Action tag already exists.

## Inputs

| Input | Default | Description |
| ------------------- | ------------------- | ----------------------------------------------------------------- |
| `arcready-version` | `0.3.0` | ArcReady npm package version to run |
| `working-directory` | `.` | Directory to scan |
| `fail-on` | `critical` | Fail when findings reach `critical`, `warning`, `info`, or `none` |
| `output-dir` | `.arcready/reports` | Directory for ArcReady report files |
| `upload-artifact` | `true` | Upload ArcReady reports as a workflow artifact |
| `artifact-name` | `arcready-report` | Artifact name for uploaded ArcReady reports |
| Input | Main default | Stable v0.3 tag | Description |
| ------------------- | ------------------- | --------------- | ----------------------------------------------------------------- |
| `arcready-version` | `0.4.0` | `0.3.0` | ArcReady npm package version to run |
| `working-directory` | `.` | `.` | Directory to scan |
| `fail-on` | `critical` | `critical` | Fail when findings reach `critical`, `warning`, `info`, or `none` |
| `output-dir` | `.arcready/reports` | same | Directory for ArcReady report files |
| `upload-artifact` | `true` | `true` | Upload ArcReady reports as a workflow artifact |
| `artifact-name` | `arcready-report` | same | Artifact name for uploaded ArcReady reports |

## Working Directory

Expand All @@ -50,6 +55,7 @@ Scan a subdirectory:
```yaml
- uses: tanka420/arcready@v0.3.0
with:
arcready-version: "0.4.0"
working-directory: apps/wallet
fail-on: critical
```
Expand All @@ -69,6 +75,7 @@ Upload artifacts with the default settings:
```yaml
- uses: tanka420/arcready@v0.3.0
with:
arcready-version: "0.4.0"
upload-artifact: true
```

Expand All @@ -77,6 +84,7 @@ Customize the report directory and artifact name:
```yaml
- uses: tanka420/arcready@v0.3.0
with:
arcready-version: "0.4.0"
output-dir: reports/arcready
artifact-name: arc-static-validation
```
Expand Down Expand Up @@ -114,4 +122,6 @@ uses: tanka420/arcready@v0.3.0

It checks a known-good fixture that should pass and a known-bad fixture that should fail as expected.

External action smoke validation is configured to use `uses: tanka420/arcready@v0.3.0` after the `v0.3.0` tag is created and pushed.
External action smoke validation currently remains pinned to
`uses: tanka420/arcready@v0.3.0`; R01 changes that reference only in the later,
separately reviewed exact-SHA and tagged-proof checkpoints.
32 changes: 15 additions & 17 deletions docs/npm-publishing.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,19 @@
# npm Publishing

ArcReady is published on npm as an installable CLI package. The current public
version is `arcready@0.3.0`. The architecture-approved R01 E1 candidate selects
`0.4.0` from frozen base `4b7ee02901f5313b8bd33e1e22de69b1b4e2d620`.
The candidate is not published, and its exact operational commit remains
pending final validation and review.
version is the registry-verified `arcready@0.4.0`, published from merged E1
commit `be945efd2fb6d6ec625d9aa28ebdfc3cae7e91af`.

## Current Package

| Field | Value |
| --------------------- | -------------------------- |
| Package name | `arcready` |
| Published version | `0.3.0` |
| Selected next version | `0.4.0` (R01 E1 candidate) |
| License | MIT |
| Node.js | `>=22` |
| CLI bin | `arcready` |
| Field | Value |
| --------------------- | --------------------------- |
| Package name | `arcready` |
| Published version | `0.4.0` |
| Selected next version | none; R01 E2 changes Action |
| License | MIT |
| Node.js | `>=22` |
| CLI bin | `arcready` |

The npm package should include only:

Expand Down Expand Up @@ -50,9 +48,9 @@ cd packages/arcready
npm publish --dry-run
```

Inspect the output before release. The dry run must show the separately approved,
unpublished candidate version and only the expected package files. Do not try to
publish `arcready@0.3.0` again.
Inspect the output before any future release. It must show a separately approved,
unpublished version and only the expected package files. Do not try to republish
the immutable `arcready@0.4.0` version.

Use the versioned
[v0.4.0 npm checklist](releases/v0.4.0-npm-checklist.md) for E1 evidence. Record
Expand All @@ -72,9 +70,9 @@ Confirm the package name is still available or owned by the project:
npm view arcready
```

## Do Not Run This Until Release Approval
## Do Not Run This Without Release Approval

The real publish command is not part of this task:
The real publish command is never implied by Action or documentation work:

```bash
npm publish
Expand Down
Loading
Loading