phpcs.xml

<?xml version="1.0"?>
<ruleset name="Gratis AI Agent Coding Standards">
    <description>PHP_CodeSniffer ruleset for Gratis AI Agent WordPress plugin.</description>

    <!-- Scan these files -->
    <file>.</file>

    <!-- Exclude paths -->
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
    <exclude-pattern>*/build/*</exclude-pattern>
    <exclude-pattern>*/tests/*</exclude-pattern>
    <exclude-pattern>*/bin/*</exclude-pattern>
    <exclude-pattern>*/.github/*</exclude-pattern>
    <exclude-pattern>*/compat/*</exclude-pattern>

    <!-- Arguments -->
    <arg name="extensions" value="php"/>
    <arg name="basepath" value="."/>
    <arg name="parallel" value="8"/>
    <arg value="ps"/>

    <!-- WordPress version -->
    <config name="minimum_supported_wp_version" value="6.7"/>

    <!-- Text domain -->
    <config name="text_domain" value="gratis-ai-agent"/>

    <!-- Use WordPress Coding Standards -->
    <rule ref="WordPress">
        <!-- Allow PSR-4 class file naming (ClassName.php instead of class-classname.php) -->
        <exclude name="WordPress.Files.FileName.InvalidClassFileName"/>
        <exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/>

        <!-- Allow camelCase method names (PSR convention) -->
        <exclude name="WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid"/>

        <!-- Allow short array syntax -->
        <exclude name="Universal.Arrays.DisallowShortArraySyntax"/>

        <!-- Allow direct database queries (plugin uses custom tables) -->
        <exclude name="WordPress.DB.DirectDatabaseQuery.DirectQuery"/>
        <exclude name="WordPress.DB.DirectDatabaseQuery.NoCaching"/>

        <!-- Allow short ternary (null coalescing style) - modern PHP -->
        <exclude name="Universal.Operators.DisallowShortTernary.Found"/>

        <!-- Allow non-Yoda conditions - more readable -->
        <exclude name="WordPress.PHP.YodaConditions.NotYoda"/>

        <!-- File header order is not critical -->
        <exclude name="PSR12.Files.FileHeader.IncorrectOrder"/>

        <!-- Allow empty catch blocks (intentional error suppression) -->
        <exclude name="Generic.CodeAnalysis.EmptyStatement.DetectedCatch"/>

        <!-- Allow unused function parameters (interface compliance) -->
        <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.Found"/>

        <!-- Relax commenting requirements for now -->
        <exclude name="Squiz.Commenting.FileComment.Missing"/>
        <exclude name="Squiz.Commenting.ClassComment.Missing"/>
        <exclude name="Squiz.Commenting.FunctionComment.Missing"/>
        <exclude name="Squiz.Commenting.FunctionComment.MissingParamTag"/>
        <exclude name="Squiz.Commenting.VariableComment.Missing"/>
        <exclude name="Generic.Commenting.DocComment.MissingShort"/>
        <exclude name="Squiz.Commenting.BlockComment.NoEmptyLineBefore"/>
        <exclude name="Squiz.Commenting.FunctionComment.ThrowsNotCapital"/>
        <exclude name="Squiz.Commenting.FunctionCommentThrowTag.Missing"/>
        <exclude name="Squiz.Commenting.FunctionComment.WrongStyle"/>
        <exclude name="Squiz.Commenting.InlineComment.InvalidEndChar"/>

        <!-- Allow commented out code during development -->
        <exclude name="Squiz.PHP.CommentedOutCode.Found"/>

        <!-- Allow 'class' as parameter name -->
        <exclude name="Universal.NamingConventions.NoReservedKeywordParameterNames.classFound"/>

        <!-- Allow multiple classes per file for compat layer -->
        <exclude name="Generic.Files.OneObjectStructurePerFile.MultipleFound"/>

        <!-- Allow property names from external APIs -->
        <exclude name="WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase"/>
    </rule>

    <!-- Enforce output escaping: all dynamic output must pass through an escaping function.
         Use esc_html(), esc_attr(), esc_url(), wp_kses_post(), etc. as appropriate.
         Inline phpcs:ignore is permitted only for false positives (e.g. ErrorException
         constructor arguments, which are not output). -->
    <rule ref="WordPress.Security.EscapeOutput"/>

    <!-- Enforce nonce verification: any handler that reads $_POST, $_GET, $_REQUEST, or
         $_COOKIE must verify a nonce via wp_verify_nonce(), check_admin_referer(), or
         check_ajax_referer() before accessing those values.
         REST API endpoints are exempt — WP_REST_Request enforces authentication and
         permission callbacks at the framework level. -->
    <rule ref="WordPress.Security.NonceVerification"/>

    <!-- Verify text domain usage -->
    <rule ref="WordPress.WP.I18n">
        <properties>
            <property name="text_domain" type="array">
                <element value="gratis-ai-agent"/>
            </property>
        </properties>
    </rule>

    <!-- Check for PHP cross-version compatibility -->
    <rule ref="PHPCompatibilityWP"/>
    <config name="testVersion" value="8.2-"/>

    <!-- WooCommerce custom capabilities — registered by WooCommerce, not core WordPress.
         These are valid capabilities used in permission_callback() checks. -->
    <rule ref="WordPress.WP.Capabilities">
        <properties>
            <property name="custom_capabilities" type="array">
                <element value="manage_woocommerce"/>
                <element value="view_woocommerce_reports"/>
                <element value="edit_products"/>
                <element value="publish_products"/>
                <element value="read_products"/>
                <element value="delete_products"/>
            </property>
        </properties>
    </rule>

</ruleset>