Metadata-Version: 2.4
Name: cytoscnpy
Version: 1.0.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: pytest ; extra == 'dev'
Provides-Extra: dev
License-File: License
Summary: High-performance dead code elimination analysis tool for Python (Rust implementation).
Author: djinn09
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/djinn09/cytoscnpy
Project-URL: Repository, https://github.com/djinn09/cytoscnpy
Project-URL: Bug Tracker, https://github.com/djinn09/cytoscnpy/issues

# CytoScnPy - High-Performance Python Static Analysis 🦀🐍

[![CI](https://github.com/djinn09/CytoScnPy/actions/workflows/rust-ci.yml/badge.svg)](https://github.com/djinn09/CytoScnPy/actions/workflows/rust-ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Version](https://img.shields.io/badge/version-1.0.0-green.svg)](https://github.com/djinn09/CytoScnPy)

A lightning-fast static analysis tool for Python codebases, powered by Rust with hybrid Python integration. Detects dead code, security vulnerabilities (including taint analysis), and code quality issues with extreme speed. Code quality metrics include cyclomatic complexity, Halstead metrics, maintainability index, nesting depth, and more.

## 🚀 Why CytoScnPy?

- **🔥 Blazing Fast**: Faster in dead code detection.
- **💾 Memory Efficient**: Uses less memory.
- **🐍 Python Native**: Installable via `pip`, importable in Python code
- **⚡ CLI Ready**: Standalone command-line tool with rich output
- **🔍 Comprehensive**: Dead code, secrets, security, taint analysis, quality metrics
- **🎯 Framework Aware**: Understands Flask, Django, FastAPI patterns
- **📊 Benchmarked**: Continuous benchmarking with 126-item ground truth suite

## 📦 Installation

```bash
# Install from PyPI (when published)
pip install cytoscnpy

# Or install from source
git clone https://github.com/djinn09/CytoScnPy.git
cd CytoScnPy
pip install maturin
maturin develop -m cytoscnpy/Cargo.toml
```

## 🛠️ Usage

### Command Line

```bash
# Basic usage
cytoscnpy [PATHS]... [OPTIONS]

# Examples:
cytoscnpy .                                     # Analyze current directory
cytoscnpy /path/to/project --json               # Output as JSON
cytoscnpy . --secrets --danger --quality        # Enable specific checks
cytoscnpy . --taint                             # Enable taint analysis

# Options:
#   -c, --confidence <CONFIDENCE>      Set confidence threshold (0-100)
#       --secrets                      Scan for secrets
#       --danger                       Scan for dangerous code patterns
#       --quality                      Scan for code quality issues
#       --taint                        Enable taint analysis
#       --json                         Output results as JSON
#       --include-tests                Include test files in analysis
#       --exclude-folders <FOLDERS>    Exclude specific folders
#       --include-folders <FOLDERS>    Force include specific folders
#       --include-ipynb                Include Jupyter notebooks
#       --ipynb-cells                  Report findings per cell
#   -h, --help                         Print help
#   -V, --version                      Print version

# Subcommands
# -----------------------------------------------------------------------
# Raw Metrics (LOC, SLOC, Comments)
cytoscnpy raw /path/to/project
cytoscnpy raw . --json --exclude-folder venv

# Cyclomatic Complexity (McCabe)
# Calculates complexity for each function/method
cytoscnpy cc .
cytoscnpy cc /path/to/file.py --json

# Halstead Metrics
# Calculates Difficulty, Effort, Volume, Bugs, Time
cytoscnpy hal .
cytoscnpy hal . --exclude-folder tests

# Maintainability Index
# Combined metric (0-100) indicating code maintainability
# < 65 = Hard to maintain
# > 85 = Easy to maintain
cytoscnpy mi .
cytoscnpy mi . --json

> **Note**: Average Complexity and Maintainability Index are automatically calculated and shown in the summary of the main `cytoscnpy .` command.
```

## ✨ Features

### Dead Code Detection

- **Unused functions, classes, methods** with cross-module tracking
- **Unused imports and variables** with scope-aware analysis
- **Entry point detection** (`if __name__ == "__main__"`) to prevent false positives
- **Dynamic pattern recognition** (`hasattr`, `getattr`, `globals()`)
- **Pragma support** (`# pragma: no cytoscnpy` to suppress findings)

### Security Analysis

CytoScnPy comes with built-in security features to keep your codebase safe:

- **Taint Analysis**: Tracks untrusted user input to prevent SQL Injection and XSS.
- **Secret Scanning**: Finds hardcoded API keys and credentials using high-entropy checks.
- **Dangerous Code**: Alerts you to unsafe usage of `eval()`, `pickle`, and `subprocess`.

> For deep technical details on how the security engine works, see [cytoscnpy/README.md](cytoscnpy/README.md#security-analysis).

### Code Quality Metrics

| Metric                    | Description                                           |
| ------------------------- | ----------------------------------------------------- |
| **Raw Metrics**           | LOC, LLOC, SLOC, Comments, Multi-line strings, Blanks |
| **Cyclomatic Complexity** | Control flow complexity (McCabe)                      |
| **Halstead Metrics**      | Difficulty, Effort, Volume, Bugs, Time                |
| **Maintainability Index** | Combined metric (0-100 scale)                         |
| **Nesting Depth**         | Maximum indentation level analysis                    |

### Framework Support

| Framework   | Detected Patterns                                         |
| ----------- | --------------------------------------------------------- |
| **Flask**   | `@app.route`, `request` object sources, `render_template` |
| **Django**  | `request` handling, ORM patterns, template rendering      |
| **FastAPI** | `@app.get/post/...`, `Request` parameter sources          |

### Smart Heuristics

- **Dataclass fields** automatically marked as used
- **Settings/Config classes** with uppercase variables ignored
- **Visitor pattern methods** (`visit_*`, `leave_*`, `transform_*`) marked as used
- **`__all__` exports** prevent flagging as unused
- **Base class tracking** for inheritance-aware analysis

### Configuration

Create `.cytoscnpy.toml` or add to `pyproject.toml`:

```toml
[tool.cytoscnpy]
# General Settings
confidence = 60  # Minimum confidence threshold (0-100)
exclude_folders = ["venv", ".tox", "build", "node_modules", ".git"]
include_folders = ["src", "tests"] # Optional: whitelist folders
include_tests = false

# Analysis Features
secrets = true
danger = true
quality = true

# Code Quality Thresholds
max_lines = 100       # Max lines per function
max_args = 5          # Max arguments per function
complexity = 10       # Max cyclomatic complexity
nesting = 4           # Max indentation depth
min_mi = 65.0         # Minimum Maintainability Index
ignore = ["R001"]     # Ignore specific rule IDs

# CI/CD Integration
fail_threshold = 5.0  # Exit with code 1 if unused code % exceeds this

# Advanced Secret Scanning
[tool.cytoscnpy.secrets_config]
entropy_enabled = true
entropy_threshold = 4.0  # Higher = more random (API keys usually > 4.0)
min_length = 16          # Min length to check for entropy
scan_comments = true     # Scan comments for secrets

# Custom Secret Patterns
[[tool.cytoscnpy.secrets_config.patterns]]
name = "Slack Token"
regex = "xox[baprs]-([0-9a-zA-Z]{10,48})"
severity = "HIGH"
```

#### Environment Variables

You can also configure CytoScnPy via environment variables (useful for CI/CD):

| Variable                   | Description                         |
| -------------------------- | ----------------------------------- |
| `CYTOSCNPY_FAIL_THRESHOLD` | Fail threshold % (overrides config) |

## 📊 Performance

### Speed Comparison

| Metric | CytoScnPy |
| ------ | --------- |
| Time   | **0.07s** |
| Memory | **~14MB** |

### Accuracy (Benchmark Suite: 126 items)

| Detection Type | Precision | Recall   | F1 Score |
| -------------- | --------- | -------- | -------- |
| Classes        | 0.75      | 0.82     | 0.78     |
| Functions      | 0.57      | 0.74     | 0.64     |
| Methods        | **1.00**  | 0.59     | 0.74     |
| Imports        | 0.50      | 0.37     | 0.42     |
| Variables      | 0.25      | 0.16     | 0.19     |
| **Overall**    | **0.61**  | **0.57** | **0.59** |

> See [benchmark/README.md](benchmark/README.md) for detailed comparison against Vulture, Flake8, Pylint, Ruff, and others.

## 🏗️ Architecture

See [cytoscnpy/README.md](cytoscnpy/README.md#architecture) for detailed architecture and technology stack information.

## 🧪 Testing

See [CONTRIBUTING.md](CONTRIBUTING.md#testing) for testing instructions.

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## 📝 License

Apache-2.0 License - see [License](License) file for details.

## 🔗 Links

- **Rust Core Documentation**: [cytoscnpy/README.md](cytoscnpy/README.md)
- **Benchmarks & Accuracy**: [BENCHMARK.md](benchmark/BENCHMARK.md)
- **Roadmap**: [ROADMAP.md](ROADMAP.md)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md)

## 📚 References

CytoScnPy's design and implementation in Rust are inspired by and reference the following Python libraries:

- [**Skylos**](https://github.com/duriantaco/skylos)
- [**Radon**](https://github.com/rubik/radon)

