feat(form-builder): integrate PublishGuard framework into FormSchemaService::publish() (WS-6)

assertPublishGuardsSatisfied() runs additively after the existing assertRequiredBindingsPresent() check. Failures are collected (not first-fail) so PublishGuardViolationException carries the full list to the builder UI in one 422 response. PurposeRequirementsNotMetException remains for missing bindings; PublishGuardViolationException covers semantic constraints (is_identity_key flag, no-ambiguous-trust, append-collection-only, section-aware schemas, conditional triggers). Two pre-existing tests updated their fixtures to satisfy the new guards (PublishChecksRelationalBindingsTest + PurposeSchemaLifecycleTest): EMAIL field type + is_identity_key on person.email + unique trust levels are now required for event_registration to publish. Refs: RFC-WS-6.md §3 (Q13) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-25 23:07:12 +02:00
parent e3c9211e3f
commit 7a747382a0
5 changed files with 288 additions and 15 deletions
--- a/api/tests/Feature/FormBuilder/Bindings/PublishChecksRelationalBindingsTest.php
+++ b/api/tests/Feature/FormBuilder/Bindings/PublishChecksRelationalBindingsTest.php
@@ -4,9 +4,11 @@ declare(strict_types=1);

 namespace Tests\Feature\FormBuilder\Bindings;

+use App\Enums\FormBuilder\FormFieldType;
 use App\Enums\FormBuilder\FormPurpose;
 use App\Exceptions\FormBuilder\PurposeRequirementsNotMetException;
 use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldBinding;
 use App\Models\FormBuilder\FormSchema;
 use App\Models\Organisation;
 use App\Models\User;
@@ -53,9 +55,22 @@ final class PublishChecksRelationalBindingsTest extends TestCase
            $this->actor,
        );

-        FormField::factory()->withEntityBinding('person', 'email')->create(['form_schema_id' => $schema->id]);
-        FormField::factory()->withEntityBinding('person', 'first_name')->create(['form_schema_id' => $schema->id]);
-        FormField::factory()->withEntityBinding('person', 'last_name')->create(['form_schema_id' => $schema->id]);
+        // WS-6 publish guards require: EMAIL field type, identity_key flag
+        // on person.email, unique trust levels per (entity, attribute).
+        $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]);
+
+        $firstField = FormField::factory()->create(['form_schema_id' => $schema->id]);
+        FormFieldBinding::factory()->forField($firstField)->entityOwned('person', 'first_name')
+            ->create(['trust_level' => 70]);
+
+        $lastField = FormField::factory()->create(['form_schema_id' => $schema->id]);
+        FormFieldBinding::factory()->forField($lastField)->entityOwned('person', 'last_name')
+            ->create(['trust_level' => 60]);

        $published = $this->service->publish($schema->fresh(), $this->actor);

