From e3f4e82f55631cdefbf89d8496b5b17ef5614ce3 Mon Sep 17 00:00:00 2001
From: rtcoder <dawidjez@gmail.com>
Date: Wed, 17 Jun 2026 19:18:19 +0200
Subject: [PATCH] Add CLI quality checks

---
 README.md                                 |   9 ++
 REFACTORING.md                            |   3 +-
 docs/index.html                           |  21 +++-
 src/Console/Commands/Doctor.php           |  62 +---------
 src/Console/Commands/Lint.php             |  49 ++++++++
 src/Console/Commands/Qa.php               |  49 ++++++++
 src/Console/Console.php                   |   4 +-
 src/Console/Quality/CheckResult.php       |  36 ++++++
 src/Console/Quality/ProjectFileFinder.php | 124 +++++++++++++++++++
 src/Console/Quality/QualityChecks.php     | 141 ++++++++++++++++++++++
 src/Error/ErrorHandler.php                |   8 +-
 src/Service/ServiceContainer.php          |   2 +-
 src/Service/ServiceInterface.php          |   2 +-
 tests/Feature/QualityCommandsTest.php     |  62 ++++++++++
 14 files changed, 502 insertions(+), 70 deletions(-)
 create mode 100644 src/Console/Commands/Lint.php
 create mode 100644 src/Console/Commands/Qa.php
 create mode 100644 src/Console/Quality/CheckResult.php
 create mode 100644 src/Console/Quality/ProjectFileFinder.php
 create mode 100644 src/Console/Quality/QualityChecks.php
 create mode 100644 tests/Feature/QualityCommandsTest.php

diff --git a/README.md b/README.md
index 118a8ba..8b7f5e3 100644
--- a/README.md
+++ b/README.md
@@ -451,6 +451,15 @@ Run the test suite:
 ./shift test
 ```
 
+Run local quality checks:
+
+```sh
+./shift lint
+./shift qa
+```
+
+`shift lint` checks PHP syntax and basic file hygiene. `shift qa` runs Composer validation, lint checks, the test suite, and route listing.
+
 Run the example module command:
 
 ```sh
diff --git a/REFACTORING.md b/REFACTORING.md
index 9a11a06..330dbda 100644
--- a/REFACTORING.md
+++ b/REFACTORING.md
@@ -40,6 +40,7 @@ ShiftPHP is moving toward an API-only modular monolith. View templates, compiled
 - [x] Structured exception logging with JSON file logger and service container override.
 - [x] Request id lifecycle with generated `X-Request-Id` response headers and log context.
 - [x] Developer documentation organized into a Laravel-like guide.
+- [x] CLI quality gate with `shift lint` and `shift qa`.
 - [x] Removal of view storage and example page assets from runtime.
 - [x] Removal of legacy `application/controllers` and `application/routes.php`.
 - [x] Domain-oriented framework namespaces:
@@ -165,4 +166,4 @@ Internal errors return a generic `500` message unless `display_errors` is enable
 
 ## Next
 
-- [ ] Static analysis and coding style checks.
+- [ ] Deeper static analysis for framework contracts and type safety.
diff --git a/docs/index.html b/docs/index.html
index 179d170..77435ce 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -297,6 +297,7 @@ <h2>Operations</h2>
                 <ul>
                     <li><a href="#logging">Logging</a></li>
                     <li><a href="#cache">Cache</a></li>
+                    <li><a href="#quality-checks">Quality Checks</a></li>
                     <li><a href="#doctor">Doctor</a></li>
                     <li><a href="#testing">Testing</a></li>
                     <li><a href="#releases">Releases</a></li>
@@ -325,7 +326,8 @@ <h2>Installation</h2>
 
                 <p>Run the framework checks:</p>
 
-                <pre><code>./shift doctor</code></pre>
+                <pre><code>./shift doctor
+./shift qa</code></pre>
             </section>
 
             <section id="configuration">
@@ -806,13 +808,26 @@ <h2>Cache</h2>
                 <p>Rebuild the module cache after changing module boundaries, module config, or module command mappings.</p>
             </section>
 
