Clean Code - Submission agent for #QodoAgentChallenge

agents/clean-code-agent/README.md

@@ -0,0 +1,44 @@
+# Clean Code Agent
+
+The Clean Code Agent is an AI-powered tool designed to help developers write more readable, maintainable, and well-structured code. It analyzes your source code and provides actionable feedback based on established clean code principles.
+
+## Key Features
+
+- **Automated Code Refactoring:** Goes beyond simple analysis by providing `diff`-style previews for fixing issues related to naming, complexity, and code smells.
+- **Automatic Docstring Generation:** Identifies public functions missing documentation and generates complete docstrings, including parameters and return values.
+- **Unit Test Scaffolding:** Creates basic unit test files for your modules, encouraging a test-driven development culture.
+- **Linter Integration:** Can run a command-line linter (e.g., ESLint, Pylint) and use its output as a baseline for its own, more context-aware analysis.
+- **Customizable Rule Sets:** Allows teams to enforce their own coding standards by providing a custom rules file.
+- **CI/CD Integration:** Includes ready-to-use configuration examples for GitHub Actions, GitLab CI, Jenkins, and Azure DevOps to automate code quality checks in your pipeline.
+- **Structured Output:** Produces machine-readable JSON output, perfect for integrations and quality gating.
+
+## How to Use
+
+You can run the Clean Code Agent using the `qodo` command-line tool.
+
+### Basic Analysis
+
+```bash
+qodo clean_code --set files="path/to/your/code" --set language="your_language"
+```
+
+### Generating Docstrings and Tests
+
+```bash
+qodo clean_code --set files="src/my_module.py" --set language="python" --set generate_docstrings=true --set generate_tests=true
+```
+
+### CI/CD Integration
+
+For examples of how to integrate the agent into your CI/CD pipeline, see the configuration files in the `examples/ci-configs` directory.
+
+## Arguments
+
+- `files` (required): A comma-separated list of file paths or directories to analyze.
+- `language` (required): The programming language of the files (e.g., 'python', 'javascript').
+- `report_format` (optional): The format for the output report ('markdown' or 'json'). Defaults to 'markdown'.
+- `linter_command` (optional): A linter command to run before analysis.
+- `rules_file` (optional): A path to a file containing custom analysis rules.
+- `complexity_analysis` (optional): Whether to perform and report on cyclomatic complexity. Defaults to `false`.
+- `generate_docstrings` (optional): If true, generates missing docstrings for public functions. Defaults to `false`.
+- `generate_tests` (optional): If true, generates a scaffold for unit tests. Defaults to `false`.

agents/clean-code-agent/agent.toml

