Test123/docs/AUTOMATION.md

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