diff --git a/.github/workflows/README-a3-python.md b/.github/workflows/README-a3-python.md deleted file mode 100644 index fe1b9d898..000000000 --- a/.github/workflows/README-a3-python.md +++ /dev/null @@ -1,208 +0,0 @@ -# A3 Python Code Analysis - Automated Bug Detection - -## Overview - -A3 Python Code Analysis is an AI-powered GitHub Agentic Workflow that automatically analyzes Python code in the Z3 repository using the `a3-python` tool. It identifies potential bugs, code quality issues, and provides actionable recommendations for improvements. - -## Features - -- **Automated Analysis**: Runs a3-python tool on all Python files in the `src/` directory -- **Smart Classification**: Distinguishes between true positives (real issues) and false positives -- **Issue Creation**: Automatically creates GitHub issues when 2+ likely issues are detected -- **Comprehensive Reports**: Includes severity levels, file locations, and fix recommendations -- **Weekly Schedule**: Runs automatically every Sunday to catch issues early -- **Manual Trigger**: Can be triggered on-demand via workflow dispatch - -## How to Use - -### Scheduled Runs (Automatic) - -The workflow runs automatically every Sunday at midnight UTC. No action required. - -### Manual Trigger (Workflow Dispatch) - -1. Go to **Actions** → **A3 Python Code Analysis** in the GitHub repository -2. Click **Run workflow** -3. Select the branch (usually `main`) -4. Click **Run workflow** - -The workflow will: -1. Install the a3-python tool from PyPI -2. Run analysis on all Python files in `src/` -3. Save output to `a3-python-output.txt` -4. Classify findings as true positives or false positives -5. Create a GitHub issue if 2+ likely issues are found - -## What Gets Analyzed - -The workflow analyzes: -- All Python files (`.py`) in the `src/` directory -- Python code for bugs, security issues, and quality problems -- Import statements and dependencies -- Code patterns and potential issues - -## Issue Creation Logic - -An issue is created **only when**: -- ✅ Analysis finds **2 or more true positives** (likely issues) -- ✅ Issues are actionable and specific -- ✅ Analysis completed successfully - -An issue is **not created** when: -- ❌ Zero or one true positive found -- ❌ Only false positives detected -- ❌ Analysis failed to run -- ❌ No Python files found - -## Issue Structure - -When issues are created, they include: - -### Summary Section -- Analysis date -- Total findings count -- True positives count -- False positives count - -### True Positives Section -For each likely issue: -- **File**: Path to the affected file -- **Line**: Line number (if available) -- **Severity**: High / Medium / Low -- **Description**: Detailed explanation -- **Recommendation**: How to fix it - -### Analysis Details -- False positives with dismissal reasons (collapsible) -- Complete raw output from a3-python (collapsible) - -### Recommendations -- Prioritization guidance -- Action items - -## Classification Criteria - -### True Positives (Real Issues) -Issues that meet these criteria: -- Represents a real bug or problem -- Could impact functionality, security, or performance -- Actionable with a clear fix -- In code owned by the repository (not third-party) - -Examples: -- Logic errors or bugs -- Security vulnerabilities -- Performance issues -- Broken imports or dependencies -- Type mismatches or incorrect usage - -### False Positives (Not Issues) -Findings that are dismissed: -- Style preferences without functional impact -- Intentional design decisions -- Test code patterns -- Generated or vendored code -- Overly pedantic warnings - -## Output Files - -The workflow generates: -- `a3-python-output.txt`: Raw output from the a3-python analysis tool - - Contains all findings from the tool - - Includes errors, warnings, and recommendations - - Saved in the workflow run artifacts - -## Configuration - -The workflow is configured with: - -- **Trigger**: Weekly schedule (Sundays at midnight UTC) + manual dispatch -- **Timeout**: 45 minutes -- **Permissions**: Read-only (safe-outputs handle issue creation) -- **Labels**: Issues are labeled with `bug`, `automated-analysis`, `a3-python` -- **Tracker ID**: All issues include `a3-python-analysis` identifier for tracking - -## Running a3-python Locally - -To test the analysis locally: - -```bash -# Install a3-python -pip install a3-python - -# Run analysis on src directory -a3 analyze ./src - -# Or with additional options -a3 analyze ./src --generate-docs --dependency-graph - -# Or debug mode -a3 debug ./src --execute-tests --validate-imports -``` - -## Interpreting Results - -When reviewing issues created by this workflow: - -1. **Check Severity**: Start with high-severity issues first -2. **Verify the Issue**: Confirm it's a real problem in the codebase -3. **Review Recommendation**: Follow the suggested fix if appropriate -4. **Test Changes**: Ensure fixes don't break functionality -5. **Close or Comment**: Update the issue with your findings - -## Customization - -To modify the agent behavior without recompiling: - -1. Edit `.github/workflows/a3-python.md` (the markdown body after `---`) -2. Changes take effect immediately on the next run -3. No compilation needed for prompt changes - -For configuration changes (schedule, permissions, etc.): - -```bash -# Edit the YAML frontmatter in .github/workflows/a3-python.md -# Then recompile: -gh aw compile a3-python -``` - -## Limitations - -- Analyzes only Python files (`.py`) in the `src/` directory -- Depends on a3-python tool's capabilities and accuracy -- May have false positives that require human review -- Cannot automatically fix issues (only reports them) -- Requires API key if a3-python needs one (set `A3_API_KEY` secret) - -## Security - -- **Read-only permissions** for repository access -- **Safe outputs** handle all write operations (issue creation) -- **No secrets exposed** to the AI agent -- **Strict mode enabled** for enhanced security validation -- **Network access** controlled and limited - -## Troubleshooting - -### Tool Installation Fails -If a3-python fails to install, the workflow will report the error and exit gracefully. - -### No Output Generated -If the analysis produces no output, the workflow will document this and exit without creating an issue. - -### All False Positives -If all findings are false positives, the workflow will exit gracefully without creating an issue. - -## Support - -If the workflow encounters issues: -- Check the workflow run logs in the Actions tab -- Review error messages in the output -- Ensure Python files exist in the `src/` directory -- Verify a3-python tool is working: `pip install a3-python && a3 --version` - -## See Also - -- [a3-python on PyPI](https://pypi.org/project/a3/) -- [GitHub Agentic Workflows Documentation](https://github.github.com/gh-aw/) -- [Z3 Repository Structure](../../README.md)