(Add System Command Line tooling) Development to Main

CHANGELOG.md

@@ -5,6 +5,173 @@ 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).
 
+## [2.2.1] - 2026-02-03
+
+### Added
+
+- **Enhanced project type detection for non-WordPress codebases:**
+  - Detects frameworks from `package.json` dependencies: `nodejs`, `react`, `nextjs`, `vue`, `nuxt`, `express`, `typescript`
+  - Comma-separated output when multiple frameworks detected (e.g., `[nodejs, react, nextjs]`)
+  - Extracts project name, version, description, and author from `package.json`
+  - Falls back to file-based detection: `javascript` (JS/TS files), `php` (PHP files), `php, javascript` (mixed)
+  - WordPress plugin/theme detection unchanged and takes precedence
+
+### Fixed
+
+- **PHP superglobal rules now respect PHP-only scope in JS/Node scans:**
+  - Updated `dist/bin/check-performance.sh` so Direct Superglobal Manipulation (`spo-002-superglobals`) and Unsanitized Superglobal Read rules explicitly restrict grep to `*.php` files.
+  - Prevents PHP-specific security checks from scanning documentation files (e.g., `.md`) and non-PHP assets when running WPCC against JS/Node/React projects.
+  - Resolves false positives where Markdown docs containing PHP examples triggered superglobal findings in JS-only repositories.
+
+### Tested
+
+- ✅ PHP file discovery and caching verified (lines 3147-3178)
+- ✅ PHP security patterns have `--include=*.php` guards (lines 3368, 3536)
+- ✅ `cached_grep` fallback handles JS-only projects (lines 3271-3280)
+- ✅ `unsanitized-superglobal-read.php` fixture: detects violations correctly
+- ✅ `wpdb-no-prepare.php` fixture: detects SQL injection risks
+- ✅ JS-only directory (`headless/`): runs without crashing, no false positives
+- ✅ Backwards compatibility confirmed: existing PHP scanning unchanged
+- ✅ Type detection: `nodejs` from package.json
+- ✅ Type detection: `nodejs, react, nextjs` from Next.js project
+- ✅ Type detection: `nodejs, typescript, vue, nuxt` from Nuxt project
+- ✅ Type detection: `php, javascript` from mixed fixtures directory
+
+## [2.2.0] - 2026-02-03
+
+### Added
+
+- **JS/Node-only project support:** Relaxed the PHP file gate so WP Code Check can analyze pure JavaScript/TypeScript and Node/React codebases.
+  - When no PHP files are found but JS/TS files are present, the scanner now skips PHP-only checks gracefully and runs headless/Node.js/JS pattern sets instead.
+  - Grep helpers fall back to recursive search over the original paths when the PHP file cache is unavailable, preserving performance optimizations for PHP projects while enabling non-WordPress scans.
+  - JSON and HTML report generation remain fully supported for these non-WordPress projects.
+
+## [2.1.0] - 2026-01-28
+
+### Added
+
+#### WPCC Branding - Primary Command Alias
+
+- **New primary alias:** `wpcc` (for WP Code Check) replaces `wp-check` as the primary branding
+- **Backward compatibility:** `wp-check` alias remains available for existing workflows
+- **Installation:** Both aliases are automatically configured during `./install.sh`
+- **Tab completion:** Works with both `wpcc` and `wp-check` commands
+- **Documentation:** All examples updated to show `wpcc` as primary command
+
+#### Phase 1: Claude Code AI Triage Integration
+
+- **AI-powered finding analysis:** New `--ai-triage` flag enables automatic AI analysis of scan findings using Claude Code CLI with graceful fallback to built-in Python triage
+- **Backend orchestration:** Modular architecture supports multiple LLM backends (Claude, fallback) with extensibility for future providers (OpenAI, Ollama)
+- **Configurable AI options:**
+  - `--ai-backend <name>` - Specify backend (claude|fallback, default: auto-detect)
+  - `--ai-timeout <seconds>` - AI analysis timeout (default: 300s)
+  - `--ai-max-findings <n>` - Limit findings to analyze (default: 200)
+  - `--ai-verbose` - Show AI triage progress
+- **Automatic HTML regeneration:** After AI triage completes, HTML report is automatically regenerated with AI analysis included
+- **Graceful degradation:** If Claude CLI unavailable or fails, automatically falls back to built-in `ai-triage.py` without interrupting scan
+- **JSON schema integration:** AI triage results injected into JSON log with `ai_triage` section containing classifications, confidence levels, and recommendations
+
+### New Files
+
+- `dist/bin/lib/ai-triage-backends.sh` - Backend orchestration and detection
+- `dist/bin/lib/claude-triage.sh` - Claude Code CLI integration with timeout handling
+
+### Modified Files
+
+- `dist/bin/check-performance.sh`:
+  - Added AI triage variable declarations (lines 147-152)
+  - Added source statements for AI triage libraries (lines 66-70)
+  - Added CLI argument parsing for `--ai-triage`, `--ai-backend`, `--ai-timeout`, `--ai-max-findings`, `--ai-verbose` (lines 810-829)
+  - Added AI triage execution after HTML generation (lines 6156-6185)
+  - Updated help text with AI triage options and examples (lines 469-479, 516-530)
+
+### Example Usage
+
+```bash
+# Auto-detect and run AI triage (uses Claude if available, falls back to built-in)
+wp-check ~/my-plugin --ai-triage
+
+# Explicit Claude backend with custom timeout
+wp-check ~/my-plugin --ai-triage --ai-backend claude --ai-timeout 600
+
+# With verbose output to see AI triage progress
+wp-check ~/my-plugin --ai-triage --ai-verbose
+
+# Limit AI analysis to top 50 findings
+wp-check ~/my-plugin --ai-triage --ai-max-findings 50
+```
+
+### Testing
+
+- ✅ Tested with WooCommerce Smart Coupons plugin (61 findings)
+- ✅ Claude CLI detection working
+- ✅ Fallback to ai-triage.py verified
+- ✅ HTML regeneration with AI triage data confirmed
+- ✅ Graceful degradation when Claude unavailable
+
+## [2.0.16] - 2026-01-27
+
+### Added
+
+#### HTML Report Usability Improvements
+
+- **Plugin slug in HTML filename:** HTML reports now automatically append the first 4 characters of the plugin/theme name to the filename for easier identification. Example: `2026-01-27-220926-UTC-wooc.html` for "WooCommerce Smart Coupons" instead of just `2026-01-27-220926-UTC.html`. This makes it much easier to find specific reports later when scanning multiple plugins.
+
+- **Metadata comments at top of HTML file:** Added HTML comment block at the very top of report files containing key metadata (plugin name, version, type, author, scan timestamp, files analyzed, LOC, errors, warnings, path, scanner version). This allows quick inspection of report metadata in any text editor without opening the file in a browser or scrolling down the page.
+
+  Example metadata comment:
+  ```html
+  <!--
+  WP Code Check Performance Report
+  ================================
+  Plugin/Theme: WooCommerce Smart Coupons v9.64.0
+  Type: plugin
+  Author: StoreApps
+  Scanned: 2026-01-27T22:09:26Z
+  Files Analyzed: 122
+  Lines of Code: 63,525
+  Total Errors: 3
+  Total Warnings: 0
+  Path: /path/to/plugin
+  Scanner Version: 2.0.16
+  -->
+  ```
+
+#### New Detection Pattern: WordPress Template Tags in Loops (N+1 Queries)
+
+Source: IRL - Smart Coupons Plugin
+
+- **Pattern ID:** `wp-template-tags-in-loops` – New scripted pattern that detects WordPress template tag functions (`get_the_title()`, `get_the_content()`, `get_permalink()`, etc.) called with explicit post ID parameters inside loops. This is one of the most common WordPress performance anti-patterns found in plugins and themes.
+
+- **Detection logic:** Uses grep to find `foreach` and `while` loops, then validates with `dist/bin/validators/wp-template-tags-in-loops.sh` to check if template tags are called with parameters (e.g., `get_the_title($post_id)`) instead of using the global `$post` context.
+
+- **Severity:** CRITICAL – Each template tag call with a parameter triggers a separate database query. Example: 100 posts × 3 template tags = 300 queries instead of 1 query with proper `WP_Query` usage.
+
+- **Template tags detected:**
+  - `get_the_title()` - Post title
+  - `get_the_content()` - Post content
+  - `get_the_excerpt()` - Post excerpt
+  - `get_permalink()` - Post URL
+  - `get_the_author()` - Author name
+  - `get_the_date()` / `get_the_time()` - Post dates
+  - `get_the_category()` / `get_the_tags()` - Taxonomies
+  - `get_the_post_thumbnail()` / `get_the_post_thumbnail_url()` - Featured images
+  - `get_post()` - Full post object fetch
+
+- **False positive prevention:** The validator script detects proper usage patterns:
+  - Template tags called without parameters (uses global `$post`) → Not flagged
+  - Loops with `setup_postdata($post)` calls → Not flagged
+  - Single template tag calls outside loops → Not flagged
+
+- **Fixture test:** Added `dist/tests/fixtures/wp-template-tags-in-loops.php` with 6 violation examples (template tags with parameters in loops) and 6 safe patterns (proper `WP_Query` usage, `setup_postdata()`, direct property access).
+
+- **Rationale:** This pattern addresses a gap identified during real-world testing of WooCommerce Smart Coupons plugin. The example code `foreach ($coupon_ids as $coupon_id) { $title = get_the_title($coupon_id); }` was not detected by existing N+1 patterns, which focus on meta functions and WooCommerce-specific functions.
+
+- **Impact examples:**
+  - 100 posts with `get_the_title($id)` + `get_permalink($id)` = 200 queries instead of 1
+  - E-commerce product listing with 50 products × 5 template tags = 250 queries
+  - Archive page with 20 posts × 3 template tags = 60 queries per page load
+
 ## [2.0.15] - 2026-01-27
 
 ### Added

PROJECT/2-WORKING/BACKLOG.md

@@ -1,14 +1,12 @@
 # Backlog - Issues to Investigate
 
 ## 2026-01-27
-Post DB Query constructur pattern
-- [z] Update the pattern description to document the limitations
-- [z] Update the CHANGELOG with the new pattern
-- [x] Adjust the fixture test expectations after adding the DB query in constructor pattern (currently expects 4 errors, but detects 6) - **COMPLETED 2026-01-27**: Updated `dist/tests/expected/fixture-expectations.json` to expect 6 errors (includes 2 false positives with safety guards). CHANGELOG updated with rationale.
 
-- [ ] Re-integrate the Local VS Code Editor jump buttons
+- [x]  Add System CLI support
 
-2026-01-17
+- [x] Append file names with first 4 characters of the plugin name to the output file name so its easier to find later.
+
+## 2026-01-17
 - [ ] Add new Test Fixtures for DSM patterns 
 - [ ] Research + decision: verify whether `spo-002-superglobals-bridge` should be supported in `should_suppress_finding()` (in `dist/bin/check-performance.sh`) and define the implementation path (add allowlist vs require baseline); update DSM fixture plan accordingly.