ari/cqas
1
0
Fork 0
Code Issues Pull requests Projects Releases 4 Packages Wiki Activity Actions
cqas/doc/md/overview.md
Arija A. 32fa0c3bf1
 Remove pointless CLI flags 
They are outadted and were used in the original iteration of the tool in
private for code-switching between modes, until I relised that I could
simply treat everything as a project.

Signed-off-by: Arija A. <ari@ari.lt>
2025-09-21 00:50:47 +03:00

456 lines
14 KiB
Markdown
Raw Permalink Blame History

# CQaS Overview
CQaS (Code Quality And Security) is a comprehensive Python static analysis tool designed to evaluate and improve the quality, security, and maintainability of Python codebases. Built with an educational focus and extensible architecture, CQaS provides developers with actionable insights into their code quality through multiple analysis dimensions.
## Project Purpose
CQaS was originally developed for educational purposes as part of a maturity/graduation work project in cybersecurity questioning the balance between security and code quality in real-life settings. The tool addresses the critical need for:
- **Code Quality Assessment**: Comprehensive evaluation of Python code following industry standards
- **Security Vulnerability Detection**: Static analysis to identify potential security issues
- **Technical Debt Management**: Quantification and tracking of code maintainability
- **Developer Education**: Clear reporting and recommendations for code improvement
## Key Features
- **Multi-dimensional Analysis**: Quality, security, maintainability, complexity, and technical debt
- **File and Project-level Scans**: Flexible analysis scope from individual files to entire projects
- **Comprehensive Metrics**: Many different code quality and security metrics
- **Smart Reporting**: Colour-coded output with actionable recommendations
- **Complexity Analysis**: Cyclomatic and cognitive complexity measurement
- **Readability Assessment**: Code style, naming conventions, and documentation quality
- **Maintainability Index**: IEEE-based maintainability scoring
- **Technical Debt**: Quantified debt ratio and estimated remediation time
- **Halstead Metrics**: Software complexity measurement through operator/operand analysis
- **Vulnerability Detection**: 8 categories of security issues with CVSS scoring
- **Risk Assessment**: Severity-based classification (LOW, MEDIUM, HIGH, CRITICAL)
- **Pattern Matching**: Static analysis for common security anti-patterns
- **Best Practice Validation**: Security coding standard compliance
- **Dead Code Detection**: Identification of unused functions, classes, and imports
- **Duplication Analysis**: Cross-file and within-file code duplication measurement
- **Import Analysis**: Dependency tracking and circular import detection
- **PEP8 Compliance**: Python style guide adherence checking
## Architecture Overview
CQaS follows a modular, extensible architecture built around the Abstract Syntax Tree visitor pattern:
```
CQaS Architecture
├── Core Engine
│ ├── Base Analyser (Abstract)
│ └── File/Project Analysis Orchestration
├── Analysis Modules
│ ├── Complexity Analyser
│ ├── Security Analyser
│ ├── Dead Code Analyser
│ ├── Duplication Analyser
│ ├── Readability Analyser
│ ├── Halstead Analyser
│ ├── Import Analyser
│ └── PEP8 Analyser
├── Data Structures
│ ├── Analysis Results
│ ├── Metrics Classes
│ └── Issue Classifications
└── Reporting Engine
├── Console Output
├── JSON Export
└── Recommendation Generation
```
## Analysis Capabilities
### Individual File Analysis
CQaS can analyze single Python files, providing:
- Complete quality metrics assessment
- Security vulnerability identification
- Code complexity evaluation
- Style and readability scoring
- Technical debt estimation
### Project-level Analysis
For entire projects, CQaS offers:
- Cross-file duplication detection
- Project-wide statistics aggregation
- File ranking by quality/security scores
- Comprehensive project health reports
- Technical debt portfolio analysis
## Quick Start
### Installation
```bash
# For users (basic functionality)
pip install --user --upgrade cqas
# For coloured output
pip install --user --upgrade cqas[colour]
# For development
pip install --upgrade -e .
```
### Basic Usage
```bash
# Analyze a single file
cqas myfile.py
# Analyze a directory with progress tracking
cqas src/ --verbose
# Full project analysis with recommendations
cqas . --feedback --colour
# JSON output to file
cqas . --json --output report.json
```
### Example Output
### Single File
```
================================================================================
PYTHON CODE QUALITY & SECURITY ANALYSIS REPORT
================================================================================
COMPLEXITY HOTSPOTS ANALYSIS
------------------------------------------------------------
Top 1 Complexity Hotspots:
----------------------------------------
FUNCTION 'main' in __main__.py:167 - Complexity: 21
FILES REQUIRING IMMEDIATE ATTENTION
------------------------------------------------------------
File: __main__.py (Issue Score: 21.0)
Quality: 71.0/100 | Security: 100.0/100 | Maintainability: Poor
Complexity: 26 | Lines: 284 | Tech Debt: 18.0%
Issues: Dead Code: 6 | Style: 7
TECHNICAL DEBT ANALYSIS
------------------------------------------------------------
Total Estimated Debt: 0.9 hours
Average Debt Ratio: 18.0%
Files with Highest Technical Debt:
----------------------------------------
__main__.py: 0.9h (Ratio: 18.0%)
COMPREHENSIVE PROJECT STATISTICS
------------------------------------------------------------
File Analysis:
Files Found: 1
Files Analysed: 1
Files with Errors: 0
Analysis Duration: 0.05 seconds
Code Structure:
Total Lines: 284
Logical Lines: 220
Functions: 4
Classes: 0
Average Quality Metrics:
Cyclomatic Complexity: 26.0
Maintainability Index: 32.4/100
Readability Score: 86.8/100
Code Duplication: 2.4%
Issue Summary:
Security Issues: 0
Style Issues: 7
Dead Code Items: 6
Project Duplication Analysis:
Duplicate Blocks: 0
Duplicated Lines (est.): 0
Total Code Lines: 0
Duplication Percentage: 0.0%
QUALITY DISTRIBUTION ANALYSIS
------------------------------------------------------------
Quality Score Distribution:
Excellent (90-100): 0 files
Good (75-89): 0 files
Fair (60-74): 1 files
Poor (40-59): 0 files
Critical (0-39): 0 files
Complexity Distribution:
Simple (≤10): 0 files
Moderate (11-20): 0 files
Complex (21-50): 1 files
Very Complex (>50): 0 files
Maintainability Distribution:
Excellent (≥85): 0 files
Good (70-84): 0 files
Fair (55-69): 0 files
Poor (25-54): 1 files
Legacy (<25): 0 files
AVERAGE METRICS
----------------------------------------
Cyclomatic Complexity: 26.0
Maintainability Index: 32.4/100
Technical Debt Ratio: 18.0%
Code Duplication: 2.4%
Readability Score: 86.8/100
Code Quality Index: 71.0/100
VERDICTS
----------------------------------------
Overall: Very Good: High-quality, secure codebase ready for production
Quality: Good: Generally well-written with room for improvement
Security: Excellent: Outstanding security posture
Maintainability: Poor: Maintenance challenges present
Complexity: Poor: High complexity, refactoring recommended
EXECUTIVE SUMMARY
----------------------------------------
Files Analysed: 1
Total Lines of Code: 284
Overall Quality Index: 70.99/100
Overall Security Score: 100.0/100
Security Issues Found: 0 (0 high/critical)
================================================================================
Analysis completed in 0.05s. Report generated by the CQaS analyser v1.0.0
================================================================================
```
### Whole Project
```
Found 26 Python files to analyse
Analysing (1/26) [3.8%]: ./__init__.py
Analysing (2/26) [7.7%]: ./__main__.py
Analysing (3/26) [11.5%]: ./_colours.py
Analysing (4/26) [15.4%]: ./_reporter.py
Analysing (5/26) [19.2%]: ./analysers/__init__.py
Analysing (6/26) [23.1%]: ./analysers/base.py
Analysing (7/26) [26.9%]: ./analysers/complexity.py
Analysing (8/26) [30.8%]: ./analysers/dead_code.py
Analysing (9/26) [34.6%]: ./analysers/duplication.py
Analysing (10/26) [38.5%]: ./analysers/full.py
Analysing (11/26) [42.3%]: ./analysers/halstead.py
Analysing (12/26) [46.2%]: ./analysers/imports.py
Analysing (13/26) [50.0%]: ./analysers/pep8.py
Analysing (14/26) [53.8%]: ./analysers/readability.py
Analysing (15/26) [57.7%]: ./analysers/security.py
Analysing (16/26) [61.5%]: ./constructs/__init__.py
Analysing (17/26) [65.4%]: ./constructs/classification.py
Analysing (18/26) [69.2%]: ./constructs/complexity.py
Analysing (19/26) [73.1%]: ./constructs/dead_code.py
Analysing (20/26) [76.9%]: ./constructs/duplication.py
Analysing (21/26) [80.8%]: ./constructs/full.py
Analysing (22/26) [84.6%]: ./constructs/halstead.py
Analysing (23/26) [88.5%]: ./constructs/imports.py
Analysing (24/26) [92.3%]: ./constructs/pep8.py
Analysing (25/26) [96.2%]: ./constructs/readability.py
Analysing (26/26) [100.0%]: ./constructs/security.py
Generating report for 26 files...
================================================================================
PYTHON CODE QUALITY & SECURITY ANALYSIS REPORT
================================================================================
COMPLEXITY HOTSPOTS ANALYSIS
------------------------------------------------------------
Top 6 Complexity Hotspots:
----------------------------------------
FUNCTION '_get_number_colour' in _reporter.py:54 - Complexity: 33
FUNCTION 'main' in __main__.py:167 - Complexity: 21
FUNCTION 'find_dead_code' in dead_code.py:166 - Complexity: 17
FUNCTION '_find_python_files' in full.py:499 - Complexity: 12
FUNCTION 'calculate_project_statistics' in full.py:581 - Complexity: 11
CLASS 'CQaSReporter' in _reporter.py:21 - 22 methods
FILES REQUIRING IMMEDIATE ATTENTION
------------------------------------------------------------
File: _reporter.py (Issue Score: 82.0)
Quality: 50.1/100 | Security: 100.0/100 | Maintainability: Legacy
Complexity: 105 | Lines: 1014 | Tech Debt: 32.9%
Issues: Dead Code: 8 | Style: 56
File: complexity.py (Issue Score: 45.0)
Quality: 80.4/100 | Security: 100.0/100 | Maintainability: Poor
Complexity: 5 | Lines: 206 | Tech Debt: 3.3%
Issues: Dead Code: 16 | Style: 13
File: dead_code.py (Issue Score: 43.0)
Quality: 50.0/100 | Security: 100.0/100 | Maintainability: Poor
Complexity: 34 | Lines: 253 | Tech Debt: 40.6%
Issues: Dead Code: 13 | Style: 10 | Duplication: 22.0%
File: halstead.py (Issue Score: 38.0)
Quality: 68.9/100 | Security: 100.0/100 | Maintainability: Poor
Complexity: 6 | Lines: 124 | Tech Debt: 19.9%
Issues: Dead Code: 13 | Style: 9 | Duplication: 16.0%
File: full.py (Issue Score: 32.0)
Quality: 53.5/100 | Security: 100.0/100 | Maintainability: Legacy
Complexity: 80 | Lines: 694 | Tech Debt: 30.9%
Issues: Dead Code: 12
File: readability.py (Issue Score: 27.0)
Quality: 69.4/100 | Security: 100.0/100 | Maintainability: Poor
Complexity: 26 | Lines: 201 | Tech Debt: 19.1%
Issues: Dead Code: 9 | Style: 7 | Duplication: 3.3%
File: pep8.py (Issue Score: 25.0)
Quality: 64.9/100 | Security: 100.0/100 | Maintainability: Poor
Complexity: 30 | Lines: 245 | Tech Debt: 23.2%
Issues: Dead Code: 7 | Style: 7 | Duplication: 5.1%
File: full.py (Issue Score: 25.0)
Quality: 78.8/100 | Security: 100.0/100 | Maintainability: Poor
Complexity: 14 | Lines: 248 | Tech Debt: 8.4%
Issues: Dead Code: 12
File: __main__.py (Issue Score: 21.0)
Quality: 71.0/100 | Security: 100.0/100 | Maintainability: Poor
Complexity: 26 | Lines: 284 | Tech Debt: 18.0%
Issues: Dead Code: 6 | Style: 7
File: __init__.py (Issue Score: 18.0)
Quality: 91.1/100 | Security: 100.0/100 | Maintainability: Good
Complexity: 1 | Lines: 21 | Tech Debt: 0.6%
Issues: Dead Code: 9
TECHNICAL DEBT ANALYSIS
------------------------------------------------------------
Total Estimated Debt: 18.1 hours
Average Debt Ratio: 10.4%
Files with Highest Technical Debt:
----------------------------------------
_reporter.py: 4.2h (Ratio: 32.9%)
full.py: 2.9h (Ratio: 30.9%)
dead_code.py: 2.4h (Ratio: 40.6%)
imports.py: 1.9h (Ratio: 31.5%)
pep8.py: 1.2h (Ratio: 23.2%)
halstead.py: 1.1h (Ratio: 19.9%)
readability.py: 1.0h (Ratio: 19.1%)
__main__.py: 0.9h (Ratio: 18.0%)
security.py: 0.9h (Ratio: 16.9%)
duplication.py: 0.6h (Ratio: 13.8%)
COMPREHENSIVE PROJECT STATISTICS
------------------------------------------------------------
File Analysis:
Files Found: 26
Files Analysed: 26
Files with Errors: 0
Analysis Duration: 0.88 seconds
Code Structure:
Total Lines: 4,364
Logical Lines: 3,531
Functions: 143
Classes: 35
Average Quality Metrics:
Cyclomatic Complexity: 15.9
Maintainability Index: 50.6/100
Readability Score: 80.0/100
Code Duplication: 3.0%
Issue Summary:
Security Issues: 0
Style Issues: 115
Dead Code Items: 150
Project Duplication Analysis:
Duplicate Blocks: 21
Duplicated Lines (est.): 70
Total Code Lines: 3,408
Duplication Percentage: 2.1%
QUALITY DISTRIBUTION ANALYSIS
------------------------------------------------------------
Quality Score Distribution:
Excellent (90-100): 8 files
Good (75-89): 8 files
Fair (60-74): 6 files
Poor (40-59): 4 files
Critical (0-39): 0 files
Complexity Distribution:
Simple (≤10): 16 files
Moderate (11-20): 2 files
Complex (21-50): 6 files
Very Complex (>50): 2 files
Maintainability Distribution:
Excellent (≥85): 1 files
Good (70-84): 7 files
Fair (55-69): 5 files
Poor (25-54): 11 files
Legacy (<25): 2 files
ACTIONABLE RECOMMENDATIONS
------------------------------------------------------------
1. [MEDIUM] High Complexity Code
2 files have very high complexity (>50).
Action: Refactor complex functions into smaller, focused methods. Consider applying SOLID principles.
AVERAGE METRICS
----------------------------------------
Cyclomatic Complexity: 15.9
Maintainability Index: 50.6/100
Technical Debt Ratio: 10.4%
Code Duplication: 3.0%
Readability Score: 80.0/100
Code Quality Index: 79.0/100
VERDICTS
----------------------------------------
Overall: Very Good: High-quality, secure codebase ready for production
Quality: Good: Generally well-written with room for improvement
Security: Excellent: Outstanding security posture
Maintainability: Poor: Maintenance challenges present
Complexity: Acceptable: Higher complexity, consider refactoring
EXECUTIVE SUMMARY
----------------------------------------
Files Analysed: 26
Total Lines of Code: 4,364
Overall Quality Index: 78.98/100
Overall Security Score: 100.0/100
Security Issues Found: 0 (0 high/critical)
================================================================================
Analysis completed in 0.88s. Report generated by the CQaS analyser v1.0.0
================================================================================
```
Reference in a new issue View git blame Copy permalink