Metadata-Version: 2.4
Name: qodacode
Version: 0.1.0
Summary: Hybrid code analysis tool with AI-powered explanations
Author: Qodacode Team
License: MIT
Keywords: code-analysis,linter,security,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: 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: 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

**Mejores prácticas enforced automáticamente con memoria persistente del proyecto.**

## Qué es

Qodacode es una herramienta híbrida que combina:
- **Motor nativo (determinístico)**: Detecta issues en el código usando análisis estático
- **IA (Claude)**: Interpreta los resultados y explica al dev dónde está la causa

No compite con Claude Code. Lo complementa.

## Por qué existe Qodacode

### Limitaciones de Claude Code que Qodacode resuelve

| Claude Code puede... | Pero no puede... | Qodacode resuelve |
|---------------------|------------------|-------------------|
| Detectar issues cuando se lo pides | Hacerlo siempre automáticamente | Watch mode continuo |
| Leer archivos que le indicas | Conocer TODO el repo siempre | Memoria persistente |
| Encontrar problemas en el momento | Recordar mañana qué revisó | Historial de análisis |
| Analizar archivos individuales | Detectar conflictos cross-file | Contexto completo |
| Reaccionar a pedidos | Ser proactivo | Alertas automáticas |

### Lo que Claude Code hace bien (y no reemplazamos)
- Generar código rápido
- Resolver problemas
- Iterar features
- Explicar código

### Lo que Qodacode agrega
- Verificación continua automática
- Memoria persistente del proyecto
- Detección cross-file
- Mejores prácticas enforced sin pedirlo

## Para quién es

| Segmento | Dolor que resuelve |
|----------|-------------------|
| Vibe coders con IA | "¿Mi código generado está bien?" |
| Devs tradicionales | "¿Mi código cumple mejores prácticas?" |
| Equipos mixtos | "¿El código del equipo es consistente?" |
| Freelancers | "¿Puedo entregar esto a un cliente enterprise?" |

**Funciona igual para código generado por IA o código escrito manualmente. El origen no importa.**

## El problema

```
Escribes código (con IA o manual)
         ↓
Funciona en local
         ↓
¿Está listo para producción? ← No hay respuesta clara
         ↓
Rezas y deployeas
```

## La solución

```
Motor nativo detecta issues (determinístico, sin alucinaciones)
         ↓
Produce resultado estructurado (JSON)
         ↓
IA interpreta con contexto completo del proyecto
         ↓
Dev recibe explicación clara de qué y dónde arreglar
```

## Qué detecta

### Seguridad
- Secrets en código
- SQL/Command injection
- XSS
- Endpoints sin auth
- CVEs en dependencias

### Robustez
- Sin error handling en llamadas externas
- Sin timeouts
- Sin retry logic
- Race conditions

### Mantenibilidad
- Duplicación entre archivos
- Funciones >200 líneas
- Imports circulares
- Dead code

### Operabilidad
- Sin logging en flujos críticos
- Config hardcodeada
- Sin health checks
- Dockerfile mal configurado

## Comandos CLI

```bash
qodacode init      # Indexa el repo (memoria persistente)
qodacode watch     # Monitoreo continuo (background)
qodacode check     # Check on-demand
qodacode status    # Estado actual
qodacode doctor    # Verificar engines instalados
```

## Instalación

```bash
pip install qodacode
```

### Engines Opcionales

Qodacode tiene un motor nativo (Tree-sitter) que siempre funciona. Para análisis más profundo, puedes instalar engines opcionales:

| Engine | Comando | Función |
|--------|---------|---------|
| Semgrep | `pip install semgrep` | SAST profundo (--deep) |
| Gitleaks | `brew install gitleaks` | Detección de secretos (--secrets) |
| OSV | (API, requiere internet) | CVEs en dependencias (--deps) |

Verifica qué tienes instalado con:
```bash
qodacode doctor
```

### Uso en CI/CD

Para pipelines automatizados, usa `--skip-missing` para evitar prompts interactivos:

```bash
qodacode check --all --skip-missing
```

## Arquitectura

