@imwz/wp-pattern-sentinel 0.2.6 → 1.0.0

package/README.md

@@ -120,6 +120,9 @@ node bin/sentinel.js --concurrency=6 --url=... path/to/patterns/
 | `--keep-page` | `false` | Don't delete draft pages after validation |
 | `--width` | `1280` | Viewport width |
 | `--height` | `800` | Viewport height |
+| `--cache` | `false` | Skip patterns that previously passed with the same file content (see [Pass cache](#pass-cache)) |
+| `--clear-cache` | `false` | Delete `.sentinel-cache.json` and exit (or combine with a path to clear then validate) |
+| `--log` | `false` | Always write `sentinel-<timestamp>.log.json`, even when all patterns pass |
 
 ## Architecture
 
@@ -153,9 +156,53 @@ Credential rejections (wrong password) are not retried — only timeout errors t
 
 Each pattern result is printed to the terminal as soon as that worker finishes, rather than buffering everything until the full batch completes. During a long concurrent run you see progress immediately.
 
+### Pass cache
+
+`--cache` stores a `.sentinel-cache.json` file in the working directory. Each entry records the file's content hash and the last pass result:
+
+```json
+{
+  "patterns/main-hero.php": {
+    "hash": "a1b2c3d4e5f6",
+    "passed": true,
+    "checkedAt": "2026-05-16T10:00:00.000Z"
+  }
+}
+```
+
+On subsequent runs, if a pattern file's content hash matches the cached entry **and** it previously passed, the pattern is skipped. If the file has changed (even by one byte), it is re-validated and the cache entry is updated. Failed patterns are always removed from the cache so they are never skipped.
+
+```bash
+# First run — validates all, populates cache
+sentinel --cache --log patterns/
+
+# Later runs — only validates new or changed patterns
+sentinel --cache --log patterns/
+
+# Reset the cache (e.g. after a theme.json change that affects all patterns)
+sentinel --clear-cache
+
+# Clear and immediately re-validate
+sentinel --clear-cache --cache --log patterns/
+```
+
+Commit `.sentinel-cache.json` to track validated state across sessions. Add it to `.gitignore` if you prefer each developer to maintain their own local cache.
+
 ### Failure log
 
-When any pattern fails, sentinel automatically writes a `sentinel-<timestamp>.log.json` file in the current working directory and prints the path after the summary. This preserves error details for later inspection without needing to re-run.
+When any pattern fails, sentinel automatically writes a `sentinel-<timestamp>.log.json` file in the current working directory and prints the path after the summary. This preserves error details for later inspection without needing to re-run. Use `--log` to write the file even on a fully-passing run.
+
+Failing results include a `savedContent` field — the editor's serialized output — so you can diff it directly against the source file:
+
+```bash
+node -e "
+  const log = JSON.parse(require('fs').readFileSync('sentinel-*.log.json'));
+  const r = log.results.find(r => !r.passed);
+  console.log(r.savedContent);
+" | diff - patterns/my-pattern.php
+```
+
+`block_validation` errors also surface Gutenberg's human-readable issue messages (e.g. `"Expected attribute 'class' of value '…' but got '…'"`), so you no longer need to open the browser console to identify what failed.
 
 ## npm publish
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imwz/wp-pattern-sentinel",
-  "version": "0.2.6",
+  "version": "1.0.0",
   "description": "Browser-based WordPress block pattern validator using Playwright",
   "type": "module",
   "engines": {

package/src/args.js

@@ -34,6 +34,10 @@ const ARG_OPTIONS = {
   concurrency:   { type: 'string',  default: '4' },
   width:         { type: 'string',  default: '1280' },
   height:        { type: 'string',  default: '800' },
+  // Persistence
+  cache:         { type: 'boolean', default: false },
+  'clear-cache': { type: 'boolean', default: false },
+  log:           { type: 'boolean', default: false },
 };
 
 /**
@@ -126,6 +130,9 @@ export async function parseArgs(args) {
     headless:    values.headless,
     json:        values.json,
     keepPage:    values['keep-page'],
+    cache:       values.cache,
+    clearCache:  values['clear-cache'],
+    log:         values.log,
     concurrency: Math.max(1, parseInt(values.concurrency, 10)),
     viewport: {
       width:  parseInt(values.width,  10),

package/src/format.js

@@ -28,18 +28,19 @@ export function formatResult(result) {
   return lines.join('\n');
 }
 
-export function printSummary(results) {
+export function printSummary(results, skipped = 0) {
   const passed       = results.filter(r => r.passed).length;
   const failed       = results.filter(r => !r.passed).length;
   const totalErrors  = results.reduce((n, r) => n + r.errors.length, 0);
   const totalWarns   = results.reduce((n, r) => n + r.warnings.length, 0);
   const totalMs      = results.reduce((n, r) => n + r.duration, 0);
-  const avgMs        = Math.round(totalMs / results.length);
+  const avgMs        = results.length > 0 ? Math.round(totalMs / results.length) : 0;
 
   log('\n' + '='.repeat(60));
   log('Validation Summary', 'cyan');
   log('='.repeat(60));
   log(`Patterns  : ${results.length}`);
+  if (skipped > 0) log(`Skipped   : ${skipped} (cached)`, 'gray');
   log(`Passed    : ${passed}`,       passed      > 0 ? 'green'  : 'gray');
   log(`Failed    : ${failed}`,       failed      > 0 ? 'red'    : 'gray');
   log(`Errors    : ${totalErrors}`,  totalErrors > 0 ? 'red'    : 'gray');

package/src/main.js

@@ -2,6 +2,7 @@ import { chromium } from 'playwright';
 import PQueue from 'p-queue';
 import path from 'path';
 import fs from 'fs';
+import crypto from 'crypto';
 import { parseArgs, resolveFiles } from './args.js';
 import { loginToWordPress } from './login.js';
 import {
@@ -14,15 +15,78 @@ import {
 import { checkBlockValidation, compareContent } from './validation.js';
 import { log, formatResult, printSummary } from './format.js';
 
+const CACHE_FILE = '.sentinel-cache.json';
+
+function loadCache() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(process.cwd(), CACHE_FILE), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+async function saveCache(cache) {
+  try {
+    await fs.promises.writeFile(
+      path.join(process.cwd(), CACHE_FILE),
+      JSON.stringify(cache, null, 2)
+    );
+  } catch { /* ignore */ }
+}
+
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 12);
+}
+
 export async function main() {
   const options = await parseArgs(process.argv.slice(2));
-  const files   = resolveFiles(options.files);
+
+  if (options.clearCache) {
+    try {
+      fs.unlinkSync(path.join(process.cwd(), CACHE_FILE));
+      log('Cache cleared.', 'green');
+    } catch {
+      log('No cache file found.', 'gray');
+    }
+    if (options.files.length === 0) process.exit(0);
+  }
+
+  let files     = resolveFiles(options.files);
 
   if (files.length === 0) {
     log('No pattern files found.', 'red');
     process.exit(1);
   }
 
+  // Skip patterns that previously passed with the same file content.
+  const cache = options.cache ? loadCache() : {};
+  const skipped = [];
+  if (options.cache) {
+    const pending = [];
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(file, 'utf8');
+        const key     = path.relative(process.cwd(), file);
+        if (cache[key]?.passed && cache[key]?.hash === hashContent(content)) {
+          skipped.push(file);
+        } else {
+          pending.push(file);
+        }
+      } catch {
+        pending.push(file);
+      }
+    }
+    files = pending;
+    if (skipped.length > 0) {
+      log(`Skipping ${skipped.length} previously-passed pattern(s) (cached)`, 'gray');
+    }
+  }
+
+  if (files.length === 0) {
+    log('All patterns already validated — nothing to do.', 'green');
+    process.exit(0);
+  }
+
   log(`\nFound ${files.length} pattern(s) — concurrency: ${options.concurrency}`, 'cyan');
 
   const browser = await chromium.launch({
@@ -82,11 +146,25 @@ export async function main() {
     for (const r of results) console.log(JSON.stringify(r));
   }
 
-  printSummary(results);
+  printSummary(results, skipped.length);
+
+  // Update cache with results from this run.
+  if (options.cache) {
+    for (const result of results) {
+      const key = path.relative(process.cwd(), result.patternPath);
+      if (result.passed) {
+        cache[key] = { hash: result.hash, passed: true, checkedAt: new Date().toISOString() };
+      } else {
+        delete cache[key];
+      }
+    }
+    await saveCache(cache);
+    log(`  Cache updated → ${CACHE_FILE}`, 'gray');
+  }
 
-  // Write a log file when any pattern failed so details are preserved for inspection.
+  // Write a log file on failure, or always when --log is set.
   const hasFailed = results.some(r => !r.passed);
-  if (hasFailed) {
+  if (hasFailed || options.log) {
     const logPath = await writeLogFile(results);
     if (logPath) log(`  Log saved → ${logPath}`, 'gray');
   }
@@ -104,12 +182,12 @@ async function validatePatternFile(patternPath, options, context) {
   try {
     fileContent = await fs.promises.readFile(patternPath, 'utf8');
   } catch (error) {
-    return fail(patternName, startTime, 'file_error', error.message);
+    return fail(patternName, patternPath, startTime, 'file_error', error.message);
   }
 
   const blockContent = extractBlockContent(fileContent);
   if (!blockContent) {
-    return fail(patternName, startTime, 'extraction_error', 'Could not extract block content from file');
+    return fail(patternName, patternPath, startTime, 'extraction_error', 'Could not extract block content from file');
   }
 
   const page = await context.newPage();
@@ -118,12 +196,12 @@ async function validatePatternFile(patternPath, options, context) {
   try {
     const pageId = await createDraftPage(page, options.adminUrl);
     if (pageId === null) {
-      return fail(patternName, startTime, 'page_creation_error', 'Failed to create test page');
+      return fail(patternName, patternPath, startTime, 'page_creation_error', 'Failed to create test page');
     }
 
     if (!(await insertPatternIntoEditor(page, blockContent))) {
       await deletePage(page, options.adminUrl, pageId);
-      return fail(patternName, startTime, 'insertion_error', 'Failed to insert pattern into editor');
+      return fail(patternName, patternPath, startTime, 'insertion_error', 'Failed to insert pattern into editor');
     }
 
     const saveResult  = await savePage(page);
@@ -132,7 +210,11 @@ async function validatePatternFile(patternPath, options, context) {
     if (blockErrors.length > 0) {
       saveResult.errors.push(...blockErrors.map(e => ({
         type:    'block_validation',
-        message: `${e.blockName} (${e.blockId}): ${e.error}`,
+        message: `${e.blockName} (${e.blockId}): ${e.error}${
+          e.validationIssues?.length
+            ? '\n       Issues: ' + e.validationIssues.join('\n       ')
+            : ''
+        }`,
       })));
     }
 
@@ -146,6 +228,8 @@ async function validatePatternFile(patternPath, options, context) {
 
     return {
       pattern:      patternName,
+      patternPath,
+      hash:         hashContent(fileContent),
       passed:       saveResult.success && comparison.matches && blockErrors.length === 0,
       errors:       saveResult.errors,
       warnings:     saveResult.warnings,
@@ -155,15 +239,17 @@ async function validatePatternFile(patternPath, options, context) {
 
   } catch (error) {
     log(`Unexpected error — ${patternName}: ${error.message}`, 'red');
-    return fail(patternName, startTime, 'validation_error', error.message);
+    return fail(patternName, patternPath, startTime, 'validation_error', error.message);
   } finally {
     await page.close();
   }
 }
 
-function fail(pattern, startTime, type, message) {
+function fail(pattern, patternPath, startTime, type, message) {
   return {
     pattern,
+    patternPath,
+    hash:     null,
     passed:   false,
     errors:   [{ type, message }],
     warnings: [],
@@ -184,6 +270,7 @@ async function writeLogFile(results) {
         duration: r.duration,
         errors:   r.errors,
         warnings: r.warnings,
+        ...(r.passed ? {} : { savedContent: r.savedContent ?? null }),
       })),
     };
     await fs.promises.writeFile(logPath, JSON.stringify(payload, null, 2));

package/src/validation.js

@@ -8,7 +8,18 @@ export async function checkBlockValidation(page) {
     return await page.evaluate(() => {
       const walk = blocks => blocks.flatMap(block => [
         ...(block.isValid === false
-          ? [{ blockId: block.clientId, blockName: block.name, error: 'Block validation failed' }]
+          ? [{
+              blockId:          block.clientId,
+              blockName:        block.name,
+              error:            'Block validation failed',
+              validationIssues: (block.validationIssues ?? []).map(issue => {
+                try {
+                  return (issue.args ?? [])
+                    .map(a => (typeof a === 'string' ? a : JSON.stringify(a)))
+                    .join(' ');
+                } catch { return 'unknown issue'; }
+              }),
+            }]
           : []),
         ...walk(block.innerBlocks ?? []),
       ]);