# 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`