```
┌─────────────────────────────────────────────────────────┐
│                      QODACODE                           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  PARSING                                                │
│  └─ Tree-sitter (multi-lenguaje, AST)                  │
│                                                         │
│  DETECCIÓN (Motor Nativo)                               │
│  └─ Reglas determinísticas                              │
│  └─ Análisis estático                                   │
│  └─ Output estructurado (JSON)                          │
│                                                         │
│  MEMORIA PERSISTENTE                                    │
│  └─ Embeddings offline (nomic-embed)                   │
│  └─ Vector DB local (Chroma en .qodacode/)             │
│  └─ Contexto cross-file                                 │
│                                                         │
│  INTEGRACIÓN IA                                         │
│  └─ MCP Server para Claude Code                         │
│  └─ Recibe issues + contexto                            │
│  └─ Explica al dev en lenguaje natural                  │
│                                                         │
│  ✓ 100% local, nada sale de tu máquina                 │
│  ✓ IA opcional, solo para explicar                      │
└─────────────────────────────────────────────────────────┘
```

## Flujo híbrido

```
[Motor nativo detecta]
{
  "file": "src/api/payments.py",
  "line": 142,
  "rule": "no-rate-limit",
  "severity": "critical"
}

[IA responde al dev]
"Tu endpoint de pagos en payments.py:142 no tiene
rate limiting. Como este archivo maneja transacciones
y está expuesto públicamente (vi en routes.py:23),
un atacante podría hacer requests masivos. Agrega
rate limiting antes del handler."
```

## Diferenciadores

| Característica | Qodacode | Linters tradicionales |
|----------------|----------|----------------------|
| Memoria persistente | ✓ Conoce todo el repo | ✗ Olvida entre corridas |
| Contexto cross-file | ✓ Detecta relaciones | ✗ Archivo por archivo |
| Explicación contextual | ✓ IA explica el por qué | ✗ Solo muestra el error |
| Solo issues críticos | ✓ Lo que importa | ✗ 500 warnings genéricos |
| 100% local | ✓ Nada sale | Varía |

## Stack técnico

- **Lenguaje**: Python
- **Parsing**: Tree-sitter (multi-lenguaje)
- **Embeddings**: nomic-embed (offline)
- **Vector DB**: Chroma (local, en `.qodacode/`)
- **Integración IA**: MCP Server para Claude Code

## Lenguajes soportados

- **MVP**: Python + TypeScript/JavaScript
- **v1.0**: Go, Rust, Java

## Integraciones

- CLI
- VSCode/Cursor extension
- MCP Server (Claude Code)
- GitHub Actions (gate para PRs)
- Pre-commit hook

## Estructura del proyecto

```
qodacode/
├── qodacode/
│   ├── __init__.py
│   ├── cli.py           # Comandos: init, check, watch, status, why
│   ├── scanner.py       # Parsea código con tree-sitter
│   ├── rules/           # Reglas de detección
│   │   ├── __init__.py
│   │   ├── security.py  # Secrets, injection, XSS
│   │   ├── robustness.py # Error handling, timeouts
│   │   ├── maintainability.py # Duplicación, funciones largas
│   │   └── operability.py # Logging, health checks
│   ├── memory/          # Embeddings + vector DB
│   │   ├── __init__.py
│   │   ├── indexer.py   # Indexa el repo
│   │   └── store.py     # Chroma vector store
│   ├── reporter.py      # Output estructurado
│   └── mcp/             # MCP Server para Claude
│       ├── __init__.py
│       └── server.py
├── tests/
├── pyproject.toml
└── README.md
```

## Output ejemplo

```
$ qodacode check

ISSUES DETECTADOS (3)

CRÍTICO src/api/payments.py:142
  Regla: no-rate-limit
  → Endpoint público sin rate limiting

CRÍTICO src/config/settings.py:23
  Regla: hardcoded-secret
  → Secret hardcodeado: DATABASE_URL

ALTO src/services/user.py:89
  Regla: unsanitized-input
  → Input no sanitizado en query SQL

───────────────────────────
Usa 'qodacode why <file>' para explicación detallada con IA
```

## Roadmap

| Fase | Qué |
|------|-----|
| MVP | CLI + 15-20 reglas críticas + memoria básica |
| v0.2 | Watch mode + más reglas |
| v0.3 | MCP Server (integración Claude Code) |
| v0.4 | VSCode/Cursor extension |
| v1.0 | Multi-lenguaje completo + CI/CD gates |

## Open Source a estudiar (no copiar, extraer patrones)

El desarrollo se acelera estudiando estos proyectos para entender arquitecturas y patrones:

### Análisis Estático (Detección)

| Proyecto | Qué estudiar | URL |
|----------|--------------|-----|
| Semgrep | Cómo estructurar reglas YAML, motor de pattern matching | https://github.com/semgrep/semgrep |
| Bandit | Checks de seguridad para Python | https://github.com/PyCQA/bandit |
| Ruff | Velocidad extrema en análisis, arquitectura Rust | https://github.com/astral-sh/ruff |
| Tree-sitter | Parsing multi-lenguaje, AST | https://github.com/tree-sitter/tree-sitter |

