jevgrep 0.2.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 MINT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+<div align="center">
+
+# jgrep
+
+**grep for what code *does*, not what it's called.**
+
+```
+jgrep "catches an error and silently ignores it" src/
+```
+
+[![npm](https://img.shields.io/npm/v/jevgrep?color=0a0&label=npm)](https://www.npmjs.com/package/jevgrep)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](package.json)
+[![model](https://img.shields.io/badge/powered%20by-Jev%20%C2%B7%20TypeSafe-8a2be2)](https://docs.typesafe.ai)
+
+*No index. No embeddings. No LLM round-trips. A whole `src/` tree in ~2 s for about a cent.*
+
+</div>
+
+---
+
+```
+$ jgrep "catches an error and silently ignores it" src/
+
+src/loop/state.ts:108-115   p=0.96  export function readRun(projectDir: string): RunInfo | null {
+src/loop/stop.ts:20-28      p=0.93  function groupAlive(pgid: number): boolean {
+src/nl/config-store.ts:33-46 p=0.93  export async function loadProviderConfig(): Promise<...> {
+...
+79 hits / 896 chunks (0 cached) · 240406 tokens · $0.0101 · 1.8s
+```
+
+## Why
+
+| you want to find…                          | `grep` / `rg` | embeddings | an LLM | **jgrep** |
+| ------------------------------------------ | :-----------: | :--------: | :----: | :-------: |
+| an exact name or string                    | ✅ instant     | meh        | 🐢 $$  | use grep  |
+| "code that swallows errors"                | ❌             | ❌ fuzzy    | ✅ slow | ✅ **2 s** |
+| "endpoint with no auth check" *in my diff* | ❌             | ❌          | ✅ $$   | ✅ **¢**   |
+| needs an index / vector DB                 | no            | yes        | no     | **no**    |
+
+jgrep runs on [Jev](https://docs.typesafe.ai), a *System One* model: it never
+generates text, it answers typed yes/no questions with calibrated
+probabilities, in parallel, at $0.042 per million input tokens with output free.
+jgrep packs 16 code chunks and 16 questions into one request and turns the
+probabilities into `file:line` hits.
+
+## Install
+
+```bash
+npm i -g jevgrep     # installs the `jgrep` command
+jgrep init           # paste your TypeSafe key, pick where to keep it, done
+```
+
+`jgrep init` verifies the key against the API, stores it with `chmod 600`,
+and optionally teaches Claude Code / Codex to use jgrep. Get a key at
+[console.typesafe.ai](https://console.typesafe.ai).
+
+<details>
+<summary>Prefer not to run init?</summary>
+
+```bash
+export TYPESAFE_API_KEY=...                                   # env
+echo 'TYPESAFE_API_KEY=...' >> .env                           # per project
+mkdir -p ~/.config/jgrep && echo 'TYPESAFE_API_KEY=...' > ~/.config/jgrep/env   # global
+```
+</details>
+
+## Use
+
+### Find code by behavior
+
+```bash
+jgrep "reads user input without validating it" app/
+jgrep -C "parses a JWT or decodes a base64 token payload" src/     # -C prints the chunk
+jgrep -t 0.9 "builds an SQL string by concatenation" .            # stricter
+jgrep -a -t 0 "is dead code nothing calls" lib/ | head            # everything, best first
+```
+
+### Lint a change with rules written in English
+
+```bash
+jgrep --diff --staged "leaves debug output such as console.log"
+jgrep --diff origin/main "adds an HTTP endpoint that has no auth check"
+jgrep --diff origin/main "changes billing logic without touching a test"
+```
+
+Exit status is grep's (`0` matched, `1` nothing, `2` error), so CI negates it:
+
+```yaml
+- run: npm i -g jevgrep
+- run: '! jgrep --diff origin/${{ github.base_ref }} "adds an HTTP endpoint that has no auth check"'
+  env: { TYPESAFE_API_KEY: "${{ secrets.TYPESAFE_API_KEY }}" }
+```
+
+### Feed your coding agent
+
+Agents burn most of their tokens *looking* for code. jgrep hands them a short
+list of ranges instead of whole files. On a 115 KB module the agent read
+6 KB of matching chunks instead of everything.
+
+```bash
+jgrep init                   # tick "Claude Code" / "Codex" to install the skill
+jgrep --json "spawns a child process" src/ | jq '.[].file'
+```
+
+The skill also has the agent run a few `--diff --staged` rules on its own
+change before committing: a second model checking the first one's work, for
+a fraction of a cent.
+
+## All options
+
+```
+jgrep init                               interactive setup
+jgrep [options] "<description>" [path ...]
+jgrep [options] --diff [ref] "<description>"
+
+  -t, --threshold <p>   print chunks with probability >= p (default 0.7)
+  -C, --show            print the matching chunk body under each hit
+  -a, --all             print every chunk with its probability, best first
+      --json            machine-readable output
+      --diff [ref]      grep git diff hunks (working tree, or against <ref>)
+      --staged          with --diff: staged changes only
+  -b, --batch <n>       chunks per request (default 16)
+  -c, --concurrency <n> parallel requests (default 16)
+      --no-cache        ignore and do not write ~/.cache/jgrep
+```
+
+## How it works
+
+1. **Files** come from `git ls-files` (untracked included, ignored excluded),
+   or a directory walk. Binaries and files over 1 MB are skipped.
+2. **Chunks**: each file is split at column-0 line starts into 5 to 60 line
+   pieces. With `--diff`, each hunk is a chunk and keeps its `+`/`-` markers.
+3. **One request, 16 chunks, 16 questions**: `state.chunks[]` plus a Noul
+   question per chunk, *"look only at chunk c3, does it match: …"*.
+4. **Threshold**: probabilities at or above `-t` are printed in file order.
+   Answers are cached by `(model, question, chunk)` in `~/.cache/jgrep/`, so
+   the same query again is free and instant.
+
+| repo                         | chunks | time  | cost    |
+| ---------------------------- | -----: | ----: | ------: |
+| TypeScript CLI, `src/`       |    896 | 1.8 s | $0.010  |
+| same query again (cache)     |    896 | 0.0 s | $0      |
+| one module, `app/lib/`       |    521 | 1.6 s | $0.006  |
+
+## Tips
+
+- Write the description in **English** and describe the **code**, not the
+  feature: *"decides whether to alert based on OCR confidence"* beats
+  *"alert feature"*. Jev's accuracy is lower on non-English text.
+- One behavior per query. Split compound questions and combine in your head
+  (or in a script with `--json`).
+- Chunks are judged in isolation, so cross-file flow ("does this eventually
+  hit the DB") will not match. Ask about the local code.
+- `p >= 0.9` is reliable, `0.7-0.9` is worth a look.
+
+## Develop
+
+```bash
+bun test src/     # unit tests, no network
+bun run build     # dist/jgrep.js, plain node, deps bundled
+```
+
+If jgrep saved you a file-hunting session, a ⭐ on GitHub is the best thanks.
+
+MIT