Metadata-Version: 2.4
Name: codefossil
Version: 0.1.0
Summary: Production-ready CLI to detect stale npm dependencies, score risk, and provide migration guidance.
Author: CodeFossil Maintainers
License: MIT
Project-URL: Homepage, https://github.com/example/codefossil
Project-URL: Repository, https://github.com/example/codefossil
Project-URL: Issues, https://github.com/example/codefossil/issues
Keywords: cli,security,dependencies,npm,devtools,supply-chain
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: ai
Requires-Dist: openai>=1.0.0; extra == "ai"
Requires-Dist: anthropic>=0.34.0; extra == "ai"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: black>=24.8.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Dynamic: license-file

# CodeFossil

[![CI](https://github.com/example/codefossil/actions/workflows/ci.yml/badge.svg)](https://github.com/example/codefossil/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/codefossil.svg)](https://pypi.org/project/codefossil/)

CodeFossil is a production-ready Python CLI that scans JavaScript projects for stale npm dependencies, assigns risk scores, and optionally adds AI migration guidance for the highest-risk packages.

## What it does

- Scans npm `dependencies` and (optionally) `devDependencies`
- Queries registry metadata to estimate dependency freshness
- Assigns a deterministic risk score based on update age
- Supports rich terminal table output plus machine-friendly JSON and Markdown reports
- Supports incremental analysis via local cache (`.codefossil_cache.json`)
- Optionally enriches top-risk dependencies with AI advice (`openai`, `anthropic`, `groq`)

## Installation

### Standard install

```bash
pip install .
```

### Editable install for development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
```

## Usage

### Basic scan

```bash
codefossil scan .
```

### Common flags

- `--format table|json|markdown`
- `--output <file>`
- `--min-risk <int>`
- `--include-dev`
- `--incremental`
- `--ai-provider openai|anthropic|groq`
- `--api-key <key>`
- `--ai-top <int>`

### Examples

```bash
# JSON output
codefossil scan . --format json

# Markdown report with filtering
codefossil scan . --format markdown --output report.md --include-dev --min-risk 50

# Incremental analysis
codefossil scan . --incremental

# AI advice for top 5 risky dependencies
codefossil scan . --ai-provider openai --api-key sk-xxx --ai-top 5 --format markdown
```

## AI feature (optional)

When `--ai-provider` and `--api-key` are supplied, CodeFossil asks the provider for migration guidance for the top `--ai-top` risky dependencies. If provider calls fail, scanning continues and warnings are emitted.

No API keys are persisted to disk.

## Output schema

Each dependency result includes:

- `name`
- `version`
- `last_update_years`
- `risk_score`
- `risk_label` (`HIGH`, `MEDIUM`, `LOW`)
- `ai_advice` (optional)

## Risk scoring model

- `>= 5` years: `90`
- `>= 3` years: `70`
- `>= 2` years: `50`
- `>= 1` year: `30`
- `< 1` year: `10`

## Development

```bash
pip install -e .[dev]
pytest
ruff check .
black --check .
mypy codefossil
```

A sample manifest is available at `examples/package.sample.json` for manual testing.
