@webikon/webentor-codemods 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Webentor Codemods Changelog
+
+## 0.1.0
+
+- Initial release of `@webikon/webentor-codemods` — a reusable, ast-grep–powered
+  codemod runner for migrating consumer theme code across `webentor-core` updates.
+  - CLI: `list`, `run <id>`, and `run --since <ver> [--to <ver>]` (dry-run by
+    default, `--apply` to write).
+  - Migrations are **named by the webentor-core version** they upgrade to — the id
+    *is* the target version, so `run 0.13.0` reads as "run the 0.13.0 codemod".
+  - First migration `0.13.0` (core 0.12 → 0.13), with two rule sets:
+    - `editor-enqueue-iframe.yml` (PHP): moves the theme's `editor.css` +
+      `button.style.css` enqueues from `enqueue_block_editor_assets` to a new
+      `enqueue_block_assets` hook (`is_admin()` guarded) for WP 7.0's iframed
+      editor; the editor JS stays put.
+    - `deps.yml` (JSON, multi-rule): rewrites the theme's `package.json` +
+      `composer.json` dependency ranges to the 0.13.0 baseline — `webentor-core`
+      `^0.13` plus the full aligned third-party set (incl. major bumps
+      `@wordpress/components` 30→35, `@wordpress/icons` 11→14, `stylelint` 16→17,
+      `@types/wordpress__block-editor` 14→15). Value-is-string guarded so config
+      objects sharing a key aren't touched; `name`/`version` untouched.
+  - Polyglot golden tests run a migration's rules over a `before/` fixture subtree
+    (PHP + JSON together) and assert byte-exact equality with `after/`, plus
+    idempotency and a safe no-op on customized/already-migrated trees.

package/LICENCE.md

