Devour

<p align="center">
  <img src="devour_logo.svg" alt="Devour Logo" width="220">
</p>

<h1 align="center">Devour</h1>
<p align="center">Feed your AI real docs so it stops repeating the same mistakes.</p>

Code quality and review workflows are powered by [`peteromallet/desloppify`](https://github.com/peteromallet/desloppify), integrated behind Devour commands.

## Code Health Scorecard
<img src="scorecard.png" width="100%">

## Why Devour exists
I built Devour because AI tools kept drifting away from official docs, then repeating wrong patterns in later prompts.

Devour fixes that loop with a local-first workflow:
1. scrape official docs,
2. keep them in your project,
3. search and ask against that local corpus,
4. sync updates when sources change.

## What works today
- `devour init` creates a complete local workspace
- `devour scrape` supports URL, language-specific docs, local files, GitHub repos, OpenAPI specs, and `--sources`
- `devour get` supports language/framework shortcuts (now including Next.js, Svelte, Angular, Remix, SolidJS, Express)
- `devour query` is now functional (local lexical index)
- `devour ask` is hybrid local-first with live fallback when local relevance is weak
- `devour sync` updates configured sources and reindexes
- `devour status` reports real local health/statistics
- `devour push <path>` imports local docs into the workspace and reindexes
- `devour serve` local mode runs JSON-RPC over stdio (`devour_query`, `devour_status`, `devour_scrape`, `devour_ask`, `devour_sync`)
- `devour auto` routes natural-language intent to the right command
- `devour verify smoke` runs opt-in live checks and writes reports

## Experimental
- `devour serve --remote` is available as an experimental HTTP RPC mode
- remote push workflows are intentionally not enabled as stable behavior yet

## Quick start
### 1) Build
```bash
go mod download
go build -o devour ./cmd/devour
```

### 2) Initialize
```bash
./devour init
```

### 3) Get docs fast
```bash
./devour get go net/http --format markdown
./devour get nextjs routing
./devour get express middleware
```

### 4) Search locally
```bash
./devour query "json unmarshal"
```

### 5) Ask a docs-grounded question
```bash
./devour ask --lang go "how to parse json" --format text
```

### 6) Let Devour route intent automatically
```bash
./devour auto "how to use useEffect in react"
./devour auto "https://pkg.go.dev/net/http"
```

## Core commands
| Command | Purpose |
| --- | --- |
| `devour init [path]` | Create config + local storage directories |
| `devour get <language> <keyword>` | Shortcut fetch from curated official docs |
| `devour scrape <source>` | Scrape one source directly |
| `devour scrape --sources sources.yaml` | Scrape multiple configured sources |
| `devour query <text>` | Search local indexed docs |
| `devour ask --lang <lang> <question>` | Structured answer using local-first + live fallback |
| `devour sync` | Sync configured sources and rebuild index |
| `devour status` | Show docs/index/source health |
| `devour push <path>` | Import local docs into workspace |
| `devour serve` | Start local stdio JSON-RPC server |
| `devour auto "<intent>"` | Auto-route intent to command |
| `devour verify smoke` | Live smoke verification report |
| `devour quality ...` | Thin passthrough to `desloppify` |
| `devour review ...` | Holistic subjective review workflow via `desloppify review` |
| `devour scorecard` | Generate `desloppify` badge output via scan |

## Quality Prerequisite
Install `desloppify` before running `devour quality` / `devour review` / `devour scorecard`:

```bash
pip install --upgrade "desloppify[full]"
```

### AI Setup Prompt (Copy/Paste)

```text
Install or update desloppify, then scan this codebase for code quality issues
(dead code, duplication, complexity, smells). It tracks findings persistently
across sessions and reports a health score.

Requires Python 3.11+. Install from PyPI:
pip install --upgrade desloppify
# Recommended for deepest coverage (tree-sitter + Python security adapter):
pip install --upgrade "desloppify[full]"
desloppify update-skill codex    # pick yours: claude, cursor, codex, copilot, windsurf, gemini

Use Devour wrappers (delegates to desloppify):
devour quality scan --path .
devour quality status
devour quality next

Direct equivalent commands:
desloppify scan --path .
desloppify status
desloppify next

--path is the directory to scan (use "." for the whole project, or "src/" etc).
Language is auto-detected. To override: desloppify --lang python scan --path .
(note: --lang goes BEFORE the subcommand)

Fix what it finds, then:
desloppify resolve fixed <id> --note "what changed" --attest "I have actually [DESCRIBE THE CONCRETE CHANGE YOU MADE] and I am not gaming the score by resolving without fixing."

For false positives:
desloppify resolve wontfix <id> --note "reason" --attest "I have actually verified this is intentional/false-positive and I am not gaming the score by resolving without fixing."

If subjective scores feel stale or inflated:
desloppify scan --path . --reset-subjective

Because state persists, run regularly (for example before each push).
If anything seems wrong/confusing in desloppify itself, capture a repro and ask
whether to log an upstream issue.

If you need to debug desloppify internals:
git clone https://github.com/peteromallet/desloppify.git /tmp/desloppify
```

## Supported `get` / `ask` languages and frameworks
- Go (`go`, `golang`)
- Rust (`rust`)
- Python (`python`, `py`)
- Java (`java`)
- Spring (`spring`)
- TypeScript (`typescript`, `ts`)
- React (`react`)
- Vue (`vue`)
- Nuxt (`nuxt`)
- Docker (`docker`)
- Cloudflare (`cloudflare`, `cf`)
- Astro (`astro`)
- C# (`csharp`, `cs`)
- Kotlin (`kotlin`, `kt`)
- PHP (`php`)
- Ruby (`ruby`, `rb`)
- Elixir (`elixir`, `ex`)
- Next.js (`next`, `nextjs`)
- Svelte (`svelte`)
- Angular (`angular`, `ng`)
- Remix (`remix`)
- Solid (`solid`, `solidjs`) via `github.com/solidjs/solid-docs`
- Express (`express`, `expressjs`)

Run `devour languages` for examples, or `devour languages --format json` for automation.

## Config
Devour reads `devour.yaml` (or `--config`).

New additive sections:
- `indexing`: local lexical index defaults
- `verification`: live smoke timeout defaults

Starter config: `devour.example.yaml`.

## Real-world verification
Run live smoke checks (opt-in):
```bash
./devour verify smoke
```

Reports are saved to `devour_data/verify/smoke-<timestamp>.json`.

## JSON-RPC local server
`devour serve` (local mode) accepts JSON-RPC 2.0 methods:
- `devour_query`
- `devour_status`
- `devour_scrape`
- `devour_ask`
- `devour_sync`

## Development
### Test
```bash
go test ./...
```

### Typical integration loop
```bash
./devour init
./devour scrape https://pkg.go.dev/net/http --type godocs
./devour query "http client"
./devour ask --lang go "timeout example"
./devour sync
./devour status
```

## License
MIT (`LICENSE`).