+            <section id="quality-checks">
+                <h2>Quality Checks</h2>
+                <p>The CLI includes zero-dependency quality gates for local development and pull request preparation.</p>
+
+                <pre><code>./shift lint
+./shift qa</code></pre>
+
+                <p><code>shift lint</code> checks PHP syntax and basic file hygiene, including trailing whitespace and missing final newlines. <code>shift qa</code> runs Composer validation, lint checks, the test suite, and the route list command.</p>
+
+                <pre><code>./shift help lint
+./shift help qa</code></pre>
+            </section>
+
             <section id="doctor">
                 <h2>Doctor</h2>
                 <p>The doctor command runs local diagnostics and returns a non-zero exit code when a required check fails.</p>
 
                 <pre><code>./shift doctor</code></pre>
 
-                <p>It checks PHP version, required extensions, Composer JSON validity, PHP lint, the test suite, environment presence, database config, and module cache status.</p>
+                <p>It checks PHP version, required extensions, Composer JSON validity, PHP syntax, the test suite, environment presence, database config, and module cache status.</p>
             </section>
 
             <section id="testing">
@@ -822,7 +837,7 @@ <h2>Testing</h2>
                 <pre><code>composer test
 ./shift test</code></pre>
 
-                <p>The GitHub workflow validates Composer config, dumps autoload files, lints PHP files, runs tests, and verifies the route list command.</p>
+                <p>The GitHub workflow validates Composer config, dumps autoload files, lints PHP files, runs tests, and verifies the route list command. Locally, <code>./shift qa</code> runs the same kind of pre-PR quality gate.</p>
             </section>
 
             <section id="releases">
diff --git a/src/Console/Commands/Doctor.php b/src/Console/Commands/Doctor.php
index 8a3d660..b01289a 100644
--- a/src/Console/Commands/Doctor.php
+++ b/src/Console/Commands/Doctor.php
@@ -4,6 +4,7 @@
 
 use Shift\Console\Cli;
 use Shift\Console\CommandInterface;
+use Shift\Console\Quality\QualityChecks;
 use Shift\Database\DatabaseConfig;
 use Shift\Modules\ModuleLoader;
 use Throwable;
@@ -14,12 +15,13 @@ class Doctor implements CommandInterface
     public function execute(mixed ...$args): void
     {
         $cli = new Cli();
+        $quality = new QualityChecks();
         $checks = [
             $this->phpVersion(),
             $this->extensions(),
             $this->composerConfig(),
-            $this->phpLint(),
-            $this->testSuite(),
+            $quality->phpSyntax()->toRow(),
+            $quality->testSuite()->toRow(),
             $this->environment(),
             $this->databaseConfig(),
             $this->moduleCache(),
@@ -87,41 +89,6 @@ private function composerConfig(): array
         ];
     }
 
-    private function phpLint(): array
-    {
-        $files = array_merge(
-            $this->phpFiles(APP_ROOT . '/src'),
-            $this->phpFiles(APP_ROOT . '/application'),
-            $this->phpFiles(APP_ROOT . '/tests'),
-            [APP_ROOT . '/shift']
-        );
-
-        foreach ($files as $file) {
-            if (!is_file($file)) {
-                continue;
-            }
-
-            exec(escapeshellarg(PHP_BINARY) . ' -l ' . escapeshellarg($file) . ' 2>&1', $output, $exitCode);
-
-            if ($exitCode !== 0) {
-                return ['PHP lint', 'fail', basename($file) . ': ' . trim(implode(' ', $output))];
-            }
-        }
-
-        return ['PHP lint', 'ok', count($files) . ' file(s) checked'];
-    }
-
-    private function testSuite(): array
-    {
-        exec('composer test 2>&1', $output, $exitCode);
-
-        return [
-            'Test suite',
-            $exitCode === 0 ? 'ok' : 'fail',
-            $exitCode === 0 ? 'composer test passed' : trim(implode(' ', array_slice($output, -3))),
-        ];
-    }
-
     private function environment(): array
     {
         return [
@@ -157,25 +124,4 @@ private function moduleCache(): array
         ];
     }
 
-    private function phpFiles(string $path): array
-    {
-        if (!is_dir($path)) {
-            return [];
-        }
-
-        $files = [];
-        $iterator = new \RecursiveIteratorIterator(
-            new \RecursiveDirectoryIterator($path, \FilesystemIterator::SKIP_DOTS)
-        );
-
-        foreach ($iterator as $file) {
-            if ($file->isFile() && $file->getExtension() === 'php') {
-                $files[] = $file->getPathname();
-            }
-        }
-
-        sort($files);
-
-        return $files;
-    }
 }
