Metadata-Version: 2.4
Name: qodacode
Version: 1.0.0
Summary: Hybrid code analysis tool with AI-powered explanations
Author: Nelson Padilla
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: code-analysis,linter,security,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.18
Requires-Dist: chromadb>=0.4
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.25
Requires-Dist: mcp>=1.0
Requires-Dist: numpy>=1.24
Requires-Dist: openai>=1.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: semgrep>=1.50
Requires-Dist: sentence-transformers>=2.2
Requires-Dist: textual>=0.40
Requires-Dist: tree-sitter-javascript>=0.21
Requires-Dist: tree-sitter-python>=0.21
Requires-Dist: tree-sitter-typescript>=0.21
Requires-Dist: tree-sitter>=0.21
Requires-Dist: watchdog>=3.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# Qodacode

**Enterprise Code Intelligence Scanner** - Hybrid security analysis with AI-powered explanations.

[![PyPI version](https://badge.fury.io/py/qodacode.svg)](https://badge.fury.io/py/qodacode)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## What is Qodacode?

Qodacode is a **hybrid code analysis tool** that combines:
- **Deterministic Detection Engine**: 4000+ security rules with zero false positives
- **AI Explanations**: Learn why issues matter with multi-provider AI support
- **Supply Chain Security**: Typosquatting and dependency attack detection

**Three interfaces, one engine**: CLI, TUI (interactive terminal), and MCP Server (for AI coding assistants).

## Quick Start

```bash
# Install
pip install qodacode

# Quick security scan
qodacode check

# Interactive terminal interface
qodacode

# Full security audit
qodacode audit
```

### macOS (Homebrew Python)

If you get permission errors with `pip`:

```bash
# Use pipx instead
pipx install qodacode

# Or use pip with --user flag
pip install --user qodacode
```

### Troubleshooting

**"command not found" after install:**
```bash
# Check where qodacode is installed
which qodacode

# If conflicts with old version in /opt/homebrew/bin/
rm /opt/homebrew/bin/qodacode
pipx install qodacode --force
```

**Python version error:**
Qodacode requires Python 3.10+. Check your version:
```bash
python3 --version
```

## Features

### Security Analysis
- **Secret Detection**: API keys, passwords, tokens, credentials
- **SAST**: SQL injection, XSS, command injection, path traversal
- **Syntax Validation**: Catch errors before runtime
- **Custom Rules**: Project-specific patterns

### Supply Chain Security
- **Typosquatting Detection**: Catches malicious package impersonators
- **Known Malware Database**: 30+ confirmed attack packages
- **Homoglyph Detection**: Unicode lookalike attacks
- **Keyboard Proximity Analysis**: Adjacent key typos

### AI-Powered Learning
- **Junior Mode**: Get explanations for every issue found
- **Multi-Provider**: OpenAI, Anthropic, Google Gemini, Grok
- **Batch Processing**: Efficient API usage

### False Positive Reduction
- **Semantic Context Analysis**: Auto-filters safe patterns like `os.environ`, `decrypt()`, test fixtures
- **Inline Ignore**: `# qodacode-ignore: SEC-001` to suppress specific lines
- **`.qodacodeignore`**: Gitignore-style exclusion patterns
- **Baseline Mode**: For legacy projects - only show NEW issues

## Interfaces

### CLI Commands

```bash
qodacode check              # Quick scan (syntax + secrets)
qodacode check --baseline   # Only show NEW issues (not in baseline)
qodacode audit              # Full security audit
qodacode typosquat          # Check dependencies for attacks
qodacode baseline save      # Save current issues as baseline
qodacode baseline show      # View baseline info
qodacode doctor             # Verify installation
```

### TUI (Interactive Terminal)

Launch with `qodacode` (no arguments):

```
/check      Quick scan
/audit      Full audit
/typosquat  Supply chain check
/ready      Production ready?
/mode       Toggle Junior/Senior mode
/api        Configure AI provider
/export     Save results
/help       Show commands
```

### MCP Server (AI Integration)

11 tools for AI coding assistants:

| Tool | Description |
|------|-------------|
| `quick_check` | Fast syntax + secrets scan |
| `full_audit` | Complete security analysis |
| `analyze_file` | Single file deep analysis |
| `check_dependencies` | Typosquatting detection |
| `get_issues` | Retrieve current issues |
| `explain_issue` | AI explanation for issue |
| `fix_issue` | Get fix suggestion |
| `get_project_status` | Overall project health |
| `configure_mode` | Set Junior/Senior mode |
| `list_rules` | Available detection rules |
| `search_patterns` | Search for code patterns |

## Production Verdict

Qodacode gives a clear answer: **Can I deploy this code?**

```
if critical_issues > 0:
    NOT READY - Fix N critical issues
else:
    READY FOR PRODUCTION (N warnings)
```

**Philosophy**: Only critical issues block deployment. High/Medium/Low are technical debt to track, not security blockers.

## Detection Engine

| Engine | Coverage |
|--------|----------|
| **Core Engine** | Syntax errors, custom patterns |
| **Secret Detection** | 50+ secret patterns (API keys, tokens, passwords) |
| **Deep SAST** | 4000+ security rules across languages |
| **Supply Chain** | Typosquatting, malware, homoglyphs |

## Architecture

Qodacode uses a hybrid architecture for performance and security:

```
┌─────────────────────────────────────────────────┐
│  Interfaces (Python)                            │
│  CLI, TUI, MCP Server, LSP                      │
├─────────────────────────────────────────────────┤
│  Orchestration Layer (Python)                   │
│  Multi-engine coordination, deduplication       │
├─────────────────────────────────────────────────┤
│  Core Algorithms (Rust - compiled)              │
│  Fingerprinting, similarity, pattern matching   │
├─────────────────────────────────────────────────┤
│  Detection Engines                              │
│  Semgrep, Gitleaks, Tree-sitter, OSV           │
└─────────────────────────────────────────────────┘
```

The Rust core module (`qodacode_core`) provides optimized algorithms:
- **Fingerprinting**: Stable issue IDs using BLAKE3
- **Similarity**: Levenshtein distance for typosquatting
- **Homoglyphs**: Unicode lookalike detection
- **Pattern Matching**: Aho-Corasick for safe pattern recognition

Falls back to pure Python when Rust extension is not available.

## Configuration

Configuration is stored in `.qodacode/config.json`:

```json
{
  "mode": "junior",
  "language": "en",
  "ai": {
    "api_key": "sk-...",
    "provider": "openai"
  }
}
```

### AI Provider Detection

API keys are auto-detected by prefix:

| Prefix | Provider |
|--------|----------|
| `sk-ant-*` | Anthropic (Claude) |
| `sk-*` | OpenAI (GPT) |
| `xai-*` | Grok (xAI) |
| `AIza*` | Google Gemini |

## Severity Levels

| Level | Meaning | Action |
|-------|---------|--------|
| **Critical** | Security vulnerability | Must fix before deploy |
| **High** | Significant issue | Should fix, doesn't block |
| **Medium** | Code quality concern | Review when possible |
| **Low** | Minor suggestion | Nice to have |

## Languages Supported

- Python
- JavaScript/TypeScript
- Go
- Java
- More coming...

## Why Qodacode?

| Feature | Qodacode | Traditional Linters |
|---------|----------|---------------------|
| Hybrid Analysis | Deterministic + AI | Rules only |
| Supply Chain | Typosquatting detection | No |
| AI Explanations | Multi-provider | No |
| Interactive TUI | Modern terminal UI | No |
| MCP Integration | AI assistant ready | No |

## Requirements

- Python 3.10 or higher
- pip (Python package manager)

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [CLI Documentation](CLI.md)
- [TUI Documentation](TUI.md)
- [MCP Server Documentation](mcp.md)
