<?php

namespace App\Docs\Strategies;

use Knuckles\Scribe\Extracting\Strategies\Strategy;
use Knuckles\Camel\Extraction\ExtractedEndpointData;
use Illuminate\Support\Str;

/**
 * Custom Scribe Strategy to fix URL parameters for dynamic routes.
 * 
 * This strategy ensures that path parameters are correctly extracted
 * for routes with dynamic segments like /api/{table}/{action}
 */
class FixUrlParametersStrategy extends Strategy
{
    /**
     * The stage this strategy belongs to.
     */
    public string $stage = 'urlParameters';

    /**
     * Trait this strategy applies to.
     */
    public static function routableIf(ExtractedEndpointData $endpoint): bool
    {
        // Only apply to the dynamic endpoint route
        return Str::contains($endpoint->route->uri, '{table}/{action}');
    }

    /**
     * @param ExtractedEndpointData $endpointData
     * @param array $routeRules
     * @return array|null
     */
    public function __invoke(ExtractedEndpointData $endpointData, array $routeRules = []): ?array
    {
        // Extract path parameters from route URI
        $uri = $endpointData->route->uri;
        $parameters = [];

        // Match {param} patterns in the URI
        if (preg_match_all('/\{(\w+)\}/', $uri, $matches)) {
            foreach ($matches[1] as $paramName) {
                // Always add/override parameter to ensure it exists
                // This ensures path parameters are always present even if
                // default strategies didn't extract them correctly
                // Scribe expects array format, not object
                $parameters[$paramName] = [
                    'name' => $paramName,
                    'type' => 'string',
                    'required' => true,
                    'description' => $this->getParameterDescription($paramName),
                    'example' => $this->getParameterExample($paramName),
                ];
            }
        }

        // Always return parameters if found
        // Scribe will merge these with existing parameters
        if (count($parameters) > 0) {
            return $parameters;
        }

        // If no parameters found, return null to let other strategies handle it
        return null;
    }

    /**
     * Get description for a parameter
     */
    private function getParameterDescription(string $paramName): string
    {
        $descriptions = [
            'table' => 'The Module Slug or Table Name.',
            'action' => 'The operation to perform.',
        ];

        return $descriptions[$paramName] ?? ucfirst($paramName) . ' parameter.';
    }

    /**
     * Get example value for a parameter
     */
    private function getParameterExample(string $paramName): string
    {
        $examples = [
            'table' => 'users',
            'action' => 'read',
        ];

        return $examples[$paramName] ?? 'example';
    }
}