<?php
/**
 * AnswerRails Knowledge Chunker
 *
 * @package AnswerRails
 * @subpackage Knowledge
 * @since 0.0.51
 *
 * Splits a knowledge item's content into retrieval-sized chunks for the
 * local chunk store (RETRIEVAL_RESILIENCE_DESIGN). This is layer 1 of
 * the #89 hybrid retrieval architecture: in this release the chunks feed
 * the lexical (MySQL fulltext) fallback; the full hybrid build later adds
 * embeddings over the SAME chunks.
 *
 * This component is responsible for:
 * - Deterministic, pure text→chunks segmentation (no WP state, no I/O)
 *
 * It does NOT handle:
 * - Persistence (AnswerRails_Chunk_Store)
 * - Deciding WHEN to chunk (AnswerRails_Knowledge_Service sync path)
 *
 * Used by:
 * - AnswerRails_Knowledge_Service
 * - AnswerRails_Migrations (1.3.0 backfill)
 */

if (!defined('ABSPATH')) {
    exit;
}

class AnswerRails_Knowledge_Chunker {

    /**
     * Default packing target per chunk, in characters (~450–500 tokens).
     */
    const DEFAULT_TARGET_SIZE = 1800;

    /**
     * A single paragraph longer than this is split at sentence/whitespace
     * boundaries rather than kept whole.
     */
    const HARD_SPLIT_THRESHOLD = 3000;

    /**
     * Chunk a knowledge item's body text.
     *
     * Splits on blank-line paragraph boundaries and packs paragraphs
     * greedily up to the target size. Every chunk is prefixed with a
     * "Title: {title}" line so lexical search matches title words too.
     *
     * @param string $title Item title (used as the per-chunk prefix line).
     * @param string $body  Item body text (WITHOUT the sync metadata header).
     * @return string[] Ordered chunk texts; empty array for empty body.
     */
    public static function chunk($title, $body) {
        $body  = self::normalise((string) $body);
        $title = trim(preg_replace('/\s+/', ' ', (string) $title));

        if ($body === '') {
            return array();
        }

        $target = (int) apply_filters('answerrails_chunk_target_size', self::DEFAULT_TARGET_SIZE);
        // Clamp to sane bounds: below ~500 chunks shred sentences; TEXT
        // column and prompt-injection sizing cap the top end.
        $target = max(500, min(10000, $target));

        $prefix = $title !== '' ? 'Title: ' . $title . "\n" : '';

        $paragraphs = self::split_paragraphs($body, $target);
        $chunks     = array();
        $buffer     = '';

        foreach ($paragraphs as $paragraph) {
            if ($buffer === '') {
                $buffer = $paragraph;
                continue;
            }
            if (strlen($buffer) + 2 + strlen($paragraph) <= $target) {
                $buffer .= "\n\n" . $paragraph;
            } else {
                $chunks[] = $prefix . $buffer;
                $buffer   = $paragraph;
            }
        }
        if ($buffer !== '') {
            $chunks[] = $prefix . $buffer;
        }

        return $chunks;
    }

    /**
     * Split body into paragraphs, hard-splitting any paragraph that exceeds
     * HARD_SPLIT_THRESHOLD (or the target, if larger) at sentence and then
     * whitespace boundaries.
     *
     * @param string $body   Normalised body text.
     * @param int    $target Packing target (chars).
     * @return string[]
     */
    private static function split_paragraphs($body, $target) {
        $raw = preg_split('/\n\s*\n/', $body);
        $out = array();

        $hard_limit = max(self::HARD_SPLIT_THRESHOLD, $target);

        foreach ($raw as $paragraph) {
            $paragraph = trim($paragraph);
            if ($paragraph === '') {
                continue;
            }
            if (strlen($paragraph) <= $hard_limit) {
                $out[] = $paragraph;
                continue;
            }
            foreach (self::hard_split($paragraph, $target) as $piece) {
                $out[] = $piece;
            }
        }

        return $out;
    }

    /**
     * Split an oversized paragraph into <= $target pieces, preferring
     * sentence boundaries, then whitespace, then (pathological single-token
     * input) a raw cut.
     *
     * @param string $paragraph Trimmed paragraph text.
     * @param int    $target    Maximum piece size (chars).
     * @return string[]
     */
    private static function hard_split($paragraph, $target) {
        // Sentence-ish boundaries: punctuation followed by whitespace.
        $sentences = preg_split('/(?<=[.!?])\s+/', $paragraph);
        $pieces    = array();
        $buffer    = '';

        foreach ($sentences as $sentence) {
            // A single sentence longer than the target: split on whitespace.
            while (strlen($sentence) > $target) {
                $cut = strrpos(substr($sentence, 0, $target), ' ');
                if ($cut === false || $cut === 0) {
                    $cut = $target; // no whitespace to cut at — raw cut
                }
                $head = trim(substr($sentence, 0, $cut));
                if ($buffer !== '') {
                    $pieces[] = $buffer;
                    $buffer   = '';
                }
                if ($head !== '') {
                    $pieces[] = $head;
                }
                $sentence = trim(substr($sentence, $cut));
            }

            if ($sentence === '') {
                continue;
            }
            if ($buffer === '') {
                $buffer = $sentence;
            } elseif (strlen($buffer) + 1 + strlen($sentence) <= $target) {
                $buffer .= ' ' . $sentence;
            } else {
                $pieces[] = $buffer;
                $buffer   = $sentence;
            }
        }
        if ($buffer !== '') {
            $pieces[] = $buffer;
        }

        return $pieces;
    }

    /**
     * Normalise line endings and trim outer whitespace.
     *
     * @param string $text
     * @return string
     */
    private static function normalise($text) {
        $text = str_replace(array("\r\n", "\r"), "\n", $text);
        return trim($text);
    }
}