ci: check architecture rules with StructArmed

.github/workflows/static-analysis.yml

@@ -8,13 +8,15 @@ on:  # yamllint disable-line rule:truthy
       - '.php-cs-fixer.dist.php'
       - 'psalm*'
       - 'composer.*'
+      - 'tools/structarmed/**'
   push:
     paths:
       - 'src/**'
       - 'bin/dload'
       - '.php-cs-fixer.dist.php'
       - 'psalm*'
       - 'composer.*'
+      - 'tools/structarmed/**'
 
 name: 🔍 Static analysis
 
@@ -58,3 +60,32 @@ jobs:
 
       - name: 🔍 Run static analysis using vimeo/psalm
         run: composer psalm:ci
+
+  structarmed:
+    timeout-minutes: 4
+    runs-on: ubuntu-latest
+    concurrency:
+      cancel-in-progress: true
+      group: structarmed-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+    steps:
+      - name: 📦 Check out the codebase
+        uses: actions/checkout@v7
+
+      - name: 🛠️ Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          ini-values: error_reporting=E_ALL
+          coverage: none
+
+      - name: 📥 Install dependencies with composer
+        uses: ramsey/composer-install@v3
+        with:
+          dependency-versions: locked
+
+      # StructArmed lives in its own tools/structarmed namespace, which the root install skips.
+      - name: 📥 Install StructArmed
+        run: composer bin structarmed install --ansi
+
+      - name: 🏛️ Check architecture rules using boundwize/structarmed
+        run: composer structarmed:ci

.gitignore

@@ -7,3 +7,6 @@
 /.env
 *.log
 *.exe
+/tools/*/vendor/
+/tools/*/.agents/
+/tools/*/.claude/

AGENTS.md

@@ -6,6 +6,7 @@ A PHP CLI (`vendor/bin/dload`, also shipped as a PHAR) that downloads binaries a
 - `resources/software.json` is the built-in software registry; `dload.xsd` is the schema of `dload.xml`.
 - `1.x` is the development and release branch: branch from it and target pull requests at it.
 - Tests run on Testo: `vendor/bin/testo --json`. Static analysis: `composer psalm`. Code style: `composer cs:fix`.
+- Architecture rules run on StructArmed: `composer structarmed`, after a one-time `composer bin structarmed install` (it lives isolated in `tools/structarmed`). `structarmed.php` there defines the layers and rules; `baseline.php` is known debt — after cutting some, shrink it with `composer structarmed:baseline`.
 
 ## Docs and skills follow behaviour
 

composer.json

@@ -34,6 +34,7 @@
         "symfony/http-client": "^6.4 || ^7 || ^8"
     },
     "require-dev": {
+        "bamarni/composer-bin-plugin": "^1.9",
         "buggregator/trap": "^1.15",
         "composer/semver": "^3.4",
         "dereuromark/composer-prefer-lowest": "^0.1.10",
@@ -65,6 +66,7 @@
     ],
     "config": {
         "allow-plugins": {
+            "bamarni/composer-bin-plugin": true,
             "ergebnis/composer-normalize": true,
             "infection/extension-installer": true,
             "llm/skills": true
@@ -75,6 +77,11 @@
         "sort-packages": true
     },
     "extra": {
+        "bamarni-bin": {
+            "bin-links": true,
+            "forward-command": false,
+            "target-directory": "tools"
+        },
         "skills": {
             "source": "skills"
         }
@@ -95,6 +102,9 @@
         "psalm:ci": "psalm --output-format=github --shepherd --show-info=false --stats --threads=4",
         "refactor": "rector process --config=rector.php",
         "refactor:ci": "rector process --config=rector.php --dry-run --ansi",
+        "structarmed": "structarmed analyse --config=tools/structarmed/structarmed.php",
+        "structarmed:baseline": "structarmed analyse --config=tools/structarmed/structarmed.php --generate-baseline=tools/structarmed/baseline.php",
+        "structarmed:ci": "structarmed analyse --config=tools/structarmed/structarmed.php --no-progress --report=github",
         "test": [
             "testo --ansi --no-coverage"
         ],

psalm-baseline.xml

@@ -180,11 +180,6 @@
       <code><![CDATA[$softwareArray]]></code>
     </MixedAssignment>
   </file>
-  <file src="src/Module/HttpClient/Internal/NyholmFactoryImpl.php">
-    <ClassMustBeFinal>
-      <code><![CDATA[NyholmFactoryImpl]]></code>
-    </ClassMustBeFinal>
-  </file>
   <file src="src/Module/Repository/Collection/ReleasesCollection.php">
     <LessSpecificReturnStatement>
       <code><![CDATA[\ltrim(\str_replace(

src/Module/Binary/Exception/BinaryException.php

@@ -7,4 +7,4 @@
 /**
  * Base exception for binary operations.
  */
-class BinaryException extends \RuntimeException {}
+abstract class BinaryException extends \RuntimeException {}

src/Module/Binary/Internal/AbstractBinary.php

@@ -9,6 +9,9 @@
 use Internal\DLoad\Module\Config\Schema\Embed\Binary as BinaryConfig;
 use Internal\Path;
 
+/**
+ * @internal
+ */
 abstract class AbstractBinary implements Binary
 {
     private ?BinaryVersion $versionOutput = null;

src/Module/Downloader/Internal/BinaryExistenceChecker.php

@@ -12,6 +12,8 @@
  *
  * Handles operating system specific considerations for binary names,
  * such as .exe extensions on Windows.
+ *
+ * @internal
  */
 final class BinaryExistenceChecker
 {

src/Module/HttpClient/Internal/NyholmFactoryImpl.php

@@ -18,7 +18,7 @@
 /**
  * @internal
  */
-class NyholmFactoryImpl implements Factory
+final class NyholmFactoryImpl implements Factory
 {
     public function __construct(
         private readonly Logger $logger,