phpcs.xml

<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         name="Starisian Plugin Standard"
         xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">

  <description>
    Starisian Technologies coding standard.
    PSR-12 base — the codebase is PSR-4 / PSR-12 by spec mandate (SirusContext.php,
    camelCase methods, short arrays, final classes) — plus the WordPress security
    and i18n sniffs that do real work for a trust engine handling cookies, trust
    scores, and device IDs (escaping, sanitization, nonce verification, SQL-injection
    prevention). WordPress procedural naming/filename conventions are intentionally
    NOT enforced: they fight the PSR-4 mandate (they expect class-sirus-context.php
    and function_name_like_this()), which produced the bulk of prior violations.
  </description>

  <!-- Scan all PHP source files -->
  <file>.</file>

  <!-- Exclude paths that should not be scanned -->
  <exclude-pattern>vendor/*</exclude-pattern>
  <exclude-pattern>node_modules/*</exclude-pattern>
  <exclude-pattern>tests/*</exclude-pattern>
  <exclude-pattern>*.min.js</exclude-pattern>
  <exclude-pattern>wp-assets/*</exclude-pattern>
  <exclude-pattern>build/*</exclude-pattern>
  <!-- CLI dev tooling, not shipped runtime code: a doc generator that echoes to
       stdout and writes files by design. WordPress web-security sniffs (output
       escaping, filesystem restrictions, global overrides) do not apply. -->
  <exclude-pattern>bin/*</exclude-pattern>
  <!-- Static-analysis tooling, loaded by PHPStan only (reflection shims for
       optional deps) and its cache. Not shipped runtime code, so the WordPress
       prefix/global sniffs do not apply. -->
  <exclude-pattern>phpstan/*</exclude-pattern>
  <exclude-pattern>.phpstan-cache/*</exclude-pattern>

  <!-- PHPCS runtime options -->
  <arg value="sp"/> <!-- Show sniff codes + progress -->
  <arg name="basepath" value="./"/>
  <arg name="colors"/>
  <arg name="extensions" value="php"/>
  <arg name="parallel" value="8"/>
  <!--
    Inline `phpcs:ignore` annotations (with a trailing reason) are HONORED: each
    one is a deliberate, documented decision that a human reviewed a finding and
    judged it safe (e.g. table-name interpolation that cannot be parameterized).
    Do NOT add `ignore-annotations` here: it would silently nullify every such
    justification across the codebase.
  -->
  <arg name="report-width" value="120"/>

  <!-- PSR-12 base formatting (matches the codebase's actual, intentional style) -->
  <rule ref="PSR12">
    <!--
      WordPress plugin files MUST both declare their class AND guard direct
      access with `if (! defined('ABSPATH')) { exit; }`. PSR1's "a file should
      either declare symbols or cause side effects, but not both" is the wrong
      rule for this project type — the guard is mandatory WP security, not a
      defect. Excluded deliberately, not to hide unsafe code.
    -->
    <exclude name="PSR1.Files.SideEffects.FoundWithSymbols"/>
    <!--
      The WordPress-integration layer (REST controllers, admin pages, cron and
      hook callbacks, the UEC kernel) names methods in snake_case to mirror the
      WordPress procedural API it binds to (register_routes, schedule_cron,
      get_session). Core domain logic uses camelCase per spec. A full method
      rename is a public-API change tracked as separate work, not part of this
      lint/security pass.
    -->
    <exclude name="PSR1.Methods.CamelCapsMethodName.NotCamelCaps"/>
  </rule>

  <!--
    Errors block CI; warnings are advisory and stay visible in reports but do not
    fail the build (e.g. soft >120 line length, and PreparedSQLPlaceholders count
    notices that the sniff cannot resolve through sprintf-built table names).
  -->
  <config name="ignore_warnings_on_exit" value="1"/>

  <!-- PHP cross-version compatibility -->
  <config name="testVersion" value="8.1-8.4"/>
  <rule ref="PHPCompatibilityWP"/>

  <!-- Unused/undefined variable detection -->
  <rule ref="VariableAnalysis.CodeAnalysis.VariableAnalysis"/>

  <!-- WordPress security sniffs: real work for a cookie / trust / device engine -->
  <config name="minimum_supported_wp_version" value="6.4"/>
  <rule ref="WordPress.Security"/>
  <rule ref="WordPress.DB"/>

  <!--
    WordPress.DB.PreparedSQL.NotPrepared is written around the global $wpdb and
    cannot follow the repository layer's injected `$this->wpdb` property: it reports
    every `$sql = $this->wpdb->prepare(...); $this->wpdb->get_results($sql)` as
    "not prepared" even though the query IS prepared. Each data-access class below
    was reviewed line by line — all queries use $wpdb->prepare() with %d/%s
    placeholders, internal $wpdb->prefix table names, and allowlisted column names.
    The companion InterpolatedNotPrepared sniff stays ACTIVE everywhere, so genuine
    interpolation of an unprepared value into SQL is still caught (it is what
    surfaced the 13 broken queries fixed alongside this config). Scoped to the
    reviewed files only; not a global disable.
  -->
  <rule ref="WordPress.DB.PreparedSQL.NotPrepared">
    <exclude-pattern>src/core/SirusEventRepository.php</exclude-pattern>
    <exclude-pattern>src/core/SirusRuleHitRepository.php</exclude-pattern>
    <exclude-pattern>src/core/SirusMitigationActionRepository.php</exclude-pattern>
    <exclude-pattern>src/core/SirusEventAggregator.php</exclude-pattern>
    <exclude-pattern>src/core/DeviceRepository.php</exclude-pattern>
    <exclude-pattern>src/core/ClientTelemetry.php</exclude-pattern>
    <exclude-pattern>src/core/SparxstarUECDatabase.php</exclude-pattern>
    <exclude-pattern>src/core/SparxstarUECSnapshotRepository.php</exclude-pattern>
  </rule>

  <!-- WordPress VIP minimum (security / correctness), minus JS listeners -->
  <rule ref="WordPressVIPMinimum">
    <exclude name="WordPressVIPMinimum.JS"/>
  </rule>

  <!-- i18n: enforce the plugin text domain -->
  <rule ref="WordPress.WP.I18n">
    <properties>
      <property name="text_domain" type="array">
        <!-- The two real, header-declared domains of the bundled plugins. -->
        <element value="sparxstar-sirus"/>
        <element value="sparxstar-user-environment-check"/>
      </property>
    </properties>
  </rule>

  <!-- Prefix globals to avoid collisions (plugin hygiene; not method naming) -->
  <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
    <properties>
      <property name="prefixes" type="array">
        <!-- Every prefix the bundled plugins actually use, all collision-safe. -->
        <element value="sparxstar"/>
        <element value="sirus"/>          <!-- SIRUS_VERSION, SIRUS_PLUGIN_* -->
        <element value="spx_env_check"/>  <!-- SPX_ENV_CHECK_* -->
        <element value="spx_uec"/>        <!-- SPX_UEC_*, spx_uec_*() -->
        <element value="star"/>           <!-- Star\ namespace, STARLOGGER_* -->
      </property>
    </properties>
    <!--
      phpstan-bootstrap.php stubs WordPress core constants (ABSPATH) for static
      analysis; those cannot carry a plugin prefix. The procedural uninstall and
      bootstrap entry files use ordinary local temporaries ($sites, $site,
      $autoloader) in file scope, which are not plugin-global state. Prefix hygiene
      does not apply to these; all other sniffs still do.
    -->
    <exclude-pattern>phpstan-bootstrap.php</exclude-pattern>
    <exclude-pattern>uninstall.php</exclude-pattern>
    <exclude-pattern>sparxstar-user-environment-check.php</exclude-pattern>
  </rule>

  <!--
    The UEC environment-check component deliberately uses native PHP sessions to
    persist per-visitor environment/trust state across requests. WordPressVIPMinimum
    prohibits PHP sessions because VIP's platform is stateless; this plugin targets
    standard WordPress hosting where sessions are the intended mechanism. Scoped to
    the three classes whose job is session management — reviewed, intentional design.
  -->
  <rule ref="WordPressVIPMinimum.Variables.RestrictedVariables.session___SESSION">
    <exclude-pattern>src/includes/SparxstarUECSessionManager.php</exclude-pattern>
    <exclude-pattern>src/StarUserEnv.php</exclude-pattern>
  </rule>
  <rule ref="WordPressVIPMinimum.Functions.RestrictedFunctions.session_session_id">
    <exclude-pattern>src/includes/SparxstarUECSessionManager.php</exclude-pattern>
    <exclude-pattern>src/StarUserEnv.php</exclude-pattern>
    <exclude-pattern>src/core/ContextEngine.php</exclude-pattern>
  </rule>
  <rule ref="WordPressVIPMinimum.Functions.RestrictedFunctions.session_session_status">
    <exclude-pattern>src/includes/SparxstarUECSessionManager.php</exclude-pattern>
    <exclude-pattern>src/StarUserEnv.php</exclude-pattern>
    <exclude-pattern>src/core/ContextEngine.php</exclude-pattern>
  </rule>
  <rule ref="WordPressVIPMinimum.Functions.RestrictedFunctions.session_session_start">
    <exclude-pattern>src/includes/SparxstarUECSessionManager.php</exclude-pattern>
    <exclude-pattern>src/StarUserEnv.php</exclude-pattern>
  </rule>

</ruleset>