cqas/README.md

Code Quality And Security (cqas)

Python Code Quality and Security (CQaS) tester

CQaS (Code Quality And Security) is a Python CLI tool intended to scan and report on the quality, security, maintainability, and technical debt potential of Python codebases and files. It helps developers, teams, and pipelines make their Python projects have high standards for code quality as well as reduce risk caused by bugs, vulnerabilities, and unmaintainable code.

This tool is meant primarily for educational purposes. I made this to be used in my maturity/graduation work.

Installation

• For users: pip install --user --upgrade cqas (for coloured output: pip install --user --upgrade cqas[colour])
• For development: pip install --upgrade -e . (or .[colour])

Documentation

All the documentation can be found in the source code repository.

Usage

usage: cqas [-h] [--json] [--output OUTPUT] [--colour] [--no-colour]
            [--top-n TOP_N] [--max-files MAX_FILES]
            [--min-severity {LOW,MEDIUM,HIGH,CRITICAL}] [--feedback]
            [--verbose] [--quiet]
            path

Code Quality and Security Analyser (CQaS)

positional arguments:
  path                  Python file or directory to analyse

options:
  -h, --help            show this help message and exit

Output Options:
  --json, -j            Output results in JSON format
  --output, -o OUTPUT   Output file to save results
  --colour, --color, -c
                        Enable coloured output (default: enabled)
  --no-colour, --no-color, -C
                        Disable coloured output
  --top-n, -n TOP_N     Top N statistics

Analysis Options:
  --max-files, -m MAX_FILES
                        Maximum number of files to analyse (default: 1000)
  --min-severity, -s {LOW,MEDIUM,HIGH,CRITICAL}
                        Minimum security issue severity to include (default:
                        LOW)

Reporting Options:
  --feedback, -f        Generate actionable recommendations and feedback
  --verbose, -v         Verbose output with progress tracking
  --quiet, -q           Suppress progress messages

Examples:
  cqas myfile.py                       # Analyse single file
  cqas src/ -v                         # Analyse directory with progress
  cqas . --json --output report.json   # JSON output to file
  cqas project/ -p --colour            # Project analysis with colours
  cqas app.py -s HIGH -v               # High severity issues only
  cqas . -p -f --max-files 500         # Full analysis with recommendations

Features

• Individual and Project-level scans: Allows users to select and scan either whole projects or individual files.
• Comprehensive Code Quality Metrics: Measures cyclomatic and cognitive complexity, Halstead metrics, maintainability index, readability scores, PEP8 compliance, and technical debt estimations.
• Security Vulnerability Detection: Detects security issues with severity counts, combining static analysis methods.
• Dead Code Identification: Finds potential dead code segments to improve code health.
• Duplication Detection: Analyses source duplication within and across files and calculates duplication percentages.
• Import Analysis: Reports on standard library, third-party, local, and circular imports for dependency insights.
• Complexity Hotspots: Identifies and ranks functions and classes with high cyclomatic complexity.
• Files Requiring Attention: Highlights files with high issue scores, showing breakdown by quality, security, maintainability, complexity, technical debt, and issue counts.
• Technical Debt Analysis: Estimates total technical debt in hours and average debt ratios, providing focused file debt breakdowns.
• Quality, Complexity, and Maintainability Distributions: Aggregated quality scores, complexity levels, and maintainability categories with clear distributions.
• Actionable Recommendations: Suggests practical next steps to improve code quality based on analysis results.
• Colourful Console Reporting: Uses contextual colour coding for scores, counts, ratios, and categories for enhanced readability.
• Efficient and Scalable: Limits analysis to a configurable number of files and supports progress indication during scanning.
• Extensible Architecture: Modular analysers for extensibility and independent evolution of complexity, security, duplication, and style modules.