diff --git a/src/Console/Commands/Lint.php b/src/Console/Commands/Lint.php
new file mode 100644
index 0000000..c978aa8
--- /dev/null
+++ b/src/Console/Commands/Lint.php
@@ -0,0 +1,49 @@
+<?php
+
+namespace Console\Commands;
+
+use Shift\Console\Cli;
+use Shift\Console\CommandInterface;
+use Shift\Console\Quality\CheckResult;
+use Shift\Console\Quality\QualityChecks;
+
+#[\Shift\Console\Attributes\Command('lint', aliases: ['l'], group: 'diagnostics')]
+class Lint implements CommandInterface
+{
+    public function execute(mixed ...$args): void
+    {
+        $this->render((new QualityChecks())->lint(), 'Lint checks passed.', 'Lint checks failed.');
+    }
+
+    public function getHelp(): string
+    {
+        return 'Usage: ./shift lint';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Run PHP syntax and file hygiene checks.';
+    }
+
+    /**
+     * @param list<CheckResult> $results
+     */
+    private function render(array $results, string $successMessage, string $failureMessage): void
+    {
+        $cli = new Cli();
+        $cli->table(['Check', 'Status', 'Details'], array_map(
+            static fn (CheckResult $result): array => $result->toRow(),
+            $results
+        ));
+
+        $failed = array_values(array_filter($results, static fn (CheckResult $result): bool => !$result->passed()));
+
+        if ($failed === []) {
+            $cli->success($successMessage);
+            return;
+        }
+
+        $cli->error($failureMessage);
+        exit(1);
+    }
+}
diff --git a/src/Console/Commands/Qa.php b/src/Console/Commands/Qa.php
new file mode 100644
index 0000000..a48242a
--- /dev/null
+++ b/src/Console/Commands/Qa.php
@@ -0,0 +1,49 @@
+<?php
+
+namespace Console\Commands;
+
+use Shift\Console\Cli;
+use Shift\Console\CommandInterface;
+use Shift\Console\Quality\CheckResult;
+use Shift\Console\Quality\QualityChecks;
+
+#[\Shift\Console\Attributes\Command('qa', aliases: ['quality', 'ci'], group: 'diagnostics')]
+class Qa implements CommandInterface
+{
+    public function execute(mixed ...$args): void
+    {
+        $this->render((new QualityChecks())->qa(), 'Quality checks passed.', 'Quality checks failed.');
+    }
+
+    public function getHelp(): string
+    {
+        return 'Usage: ./shift qa';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Run Composer validation, lint, tests, and route checks.';
+    }
+
+    /**
+     * @param list<CheckResult> $results
+     */
+    private function render(array $results, string $successMessage, string $failureMessage): void
+    {
+        $cli = new Cli();
+        $cli->table(['Check', 'Status', 'Details'], array_map(
+            static fn (CheckResult $result): array => $result->toRow(),
+            $results
+        ));
+
+        $failed = array_values(array_filter($results, static fn (CheckResult $result): bool => !$result->passed()));
+
+        if ($failed === []) {
+            $cli->success($successMessage);
+            return;
+        }
+
+        $cli->error($failureMessage);
+        exit(1);
+    }
+}
diff --git a/src/Console/Console.php b/src/Console/Console.php
index 5116bd1..7f4a742 100644
--- a/src/Console/Console.php
+++ b/src/Console/Console.php
@@ -16,7 +16,7 @@ class Console
 {
     /**
      * Instancja klasy Cli do operacji terminalowych
-     * 
+     *
      * @var Cli
      */
     private Cli $cli;
@@ -31,7 +31,7 @@ public function __construct()
 
     /**
      * Zwraca instancję klasy Cli
-     * 
+     *
      * @return Cli
      */
     public function cli(): Cli
diff --git a/src/Console/Quality/CheckResult.php b/src/Console/Quality/CheckResult.php
new file mode 100644
index 0000000..fd286cf
--- /dev/null
+++ b/src/Console/Quality/CheckResult.php
@@ -0,0 +1,36 @@
+<?php
+
+namespace Shift\Console\Quality;
+
+final class CheckResult
+{
+    public function __construct(
+        public readonly string $name,
+        public readonly string $status,
+        public readonly string $details
+    ) {
+    }
+
+    public static function ok(string $name, string $details): self
+    {
+        return new self($name, 'ok', $details);
+    }
+
+    public static function fail(string $name, string $details): self
+    {
+        return new self($name, 'fail', $details);
+    }
+
+    /**
+     * @return array{0: string, 1: string, 2: string}
+     */
+    public function toRow(): array
+    {
+        return [$this->name, $this->status, $this->details];
+    }
+
+    public function passed(): bool
+    {
+        return $this->status !== 'fail';
+    }
+}
diff --git a/src/Console/Quality/ProjectFileFinder.php b/src/Console/Quality/ProjectFileFinder.php
new file mode 100644
index 0000000..c0af107
--- /dev/null
+++ b/src/Console/Quality/ProjectFileFinder.php
@@ -0,0 +1,124 @@
+<?php
+
+namespace Shift\Console\Quality;
+
+use FilesystemIterator;
+use RecursiveDirectoryIterator;
+use RecursiveIteratorIterator;
+
+final class ProjectFileFinder
+{
+    /**
+     * @param list<string>|null $paths
+     * @param list<string> $hygieneExtensions
+     */
+    public function __construct(
+        private readonly ?array $paths = null,
+        private readonly array $hygieneExtensions = ['php', 'md', 'json', 'html', 'yml', 'yaml']
+    ) {
+    }
+
+    /**
+     * @return list<string>
+     */
+    public function phpFiles(): array
+    {
+        $files = array_values(array_filter(
+            $this->allFiles(),
+            static fn (string $file): bool => pathinfo($file, PATHINFO_EXTENSION) === 'php' || basename($file) === 'shift'
+        ));
+
+        sort($files);
+
+        return $files;
+    }
+
+    /**
+     * @return list<string>
+     */
+    public function hygieneFiles(): array
+    {
+        $files = array_values(array_filter($this->allFiles(), function (string $file): bool {
+            if (basename($file) === 'shift') {
+                return true;
+            }
+
+            return in_array(pathinfo($file, PATHINFO_EXTENSION), $this->hygieneExtensions, true);
+        }));
+
+        sort($files);
+
+        return $files;
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function allFiles(): array
+    {
+        $files = [];
+
+        foreach ($this->paths ?? $this->defaultPaths() as $path) {
+            if (is_file($path)) {
+                $files[] = $path;
+                continue;
+            }
+
+            if (!is_dir($path)) {
+                continue;
+            }
+
+            $iterator = new RecursiveIteratorIterator(
+                new RecursiveDirectoryIterator($path, FilesystemIterator::SKIP_DOTS)
+            );
+
+            foreach ($iterator as $file) {
+                if (!$file->isFile()) {
+                    continue;
+                }
+
+                $pathName = $file->getPathname();
+
+                if ($this->isIgnored($pathName)) {
+                    continue;
+                }
+
+                $files[] = $pathName;
+            }
+        }
+
+        return array_values(array_unique($files));
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function defaultPaths(): array
+    {
+        return [
+            APP_ROOT . '/src',
+            APP_ROOT . '/application',
+            APP_ROOT . '/database/migrations',
+            APP_ROOT . '/tests',
+            APP_ROOT . '/docs',
+            APP_ROOT . '/.github',
+            APP_ROOT . '/README.md',
+            APP_ROOT . '/REFACTORING.md',
+            APP_ROOT . '/composer.json',
+            APP_ROOT . '/bootstrap.php',
+            APP_ROOT . '/index.php',
+            APP_ROOT . '/shift',
+        ];
+    }
+
+    private function isIgnored(string $path): bool
+    {
+        foreach (['/.git/', '/vendor/', '/.idea/', '/storage/cache/', '/storage/logs/'] as $ignored) {
+            if (str_contains($path, $ignored)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}
diff --git a/src/Console/Quality/QualityChecks.php b/src/Console/Quality/QualityChecks.php
new file mode 100644
index 0000000..bfc11d8
--- /dev/null
+++ b/src/Console/Quality/QualityChecks.php
@@ -0,0 +1,141 @@
+<?php
+
+namespace Shift\Console\Quality;
+
+final class QualityChecks
+{
+    public function __construct(
+        private readonly ?ProjectFileFinder $files = null,
+        private readonly ?string $root = null
+    ) {
+    }
+
+    /**
+     * @return list<CheckResult>
+     */
+    public function lint(): array
+    {
+        return [
+            $this->phpSyntax(),
+            $this->fileHygiene(),
+        ];
+    }
+
+    /**
+     * @return list<CheckResult>
+     */
+    public function qa(): array
+    {
+        return [
+            $this->composerValidate(),
+            $this->phpSyntax(),
+            $this->fileHygiene(),
+            $this->testSuite(),
+            $this->routeList(),
+        ];
+    }
+
+    public function composerValidate(): CheckResult
+    {
+        return $this->runShellCheck('Composer config', 'composer validate --no-check-publish 2>&1', 'composer.json valid');
+    }
+
+    public function phpSyntax(): CheckResult
+    {
+        $files = $this->fileFinder()->phpFiles();
+
+        foreach ($files as $file) {
+            $output = [];
+            exec(escapeshellarg(PHP_BINARY) . ' -l ' . escapeshellarg($file) . ' 2>&1', $output, $exitCode);
+
+            if ($exitCode !== 0) {
+                return CheckResult::fail('PHP syntax', $this->relativePath($file) . ': ' . trim(implode(' ', $output)));
+            }
+        }
+
+        return CheckResult::ok('PHP syntax', count($files) . ' file(s) checked');
+    }
+
+    public function fileHygiene(): CheckResult
+    {
+        $files = $this->fileFinder()->hygieneFiles();
+
+        foreach ($files as $file) {
+            $contents = file_get_contents($file);
+
+            if ($contents === false || $contents === '') {
+                continue;
+            }
+
+            if (!str_ends_with($contents, "\n")) {
+                return CheckResult::fail('File hygiene', $this->relativePath($file) . ': missing final newline');
+            }
+
+            foreach (preg_split('/\r?\n/', $contents) ?: [] as $line => $text) {
+                if (preg_match('/[ \t]+$/', $text)) {
+                    return CheckResult::fail('File hygiene', $this->relativePath($file) . ':' . ($line + 1) . ': trailing whitespace');
+                }
+            }
+        }
+
+        return CheckResult::ok('File hygiene', count($files) . ' file(s) checked');
+    }
+
+    public function testSuite(): CheckResult
+    {
+        return $this->runShellCheck('Test suite', 'composer test 2>&1', 'composer test passed');
+    }
+
+    public function routeList(): CheckResult
+    {
+        $command = escapeshellarg(PHP_BINARY) . ' ' . escapeshellarg($this->projectRoot() . '/shift') . ' route:list 2>&1';
+
+        return $this->runShellCheck('Route list', $command, './shift route:list passed');
+    }
+
+    private function runShellCheck(string $name, string $command, string $successDetails): CheckResult
+    {
+        $previousDirectory = getcwd();
+
+        if ($previousDirectory !== false) {
+            chdir($this->projectRoot());
+        }
+
+        try {
+            exec($command, $output, $exitCode);
+        } finally {
+            if ($previousDirectory !== false) {
+                chdir($previousDirectory);
+            }
+        }
+
+        if ($exitCode === 0) {
+            return CheckResult::ok($name, $successDetails);
+        }
+
+        $details = trim(implode(' ', array_slice($output, -3)));
+
+        return CheckResult::fail($name, $details !== '' ? $details : 'Command failed with exit code ' . $exitCode);
+    }
+
+    private function fileFinder(): ProjectFileFinder
+    {
+        return $this->files ?? new ProjectFileFinder();
+    }
+
+    private function projectRoot(): string
+    {
+        return $this->root ?? APP_ROOT;
+    }
+
+    private function relativePath(string $path): string
+    {
+        $root = rtrim($this->projectRoot(), '/') . '/';
+
+        if (str_starts_with($path, $root)) {
+            return substr($path, strlen($root));
+        }
+
+        return $path;
+    }
+}
diff --git a/src/Error/ErrorHandler.php b/src/Error/ErrorHandler.php
index 96752d4..0738685 100644
--- a/src/Error/ErrorHandler.php
+++ b/src/Error/ErrorHandler.php
@@ -39,7 +39,7 @@ public static function handleError(int $level, string $message, string $file = '
             $exception = new ShiftError($message, $level);
             $exception->setFile($file);
             $exception->setLine($line);
-            
+
             self::handleException($exception);
             return true;
         }
@@ -69,12 +69,12 @@ public static function handleException(Throwable $exception): void
     public static function handleShutdown(): void
     {
         $error = error_get_last();
-        
+
         if ($error !== null && in_array($error['type'], [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR])) {
             $exception = new ShiftError($error['message'], $error['type']);
             $exception->setFile($error['file']);
             $exception->setLine($error['line']);
-            
+
             self::handleException($exception);
         }
     }
@@ -122,4 +122,4 @@ private static function shouldDisplayDetails(): bool
     {
         return in_array(strtolower((string) ini_get('display_errors')), ['1', 'on', 'true'], true);
     }
-} 
+}
diff --git a/src/Service/ServiceContainer.php b/src/Service/ServiceContainer.php
index 2cbc6ac..b8465f3 100644
--- a/src/Service/ServiceContainer.php
+++ b/src/Service/ServiceContainer.php
@@ -169,4 +169,4 @@ public function getSingletonServices(): array
     {
         return array_keys($this->singletons);
     }
-} 
+}
diff --git a/src/Service/ServiceInterface.php b/src/Service/ServiceInterface.php
index ad94d5f..2593cd2 100644
--- a/src/Service/ServiceInterface.php
+++ b/src/Service/ServiceInterface.php
@@ -22,4 +22,4 @@ public function isReady(): bool;
      * Get service name
      */
     public function getName(): string;
-} 
+}
diff --git a/tests/Feature/QualityCommandsTest.php b/tests/Feature/QualityCommandsTest.php
new file mode 100644
index 0000000..7c410c4
--- /dev/null
+++ b/tests/Feature/QualityCommandsTest.php
@@ -0,0 +1,62 @@
+<?php
+
+use Console\Commands\Lint;
+use Console\Commands\Qa;
+use Shift\Console\CommandRegistry;
+use Shift\Console\Quality\ProjectFileFinder;
+use Shift\Console\Quality\QualityChecks;
+
+return [
+    'command registry discovers quality commands' => function (): void {
+        $registry = CommandRegistry::default();
+        $commands = $registry->all();
+
+        assertSameValue(Lint::class, $commands['lint'] ?? null, 'Registry should expose lint command.');
+        assertSameValue(Qa::class, $commands['qa'] ?? null, 'Registry should expose qa command.');
+        assertSameValue(Lint::class, $registry->find('l'), 'Registry should resolve lint alias.');
+        assertSameValue(Qa::class, $registry->find('quality'), 'Registry should resolve qa alias.');
+        assertSameValue(Qa::class, $registry->find('ci'), 'Registry should resolve ci alias.');
+    },
+    'quality checks pass for valid php file' => function (): void {
+        $root = sys_get_temp_dir() . '/shift-quality-' . bin2hex(random_bytes(6));
+        mkdir($root, 0775, true);
+
+        try {
+            $file = $root . '/Example.php';
+            file_put_contents($file, "<?php\n\necho 'ok';\n");
+
+            $checks = new QualityChecks(new ProjectFileFinder([$file]), $root);
+            $result = $checks->phpSyntax();
+
+            assertSameValue('ok', $result->status, 'PHP syntax check should pass for valid PHP.');
+        } finally {
+            removeDirectory($root);
+        }
+    },
+    'quality checks detect file hygiene issues' => function (): void {
+        $root = sys_get_temp_dir() . '/shift-quality-' . bin2hex(random_bytes(6));
+        mkdir($root, 0775, true);
+
+        try {
+            $file = $root . '/README.md';
+            file_put_contents($file, "Bad whitespace  \n");
+
+            $checks = new QualityChecks(new ProjectFileFinder([$file]), $root);
+            $result = $checks->fileHygiene();
+
+            assertSameValue('fail', $result->status, 'File hygiene should fail on trailing whitespace.');
+            assertStringContains('trailing whitespace', $result->details, 'File hygiene should explain the issue.');
+        } finally {
+            removeDirectory($root);
+        }
+    },
+    'lint command reports syntax and hygiene checks' => function (): void {
+        ob_start();
+        (new Lint())->execute();
+        $output = ob_get_clean();
+
+        assertStringContains('PHP syntax', $output, 'Lint output should include PHP syntax check.');
+        assertStringContains('File hygiene', $output, 'Lint output should include file hygiene check.');
+        assertStringContains('Lint checks passed.', $output, 'Lint output should include success message.');
+    },
+];