<?php

declare(strict_types=1);

use App\Support\Links\RequiredPermissionsLinks;
use App\Support\ProductKnowledge\ContextualHelpCatalog;

it('exposes the locked first-slice topic catalog and safe knowledge source', function (): void {
    $catalog = new ContextualHelpCatalog();

    expect($catalog->keys())->toBe([
        ContextualHelpCatalog::ADMIN_CONSENT_REQUIRED,
        ContextualHelpCatalog::REQUIRED_PERMISSIONS_MISSING,
        ContextualHelpCatalog::CONNECTION_UNHEALTHY,
        ContextualHelpCatalog::VERIFICATION_STALE,
        ContextualHelpCatalog::VERIFICATION_FAILED,
        ContextualHelpCatalog::DIAGNOSTIC_EVIDENCE_INCOMPLETE,
        ContextualHelpCatalog::RETRYABLE_PROVIDER_FAILURE,
        ContextualHelpCatalog::MANUAL_HANDOFF_REQUIRED,
    ])->and($catalog->definition(ContextualHelpCatalog::ADMIN_CONSENT_REQUIRED))->toMatchArray([
        'topic_key' => ContextualHelpCatalog::ADMIN_CONSENT_REQUIRED,
        'surface_families' => ['onboarding', 'support_diagnostics'],
        'headline' => 'Admin consent required',
        'safe_next_action' => 'Grant admin consent and re-run verification.',
    ]);

    $knowledgeSource = $catalog->knowledgeSource();
    $topicsByKey = collect($knowledgeSource['topics'])->keyBy('topic_key');

    expect($knowledgeSource)->toMatchArray([
        'version' => 1,
        'topic_count' => 8,
    ])->and($topicsByKey->keys()->all())->toBe($catalog->keys())
        ->and($topicsByKey->get(ContextualHelpCatalog::ADMIN_CONSENT_REQUIRED))->toMatchArray([
            'headline' => 'Admin consent required',
            'docs_links' => [
                [
                    'label' => 'Grant admin consent',
                    'kind' => 'action',
                    'url' => null,
                    'resolver' => ContextualHelpCatalog::LINK_RESOLVER_ADMIN_CONSENT_PRIMARY,
                ],
                [
                    'label' => 'Admin consent guide',
                    'kind' => 'docs',
                    'url' => RequiredPermissionsLinks::adminConsentGuideUrl(),
                    'resolver' => null,
                ],
            ],
        ]);
});

it('rejects unknown contextual help topics', function (): void {
    $catalog = new ContextualHelpCatalog();

    expect(fn (): array => $catalog->definition('unknown-topic'))
        ->toThrow(InvalidArgumentException::class, 'Unknown contextual help topic');
});

it('keeps every machine-readable topic on the approved metadata surface only', function (): void {
    $knowledgeSource = app(\App\Support\ProductKnowledge\ContextualHelpResolver::class)->knowledgeSource();
    $allowedResolvers = [
        null,
        ContextualHelpCatalog::LINK_RESOLVER_ADMIN_CONSENT_PRIMARY,
        ContextualHelpCatalog::LINK_RESOLVER_REQUIRED_PERMISSIONS,
    ];

    foreach ($knowledgeSource['topics'] as $topic) {
        expect(array_keys($topic))->toBe([
            'topic_key',
            'surface_families',
            'headline',
            'short_explanation',
            'troubleshooting_steps',
            'safe_next_action',
            'glossary_terms',
            'docs_links',
        ]);

        foreach ($topic['docs_links'] as $link) {
            expect(array_keys($link))->toBe(['label', 'kind', 'url', 'resolver'])
                ->and($link['resolver'])->toBeIn($allowedResolvers);
        }
    }
});
