shopify-upgrade-guard 0.4.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 +57 -191
- package/dist/index.js +1 -1
- package/package.json +2 -2
- package/src/rules.js +52 -0
- package/src/version.js +1 -1
package/README.md
CHANGED
|
@@ -1,60 +1,43 @@
|
|
|
1
1
|
# Shopify Upgrade Guard
|
|
2
2
|
|
|
3
|
-
|
|
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
|
[](https://www.npmjs.com/package/shopify-upgrade-guard)
|
|
6
|
-
[](https://www.npmjs.com/package/shopify-upgrade-guard)
|
|
7
8
|
[](https://github.com/RexCode-Digital/shopify-upgrade-guard/actions/workflows/ci.yml)
|
|
8
9
|
[](https://github.com/RexCode-Digital/shopify-upgrade-guard/actions/workflows/codeql.yml)
|
|
9
|
-
[](https://securityscorecards.dev/viewer/?uri=github.com/RexCode-Digital/shopify-upgrade-guard)
|
|
11
|
+
[](https://nodejs.org/)
|
|
12
|
+
[](LICENSE)
|
|
16
13
|
|
|
17
|
-
|
|
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
|
-
|
|
16
|
+
## Features
|
|
20
17
|
|
|
21
|
-
|
|
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
|
-
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
npx shopify-upgrade-guard scan --target 2026-10
|
|
27
|
-
```
|
|
23
|
+
## Install and run
|
|
28
24
|
|
|
29
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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,185 +48,68 @@ jobs:
|
|
|
65
48
|
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
66
49
|
with:
|
|
67
50
|
fetch-depth: 0
|
|
68
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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-EXT-001` | Missing `owner_type` in eligible Checkout or Customer Account UI extension metafield declarations | [Shopify changelog](https://shopify.dev/changelog/posts/metafield-owner-types-required-for-checkout-and-customer-account-ui-extensions) |
|
|
106
|
-
| `UG-REST-001` | Legacy Admin REST usage | [REST Admin API](https://shopify.dev/docs/api/admin-rest) |
|
|
107
|
-
| `UG-VERSION-001` | Unsupported or target-retiring API versions | [API versioning](https://shopify.dev/docs/api/usage/versioning) |
|
|
108
|
-
| `UG-VERSION-002` | Supported versions older than the latest stable version | [API versioning](https://shopify.dev/docs/api/usage/versioning) |
|
|
109
|
-
| `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) |
|
|
110
|
-
| `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) |
|
|
111
|
-
| `UG-ADMIN-001` | Legacy Admin GraphQL `priceRule` usage | [2026-10 release notes](https://shopify.dev/release-notes/2026-10) |
|
|
112
|
-
| `UG-ADMIN-002` | Literal GraphQL `automaticDiscounts` root field and removed `DiscountAutomaticConnection` / `DiscountAutomaticEdge` types | [Official removal](https://shopify.dev/changelog/posts/automaticdiscounts-query-is-removed-in-api-version-2027-01) |
|
|
113
|
-
| `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) |
|
|
114
|
-
| `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) |
|
|
115
|
-
| `UG-ADMIN-006` | Literal `marketCurrencySettingsUpdate` Admin mutation removed in 2027-01 | [Official removal](https://shopify.dev/changelog/posts/removing-marketcurrencysettingsupdate-mutation) |
|
|
116
|
-
| `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) |
|
|
117
|
-
| `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) |
|
|
118
|
-
| `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) |
|
|
119
|
-
| `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) |
|
|
120
|
-
|
|
121
|
-
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.
|
|
122
|
-
|
|
123
|
-
See the [2027-01 migration guide](docs/2027-01-migration.md) for the extension `owner_type` requirement, target-version behavior, evidence, and limits. The rule is in the Unreleased change set; existing npm packages and Action tags do not gain it until a release containing this branch is published.
|
|
124
|
-
|
|
125
|
-
## CLI
|
|
59
|
+
## Example output
|
|
126
60
|
|
|
127
61
|
```text
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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
|
|
133
75
|
```
|
|
134
76
|
|
|
135
|
-
|
|
77
|
+
The example is shortened from a scan of a synthetic GraphQL document.
|
|
136
78
|
|
|
137
|
-
|
|
138
|
-
# Human-readable scan
|
|
139
|
-
npx shopify-upgrade-guard scan --target 2026-10
|
|
79
|
+
## Supported capabilities and evidence
|
|
140
80
|
|
|
141
|
-
|
|
142
|
-
npx shopify-upgrade-guard scan --target 2026-10 --format json
|
|
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.
|
|
143
82
|
|
|
144
|
-
|
|
145
|
-
npx shopify-upgrade-guard scan --target 2026-10 --format sarif
|
|
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).
|
|
146
84
|
|
|
147
|
-
|
|
148
|
-
npx shopify-upgrade-guard scan --target 2026-10 --fail-on warning --fail-on-new --base-ref origin/main
|
|
149
|
-
```
|
|
85
|
+
## Limitations and privacy
|
|
150
86
|
|
|
151
|
-
|
|
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.
|
|
152
88
|
|
|
153
|
-
##
|
|
89
|
+
## Documentation
|
|
154
90
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
```
|
|
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)
|
|
161
96
|
|
|
162
|
-
|
|
97
|
+
## Related RexCode OSS tools
|
|
163
98
|
|
|
164
|
-
|
|
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.
|
|
165
102
|
|
|
166
|
-
|
|
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.
|
|
167
104
|
|
|
168
|
-
|
|
105
|
+
## Contributing and support
|
|
169
106
|
|
|
170
|
-
|
|
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).
|
|
171
108
|
|
|
172
|
-
|
|
109
|
+
## Security
|
|
173
110
|
|
|
174
|
-
|
|
175
|
-
{
|
|
176
|
-
"targetVersion": "2026-10",
|
|
177
|
-
"failOn": "warning",
|
|
178
|
-
"exclude": ["fixtures/**"]
|
|
179
|
-
}
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
`exclude` accepts repository-relative glob patterns. Absolute paths and traversal are rejected.
|
|
183
|
-
|
|
184
|
-
See [examples](examples/) for copy-paste CI and configuration examples.
|
|
185
|
-
|
|
186
|
-
## Security and privacy
|
|
187
|
-
|
|
188
|
-
Upgrade Guard treats scanned repositories as untrusted input.
|
|
189
|
-
|
|
190
|
-
Ordinary scans:
|
|
191
|
-
|
|
192
|
-
- do not execute repository code
|
|
193
|
-
- do not contact Shopify
|
|
194
|
-
- do not require Shopify credentials
|
|
195
|
-
- do not upload source
|
|
196
|
-
- skip generated/vendor directories by default
|
|
197
|
-
- use bounded file discovery
|
|
198
|
-
|
|
199
|
-
See [SECURITY.md](SECURITY.md) and the [threat model](docs/threat-model.md).
|
|
200
|
-
|
|
201
|
-
## Related Shopify developer tools
|
|
202
|
-
|
|
203
|
-
Building or maintaining Shopify apps?
|
|
204
|
-
|
|
205
|
-
- **[ChangeGuard](https://github.com/RexCode-Digital/shopify-app-changeguard)** — Review meaningful `shopify.app*.toml` configuration changes before they reach production.
|
|
206
|
-
- **[Shopify Scope Guard](https://github.com/RexCode-Digital/shopify-scope-guard)** — Audit whether declared Shopify permissions are supported by offline code evidence.
|
|
207
|
-
- **[Shopify App Review Guard](https://github.com/RexCode-Digital/shopify-app-review-guard)** — Run deterministic preflight checks for Shopify App Store and production readiness.
|
|
208
|
-
|
|
209
|
-
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.
|
|
210
|
-
|
|
211
|
-
GitHub Marketplace: [Shopify Upgrade Guard](https://github.com/marketplace/actions/shopify-upgrade-guard)
|
|
212
|
-
|
|
213
|
-
All four tools run offline and require no Shopify credentials.
|
|
214
|
-
|
|
215
|
-
## Contributing
|
|
216
|
-
|
|
217
|
-
Contributions are welcome, especially new evidence-backed Shopify migration rules and scanner hardening.
|
|
218
|
-
|
|
219
|
-
A Shopify-specific rule should include:
|
|
220
|
-
|
|
221
|
-
1. an official `shopify.dev` evidence URL
|
|
222
|
-
2. the affected version or status
|
|
223
|
-
3. bounded deterministic detection
|
|
224
|
-
4. migration guidance
|
|
225
|
-
5. positive and false-positive tests
|
|
226
|
-
|
|
227
|
-
Start with [the contribution guide](CONTRIBUTING.md) or browse the [open issues](https://github.com/RexCode-Digital/shopify-upgrade-guard/issues).
|
|
228
|
-
|
|
229
|
-
## Roadmap
|
|
230
|
-
|
|
231
|
-
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).
|
|
232
|
-
|
|
233
|
-
See [ROADMAP.md](ROADMAP.md).
|
|
234
|
-
|
|
235
|
-
## License
|
|
236
|
-
|
|
237
|
-
MIT — see [LICENSE](LICENSE).
|
|
238
|
-
|
|
239
|
-
## Immutable SHA usage
|
|
240
|
-
|
|
241
|
-
The Action example pins the reviewed v0.2.6 release commit. Verify the release reference with:
|
|
242
|
-
|
|
243
|
-
```bash
|
|
244
|
-
git fetch --tags origin && git rev-parse 'v0.2.6^{commit}'
|
|
245
|
-
```
|
|
111
|
+
Use [SECURITY.md](SECURITY.md) for private vulnerability reporting. Do not post credentials, merchant data or private source in public issues.
|
|
246
112
|
|
|
247
|
-
|
|
113
|
+
## Licence and affiliation
|
|
248
114
|
|
|
249
|
-
|
|
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.
|