@ai-kits/wp-ag-kit 1.0.1 → 1.0.3

package/skills/woocommerce/references/sentence-case.md

@@ -0,0 +1,177 @@
+# Sentence Case for UI Text
+
+## Table of Contents
+
+- [Rule: Always Use Sentence Case](#rule-always-use-sentence-case)
+- [Examples](#examples)
+- [Exceptions](#exceptions)
+- [Common UI Elements](#common-ui-elements)
+- [Why Sentence Case?](#why-sentence-case)
+- [Quick Reference](#quick-reference)
+- [When in Doubt](#when-in-doubt)
+
+## Rule: Always Use Sentence Case
+
+**Always use sentence case for UI copy, not title case.**
+
+Sentence case means only the first word and proper nouns are capitalized.
+
+## Examples
+
+### Correct - Sentence Case
+
+- "Payment provider options"
+- "Complete setup"
+- "Add new gateway"
+- "Configure payment settings"
+- "Save changes"
+- "View documentation"
+- "Enable test mode"
+
+### Incorrect - Title Case
+
+- "Payment Provider Options"
+- "Complete Setup"
+- "Add New Gateway"
+- "Configure Payment Settings"
+- "Save Changes"
+- "View Documentation"
+- "Enable Test Mode"
+
+## Exceptions
+
+Sentence case has specific exceptions where capitalization is required:
+
+### 1. Proper Nouns
+
+Always capitalize proper nouns (names of specific products, services, or brands):
+
+**Correct:**
+
+- "Connect with WooPayments"
+- "Import from WordPress"
+- "Sync with Stripe"
+- "Enable Google Analytics"
+
+### 2. Acronyms
+
+Always capitalize acronyms:
+
+**Correct:**
+
+- "Configure API settings"
+- "Enter URL"
+- "Set up SSL certificate"
+- "Generate CSV export"
+
+### 3. Brand Names
+
+Always use the official capitalization for brand names:
+
+**Correct:**
+
+- "PayPal"
+- "WooCommerce"
+- "WordPress"
+- "Stripe"
+
+## Common UI Elements
+
+### Buttons
+
+```text
+✅ Correct:
+- "Save changes"
+- "Add product"
+- "Continue to checkout"
+- "Send test email"
+
+❌ Incorrect:
+- "Save Changes"
+- "Add Product"
+- "Continue To Checkout"
+- "Send Test Email"
+```
+
+### Labels
+
+```text
+✅ Correct:
+- "Payment method"
+- "Shipping address"
+- "Order notes"
+- "Tax rate"
+
+❌ Incorrect:
+- "Payment Method"
+- "Shipping Address"
+- "Order Notes"
+- "Tax Rate"
+```
+
+### Menu Items
+
+```text
+✅ Correct:
+- "Settings"
+- "Payment gateways"
+- "Tax settings"
+- "Shipping zones"
+
+❌ Incorrect:
+- "Settings"  (this one is actually correct - it's a single word)
+- "Payment Gateways"
+- "Tax Settings"
+- "Shipping Zones"
+```
+
+### Headings
+
+```text
+✅ Correct:
+- "Payment settings"
+- "Configure your store"
+- "Advanced options"
+
+❌ Incorrect:
+- "Payment Settings"
+- "Configure Your Store"
+- "Advanced Options"
+```
+
+### Messages and Notifications
+
+```text
+✅ Correct:
+- "Settings saved successfully"
+- "Unable to connect to payment provider"
+- "Please enter a valid email address"
+
+❌ Incorrect:
+- "Settings Saved Successfully"
+- "Unable To Connect To Payment Provider"
+- "Please Enter A Valid Email Address"
+```
+
+## Why Sentence Case?
+
+More readable, conversational, and modern. Better for accessibility and internationalization.
+
+## Quick Reference
+
+| Element Type | Example |
+|--------------|---------|
+| Button | "Save changes" |
+| Link | "View all orders" |
+| Label | "Email address" |
+| Heading | "Payment options" |
+| Message | "Order created successfully" |
+| Menu item | "Product settings" |
+| Checkbox | "Enable notifications" |
+| Tab | "General settings" |
+
+## When in Doubt
+
+Capitalize only: first word, proper nouns, and acronyms.
+
+Example: "Enable WooPayments API integration"

package/skills/woocommerce/references/type-annotations.md

@@ -0,0 +1,161 @@
+# Type Annotations for Static Analysis
+
+## Table of Contents
+
+- [Overview](#overview)
+- [When to Use PHPStan Annotations](#when-to-use-phpstan-annotations)
+- [Generic Types with @template](#generic-types-with-template)
+- [PHPStan-Specific Annotations](#phpstan-specific-annotations)
+- [Common Patterns](#common-patterns)
+- [Suppressing False Positives](#suppressing-false-positives)
+
+## Overview
+
+WooCommerce uses PHPStan for static analysis. Beyond standard PHPDoc annotations (`@param`, `@return`, `@var`), use PHPStan-specific annotations to provide richer type information that enables better type inference.
+
+## When to Use PHPStan Annotations
+
+Use PHPStan annotations when:
+
+- A method returns a type based on its input (generic/template types)
+- Standard PHPDoc cannot express the type relationship
+- You need to provide type information that PHP's type system cannot express
+
+## Generic Types with @template
+
+Use `@template` to declare generic type parameters. This enables PHPStan to infer return types based on input types.
+
+### Basic Pattern
+
+```php
+/**
+ * Get an instance of a class from the container.
+ *
+ * @template T of object
+ * @param string $class_name Class name.
+ * @phpstan-param class-string<T> $class_name
+ *
+ * @return T The instance of the requested class.
+ */
+public function get( string $class_name ) {
+    // ...
+}
+```
+
+**How it works:**
+
+1. `@template T of object` - Declares a type variable `T` constrained to objects
+2. `@phpstan-param class-string<T> $class_name` - The input is a class name string for type `T`
+3. `@return T` - The return type is the same `T` that was passed in
+
+**Result:** PHPStan knows that `$container->get( MyService::class )` returns `MyService`.
+
+### Constraint Options
+
+```php
+// Any object type
+@template T of object
+
+// Specific base class or interface
+@template T of WC_Product
+
+// No constraint (can be any type including scalars)
+@template T
+```
+
+## PHPStan-Specific Annotations
+
+### @phpstan-param vs @param
+
+Use both when you need PHPStan-specific type info while keeping standard documentation:
+
+```php
+/**
+ * @param string $class_name Class name to instantiate.
+ * @phpstan-param class-string<T> $class_name
+ */
+```
+
+- `@param string` - Standard PHPDoc (for IDEs and documentation generators)
+- `@phpstan-param class-string<T>` - PHPStan-specific (richer type info)
+
+### @phpstan-return
+
+Use when the return type is more specific than the declared type:
+
+```php
+/**
+ * @return object
+ * @phpstan-return T
+ */
+```
+
+### @phpstan-var
+
+Use for inline type assertions:
+
+```php
+/** @phpstan-var array<string, WC_Product> $products */
+$products = get_transient( 'cached_products' );
+```
+
+## Common Patterns
+
+### Factory Methods
+
+```php
+/**
+ * Create a new instance of a data store.
+ *
+ * @template T of WC_Data_Store
+ * @param string $object_type Object type (e.g., 'product', 'order').
+ * @phpstan-param class-string<T> $object_type
+ *
+ * @return T The data store instance.
+ */
+public static function load( string $object_type ) {
+    // ...
+}
+```
+
+### Container/Service Locator
+
+```php
+/**
+ * @template T of object
+ * @param string $id Service identifier.
+ * @phpstan-param class-string<T> $id
+ *
+ * @return T Service instance.
+ */
+public function get( string $id );
+```
+
+### Collections with Known Types
+
+```php
+/**
+ * @param array<int, WC_Order_Item> $items Order items.
+ * @return array<string, float> Item totals keyed by item type.
+ */
+public function calculate_totals( array $items ): array {
+    // ...
+}
+```
+
+## Suppressing False Positives
+
+When PHPStan reports an error that is a false positive (the code is correct but PHPStan cannot verify it), use inline ignores with explanations:
+
+```php
+// @phpstan-ignore return.type (method uses reflection to return correct type at runtime)
+return $this->create_instance( $class_name );
+```
+
+Common ignore identifiers:
+
+- `return.type` - Return type mismatch
+- `argument.type` - Argument type mismatch
+- `method.nonObject` - Method call on potentially non-object
+
+**Important:** Only use ignores when the code is genuinely correct. Prefer fixing the type annotations or code when possible.

package/skills/woocommerce/references/unit-tests.md

@@ -0,0 +1,362 @@
+# Unit Testing Conventions
+
+## Table of Contents
+
+- [Complete Test File Template](#complete-test-file-template)
+- [Test File Naming and Location](#test-file-naming-and-location)
+- [System Under Test Variable](#system-under-test-variable)
+- [Test Method Documentation](#test-method-documentation)
+- [Comments in Tests](#comments-in-tests)
+- [Test Configuration](#test-configuration)
+- [Example: Payment Extension Suggestions Tests](#example-payment-extension-suggestions-tests)
+- [Mocking the WooCommerce Logger](#mocking-the-woocommerce-logger)
+- [General Testing Best Practices](#general-testing-best-practices)
+
+## Complete Test File Template
+
+Use this template when creating new test files. It shows all conventions applied together:
+
+```php
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\Tests\Internal\Admin;
+
+use Automattic\WooCommerce\Internal\Admin\OrderProcessor;
+use WC_Unit_Test_Case;
+
+/**
+ * Tests for the OrderProcessor class.
+ */
+class OrderProcessorTest extends WC_Unit_Test_Case {
+
+	/**
+	 * The System Under Test.
+	 *
+	 * @var OrderProcessor
+	 */
+	private $sut;
+
+	/**
+	 * Set up test fixtures.
+	 */
+	public function setUp(): void {
+		parent::setUp();
+		$this->sut = new OrderProcessor();
+	}
+
+	/**
+	 * Tear down test fixtures.
+	 */
+	public function tearDown(): void {
+		parent::tearDown();
+	}
+
+	/**
+	 * @testdox Should return true when order is valid.
+	 */
+	public function test_returns_true_for_valid_order(): void {
+		$order = wc_create_order();
+
+		$result = $this->sut->is_valid( $order );
+
+		$this->assertTrue( $result, 'Valid orders should return true' );
+	}
+
+	/**
+	 * @testdox Should throw exception when order ID is negative.
+	 */
+	public function test_throws_exception_for_negative_order_id(): void {
+		$this->expectException( \InvalidArgumentException::class );
+
+		$this->sut->process( -1 );
+	}
+}
+```
+
+### Key Elements
+
+| Element | Requirement |
+| ------- | ----------- |
+| `declare( strict_types = 1 )` | Required at file start |
+| Namespace | Match source location: `Automattic\WooCommerce\Tests\{path}` |
+| Base class | Extend `WC_Unit_Test_Case` |
+| SUT variable | Use `$sut` with docblock "The System Under Test." |
+| Test docblock | Use `@testdox` with sentence ending in `.` |
+| Return type | Use `void` for test methods |
+| Assertion messages | Include helpful context for failures |
+
+## Test File Naming and Location
+
+| Source               | Test                                                 | Pattern                  |
+| -------------------- | ---------------------------------------------------- | ------------------------ |
+| `includes/` classes  | `tests/php/includes/{path}/class-wc-{name}-test.php` | Add `-test` suffix       |
+| `src/` classes       | `tests/php/src/{path}/{name}Test.php`                | Append `Test` (no hyphen)|
+
+Test class: Same name as source class + `_Test` or `Test` suffix, extends `WC_Unit_Test_Case`
+
+## System Under Test Variable
+
+Use `$sut` with docblock "The System Under Test."
+
+```php
+/**
+ * The System Under Test.
+ *
+ * @var OrderProcessor
+ */
+private $sut;
+```
+
+## Test Method Documentation
+
+When adding or modifying a unit test method, the part of the docblock that describes the test must be prepended with `@testdox`. End the comment with `.` for compliance with linting rules.
+
+**Example:**
+
+```php
+/**
+ * @testdox Should return true when order is valid.
+ */
+public function test_returns_true_for_valid_order() {
+    // ...
+}
+
+/**
+ * @testdox Should throw exception when order ID is negative.
+ */
+public function test_throws_exception_for_negative_order_id() {
+    // ...
+}
+```
+
+## Comments in Tests
+
+**Avoid over-commenting tests.** Test names and assertion messages should explain intent.
+
+**Good - Self-explanatory:**
+
+```php
+/**
+ * @testdox Should return true when order status is draft.
+ */
+public function test_returns_true_for_draft_orders() {
+    $order = $this->create_draft_order();
+
+    $result = $this->sut->can_delete( $order );
+
+    $this->assertTrue( $result, 'Draft orders should be deletable' );
+}
+```
+
+**Avoid - Over-commented:**
+
+```php
+/**
+ * @testdox Should return true when order status is draft.
+ */
+public function test_returns_true_for_draft_orders() {
+    // Create a draft order
+    $order = $this->create_draft_order();
+
+    // Call the method we're testing
+    $result = $this->sut->can_delete( $order );
+
+    // Verify the result is true
+    $this->assertTrue( $result, 'Draft orders should be deletable' );
+}
+```
+
+**Avoid - Arrange/Act/Assert comments:**
+
+```php
+// Don't add these structural comments
+// Arrange
+$order = $this->create_draft_order();
+
+// Act
+$result = $this->sut->can_delete( $order );
+
+// Assert
+$this->assertTrue( $result );
+```
+
+Use blank lines for visual separation instead. The test structure should be self-evident.
+
+**When comments ARE useful in tests:**
+
+- Explaining complex test setup: `// Simulate race condition by...`
+- Documenting known issues: `// Workaround for WordPress core bug #12345`
+- Clarifying business rules: `// Payment processor requires 24h hold`
+
+## Test Configuration
+
+Test configuration file: `phpunit.xml`
+
+## Example: Payment Extension Suggestions Tests
+
+The `PaymentsExtensionSuggestionsTest` class demonstrates good testing practices for country-specific functionality.
+
+### Key Patterns Used
+
+1. **Data-driven tests** using PHPUnit data providers
+2. **Extension count verification** for different merchant types
+3. **Clear test organization** by merchant type (online/offline)
+
+### Example Test Structure
+
+```php
+class PaymentsExtensionSuggestionsTest extends WC_Unit_Test_Case {
+    /**
+     * The System Under Test.
+     *
+     * @var PaymentsExtensionSuggestions
+     */
+    private $sut;
+
+    public function setUp(): void {
+        parent::setUp();
+        $this->sut = new PaymentsExtensionSuggestions();
+    }
+
+    /**
+     * @testdox Should return correct extension count for online merchants by country
+     * @dataProvider online_merchant_country_data
+     */
+    public function test_get_country_extensions_count_for_online_merchants(
+        string $country_code,
+        int $expected_count
+    ) {
+        $merchant = array(
+            'country'       => $country_code,
+            'selling_venues' => 'online',
+        );
+
+        $result = $this->sut->get_country_extensions_count( $merchant );
+
+        $this->assertSame(
+            $expected_count,
+            $result,
+            "Expected {$expected_count} extensions for online merchant in {$country_code}"
+        );
+    }
+
+    /**
+     * Data provider for online merchant tests.
+     *
+     * @return array
+     */
+    public function online_merchant_country_data() {
+        return array(
+            'United States'    => array( 'US', 5 ),
+            'United Kingdom'   => array( 'GB', 4 ),
+            'Canada'           => array( 'CA', 3 ),
+            'Australia'        => array( 'AU', 3 ),
+            // ... more countries
+        );
+    }
+
+    /**
+     * @testdox Should return correct extension count for offline merchants by country
+     * @dataProvider offline_merchant_country_data
+     */
+    public function test_get_country_extensions_count_for_offline_merchants(
+        string $country_code,
+        int $expected_count
+    ) {
+        $merchant = array(
+            'country'        => $country_code,
+            'selling_venues' => 'offline',
+        );
+
+        $result = $this->sut->get_country_extensions_count( $merchant );
+
+        $this->assertSame(
+            $expected_count,
+            $result,
+            "Expected {$expected_count} extensions for offline merchant in {$country_code}"
+        );
+    }
+
+    /**
+     * Data provider for offline merchant tests.
+     *
+     * @return array
+     */
+    public function offline_merchant_country_data() {
+        return array(
+            'United States'  => array( 'US', 2 ),
+            'United Kingdom' => array( 'GB', 1 ),
+            'Canada'         => array( 'CA', 1 ),
+            // ... more countries
+        );
+    }
+}
+```
+
+### Important Notes for Payment Extension Tests
+
+When working with payment extension suggestions:
+
+1. **Extension counts must match the implementation** in `src/Internal/Admin/Suggestions/PaymentsExtensionSuggestions.php`
+2. **When adding new countries** to the implementation, update both data providers in the test file
+3. **Tests are separated by merchant type** (online vs offline) as they have different extension counts
+4. **Data providers use descriptive keys** (country names) for better test output
+
+## Mocking the WooCommerce Logger
+
+When testing code that uses `wc_get_logger()` (directly or via `SafeGlobalFunctionProxy::wc_get_logger()`), use the `woocommerce_logging_class` filter to inject a fake logger.
+
+### Why the Filter Approach?
+
+- `register_legacy_proxy_function_mocks` doesn't intercept `SafeGlobalFunctionProxy` calls
+- Passing an object (not a class name string) bypasses `wc_get_logger()`'s internal cache
+
+### Creating a Fake Logger
+
+The fake logger must implement `WC_Logger_Interface`. Create an anonymous class with public arrays to track calls (`$debug_calls`, `$warning_calls`, etc.) and implement all interface methods (`add`, `log`, `debug`, `info`, `warning`, `error`, `emergency`, `alert`, `critical`, `notice`).
+
+### Using the Fake Logger
+
+```php
+public function test_logs_warning_for_invalid_input(): void {
+    $fake_logger = $this->create_fake_logger();
+
+    // Inject via filter - passing object bypasses cache.
+    add_filter(
+        'woocommerce_logging_class',
+        function () use ( $fake_logger ) {
+            return $fake_logger;
+        }
+    );
+
+    $this->sut->process_input( 'invalid-value' );
+
+    $this->assertCount( 1, $fake_logger->warning_calls );
+
+    remove_all_filters( 'woocommerce_logging_class' ); // Always clean up.
+}
+```
+
+### Key Points
+
+| Aspect       | Detail                                          |
+| ------------ | ----------------------------------------------- |
+| Filter name  | `woocommerce_logging_class`                     |
+| Return value | Object instance (not class name string)         |
+| Interface    | Must implement `WC_Logger_Interface`            |
+| Cleanup      | Always call `remove_all_filters()` after test   |
+
+### Reference
+
+See `PaymentGatewayTest.php:create_fake_logger()` for a complete implementation.
+
+## General Testing Best Practices
+
+1. **Always run tests after making changes** to verify functionality
+2. **Use specific test filters** during development (see running-tests.md in the woocommerce-dev-cycle skill)
+3. **Write descriptive test names** that explain what is being tested
+4. **Use data providers** for testing multiple scenarios with the same logic
+5. **Include helpful assertion messages** for debugging when tests fail
+6. **Test both success and failure cases**
+7. **Mock external dependencies** (database, API calls, etc.)