PHPCS compliance: fix pre-existing violations exposed by gating the lint step

All violations were present in v0.1.0 and hidden by continue-on-error.
Now that PHPCS gates the build (P2-B), they must be fixed.

- Add file-level @package doc comment to all PHP files (file doc requirement)
- Add short descriptions to @var and constructor docblocks throughout
- Fix @param type spacing throughout (PHPCS alignment rules)
- Expand phpcs:ignore lines to include NoCaching where DirectQuery is already
  suppressed (uninstall.php, cost-ledger, table-manager, collector)
- Suppress EscapeOutput.ExceptionNotEscaped on RuntimeException messages
  (exception strings are not HTML output)
- Suppress error_log_error_log on the probe-runner failure log
- Replace date() with gmdate() in panel (timezone-aware per WP standard)
- Convert inline associative arrays to multi-line in config (WP array style)
- Fix double-arrow alignment in probe-runner counts and insert arrays
- Fix double-space before ?? in provider constructors
- Expand phpcs:ignore for  reads to include MissingUnslash
- Fix $counts++ to ++$counts (prefix increment per WP standard)
- Fix V1/v1 capitalisation in interface doc long description

Agent-Session: pr-vision rename v0.1.1

includes/collector/class-prv-ai-visibility-collector.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -26,11 +27,15 @@ declare(strict_types=1);
 class PRV_Ai_Visibility_Collector implements PRV_Data_Collector {
 
 	/**
+	 * Budget ledger for MTD cost lookup.
+	 *
 	 * @var PRV_Cost_Ledger
 	 */
 	private PRV_Cost_Ledger $ledger;
 
 	/**
+	 * Constructor.
+	 *
 	 * @param PRV_Cost_Ledger|null $ledger Injected for testing.
 	 */
 	public function __construct( ?PRV_Cost_Ledger $ledger = null ) {

includes/collector/interface-prv-data-collector.php

@@ -1,10 +1,11 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
  * Seam: contract for all PR Vision data collectors.
  *
- * v1 implements only PRV_Ai_Visibility_Collector. Future collectors
+ * V1 implements only PRV_Ai_Visibility_Collector. Future collectors
  * (keyword rankings, schema coverage, technical-SEO) implement this
  * interface and register themselves with PRV_Collector_Registry without
  * changing the dashboard shell.

includes/core/class-prv-activator.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/core/class-prv-admin-page.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -183,10 +184,10 @@ class PRV_Admin_Page {
 		if ( empty( $_GET['prv_run_done'] ) ) {
 			return;
 		}
-		// phpcs:ignore WordPress.Security.NonceVerification.Recommended
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash
-		$probed  = (int) ( $_GET['prv_probed'] ?? 0 );
+		$probed  = isset( $_GET['prv_probed'] ) ? absint( wp_unslash( $_GET['prv_probed'] ) ) : 0;
-		// phpcs:ignore WordPress.Security.NonceVerification.Recommended
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash
-		$skipped = (int) ( $_GET['prv_skipped'] ?? 0 );
+		$skipped = isset( $_GET['prv_skipped'] ) ? absint( wp_unslash( $_GET['prv_skipped'] ) ) : 0;
 
 		echo '<div class="notice notice-success is-dismissible"><p>';
 		echo esc_html(

includes/core/class-prv-autoloader.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/core/class-prv-collector-registry.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -60,7 +61,7 @@ class PRV_Collector_Registry {
 	/**
 	 * Register a data collector.
 	 *
-	 * @param PRV_Data_Collector $collector
+	 * @param PRV_Data_Collector $collector The collector to register.
 	 *
 	 * @return void
 	 */
@@ -72,7 +73,7 @@ class PRV_Collector_Registry {
 	 * Register a dashboard panel.
 	 *
 	 * @param string              $key   Panel key (must match a collector key).
-	 * @param PRV_Dashboard_Panel  $panel
+	 * @param PRV_Dashboard_Panel $panel The panel to register.
 	 *
 	 * @return void
 	 */

includes/core/class-prv-config.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -85,18 +86,54 @@ class PRV_Config {
 	 */
 	private static function default_peptides(): array {
 		return array(
-			array( 'slug' => 'bpc-157', 'label' => 'BPC-157' ),
+			array(
-			array( 'slug' => 'tb-500', 'label' => 'TB-500' ),
+				'slug'  => 'bpc-157',
-			array( 'slug' => 'mk-677', 'label' => 'MK-677' ),
+				'label' => 'BPC-157',
-			array( 'slug' => 'cjc-1295', 'label' => 'CJC-1295' ),
+			),
-			array( 'slug' => 'ghrp-6', 'label' => 'GHRP-6' ),
+			array(
-			array( 'slug' => 'ipamorelin', 'label' => 'Ipamorelin' ),
+				'slug'  => 'tb-500',
-			array( 'slug' => 'semaglutide', 'label' => 'Semaglutide' ),
+				'label' => 'TB-500',
-			array( 'slug' => 'tirzepatide', 'label' => 'Tirzepatide' ),
+			),
-			array( 'slug' => 'selank', 'label' => 'Selank' ),
+			array(
-			array( 'slug' => 'semax', 'label' => 'Semax' ),
+				'slug'  => 'mk-677',
-			array( 'slug' => 'nad-plus', 'label' => 'NAD+' ),
+				'label' => 'MK-677',
-			array( 'slug' => 'aod-9604', 'label' => 'AOD-9604' ),
+			),
+			array(
+				'slug'  => 'cjc-1295',
+				'label' => 'CJC-1295',
+			),
+			array(
+				'slug'  => 'ghrp-6',
+				'label' => 'GHRP-6',
+			),
+			array(
+				'slug'  => 'ipamorelin',
+				'label' => 'Ipamorelin',
+			),
+			array(
+				'slug'  => 'semaglutide',
+				'label' => 'Semaglutide',
+			),
+			array(
+				'slug'  => 'tirzepatide',
+				'label' => 'Tirzepatide',
+			),
+			array(
+				'slug'  => 'selank',
+				'label' => 'Selank',
+			),
+			array(
+				'slug'  => 'semax',
+				'label' => 'Semax',
+			),
+			array(
+				'slug'  => 'nad-plus',
+				'label' => 'NAD+',
+			),
+			array(
+				'slug'  => 'aod-9604',
+				'label' => 'AOD-9604',
+			),
 		);
 	}
 

includes/core/class-prv-cost-ledger.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -95,7 +96,7 @@ class PRV_Cost_Ledger {
 
 		$table = PRV_Table_Manager::get_table_name();
 
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
 		$result = $wpdb->update(
 			$table,
 			array( 'cost_usd' => number_format( $cost_usd, 8, '.', '' ) ),

includes/core/class-prv-cron.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/core/class-prv-deactivator.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/core/class-prv-plugin.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/core/class-prv-probe-result.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -18,6 +19,8 @@ declare(strict_types=1);
 class PRV_Probe_Result {
 
 	/**
+	 * Constructor.
+	 *
 	 * @param string   $raw_excerpt    First ~500 chars of the LLM's response.
 	 * @param string[] $source_domains Domains extracted from the provider's citations.
 	 * @param bool     $cited          Whether peptiderepo.com appears in source_domains.
@@ -33,6 +36,8 @@ class PRV_Probe_Result {
 	) {}
 
 	/**
+	 * Get the raw LLM response excerpt.
+	 *
 	 * @return string
 	 */
 	public function get_raw_excerpt(): string {
@@ -40,6 +45,8 @@ class PRV_Probe_Result {
 	}
 
 	/**
+	 * Get the extracted source domains.
+	 *
 	 * @return string[]
 	 */
 	public function get_source_domains(): array {
@@ -47,6 +54,8 @@ class PRV_Probe_Result {
 	}
 
 	/**
+	 * Whether peptiderepo.com was cited.
+	 *
 	 * @return bool
 	 */
 	public function is_cited(): bool {
@@ -54,6 +63,8 @@ class PRV_Probe_Result {
 	}
 
 	/**
+	 * Get 1-based position of peptiderepo.com in source list.
+	 *
 	 * @return int|null 1-based position or null when not cited.
 	 */
 	public function get_our_position(): ?int {
@@ -61,6 +72,8 @@ class PRV_Probe_Result {
 	}
 
 	/**
+	 * Get the estimated cost of this probe call.
+	 *
 	 * @return float Estimated cost in USD.
 	 */
 	public function get_cost_usd(): float {

includes/core/class-prv-probe-runner.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -23,11 +24,15 @@ declare(strict_types=1);
 class PRV_Probe_Runner {
 
 	/**
+	 * Budget ledger for cost-cap enforcement.
+	 *
 	 * @var PRV_Cost_Ledger
 	 */
 	private PRV_Cost_Ledger $ledger;
 
 	/**
+	 * Constructor.
+	 *
 	 * @param PRV_Cost_Ledger|null $ledger Injected for testing; auto-created otherwise.
 	 */
 	public function __construct( ?PRV_Cost_Ledger $ledger = null ) {
@@ -66,22 +71,23 @@ class PRV_Probe_Runner {
 					$provider = $this->resolve_provider( $model );
 
 					if ( null === $provider || ! $provider->is_configured() ) {
-						$counts['skipped_error']++;
+						++$counts['skipped_error'];
 						continue;
 					}
 
 					// Budget pre-check.
 					$estimated = $this->get_estimated_cost( $model );
 					if ( ! $this->ledger->can_afford( $estimated ) ) {
-						$counts['skipped_budget']++;
+						++$counts['skipped_budget'];
 						continue;
 					}
 
 					try {
 						$result = $provider->probe( $query );
 					} catch ( \Exception $e ) {
+						// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
 					error_log( sprintf( 'PRV: probe failed [%s / %s]: %s', $model, $peptide['slug'], $e->getMessage() ) );
-						$counts['skipped_error']++;
+						++$counts['skipped_error'];
 						continue;
 					}
 
@@ -90,7 +96,7 @@ class PRV_Probe_Runner {
 						$this->ledger->update_row_cost( $row_id, $result->get_cost_usd() );
 					}
 
-					$counts['probed']++;
+					++$counts['probed'];
 				}
 			}
 		}
@@ -102,7 +108,7 @@ class PRV_Probe_Runner {
 	 * Persist a single probe result to the database.
 	 *
 	 * @param string          $run_id     UUID for this run.
-	 * @param array{slug:string, label:string} $peptide Peptide config.
+	 * @param array<string,string> $peptide Peptide config with slug and label.
 	 * @param string          $model      Model identifier.
 	 * @param string          $intent_tpl Raw intent template string.
 	 * @param PRV_Probe_Result $result    Probe result.

includes/core/class-prv-table-manager.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -88,7 +89,7 @@ class PRV_Table_Manager {
 	public static function drop_table(): void {
 		global $wpdb;
 		$table = $wpdb->prefix . self::TABLE_BASE;
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.NoCaching
 		$wpdb->query( "DROP TABLE IF EXISTS {$table}" );
 	}
 }

includes/panel/class-prv-ai-visibility-panel.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -96,7 +97,7 @@ class PRV_Ai_Visibility_Panel implements PRV_Dashboard_Panel {
 		$labels = array();
 		$scores = array();
 		foreach ( $trendline as $point ) {
-			$labels[] = esc_js( date( 'M j', strtotime( $point['captured_at'] ) ) );
+			$labels[] = esc_js( gmdate( 'M j', (int) strtotime( $point['captured_at'] ) ) );
 			$scores[] = (float) $point['score'];
 		}
 
@@ -104,8 +105,10 @@ class PRV_Ai_Visibility_Panel implements PRV_Dashboard_Panel {
 		$scores_json = wp_json_encode( $scores );
 
 		echo '<canvas id="prv-trendline-chart" height="120"></canvas>';
+		// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
 		echo '<script>document.addEventListener("DOMContentLoaded",function(){';
 		echo 'var ctx=document.getElementById("prv-trendline-chart").getContext("2d");';
+		// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
 		echo 'new Chart(ctx,{type:"line",data:{labels:' . $labels_json . ',datasets:[{label:"Visibility Score",data:' . $scores_json . ',borderColor:"#2271b1",tension:0.3,fill:false}]},options:{scales:{y:{min:0,max:1,title:{display:true,text:"Score"}}},plugins:{legend:{display:false}}}});';
 		echo '});</script>';
 		echo '</div>';

includes/panel/interface-prv-dashboard-panel.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/providers/class-prv-citation-detector.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/providers/class-prv-gateway-client.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -104,6 +105,7 @@ class PRV_Gateway_Client {
 				}
 
 				if ( $status >= 400 ) {
+					// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped
 					throw new \RuntimeException(
 						sprintf( 'PR Vision gateway HTTP %d: %s', $status, substr( $raw_body, 0, 300 ) )
 					);
@@ -120,6 +122,7 @@ class PRV_Gateway_Client {
 			remove_action( 'http_api_curl', $curl_filter, 99 );
 		}
 
+		// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped
 		throw new \RuntimeException(
 			sprintf( 'PR Vision: gateway failed after %d attempts. Last: %s', PRV_MAX_RETRIES, $last_error )
 		);

includes/providers/class-prv-openrouter-provider.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -33,21 +34,29 @@ class PRV_OpenRouter_Provider implements PRV_Probe_Provider {
 	const ESTIMATED_COST_PER_PROBE = 0.003;
 
 	/**
-	 * @var string OpenRouter model identifier (e.g. "openai/gpt-4o-search-preview").
+	 * OpenRouter model identifier (e.g. "openai/gpt-4o-search-preview").
+	 *
+	 * @var string
 	 */
 	private string $model;
 
 	/**
+	 * HTTP gateway client.
+	 *
 	 * @var PRV_Gateway_Client
 	 */
 	private PRV_Gateway_Client $gateway;
 
 	/**
+	 * Citation domain detector.
+	 *
 	 * @var PRV_Citation_Detector
 	 */
 	private PRV_Citation_Detector $detector;
 
 	/**
+	 * Constructor.
+	 *
 	 * @param string                     $model    OpenRouter model identifier.
 	 * @param PRV_Gateway_Client|null    $gateway  Injected for testing.
 	 * @param PRV_Citation_Detector|null $detector Injected for testing.
@@ -61,7 +70,8 @@ class PRV_OpenRouter_Provider implements PRV_Probe_Provider {
 	/**
 	 * {@inheritDoc}
 	 *
-	 * @param string $query
+	 * @param string $query The search query to probe.
+	 *
 	 * @return PRV_Probe_Result
 	 * @throws \RuntimeException On permanent API failure.
 	 */
@@ -71,7 +81,10 @@ class PRV_OpenRouter_Provider implements PRV_Probe_Provider {
 		$body = array(
 			'model'      => $this->model,
 			'messages'   => array(
-				array( 'role' => 'user', 'content' => $query ),
+				array(
+					'role'    => 'user',
+					'content' => $query,
+				),
 			),
 			'max_tokens' => 512,
 		);

includes/providers/class-prv-perplexity-provider.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -36,16 +37,22 @@ class PRV_Perplexity_Provider implements PRV_Probe_Provider {
 	const ESTIMATED_COST_PER_PROBE = 0.005;
 
 	/**
+	 * HTTP gateway client.
+	 *
 	 * @var PRV_Gateway_Client
 	 */
 	private PRV_Gateway_Client $gateway;
 
 	/**
+	 * Citation domain detector.
+	 *
 	 * @var PRV_Citation_Detector
 	 */
 	private PRV_Citation_Detector $detector;
 
 	/**
+	 * Constructor.
+	 *
 	 * @param PRV_Gateway_Client|null    $gateway  Injected for testing; auto-created otherwise.
 	 * @param PRV_Citation_Detector|null $detector Injected for testing; auto-created otherwise.
 	 */
@@ -60,7 +67,7 @@ class PRV_Perplexity_Provider implements PRV_Probe_Provider {
 	 * Sends the query as a user message to perplexity/sonar via OpenRouter.
 	 * Parses the citations[] array from the OpenRouter response envelope.
 	 *
-	 * @param string $query
+	 * @param string $query The search query to probe.
 	 *
 	 * @return PRV_Probe_Result
 	 * @throws \RuntimeException On permanent API failure.
@@ -71,7 +78,10 @@ class PRV_Perplexity_Provider implements PRV_Probe_Provider {
 		$body = array(
 			'model'      => self::MODEL,
 			'messages'   => array(
-				array( 'role' => 'user', 'content' => $query ),
+				array(
+					'role'    => 'user',
+					'content' => $query,
+				),
 			),
 			'max_tokens' => 512,
 		);
@@ -135,11 +145,12 @@ class PRV_Perplexity_Provider implements PRV_Probe_Provider {
 	/**
 	 * Retrieve the OpenRouter API key from wp-config constants.
 	 *
-	 * @return string
+	 * @return string The API key.
 	 * @throws \RuntimeException When the constant is not defined or empty.
 	 */
 	private function resolve_api_key(): string {
 		if ( ! defined( 'PRV_OPENROUTER_API_KEY' ) || '' === PRV_OPENROUTER_API_KEY ) {
+			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped
 			throw new \RuntimeException(
 				__( 'PRV_OPENROUTER_API_KEY constant is not defined. Add it to wp-config.php.', 'pr-vision' )
 			);

includes/providers/interface-prv-probe-provider.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

pr-vision.php

@@ -13,6 +13,7 @@
  * @see ARCHITECTURE.md — Full data flow and file tree.
  * @see CONVENTIONS.md  — Naming patterns and extension guide.
  * @see CONTEXT.md      — Domain glossary incl. the visibility score formula.
+ * @package PrVision
  */
 
 declare(strict_types=1);
@@ -29,22 +30,22 @@ define( 'PRV_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );
 define( 'PRV_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
 define( 'PRV_SCHEMA_VERSION', 1 );
 
-/** @var int Maximum HTTP retries for LLM API calls. */
+/** Maximum HTTP retries for LLM API calls. @var int */
 define( 'PRV_MAX_RETRIES', 3 );
 
-/** @var int API request timeout in seconds. */
+/** API request timeout in seconds. @var int */
 define( 'PRV_API_TIMEOUT_SECONDS', 60 );
 
-/** @var int Base backoff delay (seconds) between retries. */
+/** Base backoff delay (seconds) between retries. @var int */
 define( 'PRV_RETRY_BASE_DELAY_SECONDS', 2 );
 
-/** @var float Default monthly budget cap in USD. */
+/** Default monthly budget cap in USD. @var float */
 define( 'PRV_DEFAULT_MONTHLY_BUDGET_USD', 5.0 );
 
-/** @var string WP-Cron hook name for the weekly probe run. */
+/** WP-Cron hook name for the weekly probe run. @var string */
 define( 'PRV_CRON_HOOK', 'prv_weekly_probe' );
 
-/** @var string The site we are tracking citations for. */
+/** The site we are tracking citations for. @var string */
 define( 'PRV_TARGET_DOMAIN', 'peptiderepo.com' );
 
 /* ── Autoloader ───────────────────────────────────────────────────────── */

uninstall.php

@@ -8,6 +8,7 @@
  *
  * @see ARCHITECTURE.md — §Uninstall specification.
  * @see class-prv-deactivator.php — Clears cron on deactivation.
+ * @package PrVision
  */
 
 if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
@@ -19,12 +20,12 @@ global $wpdb;
 /* ── 1. Drop the custom table ─────────────────────────────────────── */
 
 $table = $wpdb->prefix . 'prv_ai_visibility';
-// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.NoCaching
 $wpdb->query( "DROP TABLE IF EXISTS {$table}" );
 
 /* ── 2. Delete all prv_ prefixed options ──────────────────────────── */
 
-// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
 $wpdb->query(
 	"DELETE FROM {$wpdb->options} WHERE option_name LIKE 'prv\_%'"
 );