@imwz/wp-pattern-sentinel 1.0.3 → 1.1.0

package/README.md

@@ -104,6 +104,9 @@ node bin/sentinel.js --no-headless --url=... path/to/patterns/
 
 # Adjust concurrency (default: 4)
 node bin/sentinel.js --concurrency=6 --url=... path/to/patterns/
+
+# Show verbose step-by-step output
+node bin/sentinel.js --verbose --url=... path/to/patterns/
 ```
 
 ## Options
@@ -118,6 +121,7 @@ node bin/sentinel.js --concurrency=6 --url=... path/to/patterns/
 | `--concurrency` | `4` | Parallel workers |
 | `--json` | `false` | Output JSON (one result per line) |
 | `--keep-page` | `false` | Don't delete draft pages after validation |
+| `--verbose` | `false` | Show detailed step-by-step progress for each pattern |
 | `--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)) |

package/package.json

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

package/src/args.js

@@ -31,6 +31,7 @@ const ARG_OPTIONS = {
   headless:      { type: 'boolean', default: true },
   json:          { type: 'boolean', default: false },
   'keep-page':   { type: 'boolean', default: false },
+  verbose:       { type: 'boolean', default: false },
   concurrency:   { type: 'string',  default: '4' },
   width:         { type: 'string',  default: '1280' },
   height:        { type: 'string',  default: '800' },
@@ -138,6 +139,7 @@ export async function parseArgs(args) {
       width:  parseInt(values.width,  10),
       height: parseInt(values.height, 10),
     },
+    verbose:     values.verbose,
     files: positionals,
   };
 }

package/src/editor.js

