[CI] [POC] Added code samples testing with Deptrac

.github/workflows/build.yaml

@@ -86,3 +86,137 @@ jobs:
               with:
                   reporter: github-check
                   filter_mode: added
+
+    code-samples:
+        name: Validate code samples
+        runs-on: "ubuntu-22.04"
+        strategy:
+            matrix:
+                php:
+                    - "8.3"
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Setup PHP Action
+              uses: shivammathur/setup-php@v2
+              with:
+                  php-version: ${{ matrix.php }}
+                  coverage: none
+                  extensions: "pdo_sqlite, gd"
+                  tools: cs2pr
+
+            -   name: Add composer keys for private packagist
+                run: |
+                    composer config http-basic.updates.ibexa.co $SATIS_NETWORK_KEY $SATIS_NETWORK_TOKEN
+                    composer config github-oauth.github.com $TRAVIS_GITHUB_TOKEN
+                env:
+                    SATIS_NETWORK_KEY: ${{ secrets.SATIS_NETWORK_KEY }}
+                    SATIS_NETWORK_TOKEN: ${{ secrets.SATIS_NETWORK_TOKEN }}
+                    TRAVIS_GITHUB_TOKEN: ${{ secrets.TRAVIS_GITHUB_TOKEN }}
+
+            - uses: ramsey/composer-install@v3
+              with:
+                    dependency-versions: highest
+
+            - name: Run PHPStan analysis
+              run: composer phpstan
+
+            - name: Deptrac
+              run: composer deptrac
+
+    code-samples-inclusion-check:
+        name: Check code samples inclusion
+        runs-on: ubuntu-latest
+        if: github.event_name == 'pull_request'
+        permissions:
+            # Needed to manage the comment
+            pull-requests: write
+
+        steps:
+            -   name: List modified files
+                id: list
+                run: |
+                    URL="https://api.github.com/repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files"
+                    echo 'CODE_SAMPLES_CHANGE<<CODE_SAMPLES_CHANGE_DELIMITER' >> "$GITHUB_OUTPUT"
+                    curl -s -X GET -G $URL | jq -r '.[] | .filename,.previous_filename' | grep '^code_samples/' | tr '\n' ' ' >> "$GITHUB_OUTPUT"
+                    echo '' >> "$GITHUB_OUTPUT"
+                    echo 'CODE_SAMPLES_CHANGE_DELIMITER' >> "$GITHUB_OUTPUT"
+
+            -   name: Checkout target branch (base_ref)
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                uses: actions/checkout@v3
+                with:
+                    ref: ${{ github.base_ref }}
+            -   name: Log target branch code_samples usage
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                run: |
+                    git fetch origin
+                    git checkout origin/${{ github.head_ref }} -- tools/code_samples/code_samples_usage.php
+                    php tools/code_samples/code_samples_usage.php ${{ steps.list.outputs.CODE_SAMPLES_CHANGE }} > $HOME/code_samples_usage_target.txt
+
+            -   name: Checkout source branch (head_ref)
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                uses: actions/checkout@v3
+                with:
+                    ref: ${{ github.head_ref }}
+            -   name: Log source branch code_samples usage
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                run: php tools/code_samples/code_samples_usage.php ${{ steps.list.outputs.CODE_SAMPLES_CHANGE }} > $HOME/code_samples_usage_source.txt
+
+            -   name: Compare code_samples usages (diff --unified)
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                # diff returns 1 if there is a difference, this is normal but seen as an error by the job.
+                continue-on-error: true
+                run: |
+                    source_length=`wc -l < $HOME/code_samples_usage_source.txt`
+                    target_length=`wc -l < $HOME/code_samples_usage_target.txt`
+                    diff -U $(( source_length > target_length ? source_length : target_length )) $HOME/code_samples_usage_target.txt $HOME/code_samples_usage_source.txt > $HOME/code_samples_usage.diff
+            -   name: Check for differences
+                id: diff
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                run: |
+                    echo "CODE_SAMPLES_DIFF=$(wc -l < $HOME/code_samples_usage.diff | xargs)" >> "$GITHUB_OUTPUT"
+            -   name: Convert code_samples usages differences (diff2html)
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != '' && steps.diff.outputs.CODE_SAMPLES_DIFF != '0'
+                run: |
+                    npm install -g diff2html-cli
+                    diff2html -f html -s side -t 'code_samples/ changes report' --su hidden --fct false -o stdout -i file -- $HOME/code_samples_usage.diff > $HOME/code_samples_usage.diff.html
+            -   name: Upload code_samples usages differences artifact
+                id: artifact
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != '' && steps.diff.outputs.CODE_SAMPLES_DIFF != '0'
+                uses: actions/upload-artifact@v4
+                with:
+                    name: code_samples_usage.diff.html
+                    path: ~/code_samples_usage.diff.html
+                    overwrite: true
+            -   name: Convert code_samples usages for comment
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != '' && steps.diff.outputs.CODE_SAMPLES_DIFF != '0'
+                run: |
+                    echo '# code_samples/ change report' >> code_samples_usage.diff.md
+                    echo '' >> code_samples_usage.diff.md
+                    php tools/code_samples/code_samples_usage_diff2html.php $HOME/code_samples_usage.diff >> code_samples_usage.diff.md
+                    echo '<a href="${{ steps.artifact.outputs.artifact-url }}">Download colorized diff</a>' >> code_samples_usage.diff.md
+            -   name: Find Comment
+                id: find-comment
+                uses: peter-evans/find-comment@v3
+                with:
+                    issue-number: ${{ github.event.pull_request.number }}
+                    comment-author: 'github-actions[bot]'
+                    body-includes: 'code_samples/ change report'
+            -   name: Delete comment
+                if: steps.find-comment.outputs.comment-id != ''
+                uses: actions/github-script@v6
+                with:
+                    script: |
+                        github.rest.issues.deleteComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          comment_id: ${{ steps.find-comment.outputs.comment-id }}
+                        })
+            -   name: Create comment
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != '' && steps.diff.outputs.CODE_SAMPLES_DIFF != '0'
+                uses: peter-evans/create-or-update-comment@v4
+                with:
+                    issue-number: ${{ github.event.pull_request.number }}
+                    body-path: code_samples_usage.diff.md
+                    edit-mode: replace

