Contributing to JevX

JevX is small and moves fast. Short pull requests with a test are the easiest to merge.

The repo

JevX lives at github.com/vij-sameerb5/JevX: a TypeScript pnpm monorepo, MIT-licensed. Issues and pull requests are welcome there.

Set up (5 minutes)

git clone https://github.com/vij-sameerb5/JevX.git && cd JevX
pnpm install          # Node ≥ 20.10, pnpm ≥ 9
pnpm test             # ~230 tests · no network, no keys
pnpm jevx --help      # the CLI from source
pnpm mcp-smoke examples/jev-demo   # the MCP server, end to end

The tests never call a real API. tests/mock-xai.ts and tests/mock-typesafe.ts stand in for xAI and TypeSafe, and tests/mock-engine.ts holds the AI's answers for the demo repo.

Where things live

Folder	What
`apps/jevx`	The `jevx` CLI and MCP server: what ships to npm
`packages/engine`	The pipeline: read → assess → scorecard → edit → apply → share
`packages/gemini`	AI transports (xAI, OpenRouter) and the adaptive context loop
`packages/analyzer` · `scanner` · `core`	Local indexing, static candidates, secret scrubbing
`tests/`	vitest, with mocks for every external service
`examples/jev-demo`	A tiny helpdesk repo every end-to-end test runs on
`supabase/`	The anonymous-outcomes dataset (insert-only SQL)
`site/`	This website
`packages/boundary` · `apps/cli`	Frozen research. Please don't build on them

Rules we keep

No API key, ever, in code, config, tests or fixtures. Keys come from the environment.
No user code leaves the machine, except to the user's own AI. Anything shared must be generic, with a test proving names are scrubbed.
Safety lives in the tool: the old rule as fallback, tests before/after with auto-revert, never touching files with uncommitted changes, jevx undo.
Prompts are versioned: bump ENGINE_PROMPT_VERSION when you change one.
Plain English in everything a user reads. Short.

A good PR

One change, with a test. pnpm test, pnpm typecheck and pnpm lint green.
A prompt or pattern change: add the case to tests/mock-engine.ts or a unit test, and say which real repo you tried it on.
An entry under "Unreleased" in apps/jevx/CHANGELOG.md.
Before a release, maintainers run bash scripts/release-check.sh. It packs, installs into a clean folder, and smoke-tests the CLI and MCP server.

Good first issues

Detect more test runners in checksFor (vitest, jest, Bun).
A jevx --only <folder> filter.
More examples in examples/: a moderation app, a search-ranking app.
Nicer diffs in .jevx/report.html.
Real terminal recordings for this site (site/recordings/*.tape, made with VHS).

Bugs & security

For a bug, include jevx --version, the command, and ideally jevx --dry-run --report-json out.json plus the relevant .jevx/debug/*.json. Check them for anything private first.

Found a way JevX could leak code or keys? Please use GitHub's private vulnerability reporting (Security → Report a vulnerability) instead of a public issue.