shopify-upgrade-guard 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,60 +1,43 @@
1
1
  # Shopify Upgrade Guard
2
2
 
3
- **Catch documented Shopify API and platform upgrade risks before they become production migrations.**
3
+ Find evidence-backed Shopify API and platform migration risks against a target version.
4
+
5
+ **RexCode Open Source · Shopify developer tools**
4
6
 
5
7
  [![npm](https://img.shields.io/npm/v/shopify-upgrade-guard?logo=npm)](https://www.npmjs.com/package/shopify-upgrade-guard)
6
- [![npm downloads](https://img.shields.io/npm/dm/shopify-upgrade-guard?logo=npm)](https://www.npmjs.com/package/shopify-upgrade-guard)
7
8
  [![CI](https://github.com/RexCode-Digital/shopify-upgrade-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/RexCode-Digital/shopify-upgrade-guard/actions/workflows/ci.yml)
8
9
  [![CodeQL](https://github.com/RexCode-Digital/shopify-upgrade-guard/actions/workflows/codeql.yml/badge.svg)](https://github.com/RexCode-Digital/shopify-upgrade-guard/actions/workflows/codeql.yml)
9
- [![license](https://img.shields.io/github/license/RexCode-Digital/shopify-upgrade-guard)](LICENSE)
10
-
11
- Shopify Upgrade Guard is an offline, evidence-backed CLI and GitHub Action for Shopify developers. It scans a repository for documented upgrade and deprecation risks, evaluates them against a target Shopify API version, and gives you migration guidance backed by official Shopify sources.
12
-
13
- **No Shopify credentials. No telemetry. No source upload. No repository code execution.**
14
-
15
- > Unofficial open-source developer tooling. Not affiliated with, endorsed by, or certified by Shopify.
10
+ [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/RexCode-Digital/shopify-upgrade-guard/badge)](https://securityscorecards.dev/viewer/?uri=github.com/RexCode-Digital/shopify-upgrade-guard)
11
+ [![Node.js 22+](https://img.shields.io/badge/Node.js-22+-22B8B2?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
12
+ [![MIT licence](https://img.shields.io/github/license/RexCode-Digital/shopify-upgrade-guard)](LICENSE)
16
13
 
17
- Maintained by RexCode Digital Ltd.
14
+ Shopify Upgrade Guard scans local application source and configuration for documented API removals, deprecations and platform changes. Each finding includes a version boundary and an official source where available.
18
15
 
19
- Part of the **RexCode Shopify developer tools** suite. Requires Node.js 20 or later for the CLI. The parser remains on GraphQL 16 because GraphQL 17.0.2 requires Node.js 22 or later, which would drop the supported Node.js 20 runtime. [Releases](https://github.com/RexCode-Digital/shopify-upgrade-guard/releases) · [npm](https://www.npmjs.com/package/shopify-upgrade-guard) · [Marketplace](https://github.com/marketplace/actions/shopify-upgrade-guard)
16
+ ## Features
20
17
 
21
- ## Quick start
18
+ - Checks migration risks against an explicit Shopify API target.
19
+ - Separates current debt from target-version findings.
20
+ - Supports JSON and SARIF output, baselines and pull-request-only findings.
21
+ - Keeps rules deterministic and links Shopify-specific checks to official evidence.
22
22
 
23
- Run it without installing anything globally:
24
-
25
- ```bash
26
- npx shopify-upgrade-guard scan --target 2026-10
27
- ```
23
+ ## Install and run
28
24
 
29
- Or install it in a project:
25
+ Requires Node.js 22 or later.
30
26
 
31
27
  ```bash
32
28
  npm install --save-dev shopify-upgrade-guard
33
29
  npx shopify-upgrade-guard scan --target 2026-10
34
30
  ```
35
31
 
36
- Upgrade Guard separates **current debt** from **target-version blockers**, so teams can see what already exists and what becomes relevant for the migration they are planning.
37
-
38
- ## Why Upgrade Guard?
39
-
40
- - **Target-aware** — evaluate findings against the Shopify version you actually plan to adopt.
41
- - **Evidence-backed** — Shopify-specific rules link to official Shopify documentation or changelog evidence.
42
- - **PR-aware** — compare independent base and head tree scans, including renamed files, to distinguish new, existing, and resolved findings.
43
- - **Baseline-friendly** — adopt the tool without forcing a big-bang cleanup of historical findings.
44
- - **CI-ready** — human, JSON, and SARIF output plus a GitHub Action.
45
- - **Offline by default** — ordinary scans require no network access, Shopify token, or store access.
46
- - **Deterministic** — designed for repeatable CI results and reviewable rule behaviour.
32
+ Use `npx shopify-upgrade-guard --help` for all commands. See the [CLI guide](docs/cli.md) and [version model](docs/version-model.md).
47
33
 
48
34
  ## GitHub Action
49
35
 
50
- A minimal pull-request gate:
36
+ Pin the v0.5.0 release tag for the `UG-TAX-001` rule. The repository ruleset prevents released semantic version tags from being changed or deleted:
51
37
 
52
38
  ```yaml
53
- name: Shopify Upgrade Guard
54
-
55
- on:
56
- pull_request:
57
-
39
+ name: Check Shopify API migration
40
+ on: [pull_request]
58
41
  permissions:
59
42
  contents: read
60
43
 
@@ -65,182 +48,68 @@ jobs:
65
48
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
66
49
  with:
67
50
  fetch-depth: 0
68
- persist-credentials: false
69
-
70
- - uses: RexCode-Digital/shopify-upgrade-guard@b0a6816f95d783f703bf031c9920004fbb865bc1 # v0.2.6
51
+ - uses: RexCode-Digital/shopify-upgrade-guard@v0.5.0 # v0.5.0
71
52
  with:
72
53
  target: 2026-10
73
54
  fail-on: warning
74
- fail-on-new: 'true'
75
55
  ```
76
56
 
77
- Use the immutable patch release tag or a reviewed full commit SHA. Existing minor aliases are retained for compatibility and are not moved by future releases.
78
-
79
- ### Action inputs
80
-
81
- | Input | Purpose |
82
- | --- | --- |
83
- | `target` | Shopify target version, for example `2026-10` |
84
- | `fail-on` | Policy threshold: `never`, `error`, `warning`, or `info` |
85
- | `fail-on-new` | Apply the failure threshold only to findings introduced by the PR |
86
- | `path` | Repository path to scan |
87
- | `base-ref` | Explicit Git base for comparison; defaults to origin/PR-base for new-only pull-request checks |
57
+ Inputs are `target`, `fail-on`, `fail-on-new`, `base-ref` and `path`. Outputs include active/new/resolved finding counts, error count, version inventory, policy outcome and JSON results. See [action.yml](action.yml).
88
58
 
89
- ### Action outputs
90
-
91
- `outcome`, `finding-count`, `new-finding-count`, `resolved-finding-count`, `error-count`, `current-versions`, and `result-json`.
92
-
93
- The Action is bundled and runs on the current GitHub `node24` JavaScript Action runtime.
94
-
95
- The example above pins v0.2.6, which does not expose `resolved-finding-count`. The independent base/head comparison and resolved-finding behaviour described below are part of the unreleased changes here; they are not available from the current npm package or Action.
96
-
97
- ## What it catches today
98
-
99
- The rule pack is intentionally focused. Literal GraphQL checks parse supported documents and ignore malformed or dynamic queries; rule-specific context limits findings to Shopify API constructs that can be identified deterministically.
100
-
101
- | Rule | Detects | Evidence |
102
- | --- | --- | --- |
103
- | `UG-CHECKOUT-001` | `useBuyerJourneyIntercept` / `buyerJourney.intercept` | [Shopify changelog](https://shopify.dev/changelog/deprecating-the-usebuyerjourneyintercept-api-on-checkout-ui-extensions) |
104
- | `UG-CHECKOUT-002` | Checkout `block_progress` capability | [Shopify changelog](https://shopify.dev/changelog/deprecating-the-usebuyerjourneyintercept-api-on-checkout-ui-extensions) |
105
- | `UG-REST-001` | Legacy Admin REST usage | [REST Admin API](https://shopify.dev/docs/api/admin-rest) |
106
- | `UG-VERSION-001` | Unsupported or target-retiring API versions | [API versioning](https://shopify.dev/docs/api/usage/versioning) |
107
- | `UG-VERSION-002` | Supported versions older than the latest stable version | [API versioning](https://shopify.dev/docs/api/usage/versioning) |
108
- | `UG-CUSTOMER-001` | Customer Account checkout removals relevant to 2026-10 | [Shopify changelog](https://shopify.dev/changelog/customer-account-api-last-incomplete-checkout-and-checkout-types-removed) |
109
- | `UG-POS-001` | Removed POS `session.currentSession.staffMemberId` usage | [Shopify changelog](https://shopify.dev/changelog/removed-session-currentsession-staffmemberid-from-pos-ui-extensions-2026-10) |
110
- | `UG-ADMIN-001` | Legacy Admin GraphQL `priceRule` usage | [2026-10 release notes](https://shopify.dev/release-notes/2026-10) |
111
- | `UG-ADMIN-002` | Literal GraphQL root `automaticDiscounts` removed in 2027-01 | [Official removal](https://shopify.dev/changelog/posts/automaticdiscounts-query-is-removed-in-api-version-2027-01) |
112
- | `UG-ADMIN-003` | GraphQL `metafieldInteger` collection conditions and types removed in 2027-01 | [Official removal](https://shopify.dev/changelog/posts/metafieldinteger-collection-condition-removed-in-api-version-2027-01) |
113
- | `UG-ADMIN-004` | `ProductVariant.barcode` read deprecated in 2026-10; it still works and no removal date is announced | [Official deprecation](https://shopify.dev/changelog/posts/product-variant-barcode-is-being-replaced-by-barcodes) |
114
- | `UG-ADMIN-006` | Literal `marketCurrencySettingsUpdate` Admin mutation removed in 2027-01 | [Official removal](https://shopify.dev/changelog/posts/removing-marketcurrencysettingsupdate-mutation) |
115
- | `UG-ADMIN-007` | `PRIVATE` / `PUBLIC_READ` literals passed as metaobject definition admin access removed in 2027-01 | [Official deprecation](https://shopify.dev/changelog/posts/removing-deprecated-private-and-public-read-enums-on-metaobject-definitions) |
116
- | `UG-SEGMENT-001` | Legacy function/date syntax inside literal segment GraphQL query arguments | [Official syntax update](https://shopify.dev/changelog/posts/updated-function-syntax-on-the-segment-query-language) |
117
- | `UG-ADMIN-005` | Source handling for removed inventory error `ITEM_NOT_STOCKED_AT_LOCATION` | [Official removal](https://shopify.dev/changelog/posts/removal-of-itemnotstockedatlocation-error) |
118
- | `UG-SCRIPT-001` | Cross-version Script Tag write restrictions; REST resource references require method review | [Script Tag deprecation](https://shopify.dev/changelog/online-store-script-tags-deprecation) |
119
-
120
- Supported inventory surfaces include Admin REST, Admin GraphQL, Checkout UI extensions, Customer Account UI extensions, POS UI extensions, Functions, Shopify app TOML, and recognized Shopify client configuration.
121
-
122
- ## CLI
59
+ ## Example output
123
60
 
124
61
  ```text
125
- shopify-upgrade-guard scan [--target YYYY-MM] [--format human|json|sarif] [--fail-on ...] [--fail-on-new]
126
- shopify-upgrade-guard baseline create|check [--path DIR]
127
- shopify-upgrade-guard rules
128
- shopify-upgrade-guard versions
129
- shopify-upgrade-guard explain UG-CHECKOUT-001
130
- ```
131
-
132
- Examples:
133
-
134
- ```bash
135
- # Human-readable scan
136
- npx shopify-upgrade-guard scan --target 2026-10
137
-
138
- # CI-friendly JSON
139
- npx shopify-upgrade-guard scan --target 2026-10 --format json
140
-
141
- # SARIF for code-scanning workflows
142
- npx shopify-upgrade-guard scan --target 2026-10 --format sarif
143
-
144
- # Fail only when the PR introduces new warning-or-higher findings
145
- npx shopify-upgrade-guard scan --target 2026-10 --fail-on warning --fail-on-new --base-ref origin/main
146
- ```
147
-
148
- Exit codes: `0` means the scan completed and policy passed; `1` means active findings exceeded the configured policy; `2` means the scanner could not complete.
149
-
150
- ## Adopt it gradually with a baseline
151
-
152
- Existing migration debt should not prevent a team from adopting Upgrade Guard.
153
-
154
- ```bash
155
- npx shopify-upgrade-guard baseline create
156
- npx shopify-upgrade-guard baseline check
62
+ Shopify Upgrade Guard
63
+ Target version: 2026-10
64
+ Files scanned: 1
65
+
66
+ ERROR UG-CUSTOMER-001
67
+ Customer Account checkout types are removed
68
+ customer.graphql:1
69
+ This usage is affected by target 2026-10.
70
+ Migration: Use Storefront cart flows or Customer.orders as appropriate.
71
+ Source: https://shopify.dev/changelog/customer-account-api-last-incomplete-checkout-and-checkout-types-removed
72
+
73
+ 1 active risk found
74
+ Result: migration recommended
157
75
  ```
158
76
 
159
- Baselined findings remain reviewable while new fingerprints stay actionable.
160
-
161
- `--fail-on-new` requires a valid Git base comparison. Upgrade Guard scans the base commit and head tree independently, then matches findings by rule, file identity, and evidence; recognized file renames keep existing debt stable. JSON includes `resolvedFindings`, and human output reports their count. Fetch full history and provide `--base-ref`, or use the pull-request Action. Missing refs/history exit 2 instead of passing an incomplete comparison.
162
-
163
- The bundled snapshot, verified 14 October 2026, lists `2026-10` as the latest stable API and `2027-01` as a release candidate for development testing. Version status uses Shopify's exact `accessibleUntil` timestamp: `2025-10` remains accessible until 16 October 2026 at 15:00 UTC, then becomes unsupported. Future version names do not imply verified rule coverage.
164
-
165
- The 2027-01 tax payload change converts IDs in tax calculation requests and tax summary webhook payloads to Global IDs. Upgrade Guard cannot reliably tell whether arbitrary runtime parsing assumes numeric IDs, so tax app handlers need review against Shopify's [official migration note](https://shopify.dev/changelog/posts/tax-webhook-summary-and-calculation-requests-now-use-global-ids).
166
-
167
- ## Configuration
168
-
169
- Commit `.upgradeguard.json` to set repository defaults:
170
-
171
- ```json
172
- {
173
- "targetVersion": "2026-10",
174
- "failOn": "warning",
175
- "exclude": ["fixtures/**"]
176
- }
177
- ```
77
+ The example is shortened from a scan of a synthetic GraphQL document.
178
78
 
179
- `exclude` accepts repository-relative glob patterns. Absolute paths and traversal are rejected.
79
+ ## Supported capabilities and evidence
180
80
 
181
- See [examples](examples/) for copy-paste CI and configuration examples.
81
+ Rules cover documented Shopify API and platform lifecycle changes across supported Admin GraphQL, Customer Account, Checkout UI, POS, extension-configuration and other tracked surfaces. Each rule defines its affected version and migration guidance; the [CLI guide](docs/cli.md), generated rule catalogue from the rules command, and [migration documentation](docs/2027-01-migration.md) describe current coverage. Rules only apply at their documented version boundary.
182
82
 
183
- ## Security and privacy
83
+ Version 0.5.0 adds `UG-TAX-001` for an explicit `tax_summaries/create` subscription when the selected target is `2027-01` or later. It reports a review warning; it cannot determine whether the handler already accepts Global IDs. See the [2027-01 research and limits](docs/2027-01-migration.md).
184
84
 
185
- Upgrade Guard treats scanned repositories as untrusted input.
85
+ ## Limitations and privacy
186
86
 
187
- Ordinary scans:
87
+ Scans are offline and do not call Shopify or execute application code. A match is a review signal, not proof of a production failure. Static detection cannot see runtime-generated operations, every framework wrapper, live subscription configuration or whether application code already handles a changed payload. Review the linked source and test the migration in your application.
188
88
 
189
- - do not execute repository code
190
- - do not contact Shopify
191
- - do not require Shopify credentials
192
- - do not upload source
193
- - skip generated/vendor directories by default
194
- - use bounded file discovery
89
+ ## Documentation
195
90
 
196
- See [SECURITY.md](SECURITY.md) and the [threat model](docs/threat-model.md).
91
+ - [Getting started](docs/getting-started.md)
92
+ - [CLI and rule behaviour](docs/cli.md)
93
+ - [Configuration and baselines](docs/configuration.md)
94
+ - [2027-01 migration research](docs/2027-01-migration.md)
95
+ - [Release process](docs/release-process.md)
197
96
 
198
- ## Related Shopify developer tools
97
+ ## Related RexCode OSS tools
199
98
 
200
- Building or maintaining Shopify apps?
99
+ - [ChangeGuard](https://github.com/RexCode-Digital/shopify-app-changeguard) reviews semantic app configuration changes.
100
+ - [Shopify Scope Guard](https://github.com/RexCode-Digital/shopify-scope-guard) checks requested access scopes against static evidence.
101
+ - [Shopify App Review Guard](https://github.com/RexCode-Digital/shopify-app-review-guard) reports App Store and production-readiness evidence.
201
102
 
202
- - **[ChangeGuard](https://github.com/RexCode-Digital/shopify-app-changeguard)** — Review meaningful `shopify.app*.toml` configuration changes before they reach production.
203
- - **[Shopify Scope Guard](https://github.com/RexCode-Digital/shopify-scope-guard)** — Audit whether declared Shopify permissions are supported by offline code evidence.
204
- - **[Shopify App Review Guard](https://github.com/RexCode-Digital/shopify-app-review-guard)** — Run deterministic preflight checks for Shopify App Store and production readiness.
103
+ Use the [four-tool workflow](https://github.com/RexCode-Digital/shopify-app-changeguard/blob/main/docs/ecosystem-workflow.md) to run the published Actions together.
205
104
 
206
- See the [coordinated workflow example](https://github.com/RexCode-Digital/shopify-app-changeguard/blob/main/docs/ecosystem-workflow.md) to run all four published Actions in one pull-request workflow.
105
+ ## Contributing and support
207
106
 
208
- GitHub Marketplace: [Shopify Upgrade Guard](https://github.com/marketplace/actions/shopify-upgrade-guard)
107
+ Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [RexCode Open Source standards](https://github.com/RexCode-Digital/.github/blob/main/docs/oss/standards.md). For usage questions or safe reproductions, use [SUPPORT.md](SUPPORT.md) or the [issue tracker](https://github.com/RexCode-Digital/shopify-upgrade-guard/issues).
209
108
 
210
- All four tools run offline and require no Shopify credentials.
109
+ ## Security
211
110
 
212
- ## Contributing
213
-
214
- Contributions are welcome, especially new evidence-backed Shopify migration rules and scanner hardening.
215
-
216
- A Shopify-specific rule should include:
217
-
218
- 1. an official `shopify.dev` evidence URL
219
- 2. the affected version or status
220
- 3. bounded deterministic detection
221
- 4. migration guidance
222
- 5. positive and false-positive tests
223
-
224
- Start with [the contribution guide](CONTRIBUTING.md) or browse the [open issues](https://github.com/RexCode-Digital/shopify-upgrade-guard/issues).
225
-
226
- ## Roadmap
227
-
228
- Current priorities include additional verified Shopify breaking-change coverage, high-confidence Functions/Customer Account/POS/GraphQL rules, and maintainable GraphQL deprecation evidence when Shopify provides a versioned source with clear redistribution rights. See the [metadata decision](docs/graphql-deprecation-metadata.md).
229
-
230
- See [ROADMAP.md](ROADMAP.md).
231
-
232
- ## License
233
-
234
- MIT — see [LICENSE](LICENSE).
235
-
236
- ## Immutable SHA usage
237
-
238
- The Action example pins the reviewed v0.2.6 release commit. Verify the release reference with:
239
-
240
- ```bash
241
- git fetch --tags origin && git rev-parse 'v0.2.6^{commit}'
242
- ```
111
+ Use [SECURITY.md](SECURITY.md) for private vulnerability reporting. Do not post credentials, merchant data or private source in public issues.
243
112
 
244
- Published patch tags and existing minor aliases are retained. Future releases do not move minor aliases; use an immutable patch tag or a reviewed full commit SHA.
113
+ ## Licence and affiliation
245
114
 
246
- The Action `base-ref` input selects an explicit Git comparison base. With `fail-on-new: true`, pull-request events default to `origin/<base branch>`; other events must supply `base-ref`. Ordinary scans do not infer a comparison from GitHub environment variables.
115
+ MIT licensed. Shopify's names and marks belong to Shopify. This independent open-source project is not affiliated with, endorsed by, or certified by Shopify.
@@ -1,6 +1,6 @@
1
1
  # Third-party notices
2
2
 
3
- The generated GitHub Action bundle `dist/index.js` contains third-party code. Its companion `dist/licenses.txt` is generated by ncc from the bundled dependency graph and carries the full licence texts for bundled modules. The direct GraphQL.js dependency is resolved in `package-lock.json` and is listed below.
3
+ The generated GitHub Action bundle `dist/index.js` contains third-party code. Its companion `dist/licenses.txt` is generated by ncc from the bundled dependency graph and carries the full licence texts for bundled modules. The direct GraphQL.js and TOML parser dependencies are resolved in `package-lock.json` and listed below.
4
4
 
5
5
  ## GraphQL.js
6
6
 
@@ -31,3 +31,25 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
31
31
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
32
32
  SOFTWARE.
33
33
  ```
34
+
35
+ ## @iarna/toml
36
+
37
+ - Upstream: [iarna/iarna-toml](https://github.com/iarna/iarna-toml)
38
+ - Version resolved by this repository: 2.2.5
39
+ - Licence: ISC
40
+
41
+ ```text
42
+ Copyright (c) 2016, Rebecca Turner <me@re-becca.org>
43
+
44
+ Permission to use, copy, modify, and/or distribute this software for any
45
+ purpose with or without fee is hereby granted, provided that the above
46
+ copyright notice and this permission notice appear in all copies.
47
+
48
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
49
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
50
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
51
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
52
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
53
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
54
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
55
+ ```
@@ -1,5 +1,5 @@
1
1
  {
2
- "verifiedAt": "2026-10-14",
2
+ "verifiedAt": "2026-10-21",
3
3
  "source": "https://shopify.dev/docs/api/usage/versioning",
4
4
  "versions": [
5
5
  {