@runwell/shopify-toolkit 0.4.1 → 0.5.0

package/bin/runwell-shopify

@@ -7,6 +7,7 @@ import { add } from '../lib/add.js';
 import { remove } from '../lib/remove.js';
 import { doctor } from '../lib/doctor.js';
 import { validate } from '../lib/validate.js';
+import { qa } from '../lib/qa.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -45,6 +46,9 @@ Commands:
   remove <module>                 Disable + clean a module's files
   doctor                          Detect drift between manifest and theme
   validate                        Run @shopify/dev-mcp validators on synced files
+  qa                              Code-first QA pipeline (validate-config, doctor,
+                                  template-integrity, orphan-assets, theme-check).
+                                  Run before any visual QA or "done" declaration.
   help                            Show this help
 
 Common options:
@@ -79,6 +83,9 @@ flags.toolkitRoot = TOOLKIT_ROOT;
       case 'validate':
         await validate(flags);
         break;
+      case 'qa':
+        await qa(flags);
+        break;
       case undefined:
       case 'help':
       case '--help':

package/lib/qa.js

@@ -0,0 +1,210 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { loadConfig, loadModuleManifest, resolveVariant } from './config-loader.js';
+
+/* qa: code-first QA pipeline for a Runwell-managed Shopify theme.
+
+   Runs in fixed order; each stage is non-fatal so callers see the full
+   picture before fixing. Exits 0 with a structured summary; exits 1 only
+   if the theme cannot be inspected at all (no manifest, no config).
+
+   Stages:
+   1. validate-config    runwell.config.json shape + module references
+   2. doctor             drift between runwell-manifest and synced files
+   3. template-integrity templates/*.json sections referenced in order
+   4. orphan-assets      runwell-* files with no matching enabled module
+   5. theme-check        shopify CLI theme-check (lint), if available
+
+   Caller can skip stages with --skip <name,name>.
+*/
+
+const STAGES = ['validate-config', 'doctor', 'template-integrity', 'orphan-assets', 'theme-check'];
+
+export async function qa(flags) {
+  const targetDir = path.resolve(flags.target || process.cwd());
+  const skip = new Set((flags.skip || '').split(',').map(s => s.trim()).filter(Boolean));
+
+  const findings = { errors: [], warnings: [], info: [] };
+  const log = (level, stage, msg) => {
+    findings[level].push({ stage, msg });
+    const tag = level === 'errors' ? 'FAIL' : level === 'warnings' ? 'WARN' : 'OK  ';
+    console.log(`  [${tag}] ${stage}: ${msg}`);
+  };
+
+  console.log(`runwell-shopify qa @ ${targetDir}`);
+  console.log('');
+
+  // Stage 1: validate-config
+  if (!skip.has('validate-config')) {
+    console.log('1/5 validate-config');
+    try {
+      const { config } = loadConfig(flags.config || './runwell.config.json');
+      if (!config.client) log('errors', 'validate-config', 'missing required field "client"');
+      if (!config.store) log('warnings', 'validate-config', 'missing field "store" (registry lookups will fail)');
+      const enabled = Object.entries(config.modules || {}).filter(([, v]) => v.enabled !== false);
+      log('info', 'validate-config', `${enabled.length} modules enabled`);
+      for (const [name, entry] of enabled) {
+        try {
+          const m = loadModuleManifest(flags.toolkitRoot, name);
+          if (entry.variant) resolveVariant(m, entry.variant);
+        } catch (e) {
+          log('errors', 'validate-config', `${name}: ${e.message}`);
+        }
+      }
+    } catch (e) {
+      log('errors', 'validate-config', e.message);
+    }
+    console.log('');
+  }
+
+  // Stage 2: doctor (manifest drift)
+  if (!skip.has('doctor')) {
+    console.log('2/5 doctor (manifest drift)');
+    const manifestPath = path.join(targetDir, 'runwell-manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+      log('errors', 'doctor', 'no runwell-manifest.json (run "runwell-shopify sync" first)');
+    } else {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      let missing = 0;
+      for (const tracked of manifest.files) {
+        if (!fs.existsSync(path.join(targetDir, tracked.path))) {
+          log('errors', 'doctor', `tracked file missing: ${tracked.path}`);
+          missing++;
+        }
+      }
+      if (!missing) log('info', 'doctor', `${manifest.files.length} tracked files all present`);
+      log('info', 'doctor', `manifest toolkit version: ${manifest.toolkit_version}`);
+    }
+    console.log('');
+  }
+
+  // Stage 3: template-integrity (every section in templates/*.json must exist)
+  if (!skip.has('template-integrity')) {
+    console.log('3/5 template-integrity');
+    const tmplDir = path.join(targetDir, 'templates');
+    if (fs.existsSync(tmplDir)) {
+      const jsons = fs.readdirSync(tmplDir).filter(f => f.endsWith('.json'));
+      const sectionsDir = path.join(targetDir, 'sections');
+      const knownSections = new Set();
+      if (fs.existsSync(sectionsDir)) {
+        for (const f of fs.readdirSync(sectionsDir)) {
+          if (f.endsWith('.liquid')) knownSections.add(f.replace(/\.liquid$/, ''));
+        }
+      }
+      let badRefs = 0;
+      for (const jf of jsons) {
+        const tpath = path.join(tmplDir, jf);
+        let parsed;
+        try { parsed = JSON.parse(fs.readFileSync(tpath, 'utf8')); }
+        catch (e) { log('errors', 'template-integrity', `${jf}: invalid JSON: ${e.message}`); continue; }
+        const sections = parsed.sections || {};
+        const order = parsed.order || Object.keys(sections);
+        for (const id of order) {
+          if (!sections[id]) {
+            log('errors', 'template-integrity', `${jf}: order references unknown section id "${id}"`);
+            badRefs++;
+          } else {
+            const t = sections[id].type;
+            // Type can be a built-in (Dawn-shipped, no local file) or a section file we have
+            // Only flag if it looks like our convention (no group sections) and isn't found locally and is not a Dawn default name
+            if (t && t.startsWith('runwell-') && !knownSections.has(t)) {
+              log('errors', 'template-integrity', `${jf}: section "${id}" type "${t}" has no matching sections/${t}.liquid`);
+              badRefs++;
+            }
+          }
+        }
+      }
+      if (!badRefs) log('info', 'template-integrity', `${jsons.length} template files all reference valid sections`);
+    } else {
+      log('warnings', 'template-integrity', 'no templates/ directory');
+    }
+    console.log('');
+  }
+
+  // Stage 4: orphan-assets (runwell-* files in theme that aren't synced from any enabled module)
+  if (!skip.has('orphan-assets')) {
+    console.log('4/5 orphan-assets');
+    const manifestPath = path.join(targetDir, 'runwell-manifest.json');
+    if (fs.existsSync(manifestPath)) {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      const tracked = new Set(manifest.files.map(f => f.path));
+      const buckets = ['sections', 'snippets', 'assets', 'templates'];
+      let orphans = 0;
+      for (const b of buckets) {
+        const dir = path.join(targetDir, b);
+        if (!fs.existsSync(dir)) continue;
+        for (const f of fs.readdirSync(dir)) {
+          if (!f.startsWith('runwell-')) continue;
+          const rel = `${b}/${f}`;
+          if (!tracked.has(rel)) {
+            log('warnings', 'orphan-assets', `${rel} is runwell-prefixed but not in current manifest (stale sync?)`);
+            orphans++;
+          }
+        }
+      }
+      if (!orphans) log('info', 'orphan-assets', 'no orphans');
+    }
+    console.log('');
+  }
+
+  // Stage 5: theme-check via Shopify CLI (parse --output json for accuracy)
+  if (!skip.has('theme-check')) {
+    console.log('5/5 theme-check');
+    await new Promise(resolve => {
+      const proc = spawn('shopify', ['theme', 'check', '--path', targetDir, '--output', 'json'], {
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+      let stdout = '';
+      proc.stdout.on('data', d => stdout += d.toString());
+      proc.on('error', () => {
+        log('warnings', 'theme-check', 'shopify CLI not available; skipping');
+        resolve();
+      });
+      proc.on('exit', () => {
+        let parsed;
+        try { parsed = JSON.parse(stdout); } catch { parsed = null; }
+        if (!Array.isArray(parsed)) {
+          log('warnings', 'theme-check', 'could not parse output');
+          return resolve();
+        }
+        const offenses = parsed.flatMap(f => (f.offenses || []).map(o => ({ ...o, path: f.path })));
+        const errs = offenses.filter(o => o.severity === 'error' || o.severity === 0);
+        const warns = offenses.filter(o => o.severity === 'warning' || o.severity === 1);
+        if (errs.length === 0 && warns.length === 0) {
+          log('info', 'theme-check', 'clean');
+        } else {
+          // Per-check rollup so the summary is actionable
+          const byCheck = {};
+          for (const o of errs) byCheck[o.check] = (byCheck[o.check] || 0) + 1;
+          const top = Object.entries(byCheck).sort((a, b) => b[1] - a[1]).slice(0, 5)
+            .map(([c, n]) => `${c}×${n}`).join(', ');
+          log(errs.length ? 'errors' : 'warnings', 'theme-check',
+            `${errs.length} errors, ${warns.length} warnings${top ? ' (' + top + ')' : ''}`);
+          // List the file-level offenders so users can jump straight to fixes
+          const filesWithErr = [...new Set(errs.map(e => path.relative(targetDir, e.path)))];
+          for (const f of filesWithErr.slice(0, 8)) {
+            const n = errs.filter(e => path.relative(targetDir, e.path) === f).length;
+            log('errors', 'theme-check', `  ${f}: ${n} error(s)`);
+          }
+        }
+        resolve();
+      });
+    });
+    console.log('');
+  }
+
+  // Summary
+  console.log('---');
+  console.log(`Summary: ${findings.errors.length} errors, ${findings.warnings.length} warnings, ${findings.info.length} info`);
+  if (findings.errors.length) {
+    console.log('\nErrors (fix before declaring done):');
+    findings.errors.forEach(f => console.log(`  - [${f.stage}] ${f.msg}`));
+  }
+  if (findings.warnings.length) {
+    console.log('\nWarnings (review):');
+    findings.warnings.forEach(f => console.log(`  - [${f.stage}] ${f.msg}`));
+  }
+
+  if (findings.errors.length) process.exitCode = 2;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runwell/shopify-toolkit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Reusable Shopify theme modules from Runwell. Replaces typically app-driven features (reviews, wishlist, urgency, FAQ, post-purchase upsell, exit popups, free-ship progress, sticky ATC, testimonials, badges, bundles) with native Liquid + JS + CSS that ship across multiple client themes via a config-driven sync CLI.",
   "type": "module",
   "main": "lib/index.js",