shopify-upgrade-guard 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shopify-upgrade-guard",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Offline static analysis for Shopify platform and API upgrade risks.",
   "type": "module",
   "bin": {
@@ -17,11 +17,14 @@
   ],
   "scripts": {
     "test": "node --test",
-    "coverage": "c8 --exclude 'dist/**' --exclude 'node_modules/**' --check-coverage --lines 90 --statements 90 --functions 85 --branches 85 --reporter=text --reporter=text-summary node --test",
-    "lint": "node --check src/cli.js && node --check src/scan.js && node --check src/action.js",
+    "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",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "package:smoke": "node scripts/package-smoke.mjs",
+    "action:check": "node scripts/check-action.mjs",
+    "prebuild:action": "node scripts/write-version.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -29,10 +32,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/efegokdemir/shopify-upgrade-guard.git"
+    "url": "https://github.com/RexCode-Digital/shopify-upgrade-guard.git"
   },
   "bugs": {
-    "url": "https://github.com/efegokdemir/shopify-upgrade-guard/issues"
+    "url": "https://github.com/RexCode-Digital/shopify-upgrade-guard/issues"
   },
   "keywords": [
     "shopify",
@@ -48,5 +51,9 @@
   "devDependencies": {
     "@vercel/ncc": "^0.38.3",
     "c8": "^10.1.3"
-  }
+  },
+  "dependencies": {
+    "graphql": "16.14.2"
+  },
+  "homepage": "https://github.com/RexCode-Digital/shopify-upgrade-guard#readme"
 }

package/src/action.js

@@ -1,14 +1,16 @@
 import * as fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import process from 'node:process';
 import { scan } from './scan.js';
 import { formatHuman, shouldFail } from './output.js';
 const input = (name) => process.env[`INPUT_${name.toUpperCase().replaceAll('-', '_')}`] || '';
-const setOutput = (name, value) => { const delimiter = `ghadelimiter_${Date.now()}`; fs.appendFileSync(process.env.GITHUB_OUTPUT || '/dev/null', `${name}<<${delimiter}\n${value}\n${delimiter}\n`); };
+const setOutput = (name, value) => { const delimiter = `ghadelimiter_${randomUUID()}`; if (!process.env.GITHUB_OUTPUT) return; fs.appendFileSync(process.env.GITHUB_OUTPUT, `${name}<<${delimiter}\n${value}\n${delimiter}\n`); };
 const target = input('target') || undefined; const threshold = input('fail-on') || 'never'; const failOnNew = input('fail-on-new') === 'true'; const root = input('path') || process.env.GITHUB_WORKSPACE || process.cwd();
 try {
-  const result = await scan(root, { target, failOn: threshold, baseRef: process.env.GITHUB_BASE_REF || undefined }); const json = JSON.stringify(result); const active = result.findings.filter((finding) => !finding.baselined);
+  if (input('fail-on-new') && !['true','false'].includes(input('fail-on-new'))) throw new Error('fail-on-new must be true or false');
+  const result = await scan(root, { target, failOn: threshold, baseRef: input('base-ref') || (failOnNew && process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : undefined) }); const json = JSON.stringify(result); const active = result.findings.filter((finding) => !finding.baselined);
   setOutput('outcome', shouldFail(result, threshold, failOnNew) ? 'failure' : 'success'); setOutput('finding-count', String(active.length)); setOutput('new-finding-count', String(active.filter((item) => item.lifecycle === 'NEW').length)); setOutput('error-count', String(active.filter((item) => item.severity === 'error').length)); setOutput('current-versions', JSON.stringify(result.inventory)); setOutput('result-json', json);
   if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `## Shopify Upgrade Guard\n\n${formatHuman(result)}\n`);
-  for (const finding of active) if (finding.file && finding.line) console.error(`::warning file=${finding.file},line=${finding.line},col=${finding.column}::${finding.title}`);
+  for (const finding of active) if (finding.file && finding.line) console.error(`::warning file=${finding.file.replaceAll('%','%25').replaceAll('\r','%0D').replaceAll('\n','%0A').replaceAll(':','%3A').replaceAll(',','%2C')},line=${finding.line},col=${finding.column}::${finding.title}`);
   if (shouldFail(result, threshold, failOnNew)) { console.error(`::error::Upgrade findings exceeded --fail-on ${threshold}${failOnNew ? ' for NEW findings' : ''}`); process.exitCode = 1; }
-} catch (error) { console.error(`::error::${error.message}`); process.exitCode = 2; }
+} catch (error) { console.error(`Upgrade Guard scanner error: ${String(error.message).replace(/[\r\n]/g, ' ')}`); process.exitCode = 2; }

package/src/baseline.js

