Initial commit

skills/skill-adapter/assets/health_report_template.md

@@ -0,0 +1,161 @@
+# Project Health Audit Report
+
+**Project Name:** `[Enter Project Name Here]`
+
+**Report Date:** `[Enter Date Here]`
+
+**Repository Path:** `[Enter Path to Repository Here - e.g., /path/to/my/repo]`
+
+**Audited By:** `[Your Name/Team Name]`
+
+**Executive Summary:**
+
+`[Provide a brief overview of the project's overall health.  Highlight key strengths and weaknesses.  For example: "This project demonstrates good test coverage in the core modules but suffers from high cyclomatic complexity in the utility functions.  Refactoring the utility functions and addressing identified dead code will significantly improve maintainability."]`
+
+## 1. Code Complexity Analysis
+
+This section analyzes the cyclomatic complexity and other code complexity metrics to identify potentially problematic areas.  High complexity can lead to increased maintenance costs and a higher likelihood of bugs.
+
+### 1.1 High Complexity Files
+
+`[List files with high cyclomatic complexity (e.g., > 10).  Include the complexity score for each file and a brief justification for concern.  Example:
+
+*   `src/utils/date_formatter.py`: Cyclomatic Complexity = 18.  This file handles a wide variety of date formatting scenarios, leading to a complex control flow.  Refactoring into smaller, more focused functions is recommended.
+*   `src/logic/data_validation.js`: Cyclomatic Complexity = 12. Contains many nested conditional statements.  Consider using a strategy pattern or rule engine to simplify the logic.
+]`
+
+### 1.2 Average Complexity
+
+`[Report the average cyclomatic complexity across the codebase.  Provide context on what constitutes a "good" or "bad" average.  Example: "The average cyclomatic complexity across the codebase is 6. This is generally acceptable, but the files listed above warrant further investigation."]`
+
+### 1.3 Recommendations
+
+`[Provide specific recommendations for addressing code complexity.  Example:
+
+*   Refactor high-complexity functions into smaller, more manageable units.
+*   Employ design patterns (e.g., Strategy, Template Method) to simplify complex control flow.
+*   Introduce unit tests to provide confidence during refactoring.
+]`
+
+## 2. Code Churn Analysis
+
+This section analyzes the frequency and magnitude of changes to the codebase.  High churn can indicate instability, frequent bug fixes, or areas undergoing significant development.
+
+### 2.1 High Churn Files
+
+`[List files with high churn (number of commits, lines added/removed). Include the relevant metrics and a brief explanation of why the churn might be concerning. Example:
+
+*   `src/api/v1/users.py`: 52 commits in the last 3 months.  This endpoint has seen frequent updates, potentially indicating ongoing feature development or bug fixes.
+*   `src/models/user.js`: 300 lines added/removed in the last month.  Significant changes to the user model may impact other parts of the application.
+]`
+
+### 2.2 Low Churn Files
+
+`[Optionally, list files with very low churn. This might indicate dead code or neglected areas.  Example:
+
+*   `src/utils/deprecated_function.py`: No commits in the last year.  This function is likely no longer used and should be considered for removal.
+]`
+
+### 2.3 Recommendations
+
+`[Provide recommendations based on the churn analysis. Example:
+
+*   Investigate the reasons for high churn in specific files.  Is it due to ongoing development, bug fixes, or refactoring?
+*   Consider archiving or removing dead code to reduce maintenance overhead.
+*   Establish clear ownership for frequently changing files to ensure code quality.
+]`
+
+## 3. Test Coverage Analysis
+
+This section analyzes the test coverage of the codebase to identify areas that lack sufficient testing.
+
+### 3.1 Low Coverage Files
+
+`[List files with low test coverage (e.g., < 80%).  Include the coverage percentage and a brief explanation of the potential risks. Example:
+
+*   `src/payment/processor.py`: Test coverage = 65%.  Critical payment processing logic lacks sufficient test coverage, increasing the risk of errors.
+*   `src/reporting/data_aggregator.js`: Test coverage = 70%.  Data aggregation logic is complex and requires thorough testing to ensure accuracy.
+]`
+
+### 3.2 Coverage Gaps
+
+`[Describe specific areas where test coverage is lacking. Example:
+
+*   Edge cases in the `date_formatter` function are not adequately tested.
+*   Error handling scenarios in the `payment_processor` are missing test cases.
+]`
+
+### 3.3 Overall Coverage
+
+`[Report the overall test coverage percentage for the project.  Provide context on what constitutes an acceptable level of coverage. Example: "The overall test coverage for the project is 85%. While this is a good starting point, improving coverage in the identified low-coverage files is crucial."]`
+
+### 3.4 Recommendations
+
+`[Provide recommendations for improving test coverage. Example:
+
+*   Write unit tests for all critical functions and classes.
+*   Focus on covering edge cases, error handling scenarios, and boundary conditions.
+*   Use code coverage tools to identify gaps in testing.
+*   Consider using test-driven development (TDD) for new features.
+]`
+
+## 4. Dead Code Analysis
+
+This section identifies code that appears to be unused and potentially removable.
+
+### 4.1 Potential Dead Code
+
+`[List functions, classes, or files that appear to be unused. Include the reasons for suspicion. Example:
+
+*   `src/utils/deprecated_function.py`: Not called by any other module.
+*   `src/config/experimental_feature.js`: Flag is always set to `false`.
+]`
+
+### 4.2 Recommendations
+
+`[Provide recommendations for dealing with potential dead code. Example:
+
+*   Thoroughly verify that the identified code is indeed unused before removing it.
+*   Use static analysis tools to confirm that the code is not referenced.
+*   Consider archiving the code instead of immediately deleting it.
+]`
+
+## 5. Security Vulnerabilities
+
+`[**Note:** This plugin does not directly perform security vulnerability scanning. Integrate with a dedicated security scanning tool (e.g., Snyk, SonarQube) for a comprehensive security assessment. This section is for documenting the findings from those tools.]`
+
+### 5.1 Identified Vulnerabilities
+
+`[List any security vulnerabilities identified by external tools. Include the vulnerability type, severity, and affected files. Example:
+
+*   **SQL Injection:** High severity, `src/api/v1/users.py`.  Untrusted user input is used directly in a SQL query.
+*   **Cross-Site Scripting (XSS):** Medium severity, `src/templates/user_profile.html`.  User-provided data is not properly sanitized before being displayed.
+]`
+
+### 5.2 Recommendations
+
+`[Provide recommendations for addressing identified security vulnerabilities. Example:
+
+*   Sanitize user input to prevent SQL injection and XSS attacks.
+*   Use parameterized queries to avoid SQL injection.
+*   Keep dependencies up-to-date to patch known vulnerabilities.
+*   Implement proper authentication and authorization mechanisms.
+]`
+
+## 6. Overall Health Score
+
+`[Assign an overall health score to the project (e.g., A, B, C, D, F).  Base the score on the findings in the previous sections.  Provide a justification for the score. Example:
+
+**Overall Health Score: B**
+
+This project demonstrates good overall health with acceptable complexity and test coverage. However, the identified high-churn files and potential dead code warrant further investigation. Addressing the security vulnerabilities is critical.
+]`
+
+## 7. Action Items
+
+`[List specific action items to improve the project's health.  Include responsible parties and deadlines. Example:
+
+*   Refactor `src/utils/date_formatter.py` to reduce cyclomatic complexity (John Doe, 2024-01-31).
+*   Write unit tests for `src/payment/processor.py` to increase test coverage (Jane Smith, 2024-02-15).
+*   Address the SQL injection vulnerability in `src/api/v1/users.py` (Security Team, 2024-01-20).
+]`