freview 🔎

One command. Five reviews. Bundled Scribe. Zero mystery meat before push.

freview is the tiny pre-push review harness we use to keep JavaScript/TypeScript projects from faceplanting on main. It runs the local Fallow + Scribe review stack, writes a durable REVIEW.md, and only prints the full report when something actually needs attention.

It is intentionally boring. Boring is how code ships.

What it runs

freview builds one review report from:

Health — project health + complexity review
Audit — risky implementation patterns and maintainability issues
Dead code — unused files, exports, and stale surface area
Duplication — copy/paste debt before it metastasizes
Docstrings — public surface documentation via scribe

Output lands in REVIEW.md at the repo root.

Install

mkdir -p ~/bin
curl -fsSL https://raw.githubusercontent.com/HurleyUS/freview/main/bin/freview -o ~/bin/freview
curl -fsSL https://raw.githubusercontent.com/HurleyUS/freview/main/bin/scribe -o ~/bin/scribe
chmod +x ~/bin/freview ~/bin/scribe

Or clone it:

git clone git@github.com:HurleyUS/freview.git
ln -sf "$PWD/freview/bin/freview" ~/bin/freview
ln -sf "$PWD/freview/bin/scribe" ~/bin/scribe

Package install

This repo ships both binaries:

bunx github:HurleyUS/freview --help
# or from a checkout
bun link

Package bins:

freview — orchestrates Fallow + bundled Scribe into REVIEW.md
scribe — docstring coverage auditor used by freview

Usage

freview
freview --root ~/Projects/uncap.us
freview --summary --explain
freview --ci

Flags

| Flag | Purpose | | --- | --- | | -r, --root <path> | Review another project root | | -f, --format <format> | Forward output format to Fallow/Scribe | | -q, --quiet | Reduce command chatter | | --summary | Request summary output from underlying tools | | --explain | Include explanatory findings | | --ci | SARIF-oriented CI mode, quiet + fail-on-issues | | --fail-on-issues | Return non-zero when findings exist |

Pre-push hook

Drop this in scripts/hooks/pre-push and symlink/copy it into .git/hooks/pre-push:

#!/usr/bin/env bash
set -euo pipefail

protected_ref='refs/heads/(main|master)$'

while read -r local_ref _local_sha remote_ref _remote_sha; do
  if [[ "$local_ref" =~ $protected_ref || "$remote_ref" =~ $protected_ref ]]; then
    exec "$HOME/bin/freview"
  fi
done

Recommended setup:

mkdir -p scripts/hooks .git/hooks
cp scripts/hooks/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-push

Requirements

macOS/Linux shell with zsh
Bun
fallow available through bunx --bun fallow

scribe is bundled in this package and invoked from bin/scribe, so installs do not depend on Michael's local ~/bin/scribe.

freview will run fallow init --quiet and fallow setup-hooks --quiet before reviewing so the target project has the expected local Fallow scaffolding.

Why this exists

Pushing to protected branches should hurt a little when the code is sketchy and be silent when the code is clean. freview gives us that: a shareable REVIEW.md, CI-friendly failure modes, and one command the whole team can wire into hooks.

License

MIT — ship it, fork it, make it yell at your own bad code.