<?php

/**
 * LolaCore - SkillParseError
 *
 * Thrown by YamlParser when a frontmatter block contains a construct
 * outside the supported subset (multiline scalars, anchors, aliases,
 * tags, escape sequences, depth > 2, etc.).
 *
 * Loud-failure: the parser never returns partial data — either a
 * complete valid array, or this exception with line+token context.
 *
 * @package LolaCore
 * @license GPL-2.0-or-later
 */

declare(strict_types=1);

namespace LolaCore\Skills\Exceptions;

class SkillParseError extends \RuntimeException
{
    private int $lineNumber;
    private string $token;
    private string $filePath;

    public function __construct(string $message, int $lineNumber, string $token, string $filePath = '')
    {
        parent::__construct($message);
        $this->lineNumber = $lineNumber;
        $this->token      = $token;
        $this->filePath   = $filePath;
    }

    public function getLineNumber(): int
    {
        return $this->lineNumber;
    }

    public function getToken(): string
    {
        return $this->token;
    }

    public function getFilePath(): string
    {
        return $this->filePath;
    }

    /**
     * Humanized message suitable for surfacing in logs or admin notices.
     */
    public function getUserMessage(): string
    {
        $path = $this->filePath !== '' ? $this->filePath : '(inline)';
        return sprintf(
            "Skill parse error in '%s' at line %d: unsupported construct '%s'. See: https://docs.lolacore.com/skills/yaml-format",
            $path,
            $this->lineNumber,
            $this->token
        );
    }
}
