Merge pull request #16 from Hypercart-Dev-Tools/arechitecture/refactor-2025-12-31

Arechitecture/refactor to Development

Author: noelsaw1

.gitignore

@@ -28,6 +28,15 @@ dist/TEMPLATES/*.txt
 *.hcc-baseline
 **/.hcc-baseline
 
+# IRL (In Real Life) examples - user-generated real-world code samples
+# Keep: folder structure and documentation
+# Ignore: actual code files (may contain proprietary code)
+dist/tests/irl/*
+!dist/tests/irl/
+!dist/tests/irl/README.md
+!dist/tests/irl/_AI_AUDIT_INSTRUCTIONS.md
+!dist/tests/irl/.gitkeep
+
 # ============================================
 # DEVELOPMENT & TESTING
 # ============================================

CHANGELOG.md

@@ -5,6 +5,198 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.69] - 2026-01-01
+
+### Added
+- **Pattern Library JSON Files** - Created 3 new pattern definition files
+  - `dist/patterns/unsanitized-superglobal-read.json` - Direct superglobal access without sanitization (HIGH severity)
+  - `dist/patterns/wpdb-query-no-prepare.json` - Database queries without prepare() (CRITICAL severity)
+  - `dist/patterns/get-users-no-limit.json` - Unbounded user queries (CRITICAL severity)
+  - **Purpose:** Separate pattern definitions from scanner logic for modularity and community contributions
+  - **Schema:** Each includes detection logic, test fixtures, IRL examples, remediation guidance, references
+  - **IRL Examples:** All 3 patterns include real-world examples from WP Activity Log v5.5.4
+  - **Total Patterns:** 4 JSON files (including existing `unsanitized-superglobal-isset-bypass.json`)
+
+- **WP Activity Log IRL Examples** - 3 annotated files from production security plugin
+  - `dist/tests/irl/wp-security-audit-log/class-select2-wpws-irl.php` (530 lines)
+    - 2 unbounded get_users() violations (lines 230, 444)
+    - AJAX user search without limits - can crash sites with 10k+ users
+  - `dist/tests/irl/wp-security-audit-log/class-wp-security-audit-log-irl.php` (1,517 lines)
+    - 1 unsanitized superglobal read (line 1261)
+    - Type juggling vulnerability in plugin visibility control
+  - `dist/tests/irl/wp-security-audit-log/class-migration-irl.php` (1,527 lines)
+    - 1 direct database query without prepare() (line 226)
+    - SQL injection risk in migration function
+  - **Total:** 3,574 lines of annotated production code
+  - **Detection Rate:** 100% - Scanner found all 3 documented violations plus 57 additional issues
+  - **Summary Document:** `PROJECT/WP-SECURITY-AUDIT-LOG-IRL-SUMMARY.md`
+
+### Changed
+- **Pattern JSON Files:** Now 4 total pattern definitions (was 1)
+  - Existing: `unsanitized-superglobal-isset-bypass.json` (isset-bypass variant)
+  - New: `unsanitized-superglobal-read.json` (direct read variant)
+  - New: `wpdb-query-no-prepare.json` (SQL injection)
+  - New: `get-users-no-limit.json` (performance)
+  - **Note:** These are distinct patterns, not duplicates
+
+### Documentation
+- **Pattern JSON Schema:** Each file includes:
+  - Pattern ID, version, severity, category
+  - Detection logic (grep patterns, exclusions, post-processing)
+  - Test fixture path and expected violation counts
+  - IRL examples with file, line, plugin, code, context, risk assessment
+  - Remediation examples (bad vs good code)
+  - References to WordPress documentation
+  - Performance impact analysis (for performance patterns)
+  - False positive guidance
+
+## [1.0.68] - 2026-01-01
+
+### Added
+- **IRL (In Real Life) Examples System** - Real-world code examples from production plugins/themes
+  - **Purpose:** Validate patterns exist in production, discover new anti-patterns, document real vulnerabilities
+  - **Structure:** `dist/tests/irl/plugin-name/filename-irl.php` with inline audit annotations
+  - **Filename Conventions:**
+    - `-irl.php` = Fully audited with annotations and pattern library updated
+    - `-inbox.php` = Quick capture for later processing (no annotations yet)
+  - **Annotation Format:** File header summary + inline comments at each anti-pattern
+  - **Examples Added:**
+    - WooCommerce All Products for Subscriptions v6.0.6 - `class-wcs-att-admin-irl.php` (1 violation)
+    - KISS Woo Coupon Debugger v2.1.0 - `AdminUI-irl.php` (2 violations)
+  - **User-Submitted Code:** Users can copy PHP/JS files from their own projects for AI analysis
+  - **Documentation:** `dist/tests/irl/README.md` and `dist/tests/irl/_AI_AUDIT_INSTRUCTIONS.md`
+
+- **Baseline Files Generated** - Suppress known issues for ongoing monitoring
+  - KISS Debugger: 22 findings baselined
+  - WooCommerce All Products for Subscriptions: 73 findings baselined
+  - Purpose: Track new issues without noise from existing known issues
+
+- **Pattern Library Separation (Integrated!)** - First pattern now loads from JSON
+  - **Pattern Definitions:** JSON files in `dist/patterns/` directory
+  - **Pattern Loader:** `dist/lib/pattern-loader.sh` - Bash library to load patterns from JSON
+  - **First Pattern:** `unsanitized-superglobal-isset-bypass.json` with full metadata
+  - **Schema:** Pattern ID, version, severity, detection logic, test fixtures, IRL examples, remediation
+  - **Integration:** Scanner now loads `unsanitized-superglobal-isset-bypass` pattern from JSON (line 1529-1540)
+  - **Fallback:** If JSON not found, falls back to hardcoded values (graceful degradation)
+  - **Benefits:** Modularity, versioning, easier testing, community contributions
+  - **Status:** ✅ Integrated - one pattern using JSON, remaining 32 patterns still hardcoded
+
+### Changed
+- **Pattern JSON:** Updated `unsanitized-superglobal-isset-bypass.json` with 3 IRL examples
+  - WooCommerce All Products for Subscriptions: Line 451 (isset bypass in admin scripts)
+  - KISS Debugger: Line 434 (boolean cast without sanitization)
+  - KISS Debugger: Line 472 (string comparison without sanitization)
+  - Each includes: plugin name, version, context, original line number
+- **Gitignore:** Added rules for IRL folder
+  - Keeps: `dist/tests/irl/`, `README.md`, `_AI_AUDIT_INSTRUCTIONS.md`, `.gitkeep`
+  - Ignores: All user-created IRL example files (may contain proprietary code)
+  - Rationale: Users can collect real-world examples without committing them to public repo
+
+### Fixed
+- **Version Number:** Updated SCRIPT_VERSION to 1.0.68 (was showing 1.0.66)
+- **Bash Error:** Removed `local` keyword outside function (line 434) - was causing error on script start
+
+## [1.0.67] - 2026-01-01
+
+### Fixed
+- **CRITICAL BUG: Path Quoting in Grep Commands** - Fixed all 16 grep commands to properly quote `$PATHS` variable
+  - **Impact:** Scanner was completely broken for any project path containing spaces (e.g., `/Users/name/Local Sites/project/`)
+  - **Root Cause:** Unquoted `$PATHS` variable caused shell to split paths on spaces, breaking grep searches
+  - **Affected Checks:** ALL pattern-based checks (unsanitized superglobals, SQL injection, N+1 queries, etc.)
+  - **Fix:** Added quotes around all `$PATHS` references in grep commands: `$PATHS` → `"$PATHS"`
+  - **Verification:** Tested with WooCommerce All Products for Subscriptions plugin in path with spaces - now correctly detects 7 errors + 1 warning (previously reported 0 issues)
+  - **Files Changed:** `dist/bin/check-performance.sh` (lines 1373, 1541, 1647, 1719, 1798, 1862, 1926, 1987, 2057, 2122, 2188, 2228, 2272, 2627, 2676, 2759)
+  - **Safeguards Added:** Inline comments at each grep command referencing SAFEGUARDS.md to prevent future regressions
+
+### Improved
+- **Enhanced Pattern: Unsanitized Superglobal Read** - Now catches `isset()` bypass pattern
+  - **Pattern:** `isset( $_GET['x'] ) && $_GET['x'] === 'value'` (isset check + direct usage on same line)
+  - **Detection Logic:** Counts superglobal occurrences per line - skips if only 1 occurrence with isset/empty (existence check), reports if 2+ occurrences (isset + usage)
+  - **Example Violations Found:**
+    - `isset( $_GET['tab'] ) && $_GET['tab'] === 'subscriptions'` (line 451, class-wcs-att-admin.php)
+    - `isset( $_GET['switch-subscription'] ) && isset( $_GET['item'] )` (line 86, class-wcs-att-manage-switch.php)
+    - `! empty( $_REQUEST['add-to-cart'] ) && is_numeric( $_REQUEST['add-to-cart'] )` (line 108, class-wcs-att-manage-switch.php)
+  - **Test Fixture:** `dist/tests/fixtures/unsanitized-superglobal-isset-bypass.php` (5 violations, 6 valid examples)
+
+### Added
+- **SAFEGUARDS.md** - Critical implementation safeguards documentation
+  - **Purpose:** Prevent catastrophic regressions by documenting critical implementation details that must not be changed
+  - **Contents:**
+    - Path variable quoting rules (with line numbers for all 16 affected grep commands)
+    - isset() bypass detection logic explanation
+    - Version increment checklist
+    - Critical test cases for verification
+    - Debugging guide for silent failures
+  - **Inline References:** Added safeguard comments at all 16 grep commands pointing to SAFEGUARDS.md
+
+## [1.0.66] - 2026-01-01
+
+### Added
+- **Enhancement #10: WooCommerce N+1 Query Patterns** - Detects WC-specific N+1 performance issues
+  - **Rule ID:** `wc-n-plus-one-pattern`
+  - **Severity:** HIGH (customizable via severity config)
+  - **Category:** performance
+  - **Rationale:** WooCommerce functions called inside loops cause query multiplication (100 orders × 3 meta queries = 300 queries per page)
+  - **Detection:** Finds `wc_get_order()`, `wc_get_product()`, `get_post_meta()`, `get_user_meta()`, `->get_meta()` called inside loops over WC orders/products
+  - **Test Fixture:** Added `dist/tests/fixtures/wc-n-plus-one.php` with examples of violations and valid code (pre-fetching, caching)
+
+### Changed
+- **Check Count:** Increased from 32 to 33 checks (+1 new WooCommerce-specific check)
+- **Documentation:** Updated README files to reflect new check and count
+- **Severity Config:** Updated `severity-levels.json` to include new rule ID
+
+## [1.0.65] - 2026-01-01
+
+### Added
+- **Enhanced Pattern #2: Admin Functions Without Capability Checks** - Expanded detection coverage
+  - **Rule ID:** `admin-no-capability-check`
+  - **Severity:** HIGH (customizable via severity config)
+  - **Enhancement:** Now detects `add_menu_page`, `add_submenu_page`, `add_options_page`, and `add_management_page` callbacks missing capability checks (in addition to existing AJAX handler detection)
+  - **Test Fixture:** Added `dist/tests/fixtures/admin-no-capability.php` with examples of violations and valid code
+
+- **New Pattern #5: WooCommerce Subscriptions Queries Without Limits** - Prevents performance issues
+  - **Rule ID:** `wcs-get-subscriptions-no-limit`
+  - **Severity:** MEDIUM (customizable via severity config)
+  - **Category:** performance
+  - **Rationale:** WooCommerce Subscriptions functions should include 'limit' parameter to prevent performance degradation with large subscription counts
+  - **Detection:** Finds `wcs_get_subscriptions`, `wcs_get_subscriptions_for_order`, `wcs_get_subscriptions_for_product`, `wcs_get_subscriptions_for_user` called without 'limit' parameter
+  - **Test Fixture:** Added `dist/tests/fixtures/wcs-no-limit.php` with examples of violations and valid code
+
+### Changed
+- **Check Count:** Increased from 31 to 32 checks (+1 new check, +1 enhanced check)
+- **Documentation:** Updated README files to reflect new checks and count
+- **Severity Config:** Updated `severity-levels.json` to include new rule ID
+
+## [1.0.64] - 2026-01-01
+
+### Added
+- **New Check: Direct Database Queries Without $wpdb->prepare()** - Detects SQL injection vulnerabilities
+  - **Rule ID:** `wpdb-query-no-prepare`
+  - **Severity:** CRITICAL (customizable via severity config)
+  - **Category:** security
+  - **Rationale:** All database queries using `$wpdb->query`, `get_var`, `get_row`, `get_results`, or `get_col` must use `$wpdb->prepare()` to prevent SQL injection attacks
+  - **Detection:** Finds direct database calls without `$wpdb->prepare()` in the same statement
+  - **Test Fixture:** Added `dist/tests/fixtures/wpdb-no-prepare.php` with examples of violations and valid code
+
+- **New Check: Unsanitized Superglobal Read** - Detects XSS and parameter tampering vulnerabilities
+  - **Rule ID:** `unsanitized-superglobal-read`
+  - **Severity:** HIGH (customizable via severity config)
+  - **Category:** security
+  - **Rationale:** All access to `$_GET`, `$_POST`, and `$_REQUEST` must be sanitized using WordPress functions to prevent XSS and parameter tampering
+  - **Detection:** Finds direct superglobal access without sanitization wrappers (`sanitize_*`, `esc_*`, `absint`, `intval`, `wc_clean`, `wp_unslash`, `isset`, `empty`)
+  - **Test Fixture:** Added `dist/tests/fixtures/unsanitized-superglobal-read.php` with examples of violations and valid code
+
+### Changed
+- **Check Count:** Increased from 29 to 31 checks (+2 new security checks)
+- **Documentation:** Updated README files to reflect new checks and count
+- **Severity Config:** Updated `severity-levels.json` to include new rule IDs
+
+### Technical Details
+- Both checks use custom implementation (not `run_check` function) to support complex filtering logic
+- Implements allowlist patterns to reduce false positives (e.g., `isset`, `empty`, sanitization functions)
+- Follows the same pattern as admin capability check (manual grep → filter → display → count)
+- Correctly excludes comments and safe patterns from detection
+
 ## [1.0.63] - 2025-12-31
 
 ### Added