--- a/api/tests/Feature/FormBuilder/FormSchemaServicePublishGuardsTest.php
+++ b/api/tests/Feature/FormBuilder/FormSchemaServicePublishGuardsTest.php
@@ -0,0 +1,151 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder;
+
+use App\Enums\FormBuilder\FormFieldType;
+use App\Enums\FormBuilder\FormPurpose;
+use App\Exceptions\FormBuilder\PublishGuardViolationException;
+use App\Exceptions\FormBuilder\PurposeRequirementsNotMetException;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldBinding;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\User;
+use App\Services\FormBuilder\FormSchemaService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class FormSchemaServicePublishGuardsTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_valid_event_registration_schema_publishes(): void
+    {
+        $schema = $this->buildValidEventRegistrationSchema();
+
+        $this->service()->publish($schema, $this->actor());
+
+        $this->assertTrue($schema->refresh()->is_published);
+    }
+
+    public function test_missing_required_bindings_throws_existing_exception_first(): void
+    {
+        $schema = FormSchema::factory()->create([
+            'purpose' => FormPurpose::EVENT_REGISTRATION->value,
+        ]);
+        // No bindings → required_bindings (person.email/first_name/last_name) unmet.
+
+        $this->expectException(PurposeRequirementsNotMetException::class);
+        $this->service()->publish($schema, $this->actor());
+    }
+
+    public function test_missing_identity_key_flag_throws_publish_guard_violation(): void
+    {
+        $schema = $this->buildValidEventRegistrationSchema();
+        FormFieldBinding::query()->withoutGlobalScopes()
+            ->whereIn('owner_id', $schema->fields->pluck('id'))
+            ->where('target_attribute', 'email')
+            ->update(['is_identity_key' => false]);
+        $schema->load('fields.bindings');
+
+        try {
+            $this->service()->publish($schema, $this->actor());
+            $this->fail('Expected PublishGuardViolationException');
+        } catch (PublishGuardViolationException $e) {
+            $codes = array_map(static fn (\App\FormBuilder\Publishing\PublishGuardResult $v): string => $v->guardCode, $e->violations);
+            $this->assertContains('requires_identity_key_binding:person:email', $codes);
+        }
+        $this->assertFalse($schema->refresh()->is_published);
+    }
+
+    public function test_violations_are_sorted_lexicographically(): void
+    {
+        $schema = $this->buildValidEventRegistrationSchema();
+
+        // Trigger TWO violations: drop is_identity_key + create ambiguous trust.
+        FormFieldBinding::query()->withoutGlobalScopes()
+            ->whereIn('owner_id', $schema->fields->pluck('id'))
+            ->where('target_attribute', 'email')
+            ->update(['is_identity_key' => false, 'trust_level' => 60]);
+        FormFieldBinding::query()->withoutGlobalScopes()
+            ->whereIn('owner_id', $schema->fields->pluck('id'))
+            ->where('target_attribute', 'first_name')
+            ->update(['trust_level' => 60]);
+        $schema->load('fields.bindings');
+
+        try {
+            $this->service()->publish($schema, $this->actor());
+            $this->fail('Expected PublishGuardViolationException');
+        } catch (PublishGuardViolationException $e) {
+            $codes = array_map(static fn (\App\FormBuilder\Publishing\PublishGuardResult $v): string => $v->guardCode, $e->violations);
+            $sorted = $codes;
+            sort($sorted);
+            $this->assertSame($sorted, $codes, 'Violations must be sorted lexicographically by code');
+        }
+    }
+
+    public function test_response_renders_as_422_with_violation_payload(): void
+    {
+        $schema = $this->buildValidEventRegistrationSchema();
+        FormFieldBinding::query()->withoutGlobalScopes()
+            ->whereIn('owner_id', $schema->fields->pluck('id'))
+            ->where('target_attribute', 'email')
+            ->update(['is_identity_key' => false]);
+        $schema->load('fields.bindings');
+
+        try {
+            $this->service()->publish($schema, $this->actor());
+            $this->fail('Expected PublishGuardViolationException');
+        } catch (PublishGuardViolationException $e) {
+            $response = $e->render(request());
+            $this->assertSame(422, $response->getStatusCode());
+            $body = json_decode((string) $response->getContent(), true);
+            $this->assertSame('publish_blocked', $body['error']);
+            $this->assertSame('event_registration', $body['purpose_slug']);
+            $this->assertNotEmpty($body['violations']);
+        }
+    }
+
+    private function service(): FormSchemaService
+    {
+        return $this->app->make(FormSchemaService::class);
+    }
+
+    private function actor(): User
+    {
+        return User::factory()->create();
+    }
+
+    private function buildValidEventRegistrationSchema(): FormSchema
+    {
+        $schema = FormSchema::factory()->create([
+            'purpose' => FormPurpose::EVENT_REGISTRATION->value,
+            'section_level_submit' => false,
+            'is_published' => 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' => 70]);
+
+        $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]);
+
+        return $schema->fresh(['fields.bindings', 'fields.configs', 'sections']);
+    }
+}
--- a/api/tests/Feature/FormBuilder/Purposes/PurposeSchemaLifecycleTest.php
+++ b/api/tests/Feature/FormBuilder/Purposes/PurposeSchemaLifecycleTest.php
@@ -135,26 +135,42 @@ final class PurposeSchemaLifecycleTest extends TestCase
    {
        match ($purpose) {
            FormPurpose::EVENT_REGISTRATION => [
-                $this->addBindingField($schema, 'person', 'email', 'email'),
-                $this->addBindingField($schema, 'person', 'first_name', 'first_name'),
-                $this->addBindingField($schema, 'person', 'last_name', 'last_name'),
+                // WS-6 publish guards require: identity_key flag on email,
+                // EMAIL field type present, unique trust levels per target.
+                $this->addBindingField($schema, 'person', 'email', 'email', FormFieldType::EMAIL, isIdentityKey: true, trustLevel: 80),
+                $this->addBindingField($schema, 'person', 'first_name', 'first_name', trustLevel: 70),
+                $this->addBindingField($schema, 'person', 'last_name', 'last_name', trustLevel: 60),
            ],
            FormPurpose::SUPPLIER_INTAKE => [
-                $this->addBindingField($schema, 'company', 'name', 'company_name'),
+                $this->addBindingField($schema, 'company', 'name', 'company_name', isIdentityKey: true, trustLevel: 80),
            ],
            default => null,
        };
    }

-    private function addBindingField(FormSchema $schema, string $entity, string $column, string $slug): FormField
-    {
-        return FormField::factory()
-            ->withEntityBinding($entity, $column)
+    private function addBindingField(
+        FormSchema $schema,
+        string $entity,
+        string $column,
+        string $slug,
+        FormFieldType $fieldType = FormFieldType::TEXT,
+        bool $isIdentityKey = false,
+        int $trustLevel = 50,
+    ): FormField {
+        $field = FormField::factory()->create([
+            'form_schema_id' => $schema->id,
+            'field_type' => $fieldType->value,
+            'slug' => $slug,
+            'label' => ucfirst($slug),
+        ]);
+        \App\Models\FormBuilder\FormFieldBinding::factory()
+            ->forField($field)
+            ->entityOwned($entity, $column)
            ->create([
-                'form_schema_id' => $schema->id,
-                'field_type' => FormFieldType::TEXT,
-                'slug' => $slug,
-                'label' => ucfirst($slug),
+                'is_identity_key' => $isIdentityKey,
+                'trust_level' => $trustLevel,
            ]);
+
+        return $field;
    }
 }