Getting started
Requires Node.js 18+. Try it instantly with no install:
npx harvest-scan . # or install globally (command: harvest) npm install -g harvest-scan harvest .
Exit codes: 0 clean/acceptable, 1 needs attention, 2 failing/critical, 3 unexpected error.
CLI reference
harvest [options] [target]
-f, --fast fast scan: critical + heuristics + ESLint
-c, --complete complete scan: every plugin
-d, --default balanced default (when no mode is given)
--fix apply safe ESLint autofixes before scanning
-j, --json machine-readable JSON
--sarif SARIF 2.1.0 (GitHub Code Scanning)
-o, --output <f> write the report to a file
-i, --incremental scan only files changed vs git HEAD
-p, --plugin <n> run a single plugin
--baseline only fail on issues not in the saved baseline
--no-banner hide the ASCII bannerSubcommands: baseline, doctor, outdated, and plugin list|enable|disable|create.
Scan modes
| Mode | Flag | Plugins |
|---|---|---|
| Fast | -f | critical, heuristic, eslint |
| Default | (none) | + complexity, dockerfile |
| Complete | -c | all 10 plugins |
Output formats
Human (default), JSON (--json), and SARIF 2.1.0 (--sarif) which loads directly into GitHub Code Scanning.
{
"target": "src/",
"mode": "complete",
"score": 87,
"rating": "good",
"exitCode": 0,
"counts": { "total": 4, "error": 0, "warning": 4, "info": 0, "critical": 0 },
"issues": [ /* { pluginName, filePath, line, column, severity, message } */ ],
"durationMs": 210
}GitHub Action
name: Harvest
on: [push, pull_request]
permissions:
contents: read
security-events: write
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: Aditya060806/Harvest@v1
with:
target: '.'
mode: 'complete'
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: harvest.sarifBaseline (ratchet) mode
Adopt on an existing codebase without drowning in the current backlog — fail CI only on new issues.
harvest baseline . # writes .harvest/baseline.json harvest . --baseline # known issues ignored; only new issues fail
Programmatic API
import { scan, fix } from 'harvest-scan';
await fix('src/'); // optional autofix pass
const result = await scan('src/', { mode: 'complete' });
console.log(`${result.score}/100 (${result.rating})`);
for (const issue of result.issues) {
console.log(`${issue.filePath}:${issue.line} ${issue.message}`);
}Writing a plugin
A plugin extends Plugin with a static applies() and async run(). It is auto-discovered — no registration.
// plugins/no-console.js
import { Plugin } from '../src/plugin-interface.js';
export class NoConsolePlugin extends Plugin {
static pluginName = 'no-console';
static applies(file) { return file.endsWith('.js'); }
async run(file, { content }) {
return content.split('\n').flatMap((line, i) =>
line.includes('console.log')
? [{ pluginName: 'no-console', filePath: file, line: i + 1, column: 0, severity: 'info', message: 'console.log left in code' }]
: []
);
}
}harvest plugin create no-console harvest plugin list
Configuration
Optional. Create harvest.config.js to tune weights, thresholds, and enabled plugins.
// harvest.config.js
export default {
weights: { eslint: 2, xray: 8, osv: 10 },
thresholds: { complexity: 12 },
plugins: { semgrep: { enabled: false } },
};FAQ
Does it send my code anywhere?
No. Fast and default modes run fully offline. In complete mode, osv sends only dependency names/versions to the public OSV.dev API.
Which languages?
JS/TS get the deepest coverage; critical, heuristic, ai, and semgrep span many languages; dockerfile covers container images.
How do I adopt it on a large legacy repo?
Use baseline mode — record today's issues once, then only new ones fail CI.