add workflows

docs/AUTOMATION.md

@@ -0,0 +1,108 @@
+# 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.