Merge pull request #123 from Hypercart-Dev-Tools/development

Development to Main - Add new test fixtures

Author: noelsaw1

4X4.md

@@ -47,6 +47,8 @@ WP Code Check is a zero-dependency static analysis toolkit for WordPress perform
 - [x] Added Path B observability for aggregated magic-string patterns - phase timing and quality counters are now visible in text and JSON output.
 - [x] Fixed stale-registry fallback behavior - eliminated one apparent hang path in the pattern loader and guarded empty search patterns.
 - [x] Fixed high-noise direct-pattern false positives - reduced `php-shell-exec-functions`, `spo-002-superglobals`, and `php-dynamic-include` noise with targeted scanner and pattern fixes.
+- [x] Cleared all deferred items from CR self-service feedback review — added admin-only hook whitelist for `spo-004` (downgrade to INFO) and strengthened N+1 loop detection with brace-depth lexical containment in `find_meta_in_loop_line()`.
+- [x] Round 2 FP reduction pass on CR self-service scan — tightened `limit-multiplier-from-count` pattern (24 → 0 FPs), added `skip_if_context_matches` to suppress non-GET `rest-no-pagination` endpoints (16 → 8), and cross-rule dedup for superglobal rules (eliminated 23 duplicates). Total findings: **99 → 31**.
 - [ ] Phase 0b observability remains incomplete - heartbeat output and slow-check rollups are still deferred and need a focused pass.
 
 ---

AGENTS.md

@@ -1,6 +1,6 @@
 # WordPress Development Guidelines for AI Agents
 
-_Last updated: v2.2.0 — 2026-01-15_
+_Last updated: v2.2.9 — 2026-03-24_
 
 You are a seasoned CTO with 25 years of experience. Your goal is to build usable v1.0 systems that balance time, effort, and risk. You do not take shortcuts that incur unmanageable technical debt. You build modularized systems with centralized helpers (SOT) adhering strictly to DRY principles. Measure twice, build once, and deliver immediate value without sacrificing security, quality, or performance.
 
@@ -23,6 +23,51 @@ This document defines the principles, constraints, and best practices that AI ag
 
 ## 🤖 Project-Specific AI Tasks
 
+### WP Code Check Scanner — Quick Reference
+
+WP Code Check is a zero-dependency static analysis toolkit for WordPress. AI agents should know the scanner entrypoint, key flags, and integration points.
+
+**Scanner CLI:**
+```bash
+dist/bin/check-performance.sh --paths /path/to/plugin --format json
+```
+
+**Key flags:**
+| Flag | Purpose |
+|------|---------|
+| `--paths <dir>` | Directory to scan (required) |
+| `--format json\|text` | Output format (default: json, generates HTML report) |
+| `--strict` | Fail on warnings (useful for CI) |
+| `--no-log` | Suppress file logging (JSON still goes to stdout) |
+| `--generate-baseline` | Generate baseline for legacy code suppression |
+| `--project <name>` | Use a saved template configuration |
+| `--severity-config <path>` | Custom severity overrides |
+
+**Output locations:**
+- JSON logs: `dist/logs/[TIMESTAMP].json`
+- HTML reports: `dist/reports/[TIMESTAMP].html`
+- HTML from JSON: `python3 dist/bin/json-to-html.py <input.json> <output.html>`
+
+**MCP Server (Model Context Protocol):**
+WPCC includes an MCP server at `dist/bin/mcp-server.js` that exposes scan results to AI assistants (Claude Desktop, Cline, etc.). Configure in your MCP client:
+```json
+{
+  "mcpServers": {
+    "wp-code-check": {
+      "command": "node",
+      "args": ["/absolute/path/to/wp-code-check/dist/bin/mcp-server.js"]
+    }
+  }
+}
+```
+See [MCP-README.md](dist/bin/MCP-README.md) for full setup.
+
+**End-to-end workflow:** For scan → AI triage → HTML report → GitHub issue, see [_AI_INSTRUCTIONS.md](dist/TEMPLATES/_AI_INSTRUCTIONS.md).
+
+**Pattern library:** JSON pattern definitions live in `dist/patterns/*.json`. Each has an `id`, `severity`, `search_pattern`, and optional `exclude_patterns`.
+
+---
+
 ### Template Completion for Performance Checks
 
 This project includes a **Project Templates** feature (alpha) that allows users to save configuration for frequently-scanned WordPress plugins/themes. When a user creates a minimal template file (just a path), AI agents can auto-complete it with full metadata.

CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### Changed
+
+- Admin-only hook whitelist for `spo-004-missing-cap-check`: `add_action()` calls using inherently-admin-only hooks (`admin_notices`, `admin_init`, `admin_menu`, `admin_head`, `admin_footer`, `admin_enqueue_scripts`, `admin_print_styles`, `admin_print_scripts`, `network_admin_menu`, `user_admin_menu`, `network_admin_notices`, `admin_bar_init`, `admin_action_*`, `load-*`) are now downgraded to INFO severity instead of HIGH, reducing false positives for capability check findings
+
+- N+1 loop detection (`find_meta_in_loop_line`) now uses brace-depth tracking to verify `get_*_meta` calls are lexically inside a loop body, not just within 80 lines of a loop keyword. Eliminates false positives from sequential meta calls after loop closure
+
+- Tightened `limit-multiplier-from-count` JSON pattern to require `count(...) * <number>` instead of matching any `count()` call. Eliminates false positives from display/comparison uses of `count()`
+
+- `rest-no-pagination` now skips non-GET endpoints (POST, PUT, DELETE, PATCH) via new `skip_if_context_matches` scripted runner feature. Reduces false positives on action/mutation endpoints where pagination is inapplicable
+
+- Cross-rule deduplication for overlapping superglobal findings (`spo-002-superglobals`, `unsanitized-superglobal-read`, `unsanitized-superglobal-isset-bypass`). When the same file:line is flagged by multiple rules, only the first finding is kept
+
+### Fixed
+
+- N+1 pattern findings now include the actual source code line in the report. Previously the `code` field was empty because `find_meta_in_loop_line` only returned the line number without extracting the source text
+
+### Tests
+
+- Added false-positive guard cases to `n-plus-one-optimized.php` fixture: sequential `get_user_meta()` calls after loop closure should not be flagged
+- Expanded `limit-multiplier-from-count.php` fixture with display, comparison, and assignment uses of `count()` that should not match the multiplier pattern
+- Added admin-only hook whitelist cases to `admin-no-capability.php` fixture: `admin_notices`, `admin_init`, `admin_menu` hooks should be INFO, not HIGH
+
+### Documentation
+
+- Added "WP Code Check Scanner — Quick Reference" section to `AGENTS.md` with CLI flags, MCP server configuration, output locations, and pattern library pointer for AI agent discoverability
+
 ## [2.2.9] - 2026-03-23
 
 ### Added

CLAUDE.md

@@ -0,0 +1 @@
+Please review AGENTS.md for instructions that Claude Code should follow.