zhongwei/gh-jeremylongshore-claude-code-plugins-plus-plugins-mcp-project-health-auditor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:20:25 +08:00
commit e9e626f65a
17 changed files with 1063 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
skills/skill-adapter/assets/README.md Normal file
View File

@@ -0,0 +1,6 @@
# Assets
Bundled resources for project-health-auditor skill
- [ ] health_report_template.md: Template for generating a comprehensive health report.
- [ ] example_health_report.md: Example of a generated health report.

32
skills/skill-adapter/assets/config-template.json Normal file
View File

@@ -0,0 +1,32 @@
{
"skill": {
"name": "skill-name",
"version": "1.0.0",
"enabled": true,
"settings": {
"verbose": false,
"autoActivate": true,
"toolRestrictions": true
}
},
"triggers": {
"keywords": [
"example-trigger-1",
"example-trigger-2"
],
"patterns": []
},
"tools": {
"allowed": [
"Read",
"Grep",
"Bash"
],
"restricted": []
},
"metadata": {
"author": "Plugin Author",
"category": "general",
"tags": []
}
}

110
skills/skill-adapter/assets/example_health_report.md Normal file
View File

@@ -0,0 +1,110 @@
# Project Health Audit Report
This report provides a comprehensive overview of the health of your project, combining metrics for code complexity, code churn, and test coverage. It identifies areas that may require attention to improve maintainability, reduce risk, and enhance overall code quality.
## Project Information
* **Project Name:** `[Your Project Name Here]`
* **Repository Path:** `[Path to your repository, e.g., /Users/yourname/projects/my-project]`
* **Date Generated:** `[Date the report was generated, e.g., 2023-10-27]`
## Key Metrics Summary
| Metric | Value | Threshold | Status | Notes |
|-----------------|-------------|----------------|------------|-----------------------------------------------------------------------|
| Cyclomatic Complexity (Avg) | `[Average Complexity]` | <= 10 | `[Good/Warning/Critical]` | Lower is better. High complexity can indicate hard-to-understand code. |
| Code Churn (Avg Lines Changed/File) | `[Average Churn]` | <= 50 | `[Good/Warning/Critical]` | High churn can indicate areas of instability or frequent refactoring. |
| Test Coverage | `[Coverage Percentage]` | >= 80% | `[Good/Warning/Critical]` | Higher is better. Low coverage increases the risk of undetected bugs. |
| Number of Files | `[Total Files]` | N/A | N/A | Provides context for the other metrics. |
| Number of Git Commits | `[Total Commits]` | N/A | N/A | Provides context for churn. |
**Status Legend:**
* **Good:** Metric is within acceptable range.
* **Warning:** Metric is approaching the threshold and may require investigation.
* **Critical:** Metric exceeds the threshold and requires immediate attention.
## Detailed Analysis
### 1. Code Complexity
This section analyzes the complexity of your code using Cyclomatic Complexity. Higher values indicate more complex code, which can be harder to understand, test, and maintain.
* **Files with Highest Complexity:**
| File Path | Cyclomatic Complexity |
|-----------------------------------|-----------------------|
| `[Path to File 1]` | `[Complexity Value]` |
| `[Path to File 2]` | `[Complexity Value]` |
| `[Path to File 3]` | `[Complexity Value]` |
**Recommendations:** Refactor these files to reduce complexity. Consider breaking down large functions into smaller, more manageable units. Use design patterns to simplify complex logic.
* **Average Complexity per Directory:**
| Directory | Average Complexity |
|-----------------------------------|-----------------------|
| `[Path to Directory 1]` | `[Average Value]` |
| `[Path to Directory 2]` | `[Average Value]` |
**Recommendations:** Identify directories with high average complexity and prioritize refactoring efforts within those areas.
### 2. Code Churn
This section analyzes the frequency of changes (churn) in your codebase. High churn can indicate areas of instability or frequent refactoring.
* **Files with Highest Churn:**
| File Path | Lines Changed (Total) | Number of Commits | Last Modified Date |
|-----------------------------------|-----------------------|-------------------|--------------------|
| `[Path to File 1]` | `[Lines Changed]` | `[Commit Count]` | `[Date]` |
| `[Path to File 2]` | `[Lines Changed]` | `[Commit Count]` | `[Date]` |
| `[Path to File 3]` | `[Lines Changed]` | `[Commit Count]` | `[Date]` |
**Recommendations:** Investigate files with high churn. Determine the reasons for frequent changes and consider refactoring or redesigning these areas. Look for patterns in the commits and identify potential root causes.
* **Areas with High Churn (Directories):**
| Directory | Lines Changed (Total) | Number of Commits |
|-----------------------------------|-----------------------|-------------------|
| `[Path to Directory 1]` | `[Lines Changed]` | `[Commit Count]` |
| `[Path to Directory 2]` | `[Lines Changed]` | `[Commit Count]` |
### 3. Test Coverage
This section analyzes the test coverage of your codebase. Low coverage increases the risk of undetected bugs.
* **Overall Test Coverage:** `[Coverage Percentage]`
* **Files with Low Coverage:**
| File Path | Coverage Percentage |
|-----------------------------------|-----------------------|
| `[Path to File 1]` | `[Coverage Value]` |
| `[Path to File 2]` | `[Coverage Value]` |
| `[Path to File 3]` | `[Coverage Value]` |
**Recommendations:** Write unit tests for files with low coverage. Focus on testing critical functionality and edge cases. Consider using code coverage tools to identify untested code paths.
* **Areas with Low Coverage (Directories):**
| Directory | Coverage Percentage |
|-----------------------------------|-----------------------|
| `[Path to Directory 1]` | `[Coverage Value]` |
| `[Path to Directory 2]` | `[Coverage Value]` |
### 4. Combined Analysis & Recommendations
Based on the combined analysis of complexity, churn, and coverage, the following areas require the most urgent attention:
* `[File/Directory Name]` - High complexity, high churn, and low coverage. Refactor and add tests.
* `[File/Directory Name]` - High complexity and low coverage. Refactor to reduce complexity, then add tests.
* `[File/Directory Name]` - High churn. Investigate the root cause of the frequent changes and consider redesign.
## Next Steps
1. Prioritize the areas identified in the "Combined Analysis & Recommendations" section.
2. Refactor complex code to improve readability and maintainability.
3. Write unit tests to increase test coverage and reduce the risk of bugs.
4. Investigate the reasons for high churn and address any underlying instability.
5. Run this report periodically to track progress and identify new areas for improvement.

161
skills/skill-adapter/assets/health_report_template.md Normal file
View File

@@ -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).
]`

28
skills/skill-adapter/assets/skill-schema.json Normal file
View File

@@ -0,0 +1,28 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Claude Skill Configuration",
"type": "object",
"required": ["name", "description"],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"maxLength": 64,
"description": "Skill identifier (lowercase, hyphens only)"
},
"description": {
"type": "string",
"maxLength": 1024,
"description": "What the skill does and when to use it"
},
"allowed-tools": {
"type": "string",
"description": "Comma-separated list of allowed tools"
},
"version": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+$",
"description": "Semantic version (x.y.z)"
}
}
}

27
skills/skill-adapter/assets/test-data.json Normal file
View File

@@ -0,0 +1,27 @@
{
"testCases": [
{
"name": "Basic activation test",
"input": "trigger phrase example",
"expected": {
"activated": true,
"toolsUsed": ["Read", "Grep"],
"success": true
}
},
{
"name": "Complex workflow test",
"input": "multi-step trigger example",
"expected": {
"activated": true,
"steps": 3,
"toolsUsed": ["Read", "Write", "Bash"],
"success": true
}
}
],
"fixtures": {
"sampleInput": "example data",
"expectedOutput": "processed result"
}
}