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

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

* Update wiki submodule pointer for PR #111

* [sync] Refine file diff handling and tests (#62)

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/wiki

@@ -56,6 +56,7 @@
         "rector/jack": "^0.5",
         "rector/rector": "^2.4",
         "saggre/phpdocumentor-markdown": "^1.0",
+        "sebastian/diff": "^7.0",
         "shipmonk/composer-dependency-analyser": "^1.8.4",
         "symfony/config": "^7.4 || ^8.0",
         "symfony/console": "^7.4 || ^8.0",

composer.json

@@ -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/copy-resource.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/git-hooks.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/gitattributes.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/gitignore.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/license.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/sync.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
 ---------