@@ -0,0 +1,7 @@
+Copyright (c) Webikon s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @webikon/webentor-codemods
+
+Reusable, polyglot **codemods** for migrating Webentor Stack consumer projects
+across `webentor-core` updates. When a core release requires a mechanical change
+to **consumer-owned theme code** (PHP / TS / CSS / JSON), the fix ships here as a
+versioned migration you can run with one command — no install required.
+
+Powered by [ast-grep](https://ast-grep.github.io) (AST-based, so it tolerates
+formatting differences a regex would choke on).
+
+## Usage
+
+Run from your **project root** (the directory containing `web/app/themes/…`):
+
+```sh
+# See what's available
+pnpm dlx @webikon/webentor-codemods list
+
+# Preview the codemod for a core version (dry-run — prints a diff, writes nothing)
+pnpm dlx @webikon/webentor-codemods run 0.13.0
+
+# Apply it
+pnpm dlx @webikon/webentor-codemods run 0.13.0 --apply
+
+# Or run every migration across a core version range at once
+pnpm dlx @webikon/webentor-codemods run --since 0.12.0 --to 0.13.0 --apply
+```
+
+`--path <dir>` targets a different directory (defaults to the current one).
+`--package <name>` narrows `--since` to a package (defaults to `webentor-core`).
+
+> Use `npx` instead of `pnpm dlx` if you prefer — both download-and-run without
+> a permanent install.
+
+Always run a dry-run first, review the diff, then re-run with `--apply`. After
+applying, rebuild the theme and clear caches (`wp acorn optimize:clear`).
+
+## Available migrations
+
+Migrations are **named by the webentor-core version** they bring you to — the id
+*is* the target version, so "run the 0.13.0 codemod" reads literally.
+
+| id | core | what |
+| --- | --- | --- |
+| `0.13.0` | 0.12 → 0.13 | WP 7.0 iframe editor-asset enqueue change (`app/setup.php`) + the full dependency bump set (`package.json` + `composer.json`) |
+
+See each migration's `migrations/<id>/README.md` for before/after detail.
+
+## How it's built
+
+```
+migrations/
+  index.json                     registry (id = version, title, appliesTo range, rule files)
+  <version>/                     e.g. 0.13.0
+    rules/*.yml                  ast-grep rewrite rule(s), applied in order; one .yml
+                                 may hold several rules as `---`-separated documents
+    README.md                    what/why + before→after
+  __fixtures__/<version>/
+    before/  after/              golden project subtrees (drive the tests); each holds
+                                 the files a rule touches, e.g. app/setup.php,
+                                 package.json, composer.json
+    customized/                  (optional) a subtree that must NOT change (no-op guard)
+bin/webentor-codemods.mjs        the CLI runner (wraps the bundled ast-grep)
+```
+
+### Adding a future migration
+
+1. Create `migrations/<version>/rules/<rule>.yml` ast-grep rule(s) with a `fix`.
+   Rules can target multiple languages (PHP, JSON, …) — ast-grep dispatches each
+   rule to the files matching its `language`. JSON dependency rules use
+   `files:` globs to scope to `package.json` / `composer.json`.
+2. Add `before/` + `after/` (and optional `customized/`) fixture subtrees under
+   `migrations/__fixtures__/<version>/`.
+3. Register it in `migrations/index.json` (`id` = the version, `appliesTo`, `rules`).
+
+The runner and the test suite are generic — no code changes needed. Migrations
+are **idempotent** (re-running is a no-op) and **conservative** (anything that
+doesn't match the targeted shape is left untouched).
+
+## Develop & test
+
+```sh
+pnpm install        # pulls the ast-grep engine
+pnpm test           # golden tests: before→after byte-match, idempotency, no-op safety
+```

package/bin/webentor-codemods.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * @webikon/webentor-codemods — reusable codemod runner for Webentor Stack
+ * consumer projects.
+ *
+ * A thin wrapper around the bundled `ast-grep` engine (via the `@ast-grep/cli`
+ * dependency). Codemods live in `migrations/<id>/rules/*.yml` and are registered
+ * in `migrations/index.json`. The runner is intentionally generic: adding a new
+ * migration is just a new folder + an index entry — no runner changes needed.
+ *
+ * Usage (run from your project root):
+ *   webentor-codemods list
+ *   webentor-codemods run <id> [--path <dir>] [--apply]
+ *   webentor-codemods run --since <ver> [--to <ver>] [--package <name>] [--path <dir>] [--apply]
+ *
+ * Dry-run by default (prints the diff). Pass --apply to write changes.
+ */
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const MIGRATIONS_DIR = join(PKG_ROOT, 'migrations');
+
+function fail(msg) {
+  console.error(`webentor-codemods: ${msg}`);
+  process.exit(1);
+}
+
+/** Resolve the bundled ast-grep binary shipped via @ast-grep/cli. */
+function astGrepBin() {
+  try {
+    const pkgJson = require.resolve('@ast-grep/cli/package.json');
+    const bin = join(dirname(pkgJson), 'ast-grep');
+    if (existsSync(bin)) return bin;
+  } catch {
+    /* fall through to PATH */
+  }
+  return 'ast-grep'; // last resort: rely on PATH
+}
+
+function loadRegistry() {
+  const indexPath = join(MIGRATIONS_DIR, 'index.json');
+  if (!existsSync(indexPath)) fail(`migrations registry not found at ${indexPath}`);
+  try {
+    return JSON.parse(readFileSync(indexPath, 'utf8'));
+  } catch (e) {
+    fail(`could not parse migrations/index.json: ${e.message}`);
+  }
+}
+
+/** Parse a loose "x.y.z" semver into a comparable tuple. Missing parts -> 0. */
+function parseVer(v) {
+  const parts = String(v ?? '0')
+    .replace(/^[^\d]*/, '')
+    .split('.')
+    .map((n) => parseInt(n, 10) || 0);
+  return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+}
+
+function cmpVer(a, b) {
+  const x = parseVer(a);
+  const y = parseVer(b);
+  for (let i = 0; i < 3; i++) {
+    if (x[i] !== y[i]) return x[i] - y[i];
+  }
+  return 0;
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+function printList(registry) {
+  const migrations = registry.migrations ?? [];
+  if (!migrations.length) {
+    console.log('No migrations registered.');
+    return;
+  }
+  console.log('Available migrations:\n');
+  for (const m of migrations) {
+    const at = m.appliesTo
+      ? ` (${m.appliesTo.package} ${m.appliesTo.from} → ${m.appliesTo.to})`
+      : '';
+    console.log(`  ${m.id}${at}`);
+    if (m.title) console.log(`    ${m.title}`);
+    if (m.description) console.log(`    ${m.description}`);
+    console.log('');
+  }
+}
+
+/** Run a single migration's rules (in declared order) against targetPath. */
+function runMigration(migration, { targetPath, apply }) {
+  const bin = astGrepBin();
+  const migDir = join(MIGRATIONS_DIR, migration.id);
+  const rules = migration.rules ?? [];
+  if (!rules.length) fail(`migration "${migration.id}" declares no rules`);
+
+  console.log(
+    `\n▶ ${migration.id}${apply ? ' (apply)' : ' (dry-run — pass --apply to write)'}`,
+  );
+  let anyError = false;
+  for (const rel of rules) {
+    const rulePath = join(migDir, rel);
+    if (!existsSync(rulePath)) fail(`rule file not found: ${rulePath}`);
+    const args = ['scan', '--rule', rulePath];
+    if (apply) args.push('--update-all');
+    args.push(targetPath);
+    const res = spawnSync(bin, args, { stdio: 'inherit' });
+    if (res.error) {
+      console.error(`  failed to run ast-grep: ${res.error.message}`);
+      anyError = true;
+    } else if (res.status !== 0) {
+      anyError = true;
+    }
+  }
+  return !anyError;
+}
+
+function resolveMigrationsToRun(registry, flags, positional) {
+  const migrations = registry.migrations ?? [];
+
+  // `run --since <ver> [--to <ver>] [--package <name>]`
+  if (flags.since) {
+    const pkg = flags.package || 'webentor-core';
+    const from = flags.since;
+    const to = flags.to || '999.999.999';
+    const selected = migrations.filter((m) => {
+      if (!m.appliesTo || m.appliesTo.package !== pkg) return false;
+      // Apply migrations whose target ("to") version is in (from, to].
+      return cmpVer(m.appliesTo.to, from) > 0 && cmpVer(m.appliesTo.to, to) <= 0;
+    });
+    if (!selected.length) {
+      console.log(
+        `No migrations for ${pkg} in range (${from}, ${to}]. Nothing to do.`,
+      );
+    }
+    return selected;
+  }
+
+  // `run <id>`
+  const id = positional[0];
+  if (!id) fail('run requires a migration <id>, or --since <ver>');
+  const found = migrations.find((m) => m.id === id);
+  if (!found) fail(`unknown migration "${id}". Run "webentor-codemods list".`);
+  return [found];
+}
+
+function main() {
+  const [, , command, ...rest] = process.argv;
+  const { positional, flags } = parseArgs(rest);
+
+  if (!command || command === 'help' || flags.help) {
+    console.log(
+      [
+        'webentor-codemods — reusable codemods for Webentor Stack consumer projects',
+        '',
+        'Commands:',
+        '  list                                  List available migrations',
+        '  run <id> [--path <dir>] [--apply]     Run one migration (dry-run by default)',
+        '  run --since <ver> [--to <ver>]        Run every migration in a version range',
+        '       [--package <name>] [--path <dir>] [--apply]',
+        '',
+        'Run from your project root; --path defaults to the current directory.',
+      ].join('\n'),
+    );
+    process.exit(command ? 0 : 1);
+  }
+
+  const registry = loadRegistry();
+
+  if (command === 'list') {
+    printList(registry);
+    return;
+  }
+
+  if (command === 'run') {
+    const targetPath = resolve(flags.path || process.cwd());
+    if (!existsSync(targetPath)) fail(`--path does not exist: ${targetPath}`);
+    const apply = Boolean(flags.apply);
+    const toRun = resolveMigrationsToRun(registry, flags, positional);
+    let ok = true;
+    for (const m of toRun) {
+      if (!runMigration(m, { targetPath, apply })) ok = false;
+    }
+    if (!apply && toRun.length) {
+      console.log('\nDry-run complete. Re-run with --apply to write changes.');
+    }
+    process.exit(ok ? 0 : 1);
+  }
+
+  fail(`unknown command "${command}". Run "webentor-codemods help".`);
+}
+
+main();

package/migrations/0.13.0/README.md

@@ -0,0 +1,99 @@
+# `0.13.0` — upgrade a consumer theme to webentor-core 0.13.0
+
+**Applies to:** consumer themes moving `webentor-core` `0.12.x` → `0.13.0`
+(WordPress 7.0 / PHP 8.4 compatibility pass).
+
+Run from your project root:
+
+```sh
+pnpm dlx @webikon/webentor-codemods run 0.13.0          # preview (dry-run)
+pnpm dlx @webikon/webentor-codemods run 0.13.0 --apply  # apply
+```
+
+Then reinstall + rebuild + clear caches:
+
+```sh
+# in the theme dir
+pnpm install && composer update
+pnpm build
+wp acorn optimize:clear
+```
+
+This migration has two rule sets: an **editor-asset enqueue** change to
+`app/setup.php`, and a **dependency** bump set across `package.json` +
+`composer.json`.
+
+## 1. Editor-asset enqueue (`rules/editor-enqueue-iframe.yml`, PHP)
+
+Since WP 6.9/7.0 the block editor renders inside an iframe. Global canvas styles
+must be registered on `enqueue_block_assets` (not `enqueue_block_editor_assets`)
+so WordPress routes them **into** the iframe — otherwise it warns the style was
+"added to the iframe incorrectly" and the styles never reach the canvas (e.g.
+button styles missing in the editor). The editor **JavaScript** still belongs on
+`enqueue_block_editor_assets` (it loads in the outer editor document).
+
+In the theme's `app/setup.php`:
+
+```php
+add_action('enqueue_block_editor_assets', function (): void {
+    $dependencies = …;
+    \Kucrut\Vite\enqueue_asset(…, 'resources/scripts/editor.ts', …);        // JS
+    \Kucrut\Vite\enqueue_asset(…, 'resources/styles/editor.css', …);        // CSS
+    \Kucrut\Vite\enqueue_asset(…, 'resources/core-components/button/button.style.css', …); // CSS
+}, 10);
+```
+
+becomes:
+
+```php
+add_action('enqueue_block_editor_assets', function (): void {
+    $dependencies = …;
+    \Kucrut\Vite\enqueue_asset(…, 'resources/scripts/editor.ts', …);        // JS stays
+}, 10);
+
+add_action('enqueue_block_assets', function (): void {
+    if (!is_admin()) {
+        return;
+    }
+    \Kucrut\Vite\enqueue_asset(…, 'resources/styles/editor.css', …);        // CSS moved
+    \Kucrut\Vite\enqueue_asset(…, 'resources/core-components/button/button.style.css', …); // CSS moved
+}, 10);
+```
+
+The `enqueue_asset` directory + options arguments are preserved verbatim (matched
+via metavariables), so per-project tweaks to those options survive.
+
+- **Idempotent / conservative:** an already-migrated `setup.php` (no styles left
+  on that hook) does not match; a heavily customized hook also won't match and is
+  left untouched — migrate it by hand using the before/after above.
+
+## 2. Dependencies (`rules/deps.yml`, JSON)
+
+Rewrites the theme's dependency ranges to the **0.13.0 baseline** — the complete
+set that changed from theme 2.0.6 / core 0.12 → 0.13. Each rule matches a
+dependency by its exact key (with a value-is-string guard, so config objects that
+share a name like `lint-staged`/`prettier`/`stylelint` are never touched) and is
+scoped to `package.json` / `composer.json` via `files:`.
+
+| manifest | dependency | → range |
+|---|---|---|
+| package.json + composer.json | webentor-core | `^0.13.0` / `^0.13` |
+| package.json | `@wordpress/components` (major 30→35) | `^35.0.1` |
+| package.json | `@wordpress/icons` (major 11→14) | `^14.0.1` |
+| package.json | `stylelint` (major 16→17) | `^17.13.0` |
+| package.json | `stylelint-config-recommended` (major 17→18) | `^18.0.0` |
+| package.json | `@types/wordpress__block-editor` (major 14→15) | `^15.0.6` |
+| package.json | `prettier-plugin-tailwindcss` (0.7→0.8) | `^0.8.0` |
+| package.json | other `@wordpress/*`, `tailwindcss`/`@tailwindcss/*`, `@10up/block-components`, `@alpinejs/intersect`, `@vitejs/plugin-react`, `@roots/vite-plugin`, `vite`, `prettier`, `postcss`, `typescript-eslint`, `eslint`/`@eslint/js`, `eslint-plugin-prettier`, `lint-staged`, `@ianvs/prettier-plugin-sort-imports`, `@shufo/prettier-plugin-blade` | 0.13.0 ranges |
+
+**Held back (not changed):** `react`/`react-dom` (18 — WordPress runtime is React
+18), `eslint`/`@eslint/js` major (10 — blocked by `eslint-plugin-react`), `vite`
+major (8), `typescript` major (6), `lint-staged` major (17 — needs Node 22).
+`name`/`version` are never touched.
+
+- **Idempotent:** re-running rewrites to the same range → no diff.
+- **Baseline caveat:** the fix pins the 0.13.0 ranges, so a project already
+  *ahead* of the baseline within a major would be set back to it. Expected for a
+  0.12 → 0.13 upgrade; adjust by hand if you intentionally run newer.
+
+After applying, run `pnpm install` + `composer update` to refresh the lockfiles.