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

14 KiB
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

# 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

# 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
================================================================================