mirror of
https://github.com/Dvorinka/Devour.git
synced 2026-06-03 20:13:03 +00:00
Tomas Dvorak
214 lines
6.8 KiB
Markdown
214 lines
6.8 KiB
Markdown
<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`).
|