@imwz/wp-pattern-sentinel 1.1.5 → 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imwz/wp-pattern-sentinel",
-  "version": "1.1.5",
+  "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

@@ -192,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');
   }