readme, misc small adjustments and tweaks

Jamesclark32 · Aug 25, 2024 · d322771 · d322771
1 parent 4c5c545
commit d322771
Show file tree

Hide file tree

Showing 10 changed files with 116 additions and 106 deletions.
diff --git a/.editorconfig b/.editorconfig
diff --git a/README.md b/README.md
@@ -1,83 +1,98 @@
-# This is my package dev-audit
+# Dev Audit 
 
-[![Latest Version on Packagist](https://img.shields.io/packagist/v/jamesclark32/dev-audit.svg?style=flat-square)](https://packagist.org/packages/jamesclark32/dev-audit)
-[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/jamesclark32/dev-audit/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/jamesclark32/dev-audit/actions?query=workflow%3Arun-tests+branch%3Amain)
-[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/jamesclark32/dev-audit/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/jamesclark32/dev-audit/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
-[![Total Downloads](https://img.shields.io/packagist/dt/jamesclark32/dev-audit.svg?style=flat-square)](https://packagist.org/packages/jamesclark32/dev-audit)
+This package provides a Laravel console command to quickly run a set of CLI commands and summarize their outcome.
 
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+Dev Audit is intended to encapsulate a series of audits regularly run together as part of a development process, such as a pre-merge routine.
 
-## Support us
+The package ships with an opinionated set of default audits based upon the author's workflow but is easily modified to suit yours instead.
 
-[<img src="https://github-ads.s3.eu-central-1.amazonaws.com/dev-audit.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/dev-audit)
+Out of the box, Dev Audit runs:
 
-We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
+- Tests (phpunit)
+- Static Analysis (phpstan)
+- Lint check against changed PHP files (pint)
+- Lint check against changed javascript files (prettier)
+- Composer audit
+- Npm audit
 
-We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
+Once installed, Dev Audit can be run at any time using `artisan dev:audit`.
+
+Under the hood, Dev Audit executes the commands from the configuration via an instance of `Symfony/Process` and serves as a UI wrapper to summarize the results while removing feedback clutter.
+
+Typical output looks something like this:
+
+![img.png](img.png)
 
 ## Installation
 
-You can install the package via composer:
+To get started, you need only to install the package via composer:
 
 ```bash
 composer require jamesclark32/dev-audit
 ```
 
-You can publish and run the migrations with:
+Once installed, Dev Audit can be run at any time using `artisan dev:audit`.
 
-```bash
-php artisan vendor:publish --tag="dev-audit-migrations"
-php artisan migrate
-```
+## Configuration
+
+To adjust the audits to be run, simply publish and modify the config file. 
 
-You can publish the config file with:
+You can publish the config file to `config/dev-audit.php` with:
 
 ```bash
 php artisan vendor:publish --tag="dev-audit-config"
 ```
 
-This is the contents of the published config file:
+The config files contains the details of the audits to run. Audits can be added, removed, modified, or have their order adjusted.
 
-```php
-return [
-];
-```
+Any new audits need only a `title` for display purposes and the `command` to run.
 
-Optionally, you can publish the views using
+`failure_hint` content is optional, but provides the opportunity to display commands needed for likely next steps in the case of a failure.
 
-```bash
-php artisan vendor:publish --tag="dev-audit-views"
-```
-
-## Usage
+The default audit configuration looks like this:
 
 ```php
-$devAudit = new jamesclark32\DevAudit();
-echo $devAudit->echoPhrase('Hello, jamesclark32!');
-```
-
-## Testing
-
-```bash
-composer test
+return [
+     'audits' => [
+        [
+            'title' => 'PHPUnit',
+            'command' => './vendor/bin/phpunit -d memory_limit=-1 --no-progress --configuration phpunit.xml;',
+            'failure_hint' => 'Run tests using "php artisan test --stop-on-error" to help discover code issues in isolation.',
+        ],
+        [
+            'title' => 'PHPStan',
+            'command' => './vendor/bin/phpstan analyze -v --memory-limit=-1',
+            'failure_hint' => 'Address the code issues found by "./vendor/bin/phpstan analyze -v --memory-limit=-1", or adjust phpstan.neon to allow for them.',
+        ],
+        [
+            'title' => 'Pint (dirty files)',
+            'command' => './vendor/bin/pint --dirty --test',
+            'failure_hint' => 'Run "./vendor/bin/pint --dirty" to have Pint fix these code style issues while remaining scoped to files with uncommited changes only.',
+        ],
+        [
+            'title' => 'Prettier (dirty files)',
+            'command' => 'npx prettier --config .prettierrc -u -l $(git diff --name-only --diff-filter=d HEAD  | xargs)',
+            'failure_hint' => 'Run "npx prettier --config .prettierrc -u -w $(git diff --name-only --diff-filter=d HEAD  | xargs)" to have prettier fix these code style issues while remaining scoped to files with uncommited changes only.',
+        ],
+        [
+            'title' => 'Composer Audit',
+            'command' => 'composer audit',
+        ],
+        [
+            'title' => 'NPM Audit',
+            'command' => 'npm audit',
+        ],
+    ],
+];
 ```
 
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
 
-## Contributing
-
-Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
-
-## Security Vulnerabilities
-
-Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
-
 ## Credits
 
 - [James Clark](https://github.com/Jamesclark32)
-- [All Contributors](../../contributors)
 
 ## License
 

diff --git a/composer.json b/composer.json
@@ -1,6 +1,6 @@
 {
     "name": "jamesclark32/dev-audit",
-    "description": "This is my package dev-audit",
+    "description": "Quickly run a set of CLI commands and summarize their outcome",
     "keywords": [
         "jamesclark32",
         "laravel",
@@ -35,8 +35,7 @@
     },
     "autoload": {
         "psr-4": {
-            "JamesClark32\\DevAudit\\": "src/",
-            "JamesClark32\\DevAudit\\Database\\Factories\\": "database/factories/"
+            "JamesClark32\\DevAudit\\": "src/"
         }
     },
     "autoload-dev": {

diff --git a/config/dev-audit.php b/config/dev-audit.php
@@ -3,29 +3,24 @@
 return [
     'audits' => [
         [
-            'title' => 'Tests',
+            'title' => 'PHPUnit',
             'command' => './vendor/bin/phpunit -d memory_limit=-1 --no-progress --configuration phpunit.xml;',
             'failure_hint' => 'Run tests using "php artisan test --stop-on-error" to help discover code issues in isolation.',
         ],
         [
-            'title' => 'Stan',
+            'title' => 'PHPStan',
             'command' => './vendor/bin/phpstan analyze -v --memory-limit=-1',
-            'failure_hint' => 'Address the code issues found by "./vendor/bin/phpstan analyze -v --memory-limit=-1" (or adjust your phpstan.neon to allow for them).',
-        ],
-        [
-            'title' => 'Pint (all files)',
-            'command' => './vendor/bin/pint --test',
-            'failure_hint' => 'Run "./vendor/bin/pint" to have Pint fix these code style issues.',
+            'failure_hint' => 'Address the code issues found by "./vendor/bin/phpstan analyze -v --memory-limit=-1", or adjust phpstan.neon to allow for them.',
         ],
         [
             'title' => 'Pint (dirty files)',
             'command' => './vendor/bin/pint --dirty --test',
-            'failure_hint' => 'Run "./vendor/bin/pint --dirty" to have Pint fix these code style issues while remaining scoped to uncommited changes only.',
+            'failure_hint' => 'Run "./vendor/bin/pint --dirty" to have Pint fix these code style issues while remaining scoped to files with uncommited changes only.',
         ],
         [
-            'title' => 'Prettier',
+            'title' => 'Prettier (dirty files)',
             'command' => 'npx prettier --config .prettierrc -u -l $(git diff --name-only --diff-filter=d HEAD  | xargs)',
-            'failure_hint' => 'Run "npx prettier --config .prettierrc -u -w $(git diff --name-only --diff-filter=d HEAD  | xargs)" to have prettier fix these code style issues.',
+            'failure_hint' => 'Run "npx prettier --config .prettierrc -u -w $(git diff --name-only --diff-filter=d HEAD  | xargs)" to have prettier fix these code style issues while remaining scoped to files with uncommited changes only.',
         ],
         [
             'title' => 'Composer Audit',

diff --git a/img.png b/img.png
diff --git a/phpstan.neon.dist b/phpstan.neon.dist
@@ -0,0 +1,14 @@
+includes:
+    - phpstan-baseline.neon
+
+parameters:
+    level: 6
+    paths:
+        - src
+        - config
+    tmpDir: build/phpstan
+    checkOctaneCompatibility: true
+    checkModelProperties: true
+    ignoreErrors:
+        -
+            identifier: missingType.iterableValue
diff --git a/src/Commands/DevAuditCommand.php b/src/Commands/DevAuditCommand.php
@@ -29,6 +29,8 @@ class DevAuditCommand extends Command
 
     private array $audits = [];
 
+    private bool $hasUi = false;
+
     public function __construct(ProgressBarHelper $progressBarHelper, SpinnerHelper $spinner, TableHelper $tableHelper, FailureFeedbackHelper $failureFeedbackHelper, OutputFormatHelper $outputFormatHelper)
     {
         $this->progressBarHelper = $progressBarHelper;
@@ -53,16 +55,22 @@ public function handle(): int
         $outputInterface = $this->output->getOutput();
 
         if (method_exists($outputInterface, 'section')) {
-            $tableSection = $this->output->getOutput()->section();
-            $progressBarSection = $this->output->getOutput()->section();
-        }
 
-        $this->tableHelper->buildTable($tableSection, $this->audits);
-        $this->progressBarHelper->buildProgressBar($progressBarSection, $this->audits, $this->outputFormatHelper);
+            $output = $this->output->getOutput();
+            if (method_exists($output, 'section')) {
+                $this->hasUi = true;
+                $tableSection = $output->section();
+                $progressBarSection = $output->section();
+                $this->tableHelper->buildTable($tableSection, $this->audits);
+                $this->progressBarHelper->buildProgressBar($progressBarSection, $this->audits, $this->outputFormatHelper);
+            }
+        }
 
         $this->processActions();
 
-        $this->progressBarHelper->drawCompleted($this->outputFormatHelper);
+        if ($this->hasUi) {
+            $this->progressBarHelper->drawCompleted($this->outputFormatHelper);
+        }
 
         $this->output->write($this->failureFeedbackHelper->buildFailures($this->audits, $this->outputFormatHelper));
 
@@ -87,7 +95,9 @@ protected function processActions(): void
     protected function processAction(AuditModel $action, int $count): void
     {
         $action->isRunning = true;
-        $this->tableHelper->redrawTable($this->audits);
+        if ($this->hasUi) {
+            $this->tableHelper->redrawTable($this->audits);
+        }
 
         $process = $this->executeAction($action, $count);
 
@@ -96,17 +106,22 @@ protected function processAction(AuditModel $action, int $count): void
         $action->hadErrors = ! $process->isSuccessful();
         $action->output = $process->getOutput();
         $action->errorOutput = $process->getErrorOutput();
-        $this->tableHelper->redrawTable($this->audits);
+
+        if ($this->hasUi) {
+            $this->tableHelper->redrawTable($this->audits);
+        }
     }
 
     protected function executeAction(AuditModel $action, int $count): Process
     {
         $process = Process::fromShellCommandline($action->command, null, ['APP_ENV' => 'testing']);
         $process->start();
 
-        while ($process->isRunning()) {
-            $this->progressBarHelper->redrawProgressBar($count, $action->title, $this->spinner->spin(), $this->outputFormatHelper);
-            time_nanosleep(0, 250000000);
+        if ($this->hasUi) {
+            while ($process->isRunning()) {
+                $this->progressBarHelper->redrawProgressBar($count, $action->title, $this->spinner->spin(), $this->outputFormatHelper);
+                time_nanosleep(0, 250000000);
+            }
         }
 
         return $process;

diff --git a/src/Helpers/FailureFeedbackHelper.php b/src/Helpers/FailureFeedbackHelper.php
@@ -24,7 +24,8 @@ protected function buildFailure(AuditModel $action, OutputFormatHelper $outputFo
         $terminal = new Terminal;
 
         $failure = PHP_EOL.str_repeat('─', $terminal->getWidth()).PHP_EOL;
-        $failure .= $outputFormatHelper->buildOutput($action->title, 'bright-white', ['bold']);
+        $failure .= $outputFormatHelper->buildInlineOutput($action->title, 'bright-white', ['bold']);
+        $failure .= $outputFormatHelper->buildOutput(' failure details', 'gray');
 
         foreach ([
             'Command' => $action->command,
@@ -35,18 +36,18 @@ protected function buildFailure(AuditModel $action, OutputFormatHelper $outputFo
             $failure .= $this->buildSection($title, $value, $outputFormatHelper);
         }
 
-        return $failure;
+        return $failure.PHP_EOL;
     }
 
     protected function buildSection(string $title, ?string $value, OutputFormatHelper $outputFormatHelper): string
     {
         $section = PHP_EOL;
-        $section .= $outputFormatHelper->buildOutput($title, 'yellow', ['bold', 'underscore']);
+        $section .= $outputFormatHelper->buildOutput($title, 'blue', ['bold', 'underscore']);
 
         if ($value) {
-            return $section.PHP_EOL.' '.$value.PHP_EOL;
+            return $section.PHP_EOL.$value.PHP_EOL.PHP_EOL;
         }
 
-        return $section.PHP_EOL.$outputFormatHelper->buildOutput('n/a', 'gray');
+        return $section.PHP_EOL.$outputFormatHelper->buildOutput('n/a', 'gray').PHP_EOL;
     }
 }
diff --git a/src/Helpers/ProgressBarHelper.php b/src/Helpers/ProgressBarHelper.php
@@ -26,7 +26,7 @@ public function redrawProgressBar(int $actionNumber, string $actionTitle, string
 
     public function drawProgressBar(int $actionNumber, string $actionTitle, string $spinner, OutputFormatHelper $outputFormatHelper): string
     {
-        $progressBarOutput = $outputFormatHelper->buildInlineOutput("$spinner $actionNumber/$this->totalCount", 'bright-yellow');
+        $progressBarOutput = $outputFormatHelper->buildInlineOutput("$spinner running audit $actionNumber/$this->totalCount", 'bright-blue');
         $progressBarOutput .= $outputFormatHelper->buildOutput(" $actionTitle", 'bright-white');
 
         return $progressBarOutput;
@@ -35,6 +35,6 @@ public function drawProgressBar(int $actionNumber, string $actionTitle, string $
     public function drawCompleted(OutputFormatHelper $outputFormatHelper): void
     {
         $this->section->clear();
-        $this->section->overwrite($outputFormatHelper->buildOutput(".... All $this->totalCount completed.", 'bright-white'));
+        $this->section->overwrite($outputFormatHelper->buildOutput(".... All $this->totalCount audits completed", 'blue'));
     }
 }
diff --git a/tests/DevAuditTest.php b/tests/DevAuditTest.php