GitAttributesCommand.php

<?php

declare(strict_types=1);

/**
 * Fast Forward Development Tools for PHP projects.
 *
 * This file is part of fast-forward/dev-tools project.
 *
 * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
 * @license  https://opensource.org/licenses/MIT MIT License
 *
 * @see      https://github.com/php-fast-forward/
 * @see      https://github.com/php-fast-forward/dev-tools
 * @see      https://github.com/php-fast-forward/dev-tools/issues
 * @see      https://php-fast-forward.github.io/dev-tools/
 * @see      https://datatracker.ietf.org/doc/html/rfc2119
 */

namespace FastForward\DevTools\Console\Command;

use Composer\Command\BaseCommand;
use FastForward\DevTools\Composer\Json\ComposerJsonInterface;
use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
use FastForward\DevTools\Console\Input\HasJsonOption;
use FastForward\DevTools\Filesystem\FilesystemInterface;
use FastForward\DevTools\GitAttributes\CandidateProviderInterface;
use FastForward\DevTools\GitAttributes\ExistenceCheckerInterface;
use FastForward\DevTools\GitAttributes\ExportIgnoreFilterInterface;
use FastForward\DevTools\GitAttributes\MergerInterface;
use FastForward\DevTools\GitAttributes\ReaderInterface;
use FastForward\DevTools\GitAttributes\WriterInterface;
use FastForward\DevTools\Resource\FileDiffer;
use Psr\Log\LoggerInterface;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;

use function Safe\getcwd;

/**
 * Provides functionality to manage .gitattributes export-ignore rules.
 *
 * This command adds export-ignore entries for repository-only files and directories
 * to keep them out of Composer package archives.
 */
#[AsCommand(
    name: 'gitattributes',
    description: 'Manages .gitattributes export-ignore rules for leaner package archives.'
)]
final class GitAttributesCommand extends BaseCommand implements LoggerAwareCommandInterface
{
    use HasJsonOption;
    use LogsCommandResults;

    private const string FILENAME = '.gitattributes';

    private const string EXTRA_NAMESPACE = 'gitattributes';

    private const string EXTRA_KEEP_IN_EXPORT = 'keep-in-export';

    private const string EXTRA_NO_EXPORT_IGNORE = 'no-export-ignore';

    /**
     * Creates a new GitAttributesCommand instance.
     *
     * @param CandidateProviderInterface $candidateProvider the candidate provider
     * @param ExistenceCheckerInterface $existenceChecker the repository path existence checker
     * @param ExportIgnoreFilterInterface $exportIgnoreFilter the configured candidate filter
     * @param MergerInterface $merger the merger component
     * @param ReaderInterface $reader the reader component
     * @param WriterInterface $writer the writer component
     * @param FilesystemInterface $filesystem the filesystem component
     * @param ComposerJsonInterface $composer the composer.json accessor
     * @param FileDiffer $fileDiffer
     * @param LoggerInterface $logger the output-aware logger
     */
    public function __construct(
        private readonly CandidateProviderInterface $candidateProvider,
        private readonly ExistenceCheckerInterface $existenceChecker,
        private readonly ExportIgnoreFilterInterface $exportIgnoreFilter,
        private readonly MergerInterface $merger,
        private readonly ReaderInterface $reader,
        private readonly WriterInterface $writer,
        private readonly ComposerJsonInterface $composer,
        private readonly FilesystemInterface $filesystem,
        private readonly FileDiffer $fileDiffer,
        private readonly LoggerInterface $logger,
    ) {
        parent::__construct();
    }

    /**
     * Configures verification and interactive update modes.
     */
    protected function configure(): void
    {
        $this->setHelp(
            'This command adds export-ignore entries for repository-only files and directories to keep them out of Composer package archives. '
            . 'Only paths that exist in the repository are added, existing custom rules are preserved, and '
            . '"extra.gitattributes.keep-in-export" paths stay in exported archives.'
        );

        $this->addJsonOption()
            ->addOption(
                name: 'dry-run',
                mode: InputOption::VALUE_NONE,
                description: 'Preview .gitattributes synchronization without writing the file.',
            )
            ->addOption(
                name: 'check',
                mode: InputOption::VALUE_NONE,
                description: 'Report .gitattributes drift and exit non-zero when changes are required.',
            )
            ->addOption(
                name: 'interactive',
                mode: InputOption::VALUE_NONE,
                description: 'Prompt before updating .gitattributes.',
            );
    }