@@ -66,8 +66,9 @@ export function extractBlockContent(fileContent) {
  * WordPress redirects post-new.php → post.php?post=ID&action=edit,
  * so we can read the ID directly from the final URL.
  */
-export async function createDraftPage(page, baseUrl) {
+export async function createDraftPage(page, baseUrl, verbose = false) {
   try {
+    if (verbose) log('    → Creating draft page...', 'gray');
     await page.goto(`${baseUrl}/wp-admin/post-new.php?post_type=page`, {
       waitUntil: 'domcontentloaded',
       timeout: 30000,
@@ -79,12 +80,17 @@ export async function createDraftPage(page, baseUrl) {
 
     const url = page.url();
     const match = url.match(/[?&]post=(\d+)/);
-    if (match) return parseInt(match[1], 10);
+    if (match) {
+      if (verbose) log('    → Draft page created', 'gray');
+      return parseInt(match[1], 10);
+    }
 
     // Fallback: read from wp.data (editor may not have redirected yet)
-    return await page.evaluate(() =>
+    const pageId = await page.evaluate(() =>
       window.wp?.data?.select('core/editor')?.getCurrentPostId?.() ?? null
     );
+    if (verbose && pageId) log('    → Draft page created', 'gray');
+    return pageId;
   } catch (error) {
     log(`Failed to create draft page: ${error.message}`, 'red');
     return null;
@@ -94,8 +100,9 @@ export async function createDraftPage(page, baseUrl) {
 /**
  * Set the editor content via wp.data and wait for blocks to parse.
  */
-export async function insertPatternIntoEditor(page, blockContent) {
+export async function insertPatternIntoEditor(page, blockContent, verbose = false) {
   try {
+    if (verbose) log('    → Inserting pattern into editor...', 'gray');
     await page.evaluate(content => {
       window.wp.data.dispatch('core/editor').editPost({ content });
     }, blockContent);
@@ -106,6 +113,7 @@ export async function insertPatternIntoEditor(page, blockContent) {
       { timeout: 15000 }
     );
 
+    if (verbose) log('    → Pattern inserted', 'gray');
     return true;
   } catch (error) {
     log(`Failed to insert pattern: ${error.message}`, 'red');
@@ -116,9 +124,10 @@ export async function insertPatternIntoEditor(page, blockContent) {
 /**
  * Trigger savePost() and wait for the editor to finish saving.
  */
-export async function savePage(page) {
+export async function savePage(page, verbose = false) {
   const result = { success: false, errors: [], warnings: [] };
   try {
+    if (verbose) log('    → Saving page...', 'gray');
     await page.evaluate(() => window.wp.data.dispatch('core/editor').savePost());
 
     // Wait for save to start, then finish
@@ -134,6 +143,7 @@ export async function savePage(page) {
       { timeout: 30000 }
     );
 
+    if (verbose) log('    → Page saved', 'gray');
     result.success = true;
   } catch (error) {
     result.errors.push({ type: 'save_error', message: error.message });
@@ -145,8 +155,9 @@ export async function savePage(page) {
  * Delete the draft page via the WP REST API (uses the active browser session's nonce).
  * Non-fatal — a failure here does not affect validation results.
  */
-export async function deletePage(page, baseUrl, pageId) {
+export async function deletePage(page, baseUrl, pageId, verbose = false) {
   try {
+    if (verbose) log('    → Deleting draft page...', 'gray');
     await page.evaluate(async id => {
       const nonce = window.wpApiSettings?.nonce ?? '';
       await fetch(`/wp-json/wp/v2/pages/${id}?force=true`, {
@@ -154,6 +165,7 @@ export async function deletePage(page, baseUrl, pageId) {
         headers: { 'X-WP-Nonce': nonce },
       });
     }, pageId);
+    if (verbose) log('    → Draft page deleted', 'gray');
   } catch {
     // Non-fatal
   }

package/src/main.js

@@ -175,6 +175,7 @@ export async function main() {
 async function validatePatternFile(patternPath, options, context) {
   const patternName = path.basename(patternPath);
   const startTime   = Date.now();
+  const verbose     = options.verbose;
 
   log(`  Validating: ${patternName}`, 'cyan');
 
@@ -194,18 +195,18 @@ async function validatePatternFile(patternPath, options, context) {
   page.setDefaultTimeout(60000);
 
   try {
-    const pageId = await createDraftPage(page, options.adminUrl);
+    const pageId = await createDraftPage(page, options.adminUrl, verbose);
     if (pageId === null) {
       return fail(patternName, patternPath, startTime, 'page_creation_error', 'Failed to create test page');
     }
 
-    if (!(await insertPatternIntoEditor(page, blockContent))) {
-      await deletePage(page, options.adminUrl, pageId);
+    if (!(await insertPatternIntoEditor(page, blockContent, verbose))) {
+      await deletePage(page, options.adminUrl, pageId, verbose);
       return fail(patternName, patternPath, startTime, 'insertion_error', 'Failed to insert pattern into editor');
     }
 
-    const saveResult  = await savePage(page);
-    const blockErrors = await checkBlockValidation(page);
+    const saveResult  = await savePage(page, verbose);
+    const blockErrors = await checkBlockValidation(page, verbose);
 
     if (blockErrors.length > 0) {
       saveResult.errors.push(...blockErrors.map(e => ({
@@ -218,12 +219,12 @@ async function validatePatternFile(patternPath, options, context) {
       })));
     }
 
-    const comparison = await compareContent(page, blockContent);
+    const comparison = await compareContent(page, blockContent, verbose);
     saveResult.errors.push(...comparison.errors);
     saveResult.warnings.push(...comparison.warnings);
 
     if (!options.keepPage) {
-      await deletePage(page, options.adminUrl, pageId);
+      await deletePage(page, options.adminUrl, pageId, verbose);
     }
 
     return {

package/src/validation.js

@@ -3,9 +3,10 @@ import { log } from './format.js';
 /**
  * Walk the block tree and collect any blocks where isValid === false.
  */
-export async function checkBlockValidation(page) {
+export async function checkBlockValidation(page, verbose = false) {
+  if (verbose) log('    → Checking block validation...', 'gray');
   try {
-    return await page.evaluate(() => {
+    const errors = await page.evaluate(() => {
       const walk = blocks => blocks.flatMap(block => [
         ...(block.isValid === false
           ? [{
@@ -25,6 +26,8 @@ export async function checkBlockValidation(page) {
       ]);
       return walk(window.wp.data.select('core/block-editor').getBlocks());
     });
+    if (verbose) log('    → Block validation complete', 'gray');
+    return errors;
   } catch (error) {
     log(`Block validation check error: ${error.message}`, 'yellow');
     return [];
@@ -76,26 +79,40 @@ const normalizeBlockAttrJson = str => {
   });
 };
 
+/**
+ * Collapse whitespace (including newlines) between adjacent tags/comments to
+ * nothing. Custom blocks that render their wrapper markup via JSX (e.g.
+ * `<div><div className="inner">...`) serialize with zero whitespace between
+ * elements, while hand-authored pattern PHP conventionally puts each nested
+ * element on its own line for readability. That's insignificant whitespace —
+ * browsers treat it identically — so it must not produce a content_mismatch.
+ */
+const collapseInterTagWhitespace = str => str.replace(/>\s+</g, '><');
+
 /** Apply all WordPress serializer normalizations to both sides before diffing. */
 const normalizeForComparison = str =>
-  normalizeBlockAttrJson(normalizeCssProps(stripNavRef(str)));
+  collapseInterTagWhitespace(normalizeBlockAttrJson(normalizeCssProps(stripNavRef(str))));
 
 /**
  * Compare the editor's serialized output against the original source.
  * Whitespace-normalizes both sides before diffing to avoid false positives
  * from indentation changes, then surfaces up to 5 added/removed lines.
  */
-export async function compareContent(page, originalContent) {
+export async function compareContent(page, originalContent, verbose = false) {
   const result = { matches: true, errors: [], warnings: [], savedContent: null };
 
   try {
+    if (verbose) log('    → Comparing content...', 'gray');
     const savedContent = await page.evaluate(() =>
       window.wp.data.select('core/editor').getEditedPostContent()
     );
     result.savedContent = savedContent;
 
     const normalize = str => str.replace(/\s+/g, ' ').trim();
-    if (normalize(normalizeForComparison(savedContent)) === normalize(normalizeForComparison(originalContent))) return result;
+    if (normalize(normalizeForComparison(savedContent)) === normalize(normalizeForComparison(originalContent))) {
+      if (verbose) log('    → Content matches', 'gray');
+      return result;
+    }
 
     result.matches = false;
 
@@ -117,6 +134,7 @@ export async function compareContent(page, originalContent) {
         message: `Content injected by editor:\n    ${added.join('\n    ')}`,
       });
     }
+    if (verbose) log('    → Content comparison complete', 'gray');
   } catch (error) {
     result.errors.push({ type: 'comparison_error', message: error.message });
   }