MokoCLI/lib/Enterprise/RecoverySuggestion.php

<?php

/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 * SPDX-License-Identifier: GPL-3.0-or-later
 * FILE INFORMATION
 * DEFGROUP: MokoPlatform.Enterprise
 * INGROUP: MokoPlatform.Lib
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokocli
 * PATH: /lib/Enterprise/RecoverySuggestion.php
 * BRIEF: Smart error recovery suggestions for validators
 */

declare(strict_types=1);

namespace MokoCli;

/**
 * Generates actionable fix suggestions when validators detect problems.
 *
 * Each method returns a human-readable suggestion string that tells the
 * developer exactly what to do to fix the issue.
 */
class RecoverySuggestion
{
    /**
     * Suggest creating a missing required file.
     */
    public static function forMissingFile(string $file, string $template = ''): string
    {
        $suggestion = "Create the missing file: {$file}";
        if ($template !== '') {
            $suggestion .= "\n    Copy from template: {$template}";
        }
        return $suggestion;
    }

    /**
     * Suggest adding a missing XML element.
     */
    public static function forMissingXmlElement(string $element, string $value, string $file, int $afterLine = 0): string
    {
        $snippet = "<{$element}>{$value}</{$element}>";
        if ($afterLine > 0) {
            return "Add {$snippet} after line {$afterLine} in {$file}";
        }
        return "Add {$snippet} to {$file}";
    }

    /**
     * Suggest fixing a version mismatch.
     */
    public static function forVersionMismatch(string $file, string $found, string $expected): string
    {
        return "Update version in {$file}: change \"{$found}\" to \"{$expected}\"";
    }

    /**
     * Suggest creating a missing directory.
     */
    public static function forMissingDirectory(string $dir): string
    {
        return "Create the missing directory:\n    mkdir -p {$dir}";
    }

    /**
     * Suggest fixing a syntax error.
     */
    public static function forSyntaxError(string $file, int $line, string $error): string
    {
        return "Fix syntax error at {$file}:{$line}\n    {$error}";
    }

    /**
     * Suggest fixing a missing license header.
     */
    public static function forMissingHeader(string $file): string
    {
        return "Add SPDX license header to {$file}:\n"
            . "    /* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>\n"
            . "     * SPDX-License-Identifier: GPL-3.0-or-later */";
    }

    /**
     * Suggest running a command to fix an issue.
     */
    public static function forCommand(string $command, string $context = ''): string
    {
        $suggestion = "Run: {$command}";
        if ($context !== '') {
            $suggestion = "{$context}\n    {$suggestion}";
        }
        return $suggestion;
    }
}