[sync] Add preview and check modes to sync (#62)

Author: coisa

docs/commands/copy-resource.rst

@@ -22,8 +22,8 @@ Usage
 .. code-block:: bash
 
    composer copy-resource --source <path> --target <path>
-   composer dev-tools copy-resource -- --source <path> --target <path> [--overwrite]
-   vendor/bin/dev-tools copy-resource --source <path> --target <path> [--overwrite]
+   composer dev-tools copy-resource -- --source <path> --target <path> [--overwrite] [--dry-run] [--check] [--interactive]
+   vendor/bin/dev-tools copy-resource --source <path> --target <path> [--overwrite] [--dry-run] [--check] [--interactive]
 
 Options
 -------
@@ -40,6 +40,16 @@ Options
    before copying. Unchanged targets are reported as skipped, and binary or
    unreadable files fall back to a clear non-diff message.
 
+``--dry-run``
+   Preview drift for existing managed resources without writing files.
+
+``--check``
+   Exit with code ``1`` when an existing managed resource differs from the
+   packaged source.
+
+``--interactive``
+   Prompt before replacing a drifted resource.
+
 Examples
 --------
 

docs/commands/git-hooks.rst

@@ -34,6 +34,16 @@ Options
 ``--no-overwrite``
    Do not overwrite existing hook files.
 
+``--dry-run``
+   Preview managed Git hook drift without copying files.
+
+``--check``
+   Exit with code ``1`` when packaged Git hooks differ from the installed
+   versions.
+
+``--interactive``
+   Prompt before replacing a drifted Git hook.
+
 Examples
 --------
 

docs/commands/gitattributes.rst

@@ -21,7 +21,14 @@ Usage
 Options
 -------
 
-This command does not accept additional options.
+``--dry-run``
+   Preview managed ``.gitattributes`` drift without writing the file.
+
+``--check``
+   Exit with code ``1`` when ``.gitattributes`` needs an update.
+
+``--interactive``
+   Prompt before updating ``.gitattributes``.
 
 Examples
 --------
@@ -57,3 +64,5 @@ Behavior
 - Deduplicates equivalent entries and sorts them (directories before files, then alphabetically).
 - Uses CandidateProvider, ExistenceChecker, ExportIgnoreFilter, Merger,
   Reader, and Writer components from the GitAttributes namespace.
+- ``--dry-run`` and ``--check`` render a diff against the normalized managed
+  result before deciding whether to write.

docs/commands/gitignore.rst

@@ -28,6 +28,15 @@ Options
 ``--target, -t`` (optional)
    Path to the target .gitignore file (project). Default: project root .gitignore.
 
+``--dry-run``
+   Preview managed ``.gitignore`` drift without writing the file.
+
+``--check``
+   Exit with code ``1`` when ``.gitignore`` needs an update.
+
+``--interactive``
+   Prompt before updating ``.gitignore``.
+
 Examples
 --------
 
@@ -63,3 +72,5 @@ Behavior
 - By default, the source is the packaged .gitignore and the target is the project's root.
 - Duplicates are removed and entries are sorted alphabetically.
 - Uses the Reader, Merger, and Writer components from the GitIgnore namespace.
+- ``--dry-run`` and ``--check`` render a diff against the normalized managed
+  result before deciding whether to write.

docs/commands/license.rst

@@ -25,6 +25,15 @@ Options
 ``--target`` (optional)
    Path to the target LICENSE file. Default: ``LICENSE``.
 
+``--dry-run``
+   Preview managed ``LICENSE`` drift without writing the file.
+
+``--check``
+   Exit with code ``1`` when ``LICENSE`` needs an update.
+
+``--interactive``
+   Prompt before writing the generated ``LICENSE`` content.
+
 Examples
 --------
 
@@ -60,4 +69,5 @@ Behavior
 - Supports common open-source licenses: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause,
   GPL-3.0, LGPL-3.0, ISC, MPL-2.0.
 - Resolves placeholders using information from ``composer.json``.
-- Skips generation if a LICENSE file already exists.
+- Compares the generated content with the existing file before deciding whether
+  to write.

docs/commands/sync.rst

@@ -36,6 +36,16 @@ Options
    ``copy-resource`` show a readable diff in the sync output before they are
    replaced.
 
+``--dry-run``
+   Preview managed-file drift without writing changes.
+
+``--check``
+   Report managed-file drift and exit with code ``1`` when updates are
+   required.
+
+``--interactive``
+   Prompt before replacing drifted managed files.
+
 Examples
 --------
 
@@ -51,6 +61,18 @@ Sync with overwrite:
 
    composer dev-tools:sync --overwrite
 
+Preview managed-file drift:
+
+.. code-block:: bash
+
+   composer dev-tools:sync --dry-run
+
+Fail in CI when managed files drift:
+
+.. code-block:: bash
+
+   composer dev-tools:sync --check
+
 Exit Codes
 ---------
 
@@ -71,5 +93,12 @@ Behavior
 - Copies missing workflow stubs, ``.editorconfig``, and ``dependabot.yml``.
 - When ``--overwrite`` is enabled, replaced text resources emit a unified diff
   so terminal sessions and CI logs show what changed.
+- ``--dry-run`` and ``--check`` verify managed-file drift for ``composer.json``,
+  copied resources, ``.gitignore``, ``.gitattributes``, ``LICENSE``, and Git
+  hooks.
+- ``--interactive`` prompts before replacing drifted managed files when the
+  command is running in an interactive terminal.
 - Creates ``.github/wiki`` as a git submodule when missing.
 - Calls other commands in sequence.
+- ``wiki`` and ``skills`` are skipped in preview/check modes until they expose a
+  non-destructive verification path.

docs/commands/update-composer-json.rst

@@ -28,6 +28,15 @@ Options
 ``--file, -f`` (optional)
    Path to the composer.json file to update. Default: ``composer.json``.
 
+``--dry-run``
+   Preview managed ``composer.json`` drift without writing the file.
+
+``--check``
+   Exit with code ``1`` when ``composer.json`` needs an update.
+
+``--interactive``
+   Prompt before updating ``composer.json``.
+
 Examples
 --------
 
@@ -49,6 +58,8 @@ Behavior
 - If the target composer.json does not exist, the command exits silently with code 0.
 - Existing scripts with the same name are overwritten.
 - The GrumPHP extra configuration is merged with existing configuration.
+- ``--dry-run`` and ``--check`` render a diff against the managed
+  ``composer.json`` result before deciding whether to write.
 
 Exit Codes
 ---------

src/Console/Command/CopyResourceCommand.php

@@ -28,6 +28,7 @@
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Question\ConfirmationQuestion;
 use Symfony\Component\Filesystem\Path;
 
 /**
@@ -80,6 +81,21 @@ protected function configure(): void
                 shortcut: 'o',
                 mode: InputOption::VALUE_NONE,
                 description: 'Overwrite existing target files.',
+            )
+            ->addOption(
+                name: 'dry-run',
+                mode: InputOption::VALUE_NONE,
+                description: 'Preview copied resources without writing files.',
+            )
+            ->addOption(
+                name: 'check',
+                mode: InputOption::VALUE_NONE,
+                description: 'Report copied-resource drift and exit non-zero when changes are required.',
+            )
+            ->addOption(
+                name: 'interactive',
+                mode: InputOption::VALUE_NONE,
+                description: 'Prompt before replacing drifted resources.',
             );
     }
 
@@ -96,6 +112,9 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $source = (string) $input->getOption('source');
         $target = (string) $input->getOption('target');
         $overwrite = (bool) $input->getOption('overwrite');
+        $dryRun = (bool) $input->getOption('dry-run');
+        $check = (bool) $input->getOption('check');
+        $interactive = (bool) $input->getOption('interactive');
 
         if ('' === $source || '' === $target) {
             $output->writeln('<error>The --source and --target options are required.</error>');
@@ -107,10 +126,10 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $targetPath = (string) $this->filesystem->getAbsolutePath($target);
 
         if (is_dir($sourcePath)) {
-            return $this->copyDirectory($sourcePath, $targetPath, $overwrite, $output);
+            return $this->copyDirectory($sourcePath, $targetPath, $overwrite, $dryRun, $check, $interactive, $input, $output);
         }
 
-        return $this->copyFile($sourcePath, $targetPath, $overwrite, $output);
+        return $this->copyFile($sourcePath, $targetPath, $overwrite, $dryRun, $check, $interactive, $input, $output);
     }
 
     /**
@@ -127,19 +146,28 @@ private function copyDirectory(
         string $sourcePath,
         string $targetPath,
         bool $overwrite,
+        bool $dryRun,
+        bool $check,
+        bool $interactive,
+        InputInterface $input,
         OutputInterface $output
     ): int {
         $files = $this->finderFactory
             ->create()
             ->files()
             ->in($sourcePath);
 
+        $status = self::SUCCESS;
+
         foreach ($files as $file) {
             $destination = Path::join($targetPath, $file->getRelativePathname());
-            $this->copyFile($file->getRealPath(), $destination, $overwrite, $output);
+            $status = max(
+                $status,
+                $this->copyFile($file->getRealPath(), $destination, $overwrite, $dryRun, $check, $interactive, $input, $output),
+            );
         }
 
-        return self::SUCCESS;
+        return $status;
     }
 
     /**
@@ -152,15 +180,24 @@ private function copyDirectory(
      *
      * @return int the command status code
      */
-    private function copyFile(string $sourcePath, string $targetPath, bool $overwrite, OutputInterface $output): int
+    private function copyFile(
+        string $sourcePath,
+        string $targetPath,
+        bool $overwrite,
+        bool $dryRun,
+        bool $check,
+        bool $interactive,
+        InputInterface $input,
+        OutputInterface $output,
+    ): int
     {
-        if (! $overwrite && $this->filesystem->exists($targetPath)) {
+        if (! $overwrite && ! $dryRun && ! $check && ! $interactive && $this->filesystem->exists($targetPath)) {
             $output->writeln(\sprintf('<comment>Skipped existing resource %s.</comment>', $targetPath));
 
             return self::SUCCESS;
         }
 
-        if ($overwrite && $this->filesystem->exists($targetPath)) {
+        if (($overwrite || $dryRun || $check || $interactive) && $this->filesystem->exists($targetPath)) {
             $comparison = $this->overwriteDiffRenderer->render($sourcePath, $targetPath);
 
             $output->writeln(\sprintf('<comment>%s</comment>', $comparison->summary()));
@@ -172,11 +209,41 @@ private function copyFile(string $sourcePath, string $targetPath, bool $overwrit
             if ($comparison->isUnchanged()) {
                 return self::SUCCESS;
             }
+
+            if ($check) {
+                return self::FAILURE;
+            }
+
+            if ($dryRun) {
+                return self::SUCCESS;
+            }
+
+            if ($interactive && $input->isInteractive() && ! $this->shouldReplaceResource($input, $output, $targetPath)) {
+                $output->writeln(\sprintf('<comment>Skipped replacing %s.</comment>', $targetPath));
+
+                return self::SUCCESS;
+            }
         }
 
-        $this->filesystem->copy($sourcePath, $targetPath, $overwrite);
+        $this->filesystem->copy($sourcePath, $targetPath, $overwrite || $interactive);
         $output->writeln(\sprintf('<info>Copied resource %s.</info>', $targetPath));
 
         return self::SUCCESS;
     }
+
+    /**
+     * Prompts whether a drifted resource should be replaced.
+     *
+     * @param InputInterface $input the command input
+     * @param OutputInterface $output the command output
+     * @param string $targetPath the resource path that would be replaced
+     *
+     * @return bool true when the replacement SHOULD proceed
+     */
+    private function shouldReplaceResource(InputInterface $input, OutputInterface $output, string $targetPath): bool
+    {
+        $question = new ConfirmationQuestion(\sprintf('Replace drifted resource %s? [y/N] ', $targetPath), false);
+
+        return (bool) $this->getHelper('question')->ask($input, $output, $question);
+    }
 }