Getting Started

Minimal Setup

Installation:
```
composer require --dev hermes/dependencies
```
Ensure the package is added to require-dev in your composer.json.
First Run: Execute the CLI tool to generate a markdown file with dependencies:
```
vendor/bin/hermes -c
```
This generates a composer_dependencies.md file in the project root by default.
Quick Use Case: Generate a combined report for both Composer and NPM dependencies:
```
vendor/bin/hermes -a
```
Outputs dependencies.md with structured tables for both dependency types.

Where to Look First

CLI Arguments: Check vendor/bin/hermes --help for available flags (-c, -p, -a, --path, --output).
Output Format: Inspect the generated markdown files to understand the structure (e.g., tables for dependencies, versions, and licenses).
Custom Paths: Use --path to target submodules or monorepo directories:
```
vendor/bin/hermes -c --path ./modules/api
```

First Laravel Integration

Automate in post-install-cmd: Add to your composer.json to generate dependency reports on install:

"scripts": {
    "post-install-cmd": [
        "@php vendor/bin/hermes -a --output=docs/dependencies.md"
    ]
}

Publish to Docs: Commit the generated markdown to your docs/ folder and link it in your README.md:
```
## Dependencies
See [full dependency report](./docs/dependencies.md).
```

Implementation Patterns

Workflows

Dependency Audits:
- Run vendor/bin/hermes -a before major releases to document dependencies.
- Compare outputs across branches to track changes:
```
vendor/bin/hermes -a --output=docs/dependencies-v1.md
```

Monorepo Support:

Generate per-module reports:

vendor/bin/hermes -c --path ./packages/auth --output=packages/auth/dependencies.md

CI/CD Integration:

Add to Laravel’s phpunit.xml or GitHub Actions to validate dependencies:

# .github/workflows/dependencies.yml
- name: Generate Dependencies Report
  run: vendor/bin/hermes -a --output=docs/dependencies.md

Integration Tips

Laravel Artisan Commands: Extend Hermes functionality by creating a custom Artisan command:

// app/Console/Commands/GenerateDependencies.php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Symfony\Component\Process\Process;
use Symfony\Component\Process\Exception\ProcessFailedException;

class GenerateDependencies extends Command
{
    protected $signature = 'dependencies:generate
        {--type= : Type (composer|package|all)}
        {--output= : Output path}';

    public function handle()
    {
        $process = new Process(['vendor/bin/hermes', '-'.$this->option('type'), '--output='.$this->option('output')]);
        $process->run();

        if (!$process->isSuccessful()) {
            throw new ProcessFailedException($process);
        }

        $this->info('Dependencies report generated!');
    }
}

protected $commands = [
    Commands\GenerateDependencies::class,
];

Run with:

php artisan dependencies:generate --type=all --output=docs/report.md

Dynamic Documentation: Use Laravel’s Blade to embed dependency reports in admin panels:

// routes/web.php
Route::get('/admin/dependencies', function () {
    return view('admin.dependencies', [
        'composerDeps' => file_get_contents('docs/composer_dependencies.md'),
        'npmDeps' => file_get_contents('docs/package_dependencies.md'),
    ]);
});

Dependency Version Tracking: Parse the markdown output in Laravel to track versions over time:

// app/Services/DependencyTracker.php
public function parseComposerDependencies(string $markdown): array
{
    $dependencies = [];
    preg_match_all('/\|([^\|]+)\|([^\|]+)\|([^\|]+)\|/', $markdown, $matches);
    foreach ($matches[0] as $i => $row) {
        $dependencies[$matches[1][$i]] = [
            'version' => $matches[2][$i],
            'license' => $matches[3][$i],
        ];
    }
    return $dependencies;
}

Gotchas and Tips

Pitfalls

Missing package.json or composer.json:

Hermes throws exceptions if files are missing. Handle gracefully in CI:

- name: Generate Dependencies
  run: |
    if [ -f "composer.json" ]; then
      vendor/bin/hermes -c --output=docs/composer.md
    fi
    if [ -f "package.json" ]; then
      vendor/bin/hermes -p --output=docs/npm.md
    fi

Output Overwrites:
- Default outputs (composer_dependencies.md, package_dependencies.md) overwrite on each run. Use --output to avoid conflicts:
```
vendor/bin/hermes -a --output=docs/dependencies-$(date +%Y-%m-%d).md
```
NPM DevDependencies:
- By default, Hermes includes both dependencies and devDependencies from package.json. Exclude dev dependencies by modifying the package’s logic or pre-processing package.json:
```
jq 'del(.devDependencies)' package.json > temp.json && vendor/bin/hermes -p --path=temp.json
```

Debugging

Verbose Output:
- Hermes lacks verbose logging. Debug by inspecting the generated markdown or adding error_log calls to the package’s src/Hermes.php.
Path Issues:
- If --path fails, ensure the path is absolute or relative to the project root. Use pwd to verify:
```
cd /path/to/project && vendor/bin/hermes -c --path ./subdir
```
Permission Errors:
- Ensure the output directory is writable:
```
mkdir -p docs && chmod -R 777 docs
```

Tips

Custom Templates:

Extend Hermes by modifying its markdown template (located in src/Templates/DependenciesTemplate.php). Fork the package or create a wrapper:

// app/Services/CustomHermes.php
use Hermes\Dependencies\Templates\DependenciesTemplate;

class CustomDependenciesTemplate extends DependenciesTemplate
{
    public function renderComposer(array $dependencies): string
    {
        // Custom logic (e.g., add columns for security advisories)
        return "```\n".implode("\n", $dependencies)."\n```";
    }
}

Git Hooks:

Auto-generate reports on pre-commit to track dependency changes:

# .git/hooks/pre-commit
#!/bin/sh
vendor/bin/hermes -a --output=docs/dependencies.md && git add docs/dependencies.md

Security Audits:
- Combine Hermes with composer why-not or npm audit to flag vulnerable dependencies:
```
vendor/bin/hermes -c --output=docs/safe-deps.md && composer why-not --platform
```
Performance:
- Hermes is lightweight, but parsing large monorepos may slow down. Cache outputs:
```
vendor/bin/hermes -a --output=docs/dependencies.md || true  # Skip if fails
```

Local Development:

Symlink Hermes globally for easier access:

ln -s vendor/bin/hermes /usr/local/bin/hermes

Now run from anywhere:
```
hermes -c --path=/path/to/project
```

Dependencies Laravel Package