shopify-upgrade-guard 0.2.4 → 0.2.6

package/dist/licenses.txt

@@ -0,0 +1,23 @@
+graphql
+MIT
+MIT License
+
+Copyright (c) GraphQL Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "shopify-upgrade-guard",
-  "version": "0.2.4",
-  "description": "Offline static analysis for Shopify platform and API upgrade risks.",
+  "version": "0.2.6",
+  "description": "Check documented Shopify API and platform upgrade compatibility risks with an offline CLI and GitHub Action.",
   "type": "module",
   "bin": {
     "shopify-upgrade-guard": "src/cli.js",
@@ -13,14 +13,15 @@
     "action.yml",
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
     "test": "node --test",
     "coverage": "c8 --include 'src/**' --check-coverage --lines 90 --statements 90 --functions 85 --branches 85 --reporter=text --reporter=text-summary --reporter=json-summary node --test",
     "lint": "node scripts/check-source.mjs",
-    "build:action": "ncc build src/action.js -o dist --minify",
-    "check:dist": "npm run build:action && git diff --exit-code -- dist/index.js",
+    "build:action": "ncc build src/action.js -o dist --minify --license licenses.txt",
+    "check:dist": "npm run build:action && git diff --exit-code -- dist/index.js dist/licenses.txt",
     "pack:check": "npm pack --dry-run",
     "package:smoke": "node scripts/package-smoke.mjs",
     "action:check": "node scripts/check-action.mjs",
@@ -39,18 +40,20 @@
   },
   "keywords": [
     "shopify",
+    "shopify-app",
     "shopify-api",
-    "github-actions",
-    "developer-tools",
+    "upgrade",
     "migration",
-    "deprecation"
+    "compatibility",
+    "github-actions",
+    "ci"
   ],
   "publishConfig": {
     "provenance": true
   },
   "devDependencies": {
-    "@vercel/ncc": "^0.38.3",
-    "c8": "^10.1.3"
+    "@vercel/ncc": "0.45.0",
+    "c8": "12.0.0"
   },
   "dependencies": {
     "graphql": "16.14.2"

package/src/graphql.js

@@ -50,3 +50,92 @@ export function fieldMatches(file, fields, types, guidance) {
   } catch { /* Malformed/dynamic documents cannot establish schema usage. */ }
   return matches;
 }
