<?php

declare(strict_types=1);

namespace Plugin\tnt_mcp\src\Mcp\Guide;

/**
 * One thing wrong with one guide file: the file, a dotted path into its front matter
 * (`appliesTo[2]`, or `body` for the markdown half) and what was expected. The counterpart of
 * {@see \Plugin\tnt_mcp\src\Mcp\Action\CatalogValidationError}, for the same reason — a guide is
 * hand-written prose and "invalid" alone costs more than the mistake did.
 */
final class GuideValidationError
{
    private function __construct(
        public readonly string $file,
        public readonly string $path,
        public readonly string $message,
    ) {
    }

    public static function at(string $file, string $path, string $message): self
    {
        return new self($file, $path, $message);
    }

    /** `<file>: <path>: <message>` — one line, stable, greppable. */
    public function describe(): string
    {
        return \sprintf('%s: %s: %s', $this->file, $this->path === '' ? '<root>' : $this->path, $this->message);
    }
}
