@imwz/wp-pattern-sentinel 1.1.4 → 1.2.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dt/@imwz/wp-pattern-sentinel.svg)](https://www.npmjs.com/package/@imwz/wp-pattern-sentinel)
 [![License](https://img.shields.io/npm/l/@imwz/wp-pattern-sentinel.svg)](https://github.com/imagewize/wp-pattern-sentinel/blob/main/package.json)
 
-Browser-based WordPress block pattern validator. Loads each pattern into the Gutenberg editor via Playwright, saves it, and checks for block validation errors and content mismatches.
+Browser-based WordPress block pattern validator. Loads each pattern into the Gutenberg editor via Playwright, saves it, and checks for block validation errors and content mismatches. Validates `.php` pattern files and `.html` files of raw block markup. See [What it validates](#what-it-validates-php-and-html).
 
 ## Why browser-based?
 
@@ -97,6 +97,9 @@ node bin/sentinel.js \
 # Validate specific files
 node bin/sentinel.js patterns/hero.php patterns/cta.php
 
+# Raw block markup (.html) — block fixtures or post drafts
+node bin/sentinel.js tests/sentinel/ drafts/my-post.html
+
 # JSON output (one result object per line)
 node bin/sentinel.js --json --url=... path/to/patterns/
 
@@ -113,6 +116,39 @@ node bin/sentinel.js --concurrency=6 --url=... path/to/patterns/
 node bin/sentinel.js --verbose --url=... path/to/patterns/
 ```
 
+## What it validates: `.php` and `.html`
+
+Sentinel never asks WordPress for registered patterns. It reads block markup from a file, puts it into a new draft page in the editor, saves the page and compares the result. So a file doesn't have to be a registered pattern; it only has to contain serialized blocks. A folder argument is scanned recursively for both extensions, skipping `node_modules`, `vendor` and dot-folders such as `.git`. Point Sentinel at the pattern or fixture folder rather than a block theme's root: `templates/*.html` and `parts/*.html` are block markup too, but they are site templates, not post content, and don't belong in a page round-trip.
+
+| Extension | What it holds | What Sentinel strips before inserting |
+|-----------|---------------|---------------------------------------|
+| `.php` | A WordPress pattern file: PHP header, then block markup | Everything up to the first `?>` (docblock, `ABSPATH` guard), then inline PHP such as `esc_html_e()` is replaced with static text |
+| `.html` | Raw serialized blocks, exactly as WordPress stores them in `post_content` | Only a **leading** header made of plain HTML comments (`<!-- SUGGESTED TITLE: … -->`) and Blade comments (`{{-- … --}}`) |
+
+### When to use `.html`
+
+- **Testing a block that no pattern uses.** A theme block that only ever appears in post content (a CTA, a callout) has no pattern file for Sentinel to pick up. Don't wrap it in a fake pattern header. Save the block's markup as it is serialized in a real post, for example copied from `wp post get <id> --field=post_content`, as `tests/sentinel/<block>.html`.
+- **Checking post or page drafts before import.** Drafts written as `.html` block markup can be validated as they are. Header notes at the top of the file are skipped. Without that, the editor would wrap them in a Classic block and Sentinel would report a false mismatch.
+
+```bash
+# A theme's block fixtures
+sentinel --trellis --site=example.com tests/sentinel/
+
+# Blog drafts before they are imported
+sentinel --trellis --site=example.com drafts/blog-posts/
+```
+
+### Rules for `.html` files
+
+- After the header, the file must start with a block comment (`<!-- wp:… -->`). Otherwise it fails with `extraction_error`.
+- Only the header is stripped. A non-block comment *after* the first block is left in, because in post content it is real content.
+- There's no PHP handling, so an `.html` file containing `<?php` is inserted as is.
+- Use markup the editor actually produced, not hand-written HTML. The test's value is that a real serialization round-trips cleanly.
+
+### Blocks with a locked template
+
+A block that renders `InnerBlocks` with a `template` and `templateLock: "all"` or `"contentOnly"` is re-synced to that template when the editor loads it. Gutenberg matches inner blocks by position, adds any the template has extra, and removes any it no longer has. A fixture holding the markup a post stored *before* a template change will therefore fail with `content_mismatch`, and that is correct. It is exactly the change an editor would see on opening such a post. Keep one fixture per current template, and run an old one on purpose when you want to see how existing posts will be affected.
+
 ## Options
 
 | Flag | Default | Description |
@@ -212,6 +248,10 @@ node -e "
 
 `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.
 
+A block can also pass validation only because one of its block type's deprecations accepted the markup and migrated it. The editor reports such a block as valid, but it saves different markup, and it shows as broken the next time the page is opened. Sentinel re-validates every parsed block against its original markup and reports these as `block_validation` errors reading "Block was migrated by a deprecation and will save different markup". A common cause is an attribute the block does not support, such as `aria-hidden` on `core/paragraph`.
+
+`--cache` entries record the Sentinel version that passed them, so upgrading Sentinel re-validates every pattern once.
+
 ## npm publish
 
 When ready to publish:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imwz/wp-pattern-sentinel",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "Browser-based WordPress block pattern validator using Playwright",
   "type": "module",
   "engines": {
@@ -10,7 +10,8 @@
     "sentinel": "bin/sentinel.js"
   },
   "scripts": {
-    "start": "node bin/sentinel.js"
+    "start": "node bin/sentinel.js",
+    "test": "node --test test/*.test.js"
   },
   "files": [
     "bin/",

package/src/args.js

@@ -148,7 +148,7 @@ export function resolveFiles(filePaths) {
   if (!filePaths || filePaths.length === 0) {
     throw new Error(
       'No pattern files specified.\n' +
-      'Usage: sentinel [--trellis [--site=example.com]] path/to/patterns/\n' +
+      'Usage: sentinel [--trellis [--site=example.com]] path/to/patterns/  (.php and .html files)\n' +
       'Or set WP_URL, WP_USER, WP_PASS in .env'
     );
   }
@@ -162,7 +162,7 @@ export function resolveFiles(filePaths) {
     }
     const stat = fs.statSync(abs);
     if (stat.isDirectory()) {
-      resolved.push(...findPhpFiles(abs));
+      resolved.push(...findPatternFiles(abs));
     } else {
       resolved.push(abs);
     }
@@ -170,13 +170,23 @@ export function resolveFiles(filePaths) {
   return [...new Set(resolved)];
 }
 
-function findPhpFiles(dir) {
+// `.php` — WordPress pattern files. `.html` — raw serialized block markup, as
+// stored in post_content (block fixtures, post drafts).
+const PATTERN_EXTENSIONS = ['.php', '.html'];
+
+// Dependency and VCS folders are never pattern sources, but they do hold
+// stray `.php`/`.html` files (README demos, test pages) that a scan of a theme
+// root would otherwise try to validate. Dot-folders (.git, .cache) likewise.
+const SKIPPED_DIRS = new Set(['node_modules', 'vendor']);
+
+function findPatternFiles(dir) {
   const results = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      results.push(...findPhpFiles(full));
-    } else if (entry.isFile() && entry.name.endsWith('.php')) {
+      if (SKIPPED_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+      results.push(...findPatternFiles(full));
+    } else if (entry.isFile() && PATTERN_EXTENSIONS.includes(path.extname(entry.name))) {
       results.push(full);
     }
   }

package/src/editor.js

@@ -52,7 +52,9 @@ function stripPhpForValidation(content) {
  * regardless of what it contains (docblock only, or docblock + guard) — so a
  * single non-greedy strip handles both shapes in one pass.
  */
-export function extractBlockContent(fileContent) {
+export function extractBlockContent(fileContent, filePath = '') {
+  if (filePath.endsWith('.html')) return extractHtmlBlockContent(fileContent);
+
   const stripped = fileContent
     .replace(/^[\s\S]*?\?>\s*/, '')
     .trim();
@@ -61,6 +63,29 @@ export function extractBlockContent(fileContent) {
   return stripPhpForValidation(stripped);
 }
 
+/**
+ * Return the block markup of an `.html` file: serialized blocks exactly as
+ * WordPress stores them in post_content, with no PHP header.
+ *
+ * Only a *leading* header is removed — plain HTML comments that are not block
+ * delimiters (`<!-- SUGGESTED TITLE: … -->`) and Blade comments
+ * (`{{-- … --}}`). Draft files carry these as notes for humans; left in, the
+ * editor would turn them into a Classic block and report a mismatch. Comments
+ * after the first block are content and are left alone. Returns null if no
+ * block comment follows the header.
+ */
+export function extractHtmlBlockContent(fileContent) {
+  const HEADER_COMMENT = /^\s*(?:<!--(?!\s*\/?wp:)[\s\S]*?-->|\{\{--[\s\S]*?--\}\})/;
+
+  let content = fileContent;
+  while (HEADER_COMMENT.test(content)) {
+    content = content.replace(HEADER_COMMENT, '');
+  }
+  content = content.trim();
+
+  return /^<!--\s*wp:/.test(content) ? content : null;
+}
+
 const PAGE_CREATION_RETRY_DELAYS = [3_000, 8_000, 15_000]; // ms before retries 1, 2, 3 (plus jitter)
 
 /**

package/src/main.js

@@ -17,6 +17,12 @@ import { log, formatResult, printSummary } from './format.js';
 
 const CACHE_FILE = '.sentinel-cache.json';
 
+// Cache entries record the Sentinel version that passed them, so a release
+// that adds or tightens a check re-validates patterns that passed before it.
+const SENTINEL_VERSION = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+).version;
+
 function loadCache() {
   try {
     return JSON.parse(fs.readFileSync(path.join(process.cwd(), CACHE_FILE), 'utf8'));
@@ -67,7 +73,7 @@ export async function main() {
       try {
         const content = fs.readFileSync(file, 'utf8');
         const key     = path.relative(process.cwd(), file);
-        if (cache[key]?.passed && cache[key]?.hash === hashContent(content)) {
+        if (cache[key]?.passed && cache[key]?.hash === hashContent(content) && cache[key]?.version === SENTINEL_VERSION) {
           skipped.push(file);
         } else {
           pending.push(file);
@@ -153,7 +159,7 @@ export async function main() {
     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() };
+        cache[key] = { hash: result.hash, passed: true, version: SENTINEL_VERSION, checkedAt: new Date().toISOString() };
       } else {
         delete cache[key];
       }
@@ -186,7 +192,7 @@ async function validatePatternFile(patternPath, options, context) {
     return fail(patternName, patternPath, startTime, 'file_error', error.message);
   }
 
-  const blockContent = extractBlockContent(fileContent);
+  const blockContent = extractBlockContent(fileContent, patternPath);
   if (!blockContent) {
     return fail(patternName, patternPath, startTime, 'extraction_error', 'Could not extract block content from file');
   }

package/src/validation.js

@@ -1,30 +1,59 @@
 import { log } from './format.js';
 
 /**
- * Walk the block tree and collect any blocks where isValid === false.
+ * Walk the block tree and collect any blocks where isValid === false, plus any
+ * block a deprecation silently migrated.
+ *
+ * When a block fails validation, the parser tries the block type's
+ * deprecations; if one accepts the markup, the block is migrated and reported
+ * as isValid: true with no issues, yet its attributes have changed and it will
+ * save different markup. The editor then shows the block as broken on the next
+ * load. Example: core/paragraph with aria-hidden="true" is taken by an old
+ * paragraph deprecation that drops fontFamily and keeps the whole <p> as the
+ * block's text, so the first save writes a <p> nested inside another <p>.
+ * Re-running validateBlock() on the parsed block compares what it will save
+ * against the original markup, which catches this.
  */
 export async function checkBlockValidation(page, verbose = false) {
   const start = Date.now();
   if (verbose) log('    → Checking block validation...', 'gray');
   try {
     const errors = await page.evaluate(() => {
-      const walk = blocks => blocks.flatMap(block => [
-        ...(block.isValid === false
-          ? [{
-              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 ?? []),
-      ]);
+      const formatIssues = issues => (issues ?? []).map(issue => {
+        try {
+          return (issue.args ?? [])
+            .map(a => (typeof a === 'string' ? a : JSON.stringify(a)))
+            .join(' ');
+        } catch { return 'unknown issue'; }
+      });
+      const validateBlock = window.wp.blocks.validateBlock;
+      const migratedIssues = block => {
+        if (!validateBlock || block.isValid !== true || block.name === 'core/missing') return null;
+        const [isValid, issues] = validateBlock(block);
+        return isValid ? null : issues;
+      };
+      const walk = blocks => blocks.flatMap(block => {
+        const migrated = migratedIssues(block);
+        return [
+          ...(block.isValid === false
+            ? [{
+                blockId:          block.clientId,
+                blockName:        block.name,
+                error:            'Block validation failed',
+                validationIssues: formatIssues(block.validationIssues),
+              }]
+            : []),
+          ...(migrated
+            ? [{
+                blockId:          block.clientId,
+                blockName:        block.name,
+                error:            'Block was migrated by a deprecation and will save different markup',
+                validationIssues: formatIssues(migrated),
+              }]
+            : []),
+          ...walk(block.innerBlocks ?? []),
+        ];
+      });
       return walk(window.wp.data.select('core/block-editor').getBlocks());
     });
     if (verbose) log(`    → Block validation complete (${Date.now() - start}ms)`, 'gray');