Initial commit

docs/AUTOMATION.md

@@ -0,0 +1,113 @@
+# Automation
+
+## Intentional Behavior
+
+This repository is for customer debugging projects.
+
+Customers are expected to upload broken code.
+
+Because of that:
+
+- Green workflow means automation completed.
+- Red workflow means automation failed.
+- Customer code errors are listed in `reports/errors.md`.
+- Broken customer code does not fail the workflow red.
+
+This behavior is intentional for DevPlus1.
+
+## Workflows
+
+### `validate.yml`
+
+- Runs on `push`
+- Runs on `pull_request`
+- Uses runner label `linux-dev`
+- Runs `tools/validate-code.sh`
+- Prints `reports/errors.md` into Forgejo logs
+- Fails only if the validation script crashes or `reports/errors.md` is missing
+
+### `project-report.yml`
+
+- Runs on `push`
+- Runs on `pull_request`
+- Uses runner label `linux-dev`
+- Runs `tools/validate-code.sh`
+- Runs `tools/project-report.sh`
+- Prints report summaries into Forgejo logs
+- Fails only if report generation crashes or required report files are missing
+
+### `code-docs.yml`
+
+- Runs on `push`
+- Runs on `pull_request`
+- Uses runner label `linux-dev`
+- Runs `tools/generate-code-docs.sh`
+- Prints code documentation summary output into Forgejo logs
+- Fails only if the documentation script crashes or required code documentation reports are missing
+
+## Scripts
+
+### `tools/validate-code.sh`
+
+- Recursively scans the repository
+- Excludes common dependency and generated directories
+- Validates supported files when tools are installed
+- Always writes `reports/errors.md`
+- Always prints a terminal summary
+- Exits `0` even when customer code errors are found
+- Exits non-zero only for automation/report generation failure
+
+### `tools/project-report.sh`
+
+- Generates project analysis reports
+- Reads customer code error status when available
+- Writes summary and generated-file tracking reports
+- Exits non-zero only if the script itself cannot generate required outputs
+
+### `tools/generate-code-docs.sh`
+
+- Reads customer source files without modifying them
+- Generates best-effort API, file-purpose, Unity lifecycle, and call-map reports
+- Uses regex-based extraction and cautious wording
+- Exits non-zero only if report generation fails
+
+## Generated Report Files
+
+- `reports/errors.md`
+- `reports/project-flow.md`
+- `reports/file-summary.md`
+- `reports/languages.md`
+- `reports/summary.md`
+- `reports/generated-files.md`
+- `reports/customer-code-status.txt`
+- `reports/api-reference.md`
+- `reports/file-purpose.md`
+- `reports/unity-scripts.md`
+- `reports/call-map.md`
+- `reports/code-docs-summary.md`
+
+## Validation Sample Files
+
+The repository includes intentional validator fixtures under `tests/validation-samples/`.
+
+These files exist to prove:
+
+- valid samples are accepted
+- broken samples are reported
+- broken customer code does not force the workflow red
+
+## Extending The System
+
+To add more validators later:
+
+1. Update `tools/validate-code.sh`
+2. Document the validator in `docs/VALIDATORS.md`
+3. Update `docs/AUTOMATION.md` and `docs/WORKFLOWS.md` if workflow behavior changes
+4. Update `docs/CODEX_INSTRUCTIONS.md`
+
+To add more code documentation extraction later:
+
+1. Update `tools/generate-code-docs.sh`
+2. Document new reports in `docs/REPORTS.md`
+3. Document workflow changes in `docs/WORKFLOWS.md`
+4. Update `docs/CODEX_INSTRUCTIONS.md`