@@ -0,0 +1,100 @@
+version = "1.0"
+
+[commands.clean_code]
+description = "An agent that analyzes code for cleanliness, readability, and maintainability, providing suggestions for improvement."
+
+instructions = """
+You are an expert AI assistant specializing in writing clean, maintainable, and well-documented code. Your primary goal is to improve code quality by not only identifying issues but also by actively generating missing documentation and tests.
+
+**Core Analysis Task:**
+Analyze the provided source code files for readability, maintainability, and structure. For each issue, provide the file path, line number, a clear description, and a 'diff-style' refactoring preview.
+
+You should look for:
+- **Meaningful Naming:** Unclear variable, function, or class names.
+- **Function Complexity:** Functions that are too long or have too many responsibilities.
+- **Code Smells:** Duplicated code, dead code, long parameter lists.
+- **Documentation Quality:** Unclear, outdated, or redundant comments.
+
+**Advanced Generation Tasks:**
+
+1.  **Docstring Generation (`generate_docstrings` = true):**
+    - Identify any public function or method that is missing a docstring.
+    - For each one, generate a complete and accurate docstring that describes the function's purpose, its arguments (`Args:`), and what it returns (`Returns:`).
+    - The generated docstring should be included in the `suggestion` part of the output.
+
+2.  **Unit Test Scaffolding (`generate_tests` = true):**
+    - For each source file, create a corresponding test file (e.g., `test_my_module.py` for `my_module.py`).
+    - In the test file, generate a basic unit test class with placeholder test methods for each public function in the source file.
+    - The test methods should include a simple `self.fail("Test not implemented")` or equivalent.
+    - The path to the newly created test file should be included in the output.
+
+**Execution Flow:**
+- If a `linter_command` is provided, run it first and use its output to inform your analysis.
+- If a `rules_file` is provided, prioritize those rules.
+- Perform the core analysis and the advanced generation tasks as requested by the input arguments.
+"""
+
+arguments = [
+  { name = "files", type = "string", required = true, description = "A comma-separated list of file paths or directories to analyze." },
+  { name = "language", type = "string", required = true, description = "The programming language of the files (e.g., 'python', 'javascript')." },
+  { name = "report_format", type = "string", required = false, default = "markdown", description = "The format for the output report ('markdown' or 'json')." },
+  { name = "linter_command", type = "string", required = false, description = "An optional linter command to run before analysis (e.g., 'eslint .')." },
+  { name = "rules_file", type = "string", required = false, description = "An optional path to a file containing custom analysis rules." },
+  { name = "complexity_analysis", type = "boolean", required = false, default = false, description = "Whether to perform and report on cyclomatic complexity." },
+  { name = "generate_docstrings", type = "boolean", required = false, default = false, description = "If true, generates missing docstrings for public functions." },
+  { name = "generate_tests", type = "boolean", required = false, default = false, description = "If true, generates a scaffold for unit tests." }
+]
+
+tools = ["filesystem", "shell"]
+execution_strategy = "plan"
+
+output_schema = """
+{
+  "type": "object",
+  "properties": {
+    "summary": {
+      "type": "object",
+      "properties": {
+        "files_analyzed": {"type": "number"},
+        "issues_found": {"type": "number"},
+        "docstrings_generated": {"type": "number"},
+        "test_files_created": {"type": "number"}
+      }
+    },
+    "issues": {
+      "type": "array",
+      "description": "A list of clean code issues found and refactoring suggestions.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "file": {"type": "string"},
+          "line": {"type": "number"},
+          "description": {"type": "string"},
+          "suggestion": {
+            "type": "object",
+            "properties": {
+              "code_to_remove": {"type": "string"},
+              "code_to_add": {"type": "string"}
+            }
+          },
+          "cyclomatic_complexity": {
+            "type": "number",
+            "description": "The calculated cyclomatic complexity of the function or method."
+          }
+        },
+        "required": ["file", "line", "description", "suggestion"]
+      }
+    },
+    "generated_test_files": {
+      "type": "array",
+      "description": "A list of paths to the newly created unit test scaffold files.",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": ["summary", "issues"]
+}
+"""
+
+exit_expression = "summary.issues_found == 0"

agents/clean-code-agent/agent.yaml