    /**
     * Configures the current command.
     *
     * This method MUST define the name, description, and help text for the command.
     *
     * @param InputInterface $input
     * @param OutputInterface $output
     */
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $this->logger->info('Synchronizing .gitattributes export-ignore rules...', [
            'input' => $input,
        ]);
        $dryRun = (bool) $input->getOption('dry-run');
        $check = (bool) $input->getOption('check');
        $interactive = (bool) $input->getOption('interactive');

        $basePath = getcwd();
        $keepInExportPaths = $this->configuredKeepInExportPaths();

        $folderCandidates = $this->exportIgnoreFilter->filter($this->candidateProvider->folders(), $keepInExportPaths);
        $fileCandidates = $this->exportIgnoreFilter->filter($this->candidateProvider->files(), $keepInExportPaths);

        $existingFolders = $this->existenceChecker->filterExisting($basePath, $folderCandidates);
        $existingFiles = $this->existenceChecker->filterExisting($basePath, $fileCandidates);

        $entries = [...$existingFolders, ...$existingFiles];

        if ([] === $entries) {
            $this->notice('No candidate paths found in repository. Skipping .gitattributes sync.', $input);

            return $this->success(
                'No .gitattributes synchronization changes were required.',
                $input,
                logLevel: 'notice',
            );
        }

        $gitattributesPath = $this->filesystem->getAbsolutePath(self::FILENAME);
        $existingContent = $this->reader->read($gitattributesPath);
        $content = $this->merger->merge($existingContent, $entries, $keepInExportPaths);
        $renderedContent = $this->writer->render($content);
        $comparison = $this->fileDiffer->diffContents(
            'generated .gitattributes synchronization',
            $gitattributesPath,
            $renderedContent,
            '' === $existingContent ? null : $this->writer->render($existingContent),
            \sprintf('Updating managed file %s from generated .gitattributes synchronization.', $gitattributesPath),
        );

        $this->logger->notice(
            $comparison->getSummary(),
            [
                'input' => $input,
                'gitattributes_path' => $gitattributesPath,
            ],
        );

        if ($comparison->isChanged()) {
            $consoleDiff = $this->fileDiffer->formatForConsole($comparison->getDiff(), $output->isDecorated());

            if (null !== $consoleDiff) {
                $this->logger->notice(
                    $consoleDiff,
                    [
                        'input' => $input,
                        'gitattributes_path' => $gitattributesPath,
                        'diff' => $comparison->getDiff(),
                    ],
                );
            }
        }

        if ($comparison->isUnchanged()) {
            return $this->success('.gitattributes already matches the generated export-ignore rules.', $input);
        }

        if ($check) {
            return $this->failure(
                '.gitattributes requires synchronization updates.',
                $input,
                [
                    'gitattributes_path' => $gitattributesPath,
                ],
                $gitattributesPath,
            );
        }

        if ($dryRun) {
            return $this->success(
                '.gitattributes synchronization preview completed.',
                $input,
                [
                    'gitattributes_path' => $gitattributesPath,
                ],
                'notice',
            );
        }

        if ($interactive && $input->isInteractive() && ! $this->shouldWriteGitAttributes($gitattributesPath)) {
            $this->notice(
                'Skipped updating {gitattributes_path}.',
                $input,
                [
                    'gitattributes_path' => $gitattributesPath,
                ],
            );

            return $this->success(
                '.gitattributes synchronization was skipped.',
                $input,
                [
                    'gitattributes_path' => $gitattributesPath,
                ],
                'notice',
            );
        }

        $this->writer->write($gitattributesPath, $content);

        return $this->success(
            'Added {entries_count} export-ignore entries to .gitattributes.',
            $input,
            [
                'entries_count' => \count($entries),
                'gitattributes_path' => $gitattributesPath,
            ],
        );
    }

    /**
     * Prompts whether .gitattributes should be updated.
     *
     * @param string $targetPath the target path that would be updated
     *
     * @return bool true when the update SHOULD proceed
     */
    private function shouldWriteGitAttributes(string $targetPath): bool
    {
        return $this->getIO()
            ->askConfirmation(\sprintf('Update managed file %s? [y/N] ', $targetPath), false);
    }

    /**
     * Resolves the consumer-defined paths that MUST stay in exported archives.
     *
     * The preferred configuration key is "extra.gitattributes.keep-in-export".
     * The alternate "extra.gitattributes.no-export-ignore" key remains
     * supported as a compatibility alias.
     *
     * @return list<string> the configured keep-in-export paths
     */
    private function configuredKeepInExportPaths(): array
    {
        $extra = $this->composer->getExtra(self::EXTRA_NAMESPACE);

        return array_unique(array_merge(
            $extra[self::EXTRA_KEEP_IN_EXPORT] ?? [],
            $extra[self::EXTRA_NO_EXPORT_IGNORE] ?? [],
        ));
    }
}