Merge pull request #8 from imagewize/pattern-normalizer

Pattern Normalizer

Author: jasperf

.vibe/config.toml

@@ -120,8 +120,6 @@ denylist = [
 max_output_bytes = 16000
 default_timeout = 30
 denylist_standalone = [
-    "python",
-    "python3",
     "ipython",
     "bash",
     "sh",

CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-05-14
+
+### Added
+
+- **`pattern:diff` command** (`src/Commands/PatternDiffCommand.php`) — compares a Gutenberg clipboard paste against an existing PHP pattern file and reports differences (missing translations, editor-only attributes, CSS drift, WooCommerce block issues). Options:
+  - `--from-stdin` — read Gutenberg HTML from stdin (pipe from `pbpaste`)
+  - `--apply` — merge clipboard changes into the PHP file, preserving all PHP translation wrappers (`esc_html_e`, `esc_attr_e`, `wp_kses_post`, `get_template_directory_uri`)
+  - `--dry-run` — with `--apply`: print the merged result to stdout instead of writing to disk
+  - `--theme` — theme config to use (default: `elayne`)
+  - `--json` — output diff results as JSON
+  - `--similarity-threshold` — minimum block similarity score to consider a match (0–1, default: `0.95`)
+  - `--show-suggestions` / `-s` — include fix suggestions in the output
+
+- **`BlockNormalizer` class** (`src/PatternDiff/BlockNormalizer.php`) — normalises block HTML for comparison: strips editor-only attributes (`__privatePreviewState`, `isNotStackedOnMobile`, constrained layout flags, product-collection block flags), normalises CSS value tokens (font-size slugs → CSS variables, spacing presets), collapses whitespace, and decodes HTML entities. Exposes `detectEditorAttributes()`, `extractOuterBlockType()`, and `hasWooCommerceBlocks()` as public helpers.
+
+- **`PatternDiffer` class** (`src/PatternDiff/PatternDiffer.php`) — calculates structural similarity between clipboard HTML and a PHP pattern file. Extracts block HTML from PHP, computes a similarity score via `similar_text`, and finds CSS, structural, and text-node differences. WooCommerce plugin paths (`wp-content/plugins/woocommerce/patterns/*`) are exempt via `isExempt()`.
+
+- **`PatternSyncer` class** (`src/PatternDiff/PatternSyncer.php`) — implements the `--apply` merge strategy: extracts the PHP docblock header, builds a `text → PHP call` map from all translation wrappers in the original file, applies structural fixes to the clipboard (strips `__privatePreviewState`, normalises font-size slugs, removes nested `<p>` copy artefacts), then walks every HTML text node replacing raw strings with their original wrappers or generating new `esc_html_e()` calls for new strings.
+
+- **`TranslationDetector` class** (`src/PatternDiff/TranslationDetector.php`) — finds text nodes in clipboard HTML that are not yet wrapped in a translation function in the existing PHP file. Generates `esc_html_e()` fix suggestions. Exposes `isTranslated()`, `generateTranslationWrapper()`, and `extractTranslatableText()` as public helpers.
+
+- **`WooCommerceValidator` class** (`src/PatternDiff/WooCommerceValidator.php`) — validates WooCommerce-specific block structure in the diff context: checks `isDescendentOfQueryLoop` on WC blocks inside `product-template`, validates `<div>` wrappers and layout attributes, and inspects `product-collection` query metadata.
+
+- **PHPUnit test suite for `PatternDiff`** — 6 new test files covering all public methods in the feature:
+  - `tests/PatternDiff/BlockNormalizerTest.php` — 29 tests for all normalisation methods
+  - `tests/PatternDiff/PatternDifferTest.php` — 5 tests (diff result shape, identical-file similarity, PHP extraction, exempt paths)
+  - `tests/PatternDiff/PatternSyncerTest.php` — 22 tests (header extraction/stripping, PHP call map, structural fixes, translation restore, wrapper generation)
+  - `tests/PatternDiff/TranslationDetectorTest.php` — 16 tests (missing translation detection, `isTranslated`, `generateTranslationWrapper`, `extractTranslatableText`)
+  - `tests/PatternDiff/WooCommerceValidatorTest.php` — 6 tests (validate, extractWooCommerceBlocks, isDescendantOfProductTemplate)
+  - `tests/Commands/PatternDiffCommandTest.php` — 9 tests (command name, path validation, apply/dry-run guards, JSON output, threshold, theme option)
+
+### Fixed
+
+- **`PatternDiffer::isTranslatable()`** — the `if (preg_match(...))` guard around the CSS-value `return false` branch was accidentally omitted, causing the method to always return `false` after the single-character check. All text nodes after that point were silently skipped by the translation detector.
+
+### Changed
+
+- **`.vibe/config.toml`** — `python` and `python3` removed from the vibe tools denylist to allow local script execution during pattern diffing.
+
 ## [2.2.3] - 2026-05-13
 
 ### Added

README.md

@@ -71,6 +71,42 @@ pt-cli check:templates /path/to/templates/archive-product.html --theme=elayne
 pt-cli check:templates /path/to/templates/ --theme=elayne --autofix
 ```
 
+### Pattern Diff & Sync
+
+Compare a Gutenberg clipboard paste against an existing PHP pattern file, or apply
+the changes back while preserving all PHP translation wrappers.
+
+```bash
+# Report differences only (shows missing translations, editor attrs, CSS issues)
+pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin
+
+# Include fix suggestions in the diff report
+pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin --show-suggestions
+
+# Output diff results as JSON (for tooling integration)
+pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin --json
+
+# Preview the merged result without touching the file
+pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin --apply --dry-run
+
+# Apply clipboard changes to the PHP file (preserves esc_html_e, esc_attr_e, etc.)
+pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin --apply
+
+# Lower the similarity threshold for loosely matched blocks (default: 0.95)
+pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin --similarity-threshold=0.80
+```
+
+**What `--apply` does:**
+
+1. Strips editor-only attributes (`__privatePreviewState`) from block JSON.
+2. Fixes bare font-size slug values (`font-size:small`) → CSS variable (`font-size:var(--wp--preset--font-size--small)`).
+3. Removes nested `<p>` copy artefacts introduced by the Gutenberg clipboard.
+4. Re-maps every text node back to its original PHP wrapper (`esc_html_e`, `esc_attr_e`, `wp_kses_post`) from the existing file.
+5. Generates a new `esc_html_e()` wrapper for any text that is new in the clipboard.
+6. Preserves the PHP docblock header unchanged.
+
+The file is only written when `--apply` is used **without** `--dry-run`.
+
 ## Commands Reference
 
 | Command | Description |
@@ -81,6 +117,7 @@ pt-cli check:templates /path/to/templates/ --theme=elayne --autofix
 | `style:create` | Scaffold a WordPress theme style variation JSON |
 | `check` | Check PHP pattern files for compliance violations |
 | `check:templates` | Check HTML template/part files for block validation drift |
+| `pattern:diff` | Diff Gutenberg clipboard against a pattern file, or apply changes preserving PHP |
 
 ## Workflow
 
@@ -96,6 +133,19 @@ pt-cli check:templates /path/to/templates/ --theme=elayne --autofix
 | 4 | `pt-cli pattern:create --shell-only` | Create PHP file with paste marker | Host |
 | 5 | Replace marker | Paste blocks into pattern file | Host |
 
+### Pattern Sync Workflow (updating existing patterns)
+
+When an existing PHP pattern needs updating from the Site Editor, use `pattern:diff --apply`
+instead of pasting manually — it keeps all `esc_html_e()` and other PHP wrappers intact.
+
+| Step | Command | Purpose |
+|------|---------|---------|
+| 1 | Edit pattern in Site Editor | Make structural/layout changes |
+| 2 | Copy all blocks (Cmd+A, Cmd+C) | Copy updated block HTML to clipboard |
+| 3 | `pbpaste \| pt-cli pattern:diff <file> --from-stdin --apply --dry-run` | Preview merged result |
+| 4 | `pbpaste \| pt-cli pattern:diff <file> --from-stdin --apply` | Write merged result to file |
+| 5 | `pt-cli check <file> --theme=elayne` | Verify compliance passes |
+
 ### Compliance Workflow (three-pass)
 
 | Pass | Tool | Purpose | Where |

bin/pt-cli

@@ -14,19 +14,21 @@ foreach ($autoloadPaths as $path) {
 }
 
 use Imagewize\PtCli\Commands\CheckCommand;
+use Imagewize\PtCli\Commands\PatternDiffCommand;
 use Imagewize\PtCli\Commands\Scaffold\LayoutCreateCommand;
 use Imagewize\PtCli\Commands\Scaffold\PatternCreateCommand;
 use Imagewize\PtCli\Commands\Scaffold\PatternListCommand;
 use Imagewize\PtCli\Commands\Scaffold\StyleCreateCommand;
 use Imagewize\PtCli\Commands\TemplateCheckCommand;
 use Symfony\Component\Console\Application;
 
-$application = new Application('pt-cli', '2.2.3');
+$application = new Application('pt-cli', '2.3.0');
 $application->add(new CheckCommand());
 $application->add(new TemplateCheckCommand());
 $application->add(new PatternCreateCommand());
 $application->add(new LayoutCreateCommand());
 $application->add(new StyleCreateCommand());
 $application->add(new PatternListCommand());
+$application->add(new PatternDiffCommand());
 $application->setDefaultCommand('list');
 $application->run();