[build] Move generated output defaults from public to .dev-tools (#107) (#108)

coisa · github-actions[bot] · web-flow · commit 563049ab7893 · 2026-04-19T02:05:20.000-03:00
* [build] Move generated output defaults from public to build (#107) * Update wiki submodule pointer for PR #108 * [build] Move generated output defaults from public to .dev-tools (#107) * [docs] Document metrics artifacts in tooling defaults (#107) * [build] Normalize .gitignore ordering for .dev-tools (#107) --------- Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
diff --git a/.github/wiki b/.github/wiki
@@ -1 +1 @@
-Subproject commit 4b06b3922c1c982a0ae68c4b7a4aa2321ee918bd
+Subproject commit 2958728ccf14ac506ad2ef44b6fd57ba02973934
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -103,7 +103,7 @@ jobs:
             - name: Run PHPUnit tests
               env:
                 COMPOSER_ROOT_VERSION: ${{ env.TESTS_ROOT_VERSION }}
-              run: composer dev-tools tests -- --coverage=public/coverage --min-coverage=${{ steps.minimum-coverage.outputs.value }}
+              run: composer dev-tools tests -- --coverage=.dev-tools/coverage --min-coverage=${{ steps.minimum-coverage.outputs.value }}
 
     dependency-health:
         name: Dependency Health
diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,7 @@
+.dev-tools/
 .idea/
 .vscode/
 backup/
-public/
 tmp/
 vendor/
 *.cache
diff --git a/README.md b/README.md
@@ -59,7 +59,7 @@ composer dependencies --upgrade --dev
 
 # Analyze code metrics with PhpMetrics
 composer metrics
-composer metrics --target=build/metrics
+composer metrics --target=.dev-tools/metrics
 composer --working-dir=packages/example metrics
 
 # Check and fix code style using ECS and Composer Normalize
@@ -79,7 +79,7 @@ composer wiki
 
 # Generate documentation frontpage and related reports
 composer reports
-composer reports --target=build --coverage=build/coverage
+composer reports --target=.dev-tools --coverage=.dev-tools/coverage
 
 # Synchronize packaged agent skills into .agents/skills
 composer skills
diff --git a/docs/api/phpunit-support.rst b/docs/api/phpunit-support.rst
@@ -57,7 +57,7 @@ coverage metrics programmatically.
    use FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoader;
 
    $loader = new CoverageSummaryLoader();
-   $summary = $loader->load('public/coverage/coverage.php');
+   $summary = $loader->load('.dev-tools/coverage/coverage.php');
 
    $summary->executedLines();      // Number of covered lines
    $summary->executableLines();   // Total number of executable lines
diff --git a/docs/commands/docs.rst b/docs/commands/docs.rst
@@ -28,7 +28,7 @@ Options
 
 ``--target, -t`` (optional)
    Path to the output directory for the generated HTML documentation.
-   Default: ``public``.
+   Default: ``.dev-tools``.
 
 ``--source, -s`` (optional)
    Path to the source directory for the guide documentation.
@@ -55,7 +55,7 @@ Generate to custom directory:
 
 .. code-block:: bash
 
-   composer docs --target=build/docs
+   composer docs --target=dist/docs
 
 Use custom source:
 
diff --git a/docs/commands/metrics.rst b/docs/commands/metrics.rst
@@ -33,12 +33,12 @@ Options
    Comma-separated directories that should be excluded from analysis.
 
    Default:
-   ``vendor,test,tests,tmp,cache,spec,build,backup,resources``.
+   ``vendor,test,tests,tmp,cache,spec,build,.dev-tools,backup,resources``.
 
 ``--target=<directory>``
    Output directory for the generated metrics reports.
 
-   Default: ``public/metrics``.
+   Default: ``.dev-tools/metrics``.
 
    The command writes:
 
@@ -59,13 +59,13 @@ Generate an HTML report for manual inspection:
 
 .. code-block:: bash
 
-   composer metrics --target=build/metrics
+   composer metrics --target=.dev-tools/metrics
 
 Generate the full metrics artifact set for CI previews:
 
 .. code-block:: bash
 
-   composer metrics --target=build/metrics
+   composer metrics --target=.dev-tools/metrics
 
 Analyze another checkout through Composer's inherited working directory:
 
diff --git a/docs/commands/reports.rst b/docs/commands/reports.rst
@@ -30,15 +30,15 @@ Options
 
 ``--target`` (optional)
    The target directory for the generated documentation.
-   Default: ``public``.
+   Default: ``.dev-tools``.
 
 ``--coverage, -c`` (optional)
    The target directory for the generated test coverage report.
-   Default: ``public/coverage``.
+   Default: ``.dev-tools/coverage``.
 
 ``--metrics`` (optional)
    The target directory for the generated metrics report.
-   Default: ``public/metrics``.
+   Default: ``.dev-tools/metrics``.
 
 Examples
 --------
@@ -53,13 +53,13 @@ Generate to custom directories:
 
 .. code-block:: bash
 
-   composer reports --target=build --coverage=build/coverage
+   composer reports --target=.dev-tools --coverage=.dev-tools/coverage
 
 Generate reports with a custom metrics directory:
 
 .. code-block:: bash
 
-   composer reports --metrics=build/metrics
+   composer reports --metrics=.dev-tools/metrics
 
 Exit Codes
 ---------
diff --git a/docs/commands/tests.rst b/docs/commands/tests.rst
@@ -79,13 +79,13 @@ Run with coverage report:
 
 .. code-block:: bash
 
-   composer tests --coverage=public/coverage
+   composer tests --coverage=.dev-tools/coverage
 
 Run with concise coverage text output:
 
 .. code-block:: bash
 
-   composer tests --coverage=public/coverage --coverage-summary
+   composer tests --coverage=.dev-tools/coverage --coverage-summary
 
 Run tests matching a pattern:
 
diff --git a/docs/configuration/tooling-defaults.rst b/docs/configuration/tooling-defaults.rst
@@ -36,9 +36,11 @@ create them on day one.
 Generated and Cache Directories
 -------------------------------
 
-- ``public/`` contains generated documentation and report output.
-- ``public/coverage/`` contains HTML coverage, Testdox, Clover, and raw
+- ``.dev-tools/`` contains generated documentation and report output.
+- ``.dev-tools/coverage/`` contains HTML coverage, Testdox, Clover, and raw
   coverage data.
+- ``.dev-tools/metrics/`` contains PhpMetrics HTML output plus the generated
+  ``report.json`` and ``report-summary.json`` artifacts.
 - ``.github/wiki/`` contains generated Markdown API documentation and, in
   consumer repositories, the wiki submodule.
 - ``.agents/skills/`` contains symlinked packaged skills or consumer-owned
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -131,5 +131,5 @@ This approach automatically receives upstream updates while allowing additive cu
 Can I generate coverage without running the full ``standards`` pipeline?
 ------------------------------------------------------------------------
 
-Yes. Run ``vendor/bin/dev-tools tests --coverage=public/coverage`` to generate
+Yes. Run ``vendor/bin/dev-tools tests --coverage=.dev-tools/coverage`` to generate
 coverage directly.
diff --git a/docs/running/reports.rst b/docs/running/reports.rst
@@ -3,36 +3,37 @@ Test Reports
 
 The ``reports`` command is the packaged "build the site" workflow. It is aimed
 at local verification and at the reusable GitHub Actions workflow that
-publishes the ``public/`` directory.
+publishes a generated reports directory to GitHub Pages.
 
 What the Command Runs
 ---------------------
 
 ``reports`` executes the following steps:
 
-1. ``docs --target public``
-2. ``tests --coverage public/coverage --no-progress --coverage-summary``
-3. ``metrics --target public/metrics --junit public/coverage/junit.xml``
+1. ``docs --target .dev-tools``
+2. ``tests --coverage .dev-tools/coverage --no-progress --coverage-summary``
+3. ``metrics --target .dev-tools/metrics --junit .dev-tools/coverage/junit.xml``
 
 Outputs
 -------
 
 After a successful run you should expect:
 
-- the documentation site rooted at ``public/``;
+- the documentation site rooted at ``.dev-tools/``;
 - guide pages generated from the local ``docs/`` source;
-- coverage reports inside ``public/coverage/``;
-- PhpMetrics output inside ``public/metrics/``;
-- ``public/coverage/testdox.html`` and ``public/coverage/clover.xml`` for
+- coverage reports inside ``.dev-tools/coverage/``;
+- PhpMetrics output inside ``.dev-tools/metrics/``;
+- ``.dev-tools/coverage/testdox.html`` and ``.dev-tools/coverage/clover.xml`` for
   human and CI consumption;
-- ``public/metrics/report.json`` and ``public/metrics/report-summary.json`` for
+- ``.dev-tools/metrics/report.json`` and ``.dev-tools/metrics/report-summary.json`` for
   preview artifacts and machine-readable metrics summaries.
 
 Why This Command Matters
 ------------------------
 
 - it is the last stage of ``standards``;
-- the reusable ``reports.yml`` workflow publishes ``public/`` to GitHub Pages;
+- the reusable ``reports.yml`` workflow publishes the generated reports
+  directory to GitHub Pages;
 - the live documentation, coverage, metrics, and Testdox links all depend on this
   directory structure staying stable.
 
diff --git a/docs/running/specialized-commands.rst b/docs/running/specialized-commands.rst
@@ -59,7 +59,7 @@ Analyzes code metrics with PhpMetrics.
 .. code-block:: bash
 
    composer metrics
-   composer metrics --target=build/metrics
+   composer metrics --target=.dev-tools/metrics
    composer --working-dir=packages/example metrics
 
 Important details:
@@ -133,7 +133,7 @@ Builds the HTML documentation site with phpDocumentor.
 
 .. code-block:: bash
 
-   composer docs --source=docs --target=public
+   composer docs --source=docs --target=.dev-tools
 
 Important details:
 
@@ -170,9 +170,9 @@ Runs the documentation and test-report pipeline used by GitHub Pages.
 
 Important details:
 
-- it calls ``docs --target public``;
-- it calls ``tests --coverage public/coverage --no-progress --coverage-summary``;
-- it calls ``metrics --target public/metrics --junit public/coverage/junit.xml``;
+- it calls ``docs --target .dev-tools``;
+- it calls ``tests --coverage .dev-tools/coverage --no-progress --coverage-summary``;
+- it calls ``metrics --target .dev-tools/metrics --junit .dev-tools/coverage/junit.xml``;
 - ``docs`` remains detached, while ``tests`` and ``metrics`` run in sequence so
   PhpMetrics can reuse the JUnit report generated by PHPUnit;
 - it is the reporting stage used by ``standards``.
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
@@ -173,7 +173,7 @@ Recovery:
 .. code-block:: bash
 
     composer dev-tools tests
-    composer dev-tools tests -- --coverage=public/coverage
+    composer dev-tools tests -- --coverage=.dev-tools/coverage
 
 Add focused tests for the changed behavior before lowering thresholds. If local
 coverage differs from CI, compare PHP, Xdebug or PCOV, and PHPUnit versions.
diff --git a/docs/usage/documentation-workflows.rst b/docs/usage/documentation-workflows.rst
@@ -28,7 +28,7 @@ Important Command Options
      - Selects the guide source directory.
    * - ``docs``
      - ``--target``
-     - ``public``
+     - ``.dev-tools``
      - Selects the HTML output directory.
    * - ``docs``
      - ``--template``
@@ -45,7 +45,7 @@ Common Examples
 .. code-block:: bash
 
    composer docs
-   vendor/bin/dev-tools docs --source=docs --target=public
+   vendor/bin/dev-tools docs --source=docs --target=.dev-tools
    composer wiki
    composer reports
 
@@ -55,18 +55,18 @@ What Each Command Is For
 - ``docs`` builds the HTML documentation site. It fails early if the source
   guide directory does not exist.
 - ``wiki`` builds Markdown API pages intended for ``.github/wiki``.
-- ``reports`` runs ``docs --target public`` and
-  ``tests --coverage public/coverage`` and then
-  ``metrics --target public/metrics --junit public/coverage/junit.xml``.
+- ``reports`` runs ``docs --target .dev-tools`` and
+  ``tests --coverage .dev-tools/coverage`` and then
+  ``metrics --target .dev-tools/metrics --junit .dev-tools/coverage/junit.xml``.
 
 Outputs to Expect
 -----------------
 
 - an HTML site rooted at the target directory chosen for ``docs``;
 - guide pages generated from ``docs/``;
-- coverage data under ``public/coverage`` when ``reports`` or
+- coverage data under ``.dev-tools/coverage`` when ``reports`` or
   ``tests --coverage`` is used;
-- metrics data under ``public/metrics`` when ``reports`` or ``metrics`` is
+- metrics data under ``.dev-tools/metrics`` when ``reports`` or ``metrics`` is
   used;
 - Markdown API pages under ``.github/wiki`` when ``wiki`` is used.
 
diff --git a/docs/usage/testing-and-coverage.rst b/docs/usage/testing-and-coverage.rst
@@ -21,20 +21,20 @@ Useful Examples
 
 .. code-block:: bash
 
-   composer dev-tools tests
-   composer dev-tools tests -- --filter=PluginTest
-   vendor/bin/dev-tools tests --coverage=public/coverage
+   composer tests
+   composer tests -- --filter=PluginTest
+   vendor/bin/dev-tools tests --coverage=.dev-tools/coverage
    vendor/bin/dev-tools tests --no-cache --bootstrap=tests/bootstrap.php
 
 Coverage Outputs
 ----------------
 
-When ``--coverage=public/coverage`` is used, PHPUnit writes:
+When ``--coverage=.dev-tools/coverage`` is used, PHPUnit writes:
 
-- ``public/coverage/index.html``
-- ``public/coverage/testdox.html``
-- ``public/coverage/clover.xml``
-- ``public/coverage/coverage.php``
+- ``.dev-tools/coverage/index.html``
+- ``.dev-tools/coverage/testdox.html``
+- ``.dev-tools/coverage/clover.xml``
+- ``.dev-tools/coverage/coverage.php``
 
 Built-In PHPUnit Extension
 --------------------------
@@ -64,7 +64,7 @@ external tooling or build custom reports:
    use FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoader;
 
    $loader = new CoverageSummaryLoader();
-   $summary = $loader->load('public/coverage/coverage.php');
+   $summary = $loader->load('.dev-tools/coverage/coverage.php');
 
    $summary->executedLines();      // e.g., 142
    $summary->executableLines();   // e.g., 168
diff --git a/src/Config/ECSConfig.php b/src/Config/ECSConfig.php
@@ -59,7 +59,7 @@ public static function configure(): ECSConfigBuilder
         return $config
             ->withPaths([$cwd])
             ->withSkip([
-                $cwd . '/public',
+                $cwd . '/.dev-tools',
                 $cwd . '/resources',
                 $cwd . '/vendor',
                 $cwd . '/tmp',
diff --git a/src/Config/RectorConfig.php b/src/Config/RectorConfig.php
@@ -72,7 +72,7 @@ public static function configure(?callable $customize = null): callable
             ]);
             $rectorConfig->paths([$cwd]);
             $rectorConfig->skip([
-                $cwd . '/public',
+                $cwd . '/.dev-tools',
                 $cwd . '/resources',
                 $cwd . '/vendor',
                 $cwd . '/tmp',
diff --git a/src/Console/Command/DocsCommand.php b/src/Console/Command/DocsCommand.php
@@ -78,7 +78,7 @@ protected function configure(): void
                 shortcut: 't',
                 mode: InputOption::VALUE_OPTIONAL,
                 description: 'Path to the output directory for the generated HTML documentation.',
-                default: 'public',
+                default: '.dev-tools',
             )
             ->addOption(
                 name: 'source',
diff --git a/src/Console/Command/MetricsCommand.php b/src/Console/Command/MetricsCommand.php
@@ -67,13 +67,13 @@ protected function configure(): void
                 name: 'exclude',
                 mode: InputOption::VALUE_OPTIONAL,
                 description: 'Comma-separated directories that SHOULD be excluded from analysis.',
-                default: 'vendor,test,tests,tmp,cache,spec,build,backup,resources',
+                default: 'vendor,test,tests,tmp,cache,spec,build,.dev-tools,backup,resources',
             )
             ->addOption(
                 name: 'target',
                 mode: InputOption::VALUE_OPTIONAL,
                 description: 'Target directory for the generated metrics reports.',
-                default: 'public/metrics',
+                default: '.dev-tools/metrics',
             )
             ->addOption(
                 name: 'junit',
diff --git a/src/Console/Command/ReportsCommand.php b/src/Console/Command/ReportsCommand.php
diff --git a/src/GitAttributes/CandidateProvider.php b/src/GitAttributes/CandidateProvider.php
diff --git a/tests/Console/Command/DocsCommandTest.php b/tests/Console/Command/DocsCommandTest.php
diff --git a/tests/Console/Command/MetricsCommandTest.php b/tests/Console/Command/MetricsCommandTest.php
diff --git a/tests/Console/Command/ReportsCommandTest.php b/tests/Console/Command/ReportsCommandTest.php
diff --git a/tests/Console/Command/TestsCommandTest.php b/tests/Console/Command/TestsCommandTest.php

-Original file line number
+Diff line change
@@ @@ -1,7 +1,7 @@ @@
 +.dev-tools/
 .idea/
 .vscode/
 backup/
 -public/
 tmp/
 vendor/
 *.cache