# Automation

## Purpose

This repository includes two Forgejo Actions workflows for reusable customer-project automation:

- `validate.yml`: runs repository validation on push and pull request.
- `project-report.yml`: generates best-effort project analysis reports on push and pull request.

## Workflows

### `validate.yml`

- runs on `push`
- runs on `pull_request`
- uses the `linux-dev` runner label
- checks out the repository
- runs `tools/validate-code.sh`
- fails when validation finds real errors

### `project-report.yml`

- runs on `push`
- runs on `pull_request`
- uses the `linux-dev` runner label
- checks out the repository
- runs `tools/project-report.sh`
- regenerates reports in `reports/`
- does not fail because analysis finds issues or uncertainty
- only fails if the script itself crashes

## Scripts

### `tools/validate-code.sh`

This script recursively scans the repository while excluding common generated or dependency folders such as:

- `.git`
- `.forgejo`
- `node_modules`
- `vendor`
- `Library`
- `Temp`
- `Logs`
- `obj`
- `bin`

When the necessary tools are installed, it validates:

- PHP with `php -l`
- Python with `python3 -m py_compile`
- Ruby with `ruby -c`
- Perl with `perl -c`
- Shell with `bash -n`
- JavaScript with `node --check`
- JSON with `jq`
- YAML with `yamllint`
- HTML with `tidy`
- C# with `dotnet build`
- C/C++ CMake projects with `cmake` configure validation

It writes `reports/errors.md` with:

- validation summary
- files checked
- warnings
- errors
- detailed per-file results

### `tools/project-report.sh`

This script generates:

- `reports/project-flow.md`
- `reports/file-summary.md`
- `reports/languages.md`

It performs best-effort analysis for:

- language counts
- likely entry points
- possible startup files
- framework detection
- database detection
- environment files
- config files
- Docker-related files
- probable application flow

The wording is intentionally cautious. It does not claim certainty.

## Reuse In Future Customer Repositories

To reuse this automation in another repository:

1. Copy `.forgejo/workflows/validate.yml`
2. Copy `.forgejo/workflows/project-report.yml`
3. Copy `tools/validate-code.sh`
4. Copy `tools/project-report.sh`
5. Create `reports/.gitkeep`
6. Keep the exclude list if the repository includes generated or dependency folders
7. Review language and framework detection rules for project-specific needs

## Notes

- Reports are regenerated on every run.
- Validation skips checks gracefully when required tools are not installed.
- The automation is additive and does not modify customer source files.