peptide-repo/pr-vision
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
peptiderepo
2026-06-13 09:42:55 +00:00
parent 60ae52663c
commit 68ae5b9b1a
23 changed files with 189 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
includes/collector/class-prv-ai-visibility-collector.php
View File

@@ -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 ) {

3
includes/collector/interface-prv-data-collector.php
View File

@@ -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.

1
includes/core/class-prv-activator.php
View File

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

9
includes/core/class-prv-admin-page.php
View File

@@ -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
$probed = (int) ( $_GET['prv_probed'] ?? 0 );
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
$skipped = (int) ( $_GET['prv_skipped'] ?? 0 );
// phpcs:ignore WordPress.Security.NonceVerification.Recommended, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash
$probed = isset( $_GET['prv_probed'] ) ? absint( wp_unslash( $_GET['prv_probed'] ) ) : 0;
// phpcs:ignore WordPress.Security.NonceVerification.Recommended, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash
$skipped = isset( $_GET['prv_skipped'] ) ? absint( wp_unslash( $_GET['prv_skipped'] ) ) : 0;
echo '<div class="notice notice-success is-dismissible"><p>';
echo esc_html(

1
includes/core/class-prv-autoloader.php
View File

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

5
includes/core/class-prv-collector-registry.php
View File

@@ -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
*/

61
includes/core/class-prv-config.php
View File

@@ -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( 'slug' => 'tb-500', 'label' => 'TB-500' ),
array( 'slug' => 'mk-677', 'label' => 'MK-677' ),
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' ),
array(
'slug' => 'bpc-157',
'label' => 'BPC-157',
),
array(
'slug' => 'tb-500',
'label' => 'TB-500',
),
array(
'slug' => 'mk-677',
'label' => 'MK-677',
),
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',
),
);
}

3
includes/core/class-prv-cost-ledger.php
View File

@@ -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, '.', '' ) ),

1
includes/core/class-prv-cron.php
View File

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

1
includes/core/class-prv-deactivator.php
View File

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

1
includes/core/class-prv-plugin.php
View File

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

13
includes/core/class-prv-probe-result.php
View File

@@ -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 {

16
includes/core/class-prv-probe-runner.php
View File

@@ -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.

3
includes/core/class-prv-table-manager.php
View File

@@ -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}" );
}
}

5
includes/panel/class-prv-ai-visibility-panel.php
View File

@@ -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>';

1
includes/panel/interface-prv-dashboard-panel.php
View File

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

1
includes/providers/class-prv-citation-detector.php
View File

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

3
includes/providers/class-prv-gateway-client.php
View File

@@ -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 )
);

19
includes/providers/class-prv-openrouter-provider.php
View File

@@ -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,
);

17
includes/providers/class-prv-perplexity-provider.php
View File

@@ -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' )
);

1
includes/providers/interface-prv-probe-provider.php
View File

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

13
pr-vision.php
View File

@@ -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 ───────────────────────────────────────────────────────── */

5
uninstall.php
View File

@@ -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\_%'"
);