feat(form-builder): wire PurposeGuardProvider per purpose (WS-6)

Adds PurposeGuardProvider as a parallel interface to PurposeDefinition (value object stays untouched). Seven concrete providers, one per v1.0 purpose, each declaring its publish-guard list. Registry resolves and caches providers via guards_class config key. Universal guards (MaxOneIdentityKeyPerTargetEntity, AppendStrategyRequiresCollectionTarget, NoAmbiguousTrustLevels, IdentityKeyBindingsOnlyInFirstSection) wire into every purpose. The section guard is a cheap no-op when section_level_submit=false. ArtistAdvanceGuards omits RequiresIdentityKeyBinding because the artist subject is resolved via portal token, not form data. Same reasoning for supplier_intake (production_request) and the auth-based purposes. Includes a cross-cutting BindingTypeRegistryConsistencyTest that verifies tasks 5/7/8 do not contradict each other (registry ↔ guards ↔ purpose required_bindings). Refs: RFC-WS-6.md §3 (Q9, Q13) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-25 23:01:19 +02:00
parent 81a8120f98
commit e3c9211e3f
16 changed files with 763 additions and 0 deletions
--- a/api/tests/Feature/FormBuilder/Purposes/AllPurposesGuardWiringTest.php
+++ b/api/tests/Feature/FormBuilder/Purposes/AllPurposesGuardWiringTest.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\Purposes;
+
+use App\FormBuilder\Purposes\PurposeGuardProvider;
+use App\FormBuilder\Purposes\PurposeRegistry;
+use Tests\TestCase;
+
+final class AllPurposesGuardWiringTest extends TestCase
+{
+    public function test_every_purpose_has_a_guards_class(): void
+    {
+        /** @var array<string, mixed> $config */
+        $config = config('form_builder.purposes');
+        $this->assertNotEmpty($config);
+
+        foreach ($config as $slug => $attrs) {
+            $this->assertArrayHasKey(
+                'guards_class',
+                $attrs,
+                "Purpose '{$slug}' is missing the guards_class config key.",
+            );
+        }
+    }
+
+    public function test_registry_resolves_provider_for_every_purpose(): void
+    {
+        $registry = $this->app->make(PurposeRegistry::class);
+
+        foreach (array_keys($registry->all()) as $slug) {
+            $provider = $registry->guardProviderFor($slug);
+            $this->assertInstanceOf(PurposeGuardProvider::class, $provider);
+            $this->assertNotEmpty(
+                $provider->publishGuards(),
+                "Provider for '{$slug}' returned no guards.",
+            );
+        }
+    }
+}
--- a/api/tests/Feature/FormBuilder/Purposes/ArtistAdvanceGuardsIntegrationTest.php
+++ b/api/tests/Feature/FormBuilder/Purposes/ArtistAdvanceGuardsIntegrationTest.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\Purposes;
+
+use App\Enums\FormBuilder\FormFieldBindingMergeStrategy;
+use App\Enums\FormBuilder\FormPurpose;
+use App\FormBuilder\Purposes\Guards\ArtistAdvanceGuards;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldBinding;
+use App\Models\FormBuilder\FormSchema;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class ArtistAdvanceGuardsIntegrationTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_valid_schema_passes_all_guards(): void
+    {
+        $schema = $this->buildValidSchema();
+        $provider = $this->app->make(ArtistAdvanceGuards::class);
+
+        foreach ($provider->publishGuards() as $guard) {
+            $result = $guard->evaluate($schema);
+            $this->assertTrue(
+                $result->passed,
+                "Guard {$guard->code()} failed: {$result->messageKey}",
+            );
+        }
+    }
+
+    public function test_append_on_scalar_target_fails(): void
+    {
+        $schema = $this->buildValidSchema();
+        FormFieldBinding::query()
+            ->withoutGlobalScopes()
+            ->whereIn('owner_id', $schema->fields->pluck('id'))
+            ->where('target_attribute', 'stage_name')
+            ->update(['merge_strategy' => FormFieldBindingMergeStrategy::Append->value]);
+        $schema->load('fields.bindings');
+
+        $provider = $this->app->make(ArtistAdvanceGuards::class);
+
+        $failedCodes = [];
+        foreach ($provider->publishGuards() as $guard) {
+            $result = $guard->evaluate($schema);
+            if (! $result->passed) {
+                $failedCodes[] = $guard->code();
+            }
+        }
+
+        $this->assertContains('append_strategy_requires_collection_target', $failedCodes);
+    }
+
+    private function buildValidSchema(): FormSchema
+    {
+        $schema = FormSchema::factory()->create([
+            'purpose' => FormPurpose::ARTIST_ADVANCE->value,
+        ]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+        FormFieldBinding::factory()->forField($field)->entityOwned('artist', 'stage_name')
+            ->create(['trust_level' => 70]);
+        $schema->load(['fields.bindings', 'sections']);
+
+        return $schema;
+    }
+}
--- a/api/tests/Feature/FormBuilder/Purposes/EventRegistrationGuardsIntegrationTest.php
+++ b/api/tests/Feature/FormBuilder/Purposes/EventRegistrationGuardsIntegrationTest.php
@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\Purposes;
+
+use App\Enums\FormBuilder\FormFieldType;
+use App\Enums\FormBuilder\FormPurpose;
+use App\FormBuilder\Purposes\Guards\EventRegistrationGuards;
+use App\FormBuilder\Purposes\PurposeRegistry;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldBinding;
+use App\Models\FormBuilder\FormSchema;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class EventRegistrationGuardsIntegrationTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_valid_schema_passes_all_guards(): void
+    {
+        $schema = $this->buildValidSchema();
+        $provider = $this->app->make(EventRegistrationGuards::class);
+
+        foreach ($provider->publishGuards() as $guard) {
+            $result = $guard->evaluate($schema);
+            $this->assertTrue(
+                $result->passed,
+                "Guard {$guard->code()} unexpectedly failed: {$result->messageKey}",
+            );
+        }
+    }
+
+    public function test_missing_identity_key_flag_fails_specific_guard(): void
+    {
+        $schema = $this->buildValidSchema();
+        // Mutation: clear is_identity_key on the email binding.
+        FormFieldBinding::query()
+            ->withoutGlobalScopes()
+            ->whereIn('owner_id', $schema->fields->pluck('id'))
+            ->where('target_attribute', 'email')
+            ->update(['is_identity_key' => false]);
+        $schema->load('fields.bindings');
+
+        $provider = $this->app->make(EventRegistrationGuards::class);
+
+        $failedCodes = [];
+        foreach ($provider->publishGuards() as $guard) {
+            $result = $guard->evaluate($schema);
+            if (! $result->passed) {
+                $failedCodes[] = $guard->code();
+            }
+        }
+
+        $this->assertContains(
+            'requires_identity_key_binding:person:email',
+            $failedCodes,
+            'Expected the identity-key flag-check guard to fail.',
+        );
+    }
+
+    public function test_registry_resolves_event_registration_to_this_provider(): void
+    {
+        $registry = $this->app->make(PurposeRegistry::class);
+        $provider = $registry->guardProviderFor('event_registration');
+        $this->assertInstanceOf(EventRegistrationGuards::class, $provider);
+    }
+
+    private function buildValidSchema(): FormSchema
+    {
+        $schema = FormSchema::factory()->create([
+            'purpose' => FormPurpose::EVENT_REGISTRATION->value,
+            'section_level_submit' => false,
+        ]);
+
+        $emailField = FormField::factory()->create([
+            'form_schema_id' => $schema->id,
+            'field_type' => FormFieldType::EMAIL->value,
+        ]);
+        FormFieldBinding::factory()->forField($emailField)->entityOwned('person', 'email')
+            ->create(['is_identity_key' => true, 'trust_level' => 80]);
+
+        $firstNameField = FormField::factory()->create([
+            'form_schema_id' => $schema->id,
+            'field_type' => FormFieldType::TEXT->value,
+        ]);
+        FormFieldBinding::factory()->forField($firstNameField)->entityOwned('person', 'first_name')
+            ->create(['is_identity_key' => false, 'trust_level' => 60]);
+
+        $lastNameField = FormField::factory()->create([
+            'form_schema_id' => $schema->id,
+            'field_type' => FormFieldType::TEXT->value,
+        ]);
+        FormFieldBinding::factory()->forField($lastNameField)->entityOwned('person', 'last_name')
+            ->create(['is_identity_key' => false, 'trust_level' => 50]);
+
+        $schema->load(['fields.bindings', 'fields.configs', 'sections']);
+
+        return $schema;
+    }
+}
--- a/api/tests/Feature/FormBuilder/Purposes/SupplierIntakeGuardsIntegrationTest.php
+++ b/api/tests/Feature/FormBuilder/Purposes/SupplierIntakeGuardsIntegrationTest.php
@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\Purposes;
+
+use App\Enums\FormBuilder\FormPurpose;
+use App\FormBuilder\Purposes\Guards\SupplierIntakeGuards;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldBinding;
+use App\Models\FormBuilder\FormSchema;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class SupplierIntakeGuardsIntegrationTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_valid_schema_passes_all_guards(): void
+    {
+        $schema = $this->buildValidSchema();
+        $provider = $this->app->make(SupplierIntakeGuards::class);
+
+        foreach ($provider->publishGuards() as $guard) {
+            $result = $guard->evaluate($schema);
+            $this->assertTrue(
+                $result->passed,
+                "Guard {$guard->code()} failed: {$result->messageKey}",
+            );
+        }
+    }
+
+    public function test_two_identity_keys_on_company_fails(): void
+    {
+        $schema = $this->buildValidSchema();
+        $extraField = FormField::factory()->create(['form_schema_id' => $schema->id]);
+        FormFieldBinding::factory()->forField($extraField)->entityOwned('company', 'kvk_number')
+            ->create(['is_identity_key' => true, 'trust_level' => 60]);
+        $schema->load('fields.bindings');
+
+        $provider = $this->app->make(SupplierIntakeGuards::class);
+
+        $failedCodes = [];
+        foreach ($provider->publishGuards() as $guard) {
+            $result = $guard->evaluate($schema);
+            if (! $result->passed) {
+                $failedCodes[] = $guard->code();
+            }
+        }
+
+        $this->assertContains('max_one_identity_key_per_target_entity', $failedCodes);
+    }
+
+    private function buildValidSchema(): FormSchema
+    {
+        $schema = FormSchema::factory()->create([
+            'purpose' => FormPurpose::SUPPLIER_INTAKE->value,
+        ]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+        FormFieldBinding::factory()->forField($field)->entityOwned('company', 'name')
+            ->create(['is_identity_key' => true, 'trust_level' => 80]);
+        $schema->load(['fields.bindings', 'sections']);
+
+        return $schema;
+    }
+}