shopify-upgrade-guard 0.2.1 → 0.2.3

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.
Files changed (18) hide show
  1. package/README.md +183 -45
  2. package/action.yml +3 -0
  3. package/data/versions.json +55 -9
  4. package/dist/index.js +1 -1
  5. package/package.json +12 -5
  6. package/src/action.js +6 -4
  7. package/src/baseline.js +5 -3
  8. package/src/cli.js +12 -4
  9. package/src/discovery.js +11 -9
  10. package/src/git.js +2 -2
  11. package/src/graphql.js +52 -0
  12. package/src/output.js +3 -2
  13. package/src/rules.js +14 -4
  14. package/src/safe-file.js +16 -0
  15. package/src/scan.js +15 -11
  16. package/src/version-data.js +61 -0
  17. package/src/version.js +2 -0
  18. package/src/versions.js +1 -1
package/README.md CHANGED
@@ -1,56 +1,155 @@
1
1
  # Shopify Upgrade Guard
2
2
 
3
- Shopify Upgrade Guard detects documented Shopify platform/API upgrade risks in your repository before they become production migrations.
3
+ **Catch documented Shopify API and platform upgrade risks before they become production migrations.**
4
+
5
+ [![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
+ [![CI](https://github.com/efegokdemir/shopify-upgrade-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/efegokdemir/shopify-upgrade-guard/actions/workflows/ci.yml)
8
+ [![CodeQL](https://github.com/efegokdemir/shopify-upgrade-guard/actions/workflows/codeql.yml/badge.svg)](https://github.com/efegokdemir/shopify-upgrade-guard/actions/workflows/codeql.yml)
9
+ [![license](https://img.shields.io/github/license/efegokdemir/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.**
4
14
 
5
15
  > Unofficial open-source developer tooling. Not affiliated with, endorsed by, or certified by Shopify.
6
16
 
7
- This repository contains the `0.2.1` hotfix release. It is an offline, evidence-backed scanner for Shopify platform and API upgrade risks.
17
+ Part of the **RexCode Shopify developer tools** suite. Requires Node.js 20 or later for the CLI. [Releases](https://github.com/efegokdemir/shopify-upgrade-guard/releases) · [npm](https://www.npmjs.com/package/shopify-upgrade-guard) · [Marketplace](https://github.com/marketplace/actions/shopify-upgrade-guard)
18
+
19
+ ## Quick start
20
+
21
+ Run it without installing anything globally:
22
+
23
+ ```bash
24
+ npx shopify-upgrade-guard scan --target 2026-10
25
+ ```
8
26
 
9
- ## Try it locally
27
+ Or install it in a project:
10
28
 
11
29
  ```bash
12
- git clone https://github.com/efegokdemir/shopify-upgrade-guard.git
13
- cd shopify-upgrade-guard
14
- npm ci
15
- npm run build:action
16
- node src/cli.js scan --path /path/to/shopify-app --target 2026-10
30
+ npm install --save-dev shopify-upgrade-guard
31
+ npx shopify-upgrade-guard scan --target 2026-10
17
32
  ```
18
33
 
19
- The scan is offline, read-only, deterministic, and uses bundled Shopify release evidence. `--target` changes rule evaluation: target-only risks are reported as upgrade blockers, while existing debt is reported separately.
34
+ 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.
35
+
36
+ ## Why Upgrade Guard?
37
+
38
+ - **Target-aware** — evaluate findings against the Shopify version you actually plan to adopt.
39
+ - **Evidence-backed** — Shopify-specific rules link to official Shopify documentation or changelog evidence.
40
+ - **PR-aware** — distinguish newly introduced findings from pre-existing debt.
41
+ - **Baseline-friendly** — adopt the tool without forcing a big-bang cleanup of historical findings.
42
+ - **CI-ready** — human, JSON, and SARIF output plus a GitHub Action.
43
+ - **Offline by default** — ordinary scans require no network access, Shopify token, or store access.
44
+ - **Deterministic** — designed for repeatable CI results and reviewable rule behaviour.
20
45
 
21
46
  ## GitHub Action
22
47
 
23
- Pin the Action to a reviewed commit SHA in production:
48
+ A minimal pull-request gate:
24
49
 
25
50
  ```yaml
51
+ name: Shopify Upgrade Guard
52
+
53
+ on:
54
+ pull_request:
55
+
26
56
  permissions:
27
57
  contents: read
28
58
 
29
- steps:
30
- - uses: actions/checkout@<immutable-sha>
31
- - uses: efegokdemir/shopify-upgrade-guard@<immutable-sha>
32
- with:
33
- target: 2026-10
34
- fail-on: warning
59
+ jobs:
60
+ upgrade-guard:
61
+ runs-on: ubuntu-latest
62
+ steps:
63
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
64
+ with:
65
+ fetch-depth: 0
66
+ persist-credentials: false
67
+
68
+ - uses: efegokdemir/shopify-upgrade-guard@v0.2.3 # current patch release; resolve to a SHA below
69
+ with:
70
+ target: 2026-10
71
+ fail-on: warning
72
+ fail-on-new: 'true'
35
73
  ```
36
74
 
37
- Inputs: `target`, `fail-on` (`never`, `error`, `warning`, or `info`), `fail-on-new`, and `path`.
75
+ For convenience, workflows may use the movable minor release alias `efegokdemir/shopify-upgrade-guard@v0.2`. For high-assurance production workflows, resolve the current patch release to a reviewed full commit SHA; minor aliases are not immutable.
76
+
77
+ ### Action inputs
78
+
79
+ | Input | Purpose |
80
+ | --- | --- |
81
+ | `target` | Shopify target version, for example `2026-10` |
82
+ | `fail-on` | Policy threshold: `never`, `error`, `warning`, or `info` |
83
+ | `fail-on-new` | Apply the failure threshold only to findings introduced by the PR |
84
+ | `path` | Repository path to scan |
85
+
86
+ ### Action outputs
38
87
 
39
- Outputs: `outcome`, `finding-count`, `new-finding-count`, `error-count`, `current-versions` (the structured inventory), and `result-json`.
88
+ `outcome`, `finding-count`, `new-finding-count`, `error-count`, `current-versions`, and `result-json`.
40
89
 
41
- The Action uses the current GitHub `node24` JavaScript Action runtime. Consumers do not install dependencies.
90
+ The Action is bundled and runs on the current GitHub `node24` JavaScript Action runtime.
91
+
92
+ ## What it catches today
93
+
94
+ The rule pack is intentionally focused. Existing lexical checks report review signals; the `automaticDiscounts` removal check parses literal GraphQL root selections.
95
+
96
+ | Rule | Detects | Evidence |
97
+ | --- | --- | --- |
98
+ | `UG-CHECKOUT-001` | `useBuyerJourneyIntercept` / `buyerJourney.intercept` | [Shopify changelog](https://shopify.dev/changelog/deprecating-the-usebuyerjourneyintercept-api-on-checkout-ui-extensions) |
99
+ | `UG-CHECKOUT-002` | Checkout `block_progress` capability | [Shopify changelog](https://shopify.dev/changelog/deprecating-the-usebuyerjourneyintercept-api-on-checkout-ui-extensions) |
100
+ | `UG-REST-001` | Legacy Admin REST usage | [REST Admin API](https://shopify.dev/docs/api/admin-rest) |
101
+ | `UG-VERSION-001` | Unsupported or target-retiring API versions | [API versioning](https://shopify.dev/docs/api/usage/versioning) |
102
+ | `UG-VERSION-002` | Supported versions older than the latest stable version | [API versioning](https://shopify.dev/docs/api/usage/versioning) |
103
+ | `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) |
104
+ | `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) |
105
+ | `UG-ADMIN-001` | Legacy Admin GraphQL `priceRule` usage | [2026-10 release notes](https://shopify.dev/release-notes/2026-10) |
106
+ | `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) |
107
+ | `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) |
108
+
109
+ 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.
42
110
 
43
111
  ## CLI
44
112
 
45
113
  ```text
46
- node src/cli.js scan [--target YYYY-MM] [--format human|json|sarif] [--fail-on ...] [--fail-on-new]
47
- node src/cli.js baseline create|check [--path DIR]
48
- node src/cli.js rules
49
- node src/cli.js versions
50
- node src/cli.js explain UG-CHECKOUT-001
114
+ shopify-upgrade-guard scan [--target YYYY-MM] [--format human|json|sarif] [--fail-on ...] [--fail-on-new]
115
+ shopify-upgrade-guard baseline create|check [--path DIR]
116
+ shopify-upgrade-guard rules
117
+ shopify-upgrade-guard versions
118
+ shopify-upgrade-guard explain UG-CHECKOUT-001
119
+ ```
120
+
121
+ Examples:
122
+
123
+ ```bash
124
+ # Human-readable scan
125
+ npx shopify-upgrade-guard scan --target 2026-10
126
+
127
+ # CI-friendly JSON
128
+ npx shopify-upgrade-guard scan --target 2026-10 --format json
129
+
130
+ # SARIF for code-scanning workflows
131
+ npx shopify-upgrade-guard scan --target 2026-10 --format sarif
132
+
133
+ # Fail only when the PR introduces new warning-or-higher findings
134
+ npx shopify-upgrade-guard scan --target 2026-10 --fail-on warning --fail-on-new --base-ref origin/main
135
+ ```
136
+
137
+ 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.
138
+
139
+ ## Adopt it gradually with a baseline
140
+
141
+ Existing migration debt should not prevent a team from adopting Upgrade Guard.
142
+
143
+ ```bash
144
+ npx shopify-upgrade-guard baseline create
145
+ npx shopify-upgrade-guard baseline check
51
146
  ```
52
147
 
53
- Exit codes: `0` means the scan completed and the policy passed; `1` means active findings exceeded the policy; `2` means the scanner could not complete.
148
+ Baselined findings remain reviewable while new fingerprints stay actionable.
149
+
150
+ `--fail-on-new` requires a valid Git base comparison. Fetch full history and provide `--base-ref`, or use the pull-request Action. Missing refs/history exit 2 instead of passing an incomplete comparison.
151
+
152
+ The bundled snapshot, verified 4 October 2026, lists `2026-10` as latest stable and `2027-01` as release candidate. The RC is for testing. Shopify lists `2025-10` as unsupported while its accessibility table runs until 16 October 2026; support status and accessibility are distinct. Future version names do not imply verified rule coverage.
54
153
 
55
154
  ## Configuration
56
155
 
@@ -64,30 +163,69 @@ Commit `.upgradeguard.json` to set repository defaults:
64
163
  }
65
164
  ```
66
165
 
67
- `exclude` accepts repository-relative glob patterns. Absolute paths and traversal are rejected. `baseline` writes `.upgradeguard-baseline.json`; baselined findings remain visible in JSON but do not fail policy, and new fingerprints remain actionable.
166
+ `exclude` accepts repository-relative glob patterns. Absolute paths and traversal are rejected.
68
167
 
69
- ## Rules and evidence
168
+ See [examples](examples/) for copy-paste CI and configuration examples.
70
169
 
71
- The initial pack is deliberately small and high-precision. Every finding includes an official source, affected version metadata where applicable, location, confidence, and migration guidance.
170
+ ## Security and privacy
72
171
 
73
- | ID | Detection | Official evidence |
74
- | --- | --- | --- |
75
- | UG-CHECKOUT-001 | `useBuyerJourneyIntercept` / `buyerJourney.intercept` in JS/TS | [Shopify changelog](https://shopify.dev/changelog/deprecating-the-usebuyerjourneyintercept-api-on-checkout-ui-extensions) |
76
- | UG-CHECKOUT-002 | `block_progress` in an extension TOML | [Shopify changelog](https://shopify.dev/changelog/deprecating-the-usebuyerjourneyintercept-api-on-checkout-ui-extensions) |
77
- | UG-REST-001 | Versioned REST Admin URL or explicit REST client marker | [REST Admin API](https://shopify.dev/docs/api/admin-rest) |
78
- | UG-VERSION-001 | Unsupported or target-retiring version in the inventory | [API versioning](https://shopify.dev/docs/api/usage/versioning) |
79
- | UG-VERSION-002 | Supported version older than latest stable | [API versioning](https://shopify.dev/docs/api/usage/versioning) |
80
- | UG-CUSTOMER-001 | Customer Account checkout fields/types removed in 2026-10 | [Shopify changelog](https://shopify.dev/changelog/customer-account-api-last-incomplete-checkout-and-checkout-types-removed) |
81
- | UG-POS-001 | Removed POS `session.currentSession.staffMemberId` | [Shopify changelog](https://shopify.dev/changelog/removed-session-currentsession-staffmemberid-from-pos-ui-extensions-2026-10) |
82
- | UG-ADMIN-001 | Legacy Admin GraphQL `priceRule` usage | [2026-10 release notes](https://shopify.dev/release-notes/2026-10) |
83
- | UG-SCRIPT-001 | Script Tag create/update usage | [Script Tag deprecation](https://shopify.dev/changelog/online-store-script-tags-deprecation) |
84
-
85
- Supported inventory surfaces currently include Admin REST, Admin GraphQL, Checkout UI extensions, Customer Account UI extensions, POS UI extensions, Functions, Shopify app TOML, and recognized Shopify client configuration.
172
+ Upgrade Guard treats scanned repositories as untrusted input.
86
173
 
87
- ## Security and privacy
174
+ Ordinary scans:
175
+
176
+ - do not execute repository code
177
+ - do not contact Shopify
178
+ - do not require Shopify credentials
179
+ - do not upload source
180
+ - skip generated/vendor directories by default
181
+ - use bounded file discovery
182
+
183
+ See [SECURITY.md](SECURITY.md) and the [threat model](docs/threat-model.md).
184
+
185
+ ## Related Shopify developer tools
186
+
187
+ Building or maintaining Shopify apps?
188
+
189
+ - **[ChangeGuard](https://github.com/efegokdemir/shopify-app-changeguard)** — Review meaningful `shopify.app*.toml` configuration changes before they reach production.
190
+ - **[Shopify Scope Guard](https://github.com/efegokdemir/shopify-scope-guard)** — Audit whether declared Shopify permissions are supported by offline code evidence.
191
+ - **[Shopify App Review Guard](https://github.com/efegokdemir/shopify-app-review-guard)** — Run deterministic preflight checks for Shopify App Store and production readiness.
192
+
193
+ GitHub Marketplace: [Shopify Upgrade Guard](https://github.com/marketplace/actions/shopify-upgrade-guard)
194
+
195
+ All four tools run offline and require no Shopify credentials.
88
196
 
89
- No telemetry, Shopify credentials, store access, or network access is required for ordinary scans. The tool reads bounded repository files, skips generated/vendor directories, does not execute repository code, and does not upload source. See [the threat model](docs/threat-model.md).
197
+ ## Contributing
198
+
199
+ Contributions are welcome, especially new evidence-backed Shopify migration rules and scanner hardening.
200
+
201
+ A Shopify-specific rule should include:
202
+
203
+ 1. an official `shopify.dev` evidence URL
204
+ 2. the affected version or status
205
+ 3. bounded deterministic detection
206
+ 4. migration guidance
207
+ 5. positive and false-positive tests
208
+
209
+ Start with [the contribution guide](CONTRIBUTING.md) or browse the [open issues](https://github.com/efegokdemir/shopify-upgrade-guard/issues).
210
+
211
+ ## Roadmap
212
+
213
+ Current priorities include additional verified Shopify breaking-change coverage, better PR base-tree classification, high-confidence Functions/Customer Account/POS/GraphQL rules, and maintainable GraphQL deprecation evidence.
214
+
215
+ See [ROADMAP.md](ROADMAP.md).
216
+
217
+ ## License
218
+
219
+ MIT — see [LICENSE](LICENSE).
220
+
221
+ ## Immutable SHA usage
222
+
223
+ Resolve the release commit, review it, and replace `@v0.2.3` in the Action example with that full SHA:
224
+
225
+ ```bash
226
+ gh api repos/efegokdemir/shopify-upgrade-guard/git/ref/tags/v0.2.3 --jq .object.sha
227
+ ```
90
228
 
91
- ## Roadmap and limitations
229
+ Published patch tags are retained; existing minor aliases are movable. A reviewed full commit SHA is the immutable execution reference.
92
230
 
93
- GraphQL schema-wide deprecation validation and exact base-tree resolved-finding reconstruction require additional maintained evidence and are not claimed as implemented. See [ROADMAP.md](ROADMAP.md).
231
+ 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.
package/action.yml CHANGED
@@ -16,6 +16,9 @@ inputs:
16
16
  description: Apply fail-on only to findings introduced by the pull request
17
17
  required: false
18
18
  default: 'false'
19
+ base-ref:
20
+ description: Git base reference for new-only comparison; defaults to origin/PR-base on pull requests
21
+ required: false
19
22
  path:
20
23
  description: Repository path to scan
21
24
  required: false
package/data/versions.json CHANGED
@@ -1,14 +1,60 @@
1
1
  {
2
- "verifiedAt": "2026-09-30",
2
+ "verifiedAt": "2026-10-04",
3
3
  "source": "https://shopify.dev/docs/api/usage/versioning",
4
4
  "versions": [
5
- { "version": "2025-01", "releaseDate": "2025-01-01", "accessibleUntil": "2026-01-16T15:00:00Z", "status": "unsupported" },
6
- { "version": "2025-04", "releaseDate": "2025-04-01", "accessibleUntil": "2026-04-16T15:00:00Z", "status": "unsupported" },
7
- { "version": "2025-07", "releaseDate": "2025-07-01", "accessibleUntil": "2026-07-16T15:00:00Z", "status": "unsupported" },
8
- { "version": "2025-10", "releaseDate": "2025-10-01", "accessibleUntil": "2026-10-16T15:00:00Z", "status": "stable" },
9
- { "version": "2026-01", "releaseDate": "2026-01-01", "accessibleUntil": "2027-01-16T15:00:00Z", "status": "stable" },
10
- { "version": "2026-04", "releaseDate": "2026-04-01", "accessibleUntil": "2027-04-16T15:00:00Z", "status": "stable" },
11
- { "version": "2026-07", "releaseDate": "2026-07-01", "accessibleUntil": "2027-07-16T15:00:00Z", "status": "latest-stable" },
12
- { "version": "2026-10", "releaseDate": "2026-10-01", "accessibleUntil": "2027-10-16T15:00:00Z", "status": "release-candidate" }
5
+ {
6
+ "version": "2025-01",
7
+ "releaseDate": "2025-01-01",
8
+ "accessibleUntil": "2026-01-16T15:00:00Z",
9
+ "status": "unsupported"
10
+ },
11
+ {
12
+ "version": "2025-04",
13
+ "releaseDate": "2025-04-01",
14
+ "accessibleUntil": "2026-04-16T15:00:00Z",
15
+ "status": "unsupported"
16
+ },
17
+ {
18
+ "version": "2025-07",
19
+ "releaseDate": "2025-07-01",
20
+ "accessibleUntil": "2026-07-16T15:00:00Z",
21
+ "status": "unsupported"
22
+ },
23
+ {
24
+ "version": "2025-10",
25
+ "releaseDate": "2025-10-01",
26
+ "accessibleUntil": "2026-10-16T15:00:00Z",
27
+ "status": "unsupported"
28
+ },
29
+ {
30
+ "version": "2026-01",
31
+ "releaseDate": "2026-01-01",
32
+ "accessibleUntil": "2027-01-16T15:00:00Z",
33
+ "status": "stable"
34
+ },
35
+ {
36
+ "version": "2026-04",
37
+ "releaseDate": "2026-04-01",
38
+ "accessibleUntil": "2027-04-16T15:00:00Z",
39
+ "status": "stable"
40
+ },
41
+ {
42
+ "version": "2026-07",
43
+ "releaseDate": "2026-07-01",
44
+ "accessibleUntil": "2027-07-16T15:00:00Z",
45
+ "status": "stable"
46
+ },
47
+ {
48
+ "version": "2026-10",
49
+ "releaseDate": "2026-10-01",
50
+ "accessibleUntil": "2027-10-16T15:00:00Z",
51
+ "status": "latest-stable"
52
+ },
53
+ {
54
+ "version": "2027-01",
55
+ "releaseDate": "2027-01-01",
56
+ "accessibleUntil": "2028-01-16T15:00:00Z",
57
+ "status": "release-candidate"
58
+ }
13
59
  ]
14
60
  }