Documentation

harvest-scan docs

Scan your code for security risks and quality issues with a suite of composable plugins, get a single 0–100 score and letter grade, with actionable file-and-line feedback. Runs locally, in CI, and in your editor.

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 banner

Subcommands: baseline, doctor, outdated, and plugin list|enable|disable|create.

Scan modes

ModeFlagPlugins
Fast-fcritical, heuristic, eslint
Default(none)+ complexity, dockerfile
Complete-call 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.sarif

Baseline (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.

Full source, issues, and releases live on GitHub.