### Memoria / RAG para Código

| Proyecto | Qué estudiar | URL |
|----------|--------------|-----|
| Code-Graph-RAG | Indexación de código + knowledge graphs | https://github.com/vitali87/code-graph-rag |
| Code Knowledge MCP | Patrón de MCP Server con memoria | https://glama.ai/mcp/servers/@davidvc/code-knowledge-mcptool |
| Mem0 | Memoria persistente para IA | https://github.com/mem0ai/mem0 |
| RAGFlow | Motor RAG open source | https://github.com/infiniflow/ragflow |

### Embeddings (Offline)

| Modelo | Qué estudiar | URL |
|--------|--------------|-----|
| nomic-embed | Embeddings offline, ligero, local | https://huggingface.co/nomic-ai/nomic-embed-text-v1.5 |
| Qwen3-Embedding | Soporte código, Apache 2.0 | https://huggingface.co/Qwen |
| E5 models | Alta precisión, rápido | https://huggingface.co/intfloat |

### Vector DB

| Proyecto | Qué estudiar | URL |
|----------|--------------|-----|
| Chroma | Vector DB embebido, Python native | https://github.com/chroma-core/chroma |
| FAISS | Vector search de Facebook, performance | https://github.com/facebookresearch/faiss |
| LanceDB | Embebido, rápido | https://github.com/lancedb/lancedb |

### Enfoque

```
Open source = Estudiar cómo lo hicieron
                    ↓
            Extraer patrones y arquitectura
                    ↓
            Crear código propio de Qodacode
                    ↓
            Producto original, desarrollo acelerado
```

**No copiamos código. Aprendemos arquitecturas y creamos el nuestro.**

## Principios

1. **Detección nativa, explicación con IA** - Lo mejor de ambos mundos
2. **Solo issues que importan** - No 500 warnings, solo lo crítico
3. **Memoria persistente** - Conoce todo el proyecto, siempre
4. **100% local** - Privacidad total, nada sale de tu máquina
5. **Parte del workflow** - No un paso extra, siempre presente

## Por qué no muere en meses

Los productos que sobreviven resuelven **dolor diario**. Qodacode:

1. **Se integra donde vive el dev** - Cursor, VSCode, Claude Code, terminal
2. **No es un paso extra** - Watch mode corre en background
3. **Siempre relevante** - Mientras escribas código, Qodacode es útil
4. **No requiere configuración constante** - Init una vez, funciona siempre

```
El dev nunca piensa en Qodacode.
Qodacode siempre está pensando en el código del dev.
```

## Modelo de negocio

### Gratis (siempre)
- CLI completo
- Todas las reglas de detección
- Memoria persistente local
- Uso ilimitado

### Pro ($19/mes)
- Watch mode continuo
- Integración CI/CD
- Análisis automático de PRs
- Soporte prioritario

### Team ($49/mes por dev)
- Reglas custom compartidas
- Dashboard de equipo
- Métricas históricas
- Onboarding dedicado

## Competencia y diferenciación

| Herramienta | Debilidad | Qodacode gana porque |
|-------------|-----------|---------------------|
| SonarQube | Pesado, cloud, caro | 100% local, ligero, freemium |
| Semgrep | Solo SAST, sin memoria | Memoria persistente + contexto |
| Snyk | Solo seguridad, cloud | Mejores prácticas completas + local |
| Bandit | Solo Python, básico | Multi-lenguaje + explicación IA |
| Linters | 500 warnings, sin contexto | Solo lo crítico + cross-file |

**Nadie combina**: Análisis estático + memoria persistente + explicación con IA + 100% local.

## Flujo de trabajo diario

```
Mañana:
  └─ Abres Cursor
  └─ Qodacode ya indexó cambios nocturnos (watch)
  └─ Ves: "2 issues nuevos desde ayer"

Mientras codeas:
  └─ Escribes código
  └─ Qodacode detecta issue en background
  └─ Notificación: "src/api.py:45 - sin error handling"
  └─ Arreglas en el momento

Antes de commit:
  └─ Pre-commit hook corre qodacode check
  └─ Si hay críticos, bloquea commit
  └─ Arreglas y commiteas limpio

En PR:
  └─ GitHub Action corre qodacode
  └─ Comenta issues en el PR
  └─ Gate: no merge si hay críticos
```

---

**Qodacode**: Mejores prácticas enforced. Siempre. Automático. Sin pensarlo.