@@ -2,11 +2,13 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 
+import { safeRead, safePath } from './safe-file.js';
+
 export const BASELINE_FILE = '.upgradeguard-baseline.json';
 export function fingerprint(finding) { return createHash('sha256').update(`${finding.ruleId}|${finding.surface}|${finding.file}|${finding.snippet.replace(/\s+/g, ' ').trim()}`).digest('hex').slice(0, 16); }
 export async function loadBaseline(root, file = BASELINE_FILE) {
-  try { const parsed = JSON.parse(await readFile(join(root, file), 'utf8')); if (!Array.isArray(parsed.findings) || parsed.findings.some((item) => typeof item.fingerprint !== 'string')) throw new Error('findings must be an array of fingerprinted findings'); return { fingerprints: new Set(parsed.findings.map((item) => item.fingerprint)), entries: parsed.findings, file }; }
-  catch (error) { if (error.code === 'ENOENT') return { fingerprints: new Set(), entries: [], file }; throw new Error(`Invalid ${file}: ${error.message}`); }
+  try { const parsed = JSON.parse(await safeRead(root, file)); if (!Array.isArray(parsed.findings) || parsed.findings.some((item) => typeof item.fingerprint !== 'string')) throw new Error('findings must be an array of fingerprinted findings'); return { fingerprints: new Set(parsed.findings.map((item) => item.fingerprint)), entries: parsed.findings, file }; }
+  catch (error) { if (error.code === 'ENOENT') return { fingerprints: new Set(), entries: [], file }; throw new Error(`Invalid ${file}: ${error instanceof SyntaxError ? 'malformed JSON' : error.message}`); }
 }
-export async function writeBaseline(root, findings, file = BASELINE_FILE) { const payload = { schemaVersion: 1, generatedAt: new Date().toISOString(), findings: findings.map((finding) => ({ fingerprint: fingerprint(finding), ruleId: finding.ruleId, surface: finding.surface, file: finding.file })).sort((a, b) => a.fingerprint.localeCompare(b.fingerprint)) }; await writeFile(join(root, file), `${JSON.stringify(payload, null, 2)}\n`, 'utf8'); return payload; }
+export async function writeBaseline(root, findings, file = BASELINE_FILE) { const payload = { schemaVersion: 1, generatedAt: new Date().toISOString(), findings: findings.map((finding) => ({ fingerprint: fingerprint(finding), ruleId: finding.ruleId, surface: finding.surface, file: finding.file })).sort((a, b) => a.fingerprint.localeCompare(b.fingerprint)) }; await writeFile(await safePath(root, file, true), `${JSON.stringify(payload, null, 2)}\n`, 'utf8'); return payload; }
 export function applyBaseline(findings, baseline) { return findings.map((finding) => ({ ...finding, fingerprint: fingerprint(finding), baselined: baseline.fingerprints.has(fingerprint(finding)) })); }

package/src/cli.js

@@ -1,20 +1,28 @@
 #!/usr/bin/env node
+import { TOOL_VERSION } from './version.js';
 import { scan } from './scan.js';
 import { formatHuman, shouldFail, toSarif } from './output.js';
 import { rules } from './rules.js';
 import { versionSummary } from './versions.js';
 import { writeBaseline } from './baseline.js';
-import packageJson from '../package.json' with { type: 'json' };
 import process from 'node:process';
-const args = process.argv.slice(2); const command = args[0] ?? 'scan';
+const args = process.argv.slice(2); const command = args[0] && !args[0].startsWith('-') ? args[0] : 'scan';
 const value = (flag) => { const index = args.indexOf(flag); return index >= 0 ? args[index + 1] : undefined; };
 if (args.includes('--help') || command === 'help') { console.log('Usage: shopify-upgrade-guard <scan|baseline|rules|versions|explain> [options]\n\nscan options:\n  --target YYYY-MM   compare against a target version\n  --format human|json|sarif\n  --fail-on never|error|warning|info\n  --fail-on-new      apply threshold only to NEW findings\n  --base-ref REF     classify findings against a Git base ref\n  --exclude GLOB     ignore a repository-relative path pattern\n  --path DIR         repository to scan\n\nbaseline create|check writes or evaluates .upgradeguard-baseline.json'); process.exit(0); }