.gitignore

@@ -10,3 +10,4 @@ node_modules/
 .yarn
 yarn.lock
 docs/css/*.map
+.deptrac.cache

README.md

@@ -54,12 +54,31 @@ of the command.
 
 ## Testing the code samples
 
+### PHPStan
 This repository uses PHPStan to test the code samples. To run the tests locally execute the commands below:
 ```bash
 composer update
 composer phpstan
 ```
 
+Regenerate the baseline by running:
+```bash
+composer phpstan -- --generate-baseline
+```
+
+### Deptrac
+
+This repository uses Deptrac to test the code samples. To run the tests locally execute the commands below:
+```bash
+composer update
+composer deptrac
+```
+
+Regenerate the baseline by running:
+```bash
+vendor/bin/deptrac --formatter=baseline
+```
+
 ## Where to View
 
 https://doc.ibexa.co

code_samples/api/commerce/src/Command/CartCommand.php

@@ -12,11 +12,11 @@
 use Ibexa\Contracts\Cart\Value\EntryAddStruct;
 use Ibexa\Contracts\Cart\Value\EntryUpdateStruct;
 use Ibexa\Contracts\Checkout\Reorder\ReorderService;
+use Ibexa\Contracts\Core\Repository\PermissionResolver;
 use Ibexa\Contracts\Core\Repository\UserService;
 use Ibexa\Contracts\OrderManagement\OrderServiceInterface;
 use Ibexa\Contracts\ProductCatalog\CurrencyServiceInterface;
 use Ibexa\Contracts\ProductCatalog\ProductServiceInterface;
-use Ibexa\Core\Repository\Permission\PermissionResolver;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;

code_samples/api/migration/src/Command/MigrationCommand.php

@@ -2,7 +2,7 @@
 
 namespace App\Command;
 
-use Ibexa\Migration\MigrationService;
+use Ibexa\Contracts\Migration\MigrationService;
 use Ibexa\Migration\Repository\Migration;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;

code_samples/api/public_php_api/src/Command/SegmentCommand.php

@@ -4,7 +4,7 @@
 
 use Ibexa\Contracts\Core\Repository\PermissionResolver;
 use Ibexa\Contracts\Core\Repository\UserService;
-use Ibexa\Segmentation\Service\SegmentationService;
+use Ibexa\Contracts\Segmentation\SegmentationServiceInterface;
 use Ibexa\Segmentation\Value\SegmentCreateStruct;
 use Ibexa\Segmentation\Value\SegmentGroupCreateStruct;
 use Symfony\Component\Console\Attribute\AsCommand;
@@ -17,13 +17,13 @@
 )]
 class SegmentCommand extends Command
 {
-    private SegmentationService $segmentationService;
+    private SegmentationServiceInterface $segmentationService;
 
     private UserService $userService;
 
     private PermissionResolver $permissionResolver;
 
-    public function __construct(SegmentationService $segmentationService, UserService $userService, PermissionResolver $permissionResolver)
+    public function __construct(SegmentationServiceInterface $segmentationService, UserService $userService, PermissionResolver $permissionResolver)
     {
         $this->segmentationService = $segmentationService;
         $this->permissionResolver = $permissionResolver;

code_samples/back_office/calendar/src/Calendar/Holidays/EventSourceFactory.php

@@ -4,9 +4,9 @@
 
 use DateTime;
 use DateTimeInterface;
-use Ibexa\Calendar\EventSource\InMemoryEventSource;
 use Ibexa\Contracts\Calendar\EventCollection;
 use Ibexa\Contracts\Calendar\EventSource\EventSourceInterface;
+use Ibexa\Contracts\Calendar\EventSource\InMemoryEventSource;
 
 class EventSourceFactory
 {

code_samples/back_office/calendar/src/Calendar/Holidays/EventType.php

@@ -2,8 +2,8 @@
 
 namespace App\Calendar\Holidays;
 
-use Ibexa\Calendar\EventAction\EventActionCollection;
 use Ibexa\Contracts\Calendar\Event;
+use Ibexa\Contracts\Calendar\EventAction\EventActionCollection;
 use Ibexa\Contracts\Calendar\EventType\EventTypeInterface;
 
 class EventType implements EventTypeInterface

code_samples/back_office/limitation/src/Security/Limitation/CustomLimitationType.php

@@ -9,7 +9,6 @@
 use Ibexa\Contracts\Core\Repository\Values\Content\Query\CriterionInterface;
 use Ibexa\Contracts\Core\Repository\Values\User\Limitation;
 use Ibexa\Contracts\Core\Repository\Values\User\UserReference;
-use Ibexa\Contracts\Core\Repository\Values\ValueObject;
 use Ibexa\Core\Base\Exceptions\InvalidArgumentException;
 use Ibexa\Core\Base\Exceptions\InvalidArgumentType;
 use Ibexa\Core\FieldType\ValidationError;
@@ -27,7 +26,7 @@ public function acceptValue(Limitation $limitationValue): void
         }
     }
 
-    /** @return \Ibexa\Core\FieldType\ValidationError[] */
+    /** @return \Ibexa\Contracts\Core\FieldType\ValidationError[] */
     public function validate(Limitation $limitationValue): array
     {
         $validationErrors = [];
@@ -57,7 +56,7 @@ public function buildValue(array $limitationValues): CustomLimitationValue
      *
      * @return bool|null
      */
-    public function evaluate(Limitation $value, UserReference $currentUser, ValueObject $object, array $targets = null): ?bool
+    public function evaluate(Limitation $value, UserReference $currentUser, object $object, ?array $targets = null): ?bool
     {
         if (!$value instanceof CustomLimitationValue) {
             throw new InvalidArgumentException('$value', 'Must be of type: CustomLimitationValue');

code_samples/search/custom/src/Search/FieldMapper/WebinarEventTitleFulltextFieldMapper.php

@@ -22,13 +22,13 @@ public function __construct(
         $this->locationHandler = $locationHandler;
     }
 
-    public function accept(Content $content)
+    public function accept(Content $content): bool
     {
         // ContentType with ID 42 is webinar event
         return $content->versionInfo->contentInfo->contentTypeId == 42;
     }
 
-    public function mapFields(Content $content)
+    public function mapFields(Content $content): array
     {
         $mainLocationId = $content->versionInfo->contentInfo->mainLocationId;
         $location = $this->locationHandler->load($mainLocationId);

composer.json

@@ -70,13 +70,21 @@
         "ibexa/tree-builder": "~5.0.x-dev",
         "ibexa/discounts": "~5.0.x-dev",
         "ibexa/discounts-codes": "~5.0.x-dev",
+        "ibexa/product-catalog-symbol-attribute": "~5.0.x-dev",
         "ibexa/core-search": "~5.0.x-dev",
-        "ibexa/product-catalog-symbol-attribute": "~5.0.x-dev"
+        "qossmic/deptrac": "^2.0"
     },
     "scripts": {
         "fix-cs": "php-cs-fixer fix --config=.php-cs-fixer.php -v --show-progress=dots",
         "check-cs": "@fix-cs --dry-run",
-        "phpstan": "phpstan analyse"
+        "phpstan": "phpstan analyse",
+        "deptrac": "deptrac analyse"
+    },
+    "scripts-descriptions": {
+        "fix-cs": "Automatically fixes code style in all files",
+        "check-cs": "Run code style checker for all files",
+        "phpstan": "Run static code analysis",
+        "deptrac": "Run Deptrac architecture testing"
     },
     "config": {
         "allow-plugins": false