<?php
/**
 * One place that shapes what a tool returned.
 *
 * @package MazeAi
 * @since   0.1.0
 */

declare(strict_types=1);

namespace MazeAi\Tools;

defined('ABSPATH') || exit;

use MazeAi\Kernel\Support\ToolOutcome;
use MazeAi\Support\Redactor;

/**
 * Mask, then cut, then shape (decision 036): key-shaped text is masked before anything is stored or sent, a result
 * over the budget is cut and says so (the model knows it saw a part), and the trace card gets a one-line summary.
 * The "this is untrusted site data" wrapper is added later by the context builder, because it belongs to the request,
 * not to what is stored.
 *
 * @since 0.1.0
 */
final class ResultShaper
{
    /** Largest result kept and handed to the model, in bytes of JSON. */
    public const BUDGET = 16384;

    /**
     * @since 0.1.0
     * @param array{summary?: string, change?: int} $ui
     */
    public static function shape(mixed $raw, Tool $tool, array $ui = [], ?string $content = null): ToolOutcome
    {
        $data = self::cut(Redactor::maskDeep($raw));

        return new ToolOutcome(
            ToolOutcome::OK,
            $data,
            $content !== null ? Redactor::mask($content) : null,
            $ui + ['summary' => self::summary($data)],
            '',
            '',
            $tool->untrusted,
        );
    }

    /**
     * Keep a value within the budget; a larger one is cut and says so.
     *
     * @since 0.1.0
     */
    public static function cut(mixed $result): mixed
    {
        $json = wp_json_encode($result);
        if (!is_string($json) || strlen($json) <= self::BUDGET) {
            return $result;
        }

        return [
            'truncated' => true,
            'note'      => sprintf('The result was %d bytes; only the first %d are shown.', strlen($json), self::BUDGET),
            'partial'   => substr($json, 0, self::BUDGET),
        ];
    }

    /**
     * A short, neutral description of a result for the trace card: how many items or fields came back.
     *
     * @since 0.1.0
     */
    public static function summary(mixed $data): string
    {
        if (is_array($data) && ($data['truncated'] ?? false) === true) {
            return __('Large result, shortened', 'maze-graph');
        }
        if (is_array($data) && array_is_list($data)) {
            /* translators: %d: number of items. */
            return sprintf(_n('%d item', '%d items', count($data), 'maze-graph'), count($data));
        }
        if (is_array($data)) {
            foreach (['items', 'plugins', 'themes', 'posts', 'comments', 'terms', 'events', 'notes', 'tests'] as $key) {
                if (isset($data[$key]) && is_array($data[$key])) {
                    /* translators: %d: number of items. */
                    return sprintf(_n('%d item', '%d items', count($data[$key]), 'maze-graph'), count($data[$key]));
                }
            }

            /* translators: %d: number of fields. */
            return sprintf(_n('%d field', '%d fields', count($data), 'maze-graph'), count($data));
        }

        return $data === null ? __('No result', 'maze-graph') : __('1 value', 'maze-graph');
    }
}