+
+export function productVariantBarcodeMatches(file, guidance) {
+  const documents = literalDocuments(file);
+  const matches = [];
+  for (const doc of documents) try {
+    const ast = parse(doc.text, { maxTokens: 50000 });
+    const fragments = new Map(ast.definitions.filter(d => d.kind === Kind.FRAGMENT_DEFINITION).map(d => [d.name.value, d]));
+    const add = (node) => {
+      const index = doc.offset + node.name.loc.start, before = file.text.slice(0, index);
+      matches.push({ file: file.relativePath, line: before.split('\n').length, column: index - before.lastIndexOf('\n'), snippet: node.name.value, guidance });
+    };
+    const walkVariant = (selections, stack = []) => {
+      for (const node of selections ?? []) {
+        if (node.kind === Kind.FIELD && node.name.value === 'barcode') add(node);
+        else if (node.kind === Kind.INLINE_FRAGMENT) walkVariant(node.selectionSet.selections, stack);
+        else if (node.kind === Kind.FRAGMENT_SPREAD && fragments.has(node.name.value) && !stack.includes(node.name.value)) {
+          const fragment = fragments.get(node.name.value);
+          if (fragment.typeCondition.name.value === 'ProductVariant') walkVariant(fragment.selectionSet.selections, [...stack, node.name.value]);
+        }
+      }
+    };
+    const walkRoot = (selections, stack = []) => {
+      for (const node of selections ?? []) {
+        if (node.kind === Kind.FIELD && node.name.value === 'productVariant') walkVariant(node.selectionSet?.selections);
+        else if (node.kind === Kind.FIELD && node.name.value === 'productVariants') {
+          for (const connection of node.selectionSet?.selections ?? []) {
+            if (connection.kind !== Kind.FIELD || !['nodes', 'edges'].includes(connection.name.value)) continue;
+            const variants = connection.name.value === 'nodes' ? connection.selectionSet?.selections : connection.selectionSet?.selections?.filter(edge => edge.kind === Kind.FIELD && edge.name.value === 'node').flatMap(edge => edge.selectionSet?.selections ?? []);
+            walkVariant(variants);
+          }
+        } else if (node.kind === Kind.INLINE_FRAGMENT) walkRoot(node.selectionSet.selections, stack);
+        else if (node.kind === Kind.FRAGMENT_SPREAD && fragments.has(node.name.value) && !stack.includes(node.name.value)) {
+          const fragment = fragments.get(node.name.value);
+          if (fragment.typeCondition.name.value === 'QueryRoot') walkRoot(fragment.selectionSet.selections, [...stack, node.name.value]);
+        }
+      }
+    };
+    for (const definition of ast.definitions) {
+      if (definition.kind === Kind.OPERATION_DEFINITION && definition.operation === 'query') walkRoot(definition.selectionSet.selections);
+      if (definition.kind === Kind.FRAGMENT_DEFINITION && definition.typeCondition.name.value === 'ProductVariant') walkVariant(definition.selectionSet.selections, [definition.name.value]);
+    }
+  } catch { /* Malformed or dynamic documents cannot establish a ProductVariant field use. */ }
+  return matches;
+}
+
+export function segmentQueryMatches(file, guidance) {
+  const pattern = /(?:\b[a-z][\w.]*(?:\([^)]*\))?\s*=\s*(?:true|false)\b|\b(?:12_months_ago|90_days_ago|30_days_ago|7_days_ago)\b)/gi;
+  const documents = literalDocuments(file);
+  const matches = [];
+  for (const doc of documents) try {
+    const ast = parse(doc.text, { maxTokens: 50000 });
+    visit(ast, { Field(node) {
+      if (!/^segments?(?:Create|Update|Upsert|Delete)?$/i.test(node.name.value)) return;
+      const inspect = (value) => {
+        if (!value) return;
+        if (value.kind === Kind.OBJECT) for (const field of value.fields) {
+          if (field.name.value === 'query' && field.value.kind === Kind.STRING) {
+            const legacy = [...field.value.value.matchAll(pattern)];
+            for (const match of legacy) {
+              const index = doc.offset + field.value.loc.start + match.index;
+              const before = file.text.slice(0, index);
+              matches.push({ file: file.relativePath, line: before.split('\n').length, column: index - before.lastIndexOf('\n'), snippet: match[0], guidance });
+            }
+          } else inspect(field.value);
+        }
+        else if (value.kind === Kind.LIST) value.values.forEach(inspect);
+      };
+      for (const arg of node.arguments ?? []) {
+        if (arg.name.value === 'query' && arg.value.kind === Kind.STRING) {
+          const legacy = [...arg.value.value.matchAll(pattern)];
+          for (const match of legacy) {
+            const index = doc.offset + arg.value.loc.start + match.index, before = file.text.slice(0, index);
+            matches.push({ file: file.relativePath, line: before.split('\n').length, column: index - before.lastIndexOf('\n'), snippet: match[0], guidance });
+          }
+        } else inspect(arg.value);
+      }
+    } });
+  } catch { /* Malformed or dynamic documents are not evidence. */ }
+  return matches;
+}
+
+function literalDocuments(file) {
+  if (/\.(graphql|gql)$/.test(file.relativePath)) return [{ text: file.text, offset: 0 }];
+  if (!/\.(?:[jt]sx?)$/.test(file.relativePath)) return [];
+  return [...file.text.matchAll(/([`"'])([\s\S]*?)\1/g)].flatMap(match => {
+    const text = match[2];
+    return !text.includes('${') && /(?:\bquery\b|\bmutation\b|#graphql|^\s*\{)/.test(text) ? [{ text, offset: match.index + 1 }] : [];
+  });
+}

package/src/rules.js

@@ -1,6 +1,6 @@
 import { isAtOrAfter, statusFor, latestStable, becomesUnsupportedBefore } from './versions.js';
 
-import { rootFieldMatches, fieldMatches } from './graphql.js';
+import { rootFieldMatches, fieldMatches, productVariantBarcodeMatches, segmentQueryMatches } from './graphql.js';
 
 const checkoutDeprecation = '2026-07';
 const removalVersion = '2026-10';
@@ -56,6 +56,34 @@ export const rules = [
     detect(file) { return rootFieldMatches(file, 'automaticDiscounts', 'Use discountNodes(first: ..., query: "method:automatic") and move discount fragments under DiscountNode.discount.'); },
     evaluate(match, context) { return removalAware(match, this, context); }
   },
+  {
+    id: 'UG-ADMIN-003', surface: 'admin_graphql_api', severity: 'error', title: 'Integer metafield collection condition is removed', removedIn: '2027-01', confidence: 'high',
+    documentationUrl: 'https://shopify.dev/changelog/posts/metafieldinteger-collection-condition-removed-in-api-version-2027-01', migrationUrl: 'https://shopify.dev/docs/api/admin-graphql/2027-01/input-objects/CollectionSourceInclusionConditionInput',
+    description: 'Admin GraphQL collection condition fields and types named metafieldInteger are removed in API version 2027-01. Migrate to metafieldInt and send integer condition values as strings.',
+    detect(file) { if (!sourceExtensions.test(file.relativePath)) return []; return fieldMatches(file, ['metafieldInteger'], ['CollectionSourceInclusionConditionMetafieldInteger', 'CollectionSourceInclusionConditionMetafieldIntegerRelation'], 'Replace metafieldInteger with metafieldInt and serialize the integer condition value as a string.'); },
+    evaluate(match, context) { return removalAware(match, this, context); }
+  },
+  {
+    id: 'UG-ADMIN-004', surface: 'admin_graphql_api', severity: 'warning', title: 'ProductVariant.barcode is deprecated', deprecatedIn: '2026-10', confidence: 'high',
+    documentationUrl: 'https://shopify.dev/changelog/posts/product-variant-barcode-is-being-replaced-by-barcodes', migrationUrl: 'https://shopify.dev/docs/api/admin-graphql/2026-10/objects/ProductVariant',
+    description: 'ProductVariant.barcode is deprecated from API version 2026-10 and returns only the first entry after a variant has multiple barcodes. Migrate reads to the barcodes connection when every identifier matters; Shopify has not announced a removal date.',
+    detect(file) { if (!sourceExtensions.test(file.relativePath)) return []; return productVariantBarcodeMatches(file, 'Review this ProductVariant.barcode read. Use the barcodes connection if the integration must handle every barcode.'); },
+    evaluate(match, context) { return deprecationAware(match, this, context); }
+  },
+  {
+    id: 'UG-SEGMENT-001', surface: 'admin_graphql_api', severity: 'warning', title: 'Legacy segment query syntax is deprecated', deprecatedIn: '2026-10', confidence: 'high',
+    documentationUrl: 'https://shopify.dev/changelog/posts/updated-function-syntax-on-the-segment-query-language', migrationUrl: 'https://shopify.dev/docs/apps/build/shopifyql/segment-query-language-reference',
+    description: 'In API version 2026-10, segment functions use MATCHES or NOT MATCHES instead of = true or = false; named date tokens 12_months_ago, 90_days_ago, 30_days_ago, and 7_days_ago are deprecated. Migrate to the documented operators and date offsets.',
+    detect(file) { if (!sourceExtensions.test(file.relativePath)) return []; return segmentQueryMatches(file, 'Update this literal Shopify segment query to MATCHES/NOT MATCHES and replace deprecated named dates with supported date offsets.'); },
+    evaluate(match, context) { return deprecationAware(match, this, context); }
+  },
+  {
+    id: 'UG-ADMIN-005', surface: 'admin_graphql_api', severity: 'error', title: 'ITEM_NOT_STOCKED_AT_LOCATION handling is obsolete', removedIn: '2026-10', confidence: 'high',
+    documentationUrl: 'https://shopify.dev/changelog/posts/removal-of-itemnotstockedatlocation-error', migrationUrl: 'https://shopify.dev/changelog/posts/removal-of-itemnotstockedatlocation-error',
+    description: 'Shopify removed ITEM_NOT_STOCKED_AT_LOCATION from the relevant inventory mutation error codes in API version 2026-10. Remove logic that depends on this specific error; inventory quantities can now be adjusted at any location.',
+    detect(file) { if (!sourceExtensions.test(file.relativePath)) return []; return matches(maskComments(file.text), /(?:(?:===|!==|==|!=)\s*(['"])ITEM_NOT_STOCKED_AT_LOCATION\1|\bcase\s+(['"]?)ITEM_NOT_STOCKED_AT_LOCATION\2|\b[A-Z][A-Za-z0-9_]*\.ITEM_NOT_STOCKED_AT_LOCATION\b)/g, 'Remove handling for ITEM_NOT_STOCKED_AT_LOCATION; Shopify no longer emits this error code from API version 2026-10.'); },
+    evaluate(match, context) { return removalAware(match, this, context); }
+  },
   {
     id: 'UG-REST-001', surface: 'admin_rest_api', severity: 'warning', title: 'REST Admin API usage is legacy', confidence: 'high',
     documentationUrl: 'https://shopify.dev/docs/api/admin-rest', migrationUrl: 'https://shopify.dev/docs/api/admin-graphql',
@@ -89,6 +117,10 @@ function removalAware(match, rule, context) {
   if (!isAtOrAfter(context.targetVersion, rule.removedIn ?? rule.deprecatedIn)) return null;
   return { ...match, classification: 'target', reason: `This usage is affected by target ${context.targetVersion}. ${rule.description}` };
 }
+function deprecationAware(match, rule, context) {
+  if (!isAtOrAfter(context.targetVersion, rule.deprecatedIn)) return null;
+  return { ...match, classification: 'target', reason: `This usage is deprecated for target ${context.targetVersion}. ${rule.description}` };
+}
 function matches(text, pattern, guidance) { return [...text.matchAll(pattern)].map((match) => { const before = text.slice(0, match.index); return { file: null, line: before.split('\n').length, column: match.index - before.lastIndexOf('\n'), snippet: match[0], guidance }; }); }
 export function attachFile(matchesForFile, file) { return matchesForFile.map((match) => ({ ...match, file: file.relativePath })); }
 function maskCommentsAndStrings(text) { return text.replace(/\/\/[^\n]*|\/\*[\s\S]*?\*\/|(['"`])(?:\\.|(?!\1)[^\\])*\1/g, (value) => value.replace(/[^\n]/g, ' ')); }

package/src/version.js

@@ -1,2 +1,2 @@
 // Generated from package.json.
-export const TOOL_VERSION = "0.2.4";
+export const TOOL_VERSION = "0.2.6";