a3ae2c2f5327d6bf23b94129b786102d5cbdd67c diff --git a/content/blog/sama-v2-wordpress-plugin-audit.md b/content/blog/sama-v2-wordpress-plugin-audit.md new file mode 100644 index 0000000000000000000000000000000000000000..aa1a81cc4db509e9ef471fd122388acf4fd2030e --- /dev/null +++ b/content/blog/sama-v2-wordpress-plugin-audit.md @@ -0,0 +1,148 @@ +# Pointing SAMA v2 at a real WordPress plugin in the wild + +Earlier today I published [/sama/v2/example-wordpress](/sama/v2/example-wordpress) — a hypothetical event-registration plugin laid out under the v2 discipline. Hypothetical examples are easy: you design the layers and then describe a codebase that fits them. The harder question is what v2 sees when you point it at code that **wasn't** designed under any layer discipline at all. + +So I picked one. **Open Graph and Twitter Card Tags** by WPExperts (the plugin formerly known as Wonderm00n's, slug `wonderm00ns-simple-facebook-open-graph-tags`) — 200k+ active installs, ten-plus years of git history, the canonical "small useful plugin" shape that WordPress is full of. Downloaded the latest release (v3.4.0), unzipped, walked the source. + +This isn't a takedown. The plugin works. It ships. It does exactly what its name says. The question this post answers is: *if a PHP-aware SAMA v2 verifier existed, what would it report against this codebase?* + +## What's actually in the box + +Total: **6,445 lines of PHP** across 17 source files (excluding the WordPress `index.php` security stubs and the vendored Post-SMTP-recommendation library). + +The architecture, at a glance: + +``` +wonderm00n-open-graph.php 83 lines # WP entry — header, includes, uninstall hook +fbimg.php 224 lines # standalone helper (referenced from a URL) +includes/ + class-webdados-fb-open-graph.php 674 lines # CORE: hook registration, options loading +admin/ + class-webdados-fb-open-graph-admin.php 784 lines # ADMIN: settings save, FB debug call + options-page-facebook.php 556 lines # admin UI tab (HTML + HTTP + JSON parsing) + options-page-general.php 486 lines # admin UI tab + options-page-3rdparty.php 386 lines # admin UI tab + options-page-schema.php 261 lines # admin UI tab + options-page.php 246 lines # admin UI wrapper + options-page-twitter.php 188 lines # admin UI tab + options-page-seo.php 123 lines # admin UI tab + options-page-right.php 73 lines # admin UI sidebar + options-page-tools.php 51 lines # admin UI tab + options-page-recommend-post-smtp.php 34 lines # admin UI tab +public/ + class-webdados-fb-open-graph-public.php 1,554 lines # PUBLIC: the actual og:* + twitter:* + schema rendering +``` + +Three god-classes (core, admin, public), each owning a vertical slice of feature work end-to-end. Around them, eleven `options-page-*.php` files that mix HTML, business logic, HTTP, and JSON parsing in the same callback. No layer separation, no test files anywhere in the source (zero `*test*.php` files in the entire archive). + +This is normal WordPress. Most plugins in the directory look like this. + +## What the v2 verifier would report + +Walking each of the seven §4 conformance checks against what's in the source: + +### #1 Sorted + +> *Every file carries a profile-recognised prefix; lexicographic prefix order equals layer order.* + +The plugin has no prefix scheme at all. File names follow `class-vendor-feature-area.php` and `options-page-tab.php` patterns; their alphabetical sort has no relation to architectural layer. **Would fail** on every non-index source file. + +### #2 Architecture + +> *Every file maps to exactly one canonical layer; no file is unprefixed or maps to two layers.* + +Without a profile mapping any prefix to a canonical layer, **every file would be flagged unprefixed**. Even if we tried to retrofit a profile — say `class-*-public.php` → Layer 1, `class-*-admin.php` → Layer 1 — the single file behind that pattern does enough Layer 2 work (HTTP, DB, JSON parsing) that the mapping wouldn't be honest. + +### #3 Modeled (tests) + +> *Every Layer 1 and Layer 2 behavior file has a sibling test file.* + +Zero test files in the archive. The plugin has no unit tests at all — `grep -r 'PHPUnit\|TestCase' /tmp/wonderm00ns-*` returns nothing. **Would fail** the moment any source file is mapped to Layer 1 or 2. + +### #4 Modeled (boundary) + +> *External input is parsed only in Layer 2.* + +This is where it gets interesting. Boundary patterns are scattered, not localised: + +- **HTTP outbound** — `wp_remote_get(...)` lives in `admin/class-webdados-fb-open-graph-admin.php:464` (calling Facebook's Graph debug API) AND in `admin/options-page-facebook.php:307` (calling Facebook's translation XML) AND in `public/class-webdados-fb-open-graph-public.php:1301` (fetching remote images). Three different files, three different layers conceptually. +- **JSON parsing** — `json_decode` lives in `admin/class-webdados-fb-open-graph-admin.php:475` AND `admin/options-page-facebook.php:364`. Mixed with HTML output in the second case. +- **Filesystem reads** — `file_get_contents()` against a bundled XML file in `admin/options-page-facebook.php:339`. Same file mixes this with HTTP, JSON parsing, and direct HTML echoing. +- **Superglobals** — **43 raw `$_POST` / `$_GET` / `$_REQUEST` accesses** across the codebase. Most of them in admin classes, but the pattern is "wherever a hook needs to read the request, just touch the superglobal directly." + +A boundary-ratio metric here would be near-zero: parsing happens almost anywhere except in a dedicated adapter layer (because there isn't one). + +### #5 Atomic + +> *No file exceeds the line cap (default ~700; profile may lower, never raise). No barrel re-export files.* + +Three files over the 700-line cap: + +- `public/class-webdados-fb-open-graph-public.php` — **1,554 lines** (220% of cap) +- `admin/class-webdados-fb-open-graph-admin.php` — **784 lines** (112%) +- `includes/class-webdados-fb-open-graph.php` — 674 lines (just under, but close) + +The 1,554-line public class is a textbook example of what §4.5 was written to prevent. Inside that one file: OG tag generation, Twitter Card generation, Schema.org JSON-LD generation, image URL resolution, image dimension caching, remote image fetching via `wp_remote_get`, WooCommerce product handling, multilingual locale logic, third-party SEO plugin compatibility (Yoast, AIOSEO), and the WP filter callbacks that wire it all up. Each of those is a sublayer or a separate file under v2. + +### #6 The Law (§1.2) + +> *Imports always point to a strictly lower layer number — never upward, never sideways across a higher number, never cyclic.* + +PHP `require_once` does exist as an import edge, but without a profile mapping the verifier has nothing to check against. The architectural spirit of §1.2 — that lower concerns shouldn't reach into higher ones — is violated structurally: the **entry file itself** (`wonderm00n-open-graph.php`) contains direct `$wpdb->query("DELETE FROM ...")` calls in the uninstall hook. The Pure layer doesn't exist; the Adapter layer is everywhere. + +### #7 Consistency (§3) + +> *No file's imports contradict its declared layer.* + +Vacuous — there are no declared layers to contradict. + +**Summary score:** 0 of 7 checks would pass. Which is not surprising and not the point. The plugin wasn't built under v2; you can't grade an essay against rules its author never opted into. + +## Estimated §5 metrics + +A PHP-aware metrics emitter doesn't exist yet, but the values can be estimated by hand against the operational definitions on [/sama/v2 §5](/sama/v2#5-operational--core-metrics-definitions): + +| metric | this plugin (estimated) | tdd.md (measured) | +|---|---|---| +| **graphDepth** | ~3 (entry → core → public/admin classes; very flat, almost no transitive depth) | 7 | +| **boundaryRatio** | <10% (no dedicated adapter sublayer — parsing is spread across admin classes, UI pages, the entry file, and the public class) | 100% | +| **workingSetFit** (50 ≤ LOC ≤ 500) | ~47% (8 of 17 non-index source files in the sweet spot; three big god-classes drag it down) | 80% | +| **violationCounts** (sum) | 17+ Atomic, dozens of boundary, ~17 Architecture | 0 | + +The interesting comparison isn't ✓ vs ✗ — that's the compliance score §5 explicitly tells us *not* to lead with. The interesting comparison is the **delta on the same metric axes**. Compliance proves the rules were followed; the delta is the variable that proves whether following them was worth the cost. + +## What v2 makes visible that the existing code hides + +Three architectural facts the v2 lens surfaces: + +**1. The 1,554-line public class is doing seven jobs at once.** Under v2, the rendering of `og:*` tags, Twitter Cards, Schema.org JSON-LD, image-URL resolution, third-party SEO compatibility, and WooCommerce-specific behaviour would each live in their own Core (`b*_`) file with a sibling test. Today, changing one of them risks touching all of them, and there's no test fixture to catch a regression. A PR review on this file is essentially trust-based — the LOC budget is too big to read end-to-end. + +**2. The 43 superglobal accesses mean every change to a settings field is a hand-traced refactor.** Without a `c3_*` controller sublayer that owns "how a settings POST becomes a typed value," the validation logic is duplicated across `options-page-*.php` files. An agent asked to add a new settings option has to find every place the related field is touched. v2's boundary rule reduces that to one file by construction. + +**3. `$wpdb` inside the entry file (uninstall hook).** Under v2 this is `c1_*` work in an adapter file with a sibling test that asserts what gets deleted. Today it's an inline closure that runs once per uninstall, no test, and a future change to the schema requires editing a string literal inside a `wp_*` function. The Law check would catch this in v2 land; under stock WP idioms there's nothing to push back. + +## The honest interpretation + +A v2-aware reviewer looking at this plugin doesn't conclude *"this code is bad."* They conclude: + +- The plugin is shaped exactly like WordPress's official patterns push you to shape it. WP teaches: register hooks at the top, do work in their callbacks, use `$wpdb` when you need to read or write data. There is no built-in pressure toward layer separation; in fact, the `add_action` / `add_filter` inversion-of-control pattern actively encourages mixing wiring with logic. +- 0 of 7 checks passing is the **expected baseline** for code written under WP idioms with no external discipline. Most plugins in the repository score the same. That's not a SAMA failure — that's the data point that lets us measure the delta if we ever do build a plugin under v2 from scratch. +- The PR that this post would generate — if I'd been the maintainer — wouldn't be "refactor everything." It would be one specific extraction: pull the 1,554-line public class apart into seven files of 200-300 lines each, each with a sibling unit test. The §5 metrics would shift measurably on that one refactor; the user-facing behaviour wouldn't change at all. + +## What this exercise actually buys us + +Now there are two profile snapshots in the world: this site's own `tdd-md` profile (TypeScript, scoring 7/7 ✓ on §4 with graphDepth=7, boundaryRatio=100%, workingSetFit=80%), and this hand-estimated WordPress plugin (PHP, scoring 0/7 with graphDepth≈3, boundaryRatio<10%, workingSetFit≈47%). + +That's still only n=2 and across different languages, so it's a long way from "v2 is empirically worth following." But it's the first data point where a real codebase that was **not** designed under v2 gets measured on the same axes. Future work — a v2-discipline plugin built from scratch, or a real refactor of one of the god-classes here — would let the delta speak for itself. + +The chain extended one more link today: from *"here is the spec and a hypothetical worked example"* to *"here is the spec, here is what a real plugin in the wild looks like through this lens, here is what the §5 metrics would say if a PHP-aware verifier existed."* The PHP-aware verifier itself is the next piece of cable. + +--- + +**See for yourself:** + +- The plugin: +- The v2 hypothetical plugin profile: [/sama/v2/example-wordpress](/sama/v2/example-wordpress) +- The §5 metric definitions: [/sama/v2#5-operational--core-metrics-definitions](/sama/v2#5-operational--core-metrics-definitions) +- Today's earlier post on the §5 emitter: [Compliance proves the rules were followed. Delta proves they were worth following.](/blog/sama-v2-metrics-emitter) +- Yesterday's post on building the v2 verifier: [I built the SAMA v2 verifier...](/blog/sama-v2-verifier-and-the-rename) diff --git a/src/a31_blog.ts b/src/a31_blog.ts index 9fa42f6fd7e8d3e37c408612be7ac1087cd99a9b..5f7abbec7804bef7ad2d0d07169d7f9b857162ea 100644 --- a/src/a31_blog.ts +++ b/src/a31_blog.ts @@ -12,6 +12,12 @@ export interface BlogEntry { } export const ALL_POSTS: BlogEntry[] = [ + { + slug: "sama-v2-wordpress-plugin-audit", + title: "Pointing SAMA v2 at a real WordPress plugin in the wild", + description: "The hypothetical example at /sama/v2/example-wordpress was easy — you design the layers, then describe a codebase that fits. The harder question is what v2 sees when pointed at code that was NOT designed under any layer discipline. Picked Open Graph and Twitter Card Tags (200k+ installs, 6,445 PHP lines), downloaded the actual source, walked it. Walking the seven §4 conformance checks: 0 of 7 would pass — not because the plugin is bad, but because WordPress's hook/filter idioms actively push devs toward this shape (god-classes, $wpdb scattered across layers, 43 raw superglobal accesses, a 1,554-line public class doing seven jobs at once). The interesting comparison isn't compliance ✓/✗ — it's the §5 metric deltas: this plugin would score graphDepth≈3, boundaryRatio<10%, workingSetFit≈47% against tdd.md's 7, 100%, 80%. That's not 'v2 is empirically worth following' yet — n=2 across different languages, the PHP verifier doesn't exist, the delta is just numbers — but it IS the first real-world data point measured on the same axes our own dogfood scores against.", + date: "2026-05-23", + }, { slug: "sama-v2-metrics-emitter", title: "Compliance proves the rules were followed. Delta proves they were worth following.",