-if (args.includes('--version')) { console.log(packageJson.version); process.exit(0); }
+if (args.includes('--version')) { console.log(TOOL_VERSION); process.exit(0); }
 try {
+  const valued = ['--target','--format','--fail-on','--base-ref','--exclude','--path'];
+  for (let i = command === args[0] ? 1 : 0; i < args.length; i++) {
+    const arg = args[i];
+    if (valued.includes(arg)) { if (!args[i+1] || args[i+1].startsWith('-')) throw new Error(`Missing value for ${arg}`); i++; }
+    else if (arg.startsWith('-') && arg !== '--fail-on-new') throw new Error(`Unknown argument: ${arg}`);
+    else if (!arg.startsWith('-') && !['baseline','explain'].includes(command)) throw new Error(`Unexpected argument: ${arg}`);
+  }
+  if (value('--format') && !['human','json','sarif'].includes(value('--format'))) throw new Error('format must be human, json, or sarif');
   if (command === 'rules') { for (const rule of rules) console.log(`${rule.id}\t${rule.surface}\t${rule.severity}\t${rule.title}\n  ${rule.documentationUrl}`); process.exit(0); }
   if (command === 'versions') { for (const item of versionSummary()) console.log(`${item.version} ${item.status} — accessible until ${item.accessibleUntil}`); process.exit(0); }
   if (command === 'explain') { const rule = rules.find((item) => item.id === args[1]); if (!rule) throw new Error(`Unknown rule: ${args[1]}`); console.log(`${rule.id}: ${rule.title}\n\n${rule.description}\n\nSource: ${rule.documentationUrl}${rule.migrationUrl ? `\nMigration: ${rule.migrationUrl}` : ''}`); process.exit(0); }
-  if (command === 'baseline') { const root = value('--path') ?? process.cwd(); const result = await scan(root, { target: value('--target'), noBaseline: true }); if ((args[1] ?? 'create') === 'check') { console.log(formatHuman(result)); process.exitCode = shouldFail(result, value('--fail-on') ?? 'never', args.includes('--fail-on-new')) ? 1 : 0; } else { const payload = await writeBaseline(root, result.findings); console.log(`Wrote ${payload.findings.length} findings to .upgradeguard-baseline.json`); process.exitCode = 0; } process.exit(process.exitCode ?? 0); }
+  if (command === 'baseline') { if (!['create','check'].includes(args[1] ?? 'create')) throw new Error('baseline command must be create or check'); const root = value('--path') ?? process.cwd(); const result = await scan(root, { target: value('--target'), noBaseline: (args[1] ?? 'create') === 'create', failOn: value('--fail-on'), baseRef: value('--base-ref') }); if ((args[1] ?? 'create') === 'check') { console.log(formatHuman(result)); process.exitCode = shouldFail(result, value('--fail-on') ?? result.failOn, args.includes('--fail-on-new')) ? 1 : 0; } else { const payload = await writeBaseline(root, result.findings); console.log(`Wrote ${payload.findings.length} findings to .upgradeguard-baseline.json`); process.exitCode = 0; } process.exit(process.exitCode ?? 0); }
   if (command !== 'scan') throw new Error(`Unknown command: ${command}`);
   const root = value('--path') ?? process.cwd(); const excludes = args.flatMap((arg, index) => arg === '--exclude' ? [args[index + 1]] : []).filter(Boolean); const result = await scan(root, { target: value('--target'), failOn: value('--fail-on'), baseRef: value('--base-ref'), exclude: excludes.length ? excludes : undefined }); const format = value('--format') ?? 'human';
   console.log(format === 'json' ? JSON.stringify(result, null, 2) : format === 'sarif' ? JSON.stringify(toSarif(result), null, 2) : formatHuman(result));

package/src/discovery.js

@@ -5,26 +5,28 @@ import { parseVersion } from './versions.js';
 export const IGNORED_DIRECTORIES = new Set(['.git', 'node_modules', 'dist', 'build', 'coverage', 'vendor', '.next', '.cache']);
 const supported = new Set(['.js', '.jsx', '.ts', '.tsx', '.graphql', '.gql', '.toml', '.json']);
 export async function discover(root, options = {}) {
-  const files = []; const inventory = []; const excludes = options.exclude ?? [];
+  if (!(await lstat(root)).isDirectory()) throw new Error('Scan root must be a regular directory');
+  const files = []; const inventory = []; const skipped = []; const excludes = options.exclude ?? [];
   async function walk(directory) {
     let entries;
-    try { entries = await readdir(directory, { withFileTypes: true }); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
-    for (const entry of entries) {
+    try { entries = await readdir(directory, { withFileTypes: true }); } catch (error) { throw error; }
+    for (const entry of entries.sort((a,b) => a.name.localeCompare(b.name))) {
       if (entry.name.startsWith('.') && entry.name !== '.upgradeguard.json') continue;
       const path = join(directory, entry.name); const relativePath = relative(root, path).replaceAll('\\', '/');
       if (entry.isDirectory()) { if (!IGNORED_DIRECTORIES.has(entry.name) && !isExcluded(relativePath, excludes)) await walk(path); continue; }
-      if (entry.isSymbolicLink()) continue;
+      if (entry.isSymbolicLink()) { skipped.push({ file: relativePath, reason: 'Symbolic link' }); continue; }
+      if (!entry.isFile()) continue;
       const extension = entry.name.endsWith('.toml') ? '.toml' : extname(entry.name);
       if (!supported.has(extension) || entry.name.endsWith('.min.js') || isExcluded(relativePath, excludes)) continue;
-      const stats = await lstat(path); if (stats.size > 1024 * 1024) continue;
+      const stats = await lstat(path); if (stats.size > 1024 * 1024 || files.length >= 2000) { skipped.push({ file: relativePath, reason: 'Analysis limit' }); continue; }
       const text = await readFile(path, 'utf8'); const file = { path, relativePath, text };
       files.push(file); inventory.push(...inventoryFor(file));
     }
   }
-  await walk(root); files.sort((a, b) => a.relativePath.localeCompare(b.relativePath)); inventory.sort(compareInventory); return { files, inventory };
+  await walk(root); files.sort((a, b) => a.relativePath.localeCompare(b.relativePath)); inventory.sort(compareInventory); return { files, inventory, skipped };
 }
 function inventoryFor(file) {
-  const entries = []; const toml = file.relativePath.endsWith('.toml'); const shopifyToml = /(?:^|\/)shopify\.(?:app|extension)\.toml$/.test(file.relativePath);
+  const entries = []; const toml = file.relativePath.endsWith('.toml'); const shopifyToml = /(?:^|\/)shopify\.(?:app(?:\.[^/]+)?|extension)\.toml$/.test(file.relativePath);
   const tomlVersion = shopifyToml ? matchVersion(file.text, /(?:^|\n)\s*api_version\s*=\s*["'](\d{4}-(?:0[147]|10))["']/g) : [];
   for (const match of tomlVersion) entries.push({ surface: surfaceForToml(file.relativePath, file.text), version: match.version, file: file.relativePath, line: match.line, source: 'api_version' });
   if (!toml) {
@@ -35,7 +37,7 @@ function inventoryFor(file) {
   return [...new Map(entries.map((item) => [`${item.surface}|${item.version}|${item.file}`, item])).values()];
 }
 function matchVersion(text, pattern) { return [...text.matchAll(pattern)].map((match) => { const before = text.slice(0, match.index + match[0].indexOf(match[1])); return { version: parseVersion(match[1]), line: before.split('\n').length }; }); }
-function surfaceForToml(path, text) { const normalized = path.toLowerCase(); if (normalized.includes('checkout') || /\bblock_progress\b/.test(text)) return 'checkout_ui_extension'; if (normalized.includes('customer')) return 'customer_account_ui_extension'; if (normalized.includes('pos')) return 'pos_ui_extension'; if (normalized.includes('function')) return 'shopify_function'; return normalized.endsWith('shopify.app.toml') ? 'shopify_app' : 'extension'; }
+function surfaceForToml(path, text) { const normalized = path.toLowerCase(); if (normalized.includes('checkout') || /\bblock_progress\b/.test(text)) return 'checkout_ui_extension'; if (normalized.includes('customer')) return 'customer_account_ui_extension'; if (normalized.includes('pos')) return 'pos_ui_extension'; if (normalized.includes('function')) return 'shopify_function'; return /(?:^|\/)shopify\.app(?:\.[^/]+)?\.toml$/.test(normalized) ? 'shopify_app' : 'extension'; }
 function compareInventory(a, b) { return `${a.file}:${a.line}:${a.surface}`.localeCompare(`${b.file}:${b.line}:${b.surface}`); }
 function isExcluded(path, patterns) { return patterns.some((pattern) => globToRegExp(pattern).test(path)); }
 export function validateExcludePattern(pattern) { globToRegExp(pattern); return pattern; }

package/src/git.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
 export async function changedLines(root, baseRef) {
-  if (!baseRef || baseRef.includes('..') || !/^[A-Za-z0-9_./-]+$/.test(baseRef)) return null;
-  const output = await runGit(root, ['diff', '--no-ext-diff', '--unified=0', `${baseRef}...HEAD`, '--']);
+  if (!baseRef || baseRef.startsWith('-') || baseRef.includes('..') || !/^[A-Za-z0-9_./-]+$/.test(baseRef)) throw new Error('Invalid Git base ref');
+  const output = await runGit(root, ['-c', 'core.quotePath=false', 'diff', '--no-ext-diff', '--no-textconv', '--unified=0', `${baseRef}...HEAD`, '--']);
   const ranges = new Map(); let file = null;
   for (const line of output.split('\n')) {
     if (line.startsWith('+++ b/')) { file = line.slice(6); continue; }

package/src/graphql.js

@@ -0,0 +1,52 @@
+import { parse, Kind, visit } from 'graphql';
+// Parse only literal GraphQL documents. Dynamic templates remain unsupported.
+export function rootFieldMatches(file, name, guidance) {
+  const documents = [];
+  if (/\.(graphql|gql)$/.test(file.relativePath)) documents.push({ text: file.text, offset: 0 });
+  else for (const match of file.text.matchAll(/([`"'])([\s\S]*?)\1/g)) {
+    const text = match[2];
+    if (text.includes('${') || !/(?:\bquery\b|\bmutation\b|#graphql|^\s*\{)/.test(text)) continue;
+    documents.push({ text, offset: match.index + 1 });
+  }
+  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]));
+      let visits = 0;
+      const visitRoot = (selections, stack = []) => {
+        for (const node of selections ?? []) {
+          if (++visits > 50000) throw new Error('GraphQL expansion limit');
+          if (node.kind === Kind.FIELD && node.name.value === name) {
+            const index = doc.offset + node.name.loc.start;
+            const before = file.text.slice(0,index);
+            matches.push({ file: file.relativePath, line: before.split('\n').length, column: index - before.lastIndexOf('\n'), snippet: name, guidance });
+          } else if (node.kind === Kind.INLINE_FRAGMENT) visitRoot(node.selectionSet.selections, stack);
+          else if (node.kind === Kind.FRAGMENT_SPREAD && fragments.has(node.name.value) && !stack.includes(node.name.value)) visitRoot(fragments.get(node.name.value).selectionSet.selections,[...stack,node.name.value]);
+        }
+      };
+      for (const operation of ast.definitions.filter(d=>d.kind===Kind.OPERATION_DEFINITION && d.operation === 'query')) visitRoot(operation.selectionSet.selections);
+    } catch { /* Unsupported or malformed documents are not evidence of this removal. */ }
+  }
+  return matches;
+}
+
+// Existing field/type removals require a parseable literal document too.
+export function fieldMatches(file, fields, types, guidance) {
+  const documents = [];
+  if (/\.(graphql|gql)$/.test(file.relativePath)) documents.push({ text: file.text, offset: 0 });
+  else for (const match of file.text.matchAll(/([`"'])([\s\S]*?)\1/g)) {
+    if (!match[2].includes('${') && /(?:\bquery\b|\bmutation\b|#graphql|^\s*\{)/.test(match[2])) documents.push({ text: match[2], offset: match.index + 1 });
+  }
+  const matches = [];
+  for (const doc of documents) try {
+    const ast = parse(doc.text, { maxTokens: 50000 });
+    visit(ast, { enter(node) {
+      const name = node.kind === Kind.FIELD && fields.includes(node.name.value) ? node.name : ([Kind.INLINE_FRAGMENT, Kind.FRAGMENT_DEFINITION].includes(node.kind) && types.includes(node.typeCondition?.name.value) ? node.typeCondition.name : null);
+      if (!name) return;
+      const index = doc.offset + 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: name.value, guidance });
+    } });
+  } catch { /* Malformed/dynamic documents cannot establish schema usage. */ }
+  return matches;
+}

package/src/output.js

@@ -12,7 +12,8 @@ export function formatHuman(result) {
   return lines.join('\n');
 }
 function sectionLines(findings, fallback) { if (!findings.length) return [`No ${fallback.toLowerCase()}.`]; const lines = []; for (const finding of [...findings].sort((a, b) => order[a.severity] - order[b.severity])) lines.push(`${finding.severity.toUpperCase()}  ${finding.ruleId}`, finding.title, `  ${finding.file}:${finding.line}`, `  ${finding.reason ?? finding.currentState}`, `  Migration: ${finding.migration}`, `  Source: ${finding.source}`, ''); return lines; }
-export function shouldFail(result, threshold = 'never', newOnly = false) { if (threshold === 'never') return false; return activeFindings(result).filter((finding) => !newOnly || finding.lifecycle === 'NEW').some((finding) => threshold === 'info' || (threshold === 'warning' && finding.severity !== 'info') || (threshold === 'error' && finding.severity === 'error')); }
+export function validatePolicy(threshold) { if (!['never','error','warning','info'].includes(threshold)) throw new Error('fail-on must be never, error, warning, or info'); }
+export function shouldFail(result, threshold = 'never', newOnly = false) { validatePolicy(threshold); if (newOnly && !result.comparisonAvailable) throw new Error('fail-on-new requires an available Git base comparison; use --base-ref or a pull request checkout with full history'); if (threshold === 'never') return false; return activeFindings(result).filter((finding) => !newOnly || finding.lifecycle === 'NEW').some((finding) => threshold === 'info' || (threshold === 'warning' && finding.severity !== 'info') || (threshold === 'error' && finding.severity === 'error')); }
 export function toSarif(result) {
   const ruleMap = new Map(); for (const finding of activeFindings(result)) if (!ruleMap.has(finding.ruleId)) ruleMap.set(finding.ruleId, { id: finding.ruleId, shortDescription: { text: finding.title }, helpUri: finding.source, properties: { severity: finding.severity, confidence: finding.confidence } });
-  const rules = [...ruleMap.values()]; return { version: '2.1.0', $schema: 'https://json.schemastore.org/sarif-2.1.0.json', runs: [{ tool: { driver: { name: 'Shopify Upgrade Guard', informationUri: 'https://github.com/efegokdemir/shopify-upgrade-guard', rules } }, results: activeFindings(result).map((finding) => ({ ruleId: finding.ruleId, ruleIndex: rules.findIndex((rule) => rule.id === finding.ruleId), level: finding.severity === 'error' ? 'error' : finding.severity === 'warning' ? 'warning' : 'note', message: { text: `${finding.title}. ${finding.reason ?? finding.migration}` }, partialFingerprints: { primaryLocationLineHash: finding.fingerprint }, locations: [{ physicalLocation: { artifactLocation: { uri: finding.file.replaceAll('\\', '/') }, region: { startLine: finding.line, startColumn: finding.column } } }] })) }] }; }
+  const rules = [...ruleMap.values()]; return { version: '2.1.0', $schema: 'https://json.schemastore.org/sarif-2.1.0.json', runs: [{ tool: { driver: { name: 'Shopify Upgrade Guard', informationUri: 'https://github.com/RexCode-Digital/shopify-upgrade-guard', rules } }, results: activeFindings(result).map((finding) => ({ ruleId: finding.ruleId, ruleIndex: rules.findIndex((rule) => rule.id === finding.ruleId), level: finding.severity === 'error' ? 'error' : finding.severity === 'warning' ? 'warning' : 'note', message: { text: `${finding.title}. ${finding.reason ?? finding.migration}` }, partialFingerprints: { primaryLocationLineHash: finding.fingerprint }, locations: [{ physicalLocation: { artifactLocation: { uri: finding.file.replaceAll('\\', '/').split('/').map(encodeURIComponent).join('/') }, region: { startLine: finding.line, startColumn: finding.column } } }] })) }] }; }

package/src/rules.js

@@ -1,5 +1,7 @@
 import { isAtOrAfter, statusFor, latestStable, becomesUnsupportedBefore } from './versions.js';
 
+import { rootFieldMatches, fieldMatches } from './graphql.js';
+
 const checkoutDeprecation = '2026-07';
 const removalVersion = '2026-10';
 const sourceExtensions = /\.(?:[jt]sx?|graphql|gql)$/;
@@ -22,7 +24,7 @@ export const rules = [
     id: 'UG-CUSTOMER-001', surface: 'customer_account_api', severity: 'error', title: 'Customer Account checkout types are removed', removedIn: removalVersion, confidence: 'high',
     documentationUrl: 'https://shopify.dev/changelog/customer-account-api-last-incomplete-checkout-and-checkout-types-removed', migrationUrl: 'https://shopify.dev/changelog/customer-account-api-last-incomplete-checkout-and-checkout-types-removed',
     description: 'Customer.lastIncompleteCheckout and the Checkout type subtree are removed in API version 2026-10 with no replacement. Use Storefront cart flows or Customer.orders as appropriate.',
-    detect(file) { if (!sourceExtensions.test(file.relativePath)) return []; return matches(maskComments(file.text), /\blastIncompleteCheckout\b|\bCheckout\s*\{/g, 'Remove the Customer Account checkout field/type usage and migrate to Storefront cart flows or Customer.orders.'); },
+    detect(file) { if (!sourceExtensions.test(file.relativePath)) return []; return fieldMatches(file, ['lastIncompleteCheckout'], ['Checkout'], 'Remove the Customer Account checkout field/type usage and migrate to Storefront cart flows or Customer.orders.'); },
     evaluate(match, context) { return removalAware(match, this, context); }
   },
   {
@@ -34,16 +36,24 @@ export const rules = [
   },
   {
     id: 'UG-ADMIN-001', surface: 'admin_graphql_api', severity: 'warning', title: 'Legacy GraphQL priceRule field is removed', removedIn: removalVersion, confidence: 'medium',
-    documentationUrl: 'https://shopify.dev/release-notes/2026-10', migrationUrl: 'https://shopify.dev/release-notes/2026-10',
+    documentationUrl: 'https://shopify.dev/changelog/release-notes/2026-10', migrationUrl: 'https://shopify.dev/changelog/release-notes/2026-10',
     description: 'Legacy priceRule fields and types are removed from the Admin GraphQL API in 2026-10. Use discountTitle or discountCode where applicable.',
-    detect(file) { if (!sourceExtensions.test(file.relativePath)) return []; return matches(maskComments(file.text), /\bpriceRule\b/g, 'Replace priceRule usage with the supported discountTitle or discountCode fields.'); },
+    detect(file) { if (!sourceExtensions.test(file.relativePath)) return []; return fieldMatches(file, ['priceRule'], ['PriceRule'], 'For DraftOrderDiscountNotAppliedWarning, select discountTitle and discountCode instead; review other legacy PriceRule selections against the removed public types.'); },
     evaluate(match, context) { return removalAware(match, this, context); }
   },
   {
     id: 'UG-SCRIPT-001', surface: 'online_store_script_tags', severity: 'error', title: 'Script Tag creation and updates are deprecated', deprecatedIn: removalVersion, confidence: 'high',
     documentationUrl: 'https://shopify.dev/changelog/online-store-script-tags-deprecation', migrationUrl: 'https://shopify.dev/docs/apps/build/online-store/script-tag-deprecation',
-    description: 'ScriptTag create/update operations error from 2026-10 and storefront injection stops in 2027-03. Migrate to a theme app extension/app embed block or web pixel.',
+    description: 'ScriptTag create/update operations are restricted on all API versions from October 1, 2026 and storefront injection stops on March 1, 2027. Migrate to a theme app extension/app embed block or web pixel.',
     detect(file) { if (!sourceExtensions.test(file.relativePath)) return []; return matches(maskComments(file.text), /\b(?:scriptTagCreate|scriptTagUpdate|script_tags)\b/g, 'Migrate Script Tag injection to a theme app extension/app embed block or web pixel.'); },
+    evaluate(match) { return { ...match, classification: 'current', reason: this.description, ...(match.snippet === 'script_tags' ? { severity: 'warning', confidence: 'medium', title: 'Script Tag REST usage requires migration review', reason: 'Script Tag POST/PUT are restricted across all API versions; reads and deletes remain available. Review the HTTP method and plan storefront injection migration.' } : {}) }; }
+  },
+  {
+    id: 'UG-ADMIN-002', surface: 'admin_graphql_api', severity: 'error', title: 'automaticDiscounts query is removed', removedIn: '2027-01', confidence: 'high',
+    documentationUrl: 'https://shopify.dev/changelog/posts/automaticdiscounts-query-is-removed-in-api-version-2027-01',
+    migrationUrl: 'https://shopify.dev/docs/api/admin-graphql/2027-01/queries/discountNodes',
+    description: 'The Admin GraphQL QueryRoot.automaticDiscounts field is removed in 2027-01. Migrate to discountNodes with a method:automatic filter.',
+    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); }
   },
   {

package/src/safe-file.js

@@ -0,0 +1,16 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { resolve, relative, isAbsolute, sep, join } from 'node:path';
+export async function safePath(root, file, allowMissing = false) {
+  const absolute = resolve(root, file), rel = relative(resolve(root), absolute);
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error('Input must be a repository-relative file path');
+  let current = resolve(root);
+  for (const part of rel.split(sep)) {
+    current = join(current, part);
+    try { if ((await lstat(current)).isSymbolicLink()) throw new Error('Symbolic link inputs are not supported'); }
+    catch (error) { if (allowMissing && error.code === 'ENOENT' && current === absolute) return absolute; throw error; }
+  }
+  const stat = await lstat(absolute);
+  if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error('Input must be a regular file up to 1 MiB');
+  return absolute;
+}
+export async function safeRead(root, file) { return readFile(await safePath(root, file), 'utf8'); }

package/src/scan.js

@@ -1,33 +1,37 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readFile, lstat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
 import { discover, validateExcludePattern } from './discovery.js';
 import { rules, attachFile } from './rules.js';
 import { latestStable, parseVersion, targetRecord } from './versions.js';
 import { applyBaseline, loadBaseline } from './baseline.js';
 import { changedLines } from './git.js';
+import { safeRead } from './safe-file.js';
+import { validatePolicy } from './output.js';
 
 export async function loadConfig(root) {
-  try { const config = JSON.parse(await readFile(join(root, '.upgradeguard.json'), 'utf8')); validateConfig(config); return config; }
-  catch (error) { if (error.code === 'ENOENT') return {}; throw new Error(`Invalid .upgradeguard.json: ${error.message}`); }
+  try { const config = JSON.parse(await safeRead(root, '.upgradeguard.json')); validateConfig(config); return config; }
+  catch (error) { if (error.code === 'ENOENT') return {}; throw new Error(`Invalid .upgradeguard.json: ${error instanceof SyntaxError ? 'malformed JSON' : error.message}`); }
 }
-function validateConfig(config) { if (config.targetVersion !== undefined && !parseVersion(config.targetVersion)) throw new Error('targetVersion must be a quarterly YYYY-MM version.'); if (config.failOn !== undefined && !['never', 'error', 'warning', 'info'].includes(config.failOn)) throw new Error('failOn must be never, error, warning, or info.'); if (config.exclude !== undefined && (!Array.isArray(config.exclude) || config.exclude.some((pattern) => validateExcludePattern(pattern) === undefined))) throw new Error('exclude must be an array of repository-relative glob patterns.'); if (config.baseline !== undefined && (typeof config.baseline !== 'string' || config.baseline.startsWith('/') || config.baseline.includes('..'))) throw new Error('baseline must be a repository-relative file path.'); }
+function validateConfig(config) { if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('Configuration must be an object.'); if (config.targetVersion !== undefined && !parseVersion(config.targetVersion)) throw new Error('targetVersion must be a quarterly YYYY-MM version.'); if (config.failOn !== undefined && !['never', 'error', 'warning', 'info'].includes(config.failOn)) throw new Error('failOn must be never, error, warning, or info.'); if (config.exclude !== undefined && (!Array.isArray(config.exclude) || config.exclude.some((pattern) => validateExcludePattern(pattern) === undefined))) throw new Error('exclude must be an array of repository-relative glob patterns.'); if (config.baseline !== undefined && (typeof config.baseline !== 'string' || config.baseline.startsWith('/') || config.baseline.includes('..'))) throw new Error('baseline must be a repository-relative file path.'); }
 export async function scan(root, options = {}) {
-  const config = await loadConfig(root); const targetVersion = options.target ?? config.targetVersion ?? latestStable.version; const failOn = options.failOn ?? config.failOn ?? 'never'; targetRecord(targetVersion);
+  root = resolve(root);
+  if (!(await lstat(root)).isDirectory()) throw new Error('Scan root must be a regular directory');
+  const config = await loadConfig(root); const targetVersion = options.target ?? config.targetVersion ?? latestStable.version; const failOn = options.failOn ?? config.failOn ?? 'never'; targetRecord(targetVersion); validatePolicy(failOn);
   const exclude = options.exclude ?? config.exclude ?? []; exclude.forEach(validateExcludePattern);
-  const { files, inventory } = await discover(root, { exclude }); const context = { root, targetVersion, inventory };
+  const { files, inventory, skipped } = await discover(root, { exclude }); const context = { root, targetVersion, inventory };
   const findings = [];
   for (const file of files) for (const rule of rules) {
     const detected = rule.detect(file); const matches = detected.length ? attachFile(detected, file) : inventoryMatches(rule, inventory, file);
     for (const match of matches) { const evaluated = rule.evaluate(match, context); if (evaluated) findings.push(toFinding(rule, evaluated, targetVersion)); }
   }
   const baseline = options.noBaseline ? { fingerprints: new Set(), entries: [], file: null } : await loadBaseline(root, options.baseline ?? config.baseline); let resultFindings = applyBaseline(dedupe(findings), baseline);
-  const baseRef = options.baseRef ?? process.env.GITHUB_BASE_REF;
-  if (baseRef) { try { const ranges = await changedLines(root, baseRef); resultFindings = resultFindings.map((finding) => ({ ...finding, changeStatus: isChanged(finding, ranges) ? 'introduced' : 'pre-existing', lifecycle: isChanged(finding, ranges) ? 'NEW' : 'EXISTING' })); } catch { resultFindings = resultFindings.map((finding) => ({ ...finding, lifecycle: finding.baselined ? 'EXISTING' : 'UNCHANGED' })); } }
+  const baseRef = options.baseRef;
+  if (baseRef) { const ranges = await changedLines(root, baseRef); resultFindings = resultFindings.map(finding => ({ ...finding, changeStatus: isChanged(finding, ranges) ? 'introduced' : 'pre-existing', lifecycle: isChanged(finding, ranges) ? 'NEW' : 'EXISTING' })); }
   else resultFindings = resultFindings.map((finding) => ({ ...finding, lifecycle: finding.baselined ? 'EXISTING' : 'UNCHANGED' }));
   const active = resultFindings.filter((finding) => !finding.baselined); const currentProblems = active.filter((finding) => finding.classification === 'current'); const upgradeBlockers = active.filter((finding) => finding.classification === 'target');
-  return { schemaVersion: 1, tool: 'shopify-upgrade-guard', targetVersion, failOn, latestStable: latestStable.version, filesScanned: files.length, inventory, findings: resultFindings, currentProblems, upgradeBlockers, baselinedCount: resultFindings.filter((finding) => finding.baselined).length, resolvedBaselineCount: [...baseline.fingerprints].filter((fingerprint) => !resultFindings.some((finding) => finding.fingerprint === fingerprint)).length, baselineFile: baseline.file };
+  return { schemaVersion: 1, comparisonAvailable: Boolean(baseRef), skipped, tool: 'shopify-upgrade-guard', targetVersion, failOn, latestStable: latestStable.version, filesScanned: files.length, inventory, findings: resultFindings, currentProblems, upgradeBlockers, baselinedCount: resultFindings.filter((finding) => finding.baselined).length, resolvedBaselineCount: [...baseline.fingerprints].filter((fingerprint) => !resultFindings.some((finding) => finding.fingerprint === fingerprint)).length, baselineFile: baseline.file };
 }
 function inventoryMatches(rule, inventory, file) { if (!rule.id.startsWith('UG-VERSION')) return []; return inventory.filter((item) => item.file === file.relativePath).map((item) => ({ file: item.file, line: item.line, column: 1, snippet: `${item.source}: ${item.version}`, version: item.version, guidance: 'Update this Shopify version to a supported stable release and test the migration.' })); }
-function toFinding(rule, match, targetVersion) { return { ruleId: rule.id, severity: rule.severity, title: rule.title, surface: rule.surface, file: match.file, line: match.line, column: match.column, snippet: match.snippet, targetVersion, currentState: rule.description, migration: match.guidance, source: rule.documentationUrl, migrationUrl: rule.migrationUrl ?? null, confidence: rule.confidence, classification: match.classification, reason: match.reason, deprecatedIn: rule.deprecatedIn ?? null, removedIn: rule.removedIn ?? null }; }
+function toFinding(rule, match, targetVersion) { return { ruleId: rule.id, severity: match.severity ?? rule.severity, title: match.title ?? rule.title, surface: rule.surface, file: match.file, line: match.line, column: match.column, snippet: match.snippet, targetVersion, currentState: rule.description, migration: match.guidance, source: rule.documentationUrl, migrationUrl: rule.migrationUrl ?? null, confidence: match.confidence ?? rule.confidence, classification: match.classification, reason: match.reason, deprecatedIn: rule.deprecatedIn ?? null, removedIn: rule.removedIn ?? null }; }
 function dedupe(findings) { return [...new Map(findings.map((finding) => [`${finding.ruleId}|${finding.file}|${finding.line}|${finding.snippet}`, finding])).values()]; }
 function isChanged(finding, ranges) { return Boolean(ranges?.get(finding.file)?.some((range) => finding.line >= range.start && finding.line <= range.end)); }

package/src/version-data.js

@@ -0,0 +1,61 @@
+// Generated from data/versions.json.
+export default {
+  "verifiedAt": "2026-10-04",
+  "source": "https://shopify.dev/docs/api/usage/versioning",
+  "versions": [
+    {
+      "version": "2025-01",
+      "releaseDate": "2025-01-01",
+      "accessibleUntil": "2026-01-16T15:00:00Z",
+      "status": "unsupported"
+    },
+    {
+      "version": "2025-04",
+      "releaseDate": "2025-04-01",
+      "accessibleUntil": "2026-04-16T15:00:00Z",
+      "status": "unsupported"
+    },
+    {
+      "version": "2025-07",
+      "releaseDate": "2025-07-01",
+      "accessibleUntil": "2026-07-16T15:00:00Z",
+      "status": "unsupported"
+    },
+    {
+      "version": "2025-10",
+      "releaseDate": "2025-10-01",
+      "accessibleUntil": "2026-10-16T15:00:00Z",
+      "status": "unsupported"
+    },
+    {
+      "version": "2026-01",
+      "releaseDate": "2026-01-01",
+      "accessibleUntil": "2027-01-16T15:00:00Z",
+      "status": "stable"
+    },
+    {
+      "version": "2026-04",
+      "releaseDate": "2026-04-01",
+      "accessibleUntil": "2027-04-16T15:00:00Z",
+      "status": "stable"
+    },
+    {
+      "version": "2026-07",
+      "releaseDate": "2026-07-01",
+      "accessibleUntil": "2027-07-16T15:00:00Z",
+      "status": "stable"
+    },
+    {
+      "version": "2026-10",
+      "releaseDate": "2026-10-01",
+      "accessibleUntil": "2027-10-16T15:00:00Z",
+      "status": "latest-stable"
+    },
+    {
+      "version": "2027-01",
+      "releaseDate": "2027-01-01",
+      "accessibleUntil": "2028-01-16T15:00:00Z",
+      "status": "release-candidate"
+    }
+  ]
+};

package/src/version.js

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

package/src/versions.js

@@ -1,4 +1,4 @@
-import versionData from '../data/versions.json' with { type: 'json' };
+import versionData from './version-data.js';
 
 export const VERSION_SOURCE = versionData.source;
 export const versions = Object.freeze(versionData.versions);