@@ -0,0 +1,120 @@
+version: "1.0"
+commands:
+  clean_code:
+    description: "An agent that analyzes code for cleanliness, readability, and maintainability, providing suggestions for improvement."
+    instructions: |
+      You are an expert AI assistant specializing in writing clean, maintainable, and well-documented code. Your primary goal is to improve code quality by not only identifying issues but also by actively generating missing documentation and tests.
+
+      **Core Analysis Task:**
+      Analyze the provided source code files for readability, maintainability, and structure. For each issue, provide the file path, line number, a clear description, and a 'diff-style' refactoring preview.
+
+      You should look for:
+      - **Meaningful Naming:** Unclear variable, function, or class names.
+      - **Function Complexity:** Functions that are too long or have too many responsibilities.
+      - **Code Smells:** Duplicated code, dead code, long parameter lists.
+      - **Documentation Quality:** Unclear, outdated, or redundant comments.
+
+      **Advanced Generation Tasks:**
+
+      1.  **Docstring Generation (`generate_docstrings` = true):**
+          - Identify any public function or method that is missing a docstring.
+          - For each one, generate a complete and accurate docstring that describes the function's purpose, its arguments (`Args:`), and what it returns (`Returns:`).
+          - The generated docstring should be included in the `suggestion` part of the output.
+
+      2.  **Unit Test Scaffolding (`generate_tests` = true):**
+          - For each source file, create a corresponding test file (e.g., `test_my_module.py` for `my_module.py`).
+          - In the test file, generate a basic unit test class with placeholder test methods for each public function in the source file.
+          - The test methods should include a simple `self.fail("Test not implemented")` or equivalent.
+          - The path to the newly created test file should be included in the output.
+
+      **Execution Flow:**
+      - If a `linter_command` is provided, run it first and use its output to inform your analysis.
+      - If a `rules_file` is provided, prioritize those rules.
+      - Perform the core analysis and the advanced generation tasks as requested by the input arguments.
+    arguments:
+      - name: "files"
+        type: "string"
+        required: true
+        description: "A comma-separated list of file paths or directories to analyze."
+      - name: "language"
+        type: "string"
+        required: true
+        description: "The programming language of the files (e.g., 'python', 'javascript')."
+      - name: "report_format"
+        type: "string"
+        required: false
+        default: "markdown"
+        description: "The format for the output report ('markdown' or 'json')."
+      - name: "linter_command"
+        type: "string"
+        required: false
+        description: "An optional linter command to run before analysis (e.g., 'eslint .')."
+      - name: "rules_file"
+        type: "string"
+        required: false
+        description: "An optional path to a file containing custom analysis rules."
+      - name: "complexity_analysis"
+        type: "boolean"
+        required: false
+        default: false
+        description: "Whether to perform and report on cyclomatic complexity."
+      - name: "generate_docstrings"
+        type: "boolean"
+        required: false
+        default: false
+        description: "If true, generates missing docstrings for public functions."
+      - name: "generate_tests"
+        type: "boolean"
+        required: false
+        default: false
+        description: "If true, generates a scaffold for unit tests."
+    tools: ["filesystem", "shell"]
+    execution_strategy: "plan"
+    output_schema: |
+      {
+        "type": "object",
+        "properties": {
+          "summary": {
+            "type": "object",
+            "properties": {
+              "files_analyzed": {"type": "number"},
+              "issues_found": {"type": "number"},
+              "docstrings_generated": {"type": "number"},
+              "test_files_created": {"type": "number"}
+            }
+          },
+          "issues": {
+            "type": "array",
+            "description": "A list of clean code issues found and refactoring suggestions.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "file": {"type": "string"},
+                "line": {"type": "number"},
+                "description": {"type": "string"},
+                "suggestion": {
+                  "type": "object",
+                  "properties": {
+                    "code_to_remove": {"type": "string"},
+                    "code_to_add": {"type": "string"}
+                  }
+                },
+                "cyclomatic_complexity": {
+                  "type": "number",
+                  "description": "The calculated cyclomatic complexity of the function or method."
+                }
+              },
+              "required": ["file", "line", "description", "suggestion"]
+            }
+          },
+          "generated_test_files": {
+            "type": "array",
+            "description": "A list of paths to the newly created unit test scaffold files.",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": ["summary", "issues"]
+      }
+    exit_expression: "summary.issues_found == 0"

agents/clean-code-agent/examples/ci-configs/azure-devops.yml

@@ -0,0 +1,21 @@
+trigger:
+- main
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+steps:
+- task: NodeTool@0
+  inputs:
+    versionSpec: '18.x'
+  displayName: 'Install Node.js'
+
+- script: |
+    npm install -g @qodo-ai/command
+  displayName: 'Install Qodo'
+
+- script: |
+    qodo clean_code --set files="." --set language="python" --set report_format="json"
+  displayName: 'Run Clean Code Agent'
+  env:
+    QODO_API_KEY: $(QODO_API_KEY)

agents/clean-code-agent/examples/ci-configs/github-actions.yml

@@ -0,0 +1,25 @@
+name: Clean Code Agent Analysis
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  clean-code-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Install Qodo
+        run: npm install -g @qodo-ai/command
+
+      - name: Run Clean Code Agent
+        run: |
+          qodo clean_code \
+            --set files="." \
+            --set language="python" \
+            --set report_format="json" \
+            --set generate_docstrings=true
+        env:
+          QODO_API_KEY: ${{ secrets.QODO_API_KEY }}

agents/clean-code-agent/examples/ci-configs/gitlab-ci.yml

@@ -0,0 +1,13 @@
+stages:
+  - test
+
+clean_code_check:
+  stage: test
+  image: node:18
+  script:
+    - npm install -g @qodo-ai/command
+    - qodo clean_code --set files="." --set language="python" --set report_format="json"
+  variables:
+    QODO_API_KEY: $QODO_API_KEY
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

agents/clean-code-agent/examples/ci-configs/jenkins-pipeline.groovy

@@ -0,0 +1,16 @@
+pipeline {
+    agent any
+    environment {
+        QODO_API_KEY = credentials('qodo-api-key')
+    }
+    stages {
+        stage('Clean Code Check') {
+            steps {
+                script {
+                    sh 'npm install -g @qodo-ai/command'
+                    sh 'qodo clean_code --set files="." --set language="python" --set report_format="json"'
+                }
+            }
+        }
+    }
+}