farol
Static risk report for a pull request, after the review and before the merge
TLDR
SYNOPSIS
farol [options] command [options]
DESCRIPTION
farol is a static analysis CLI for pull requests in TypeScript and React, Go, and Python. analyze reads the diff between two refs and writes where the merge risk sits, so a reviewer can spend time on the riskiest files. It runs in shadow mode: the report is advisory and the merge stays a human decision. The project tree is not executed.The npm package is @winninjs/farol and the command is farol. It needs Node.js 22 or newer. A .farol.json marks a project. farol.config.json holds tool settings such as the Datadog window used by usage.
PARAMETERS
--config FILE
Config file. The default is farol.config.json, relative to --cwd.--cwd DIR
Project directory. When a .farol.json is found walking up from the working directory and --cwd is omitted, the project is that file's directory.--farol-file FILE
Use this .farol.json instead of the nearest one.--verbose
More log output.--cache-dir DIR
Analysis cache. The default is ~/.cache/farol, or the directory in this variable when it is set:
Ignore the analysis cache.
COMMANDS
analyze --base REF --head REF
Compare two refs and write a risk report. --base and --head are required. Optional: --coverage, --eslint, --out, --ignore (repeatable globs), --pr (a positive integer), --audit, --usage, --coverage-ignore, --since, --reviewers, --cache-dir, and --no-cache. The cache defaults to ~/.cache/farol.report --in FILE
Turn a saved analysis into a text report. --in is required. Optional: --repo, --pr, --report-url, --reviewers, --since-in, --since-report-url.html --in FILE
Write an HTML report. --in is required. Optional: --out, --repo, --pr, --reviewers.comment --in FILE --pr N
Post the report as a pull-request comment. --in and --pr are required. Optional: --repo, --report-url, --reviewers, --new, --since-in, --since-report-url. This command reads a GitHub token and the repository name from the environment:
List routes in the tree at an optional ref.impact [FILE] [--ref REF]
Show what depends on a file. The file is the argument, or the file named in .farol.json when the argument is omitted.calibrate --history DIR
Calibrate scores from one or more history directories (--history repeats). Optional --window is a number of days (default 14) and --out selects the output file.history --since DATE
Record history from a date. --since is required. Optional: --branch (default HEAD), --out (default farol-history), --ignore, --first-parent.reviewers --in FILE
Suggest reviewers from a saved analysis. --in is required. Optional --out.usage [--out FILE] [--days N]
Pull usage data. --days defaults to the Datadog setting in config, or 14. Set both of these:
CAVEATS
analyze requires both --base and --head. comment needs a GitHub token and GITHUB_REPOSITORY (owner/name). usage needs a Datadog API key and application key. Ignore patterns are globs; pass each one as its own --ignore argument. A positive --pr is the only accepted pull-request number.
HISTORY
farol is published by Winnin. It is written in TypeScript and licensed under MIT.
