Metadata-Version: 2.4
Name: lucidshark
Version: 0.5.16
Summary: LucidShark - The trust layer for AI-assisted development
Author-email: Voldeq GmbH <toni.antunovic@voldeq.com>
License: Apache-2.0
Keywords: security,scanner,devsecops,sast,sca,iac,container,vulnerability,trivy,semgrep,checkov,cli,mcp,ai,claude,cursor,linting,type-checking,testing,coverage,duplication,code-clone
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
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 :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: pathspec>=0.12.0
Requires-Dist: questionary>=2.0
Requires-Dist: Jinja2>=3.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pyright>=1.1; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Dynamic: license-file

# LucidShark

<p align="center">
  <img src="docs/lucidshark.png" alt="LucidShark" width="400">
</p>

[![CI](https://github.com/lucidshark-code/lucidshark/actions/workflows/ci.yml/badge.svg)](https://github.com/lucidshark-code/lucidshark/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/lucidshark-code/lucidshark/graph/badge.svg)](https://codecov.io/gh/lucidshark-code/lucidshark)
[![PyPI version](https://img.shields.io/pypi/v/lucidshark)](https://pypi.org/project/lucidshark/)
[![Python](https://img.shields.io/pypi/pyversions/lucidshark)](https://pypi.org/project/lucidshark/)
[![License](https://img.shields.io/github/license/lucidshark-code/lucidshark)](https://github.com/lucidshark-code/lucidshark/blob/main/LICENSE)

**Unified code quality pipeline for AI-assisted development.**

```
AI writes code → LucidShark checks → AI fixes → repeat
```

## Why LucidShark

- **Local-first** - No server, no SaaS account. Runs on your machine and in CI with the same results.

- **Configuration-as-code** - `lucidshark.yml` lives in your repo. Same rules for everyone, changes go through code review.

- **AI-native** - MCP integration with Claude Code and Cursor. Structured feedback that AI agents can act on directly.

- **Unified pipeline** - Linting, type checking, security (SAST/SCA/IaC), tests, and coverage in one tool. Stop configuring 5+ separate tools.

- **Open source & extensible** - Apache 2.0 licensed. Add your own tools via the plugin system.

## Quick Start

```bash
# 1. Install LucidShark
pip install lucidshark

# 2. Set up your AI tools (Claude Code and/or Cursor)
lucidshark init --all

# 3. Restart your AI tool, then ask it:
#    "Autoconfigure LucidShark for this project"
```

That's it! Your AI assistant will analyze your codebase, ask you a few questions, and generate the `lucidshark.yml` configuration.

### Alternative: CLI Configuration

If you prefer to configure without AI:

```bash
lucidshark autoconfigure
```

### Running Scans

```bash
# Run the full quality pipeline
lucidshark scan --all

# Run specific checks
lucidshark scan --linting           # Linting (Ruff, ESLint, Biome)
lucidshark scan --type-checking     # Type checking (mypy, pyright, tsc)
lucidshark scan --sast              # Security code analysis (OpenGrep)
lucidshark scan --sca               # Dependency vulnerabilities (Trivy)
lucidshark scan --iac               # Infrastructure-as-Code (Checkov)
lucidshark scan --container         # Container image scanning (Trivy)
lucidshark scan --testing           # Run tests (pytest, Jest)
lucidshark scan --coverage          # Coverage analysis

# Auto-fix linting issues
lucidshark scan --linting --fix
```

### AI Tool Setup

#### Claude Code

```bash
lucidshark init --claude-code
```

This:
- Adds LucidShark to your Claude Code MCP configuration (`.mcp.json`)
- Creates `.claude/CLAUDE.md` with scan workflow instructions

Restart Claude Code to activate.

#### Cursor

```bash
lucidshark init --cursor
```

This:
- Adds LucidShark to Cursor's MCP configuration (`~/.cursor/mcp.json`)
- Creates `.cursor/rules/lucidshark.mdc` with auto-scan rules

#### All AI Tools

```bash
lucidshark init --all
```

Configures both Claude Code and Cursor.

## What It Checks

| Domain | Tools | What It Catches |
|--------|-------|-----------------|
| **Linting** | Ruff, ESLint, Biome, Checkstyle | Style issues, code smells |
| **Type Checking** | mypy, pyright, TypeScript | Type errors |
| **Security (SAST)** | OpenGrep | Code vulnerabilities |
| **Security (SCA)** | Trivy | Dependency vulnerabilities |
| **Security (IaC)** | Checkov | Infrastructure misconfigurations |
| **Security (Container)** | Trivy | Container image vulnerabilities |
| **Testing** | pytest, Jest, Karma (Angular), Playwright (E2E) | Test failures |
| **Coverage** | coverage.py, Istanbul | Coverage gaps |

All results are normalized to a common format.

## Configuration

LucidShark auto-detects your project. For custom settings, create `lucidshark.yml`:

```yaml
version: 1

pipeline:
  linting:
    enabled: true
    tools:
      - name: ruff

  type_checking:
    enabled: true
    tools:
      - name: mypy
        strict: true

  security:
    enabled: true
    tools:
      - name: trivy
      - name: opengrep

  testing:
    enabled: true
    tools:
      - name: pytest

  coverage:
    enabled: true
    threshold: 80

fail_on:
  linting: error
  security: high
  testing: any

ignore:
  - "**/node_modules/**"
  - "**/.venv/**"
```

## CLI Reference

```bash
# Configure AI tools (Claude Code, Cursor)
lucidshark init --claude-code             # Configure Claude Code
lucidshark init --cursor                  # Configure Cursor
lucidshark init --all                     # Configure all AI tools

# Auto-configure project (detect languages, generate lucidshark.yml)
lucidshark autoconfigure [--ci github|gitlab|bitbucket] [--non-interactive]

# Run quality pipeline
lucidshark scan [--linting] [--type-checking] [--sca] [--sast] [--iac] [--container] [--testing] [--coverage] [--all]
lucidshark scan [--fix] [--stream] [--format table|json|sarif|summary]
lucidshark scan [--fail-on critical|high|medium|low]

# Server mode
lucidshark serve --mcp                    # Run MCP server
lucidshark serve --watch                  # Watch mode with auto-checking

# Show status
lucidshark status [--tools]
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All checks passed |
| 1 | Issues found above threshold |
| 2 | Tool execution error |
| 3 | Configuration error |

## Development

```bash
git clone https://github.com/lucidshark-code/lucidshark.git
cd lucidshark
pip install -e ".[dev]"
pytest tests/
```

## Documentation

- [LLM Reference Documentation](docs/help.md) - For AI agents and detailed reference
- [Full Specification](docs/main.md)
- [Roadmap](docs/roadmap.md)

## License

Apache 2.0
