fallow 2.69.0 → 2.71.1

package/skills/fallow/references/gotchas.md

@@ -23,7 +23,7 @@ Always preview with `--dry-run` before applying. This is a destructive operation
 
 ## Don't Create Config Unless Needed
 
-Fallow works with zero configuration for most projects thanks to 90 auto-detecting framework plugins. Creating an unnecessary config file can mask issues or override detection behavior.
+Fallow works with zero configuration for most projects thanks to 94 auto-detecting framework plugins. Creating an unnecessary config file can mask issues or override detection behavior.
 
 ```bash
 # WRONG: creating config for a standard Next.js project
@@ -429,6 +429,26 @@ Fallow marks `static/style.css` and `static/app.js` as reachable. Root-relative
 
 ---
 
+## GraphQL `#import` Documents Are Tracked
+
+GraphQL `.graphql` and `.gql` files can keep nearby fragment documents reachable with relative `#import` comments. Fallow tracks `./` and `../` specifiers, including extensionless imports that resolve through `.graphql` and `.gql`; package-style specifiers are ignored.
+
+```graphql
+# src/query.graphql
+
+#import "./fragments/user-fields"
+
+query CurrentUser {
+  currentUser {
+    ...UserFields
+  }
+}
+```
+
+Fallow marks `src/fragments/user-fields.graphql` or `src/fragments/user-fields.gql` as reachable when either file exists. A typo in the relative path is reported as an unresolved import instead of silently dropping the edge.
+
+---
+
 ## Library Packages: Use `publicPackages` Instead of Visibility Tags
 
 In monorepos, shared library packages have exported APIs consumed by external consumers not visible to fallow. Instead of annotating every export with `/** @public */` (or `@internal`, `@beta`, `@alpha`), use the `publicPackages` config to mark entire workspace packages as public libraries. Exports and exported enum/class members from these packages are excluded from unused API detection.

package/skills/fallow/references/patterns.md

@@ -129,6 +129,31 @@ Parse the JSON to list specific files and exports that became unused.
 
 Computes a health score (0-100 with letter grade) in combined mode and enables the health delta header in PR comments.
 
+### GitHub Actions: Severity-Aware PR Quality Gate (Audit)
+
+```yaml
+- uses: fallow-rs/fallow@v2
+  with:
+    command: audit
+    gate: new-only        # default; fails only on findings introduced by this PR
+    fail-on-issues: true
+```
+
+Runs `fallow audit` to combine dead-code + complexity + duplication scoped to changed files. The gate respects rule severity from `.fallowrc.json`, so `unused-exports: warn` projects do not fail when a PR touches a file with pre-existing warn-tier findings. Use `gate: all` to fail on every finding in changed files.
+
+The action exposes `outputs.verdict` (`pass`/`warn`/`fail`) and `outputs.gate` for downstream conditionals; `outputs.issues` holds the introduced count under `gate: new-only` and the total count under `gate: all`.
+
+```yaml
+- uses: fallow-rs/fallow@v2
+  id: fallow
+  with:
+    command: audit
+
+- name: Block release on regression
+  if: steps.fallow.outputs.verdict == 'fail'
+  run: exit 1
+```
+
 ### GitHub Actions: Inline PR Annotations (No Advanced Security)
 
 The official action supports inline PR annotations via GitHub workflow commands. This does not require Advanced Security (unlike SARIF upload) and works on any GitHub plan.
@@ -398,6 +423,7 @@ Creates `.fallowrc.json` with mapped settings:
 - knip `rules`/`exclude`/`include` → fallow `rules` (error/warn/off)
 - knip `ignore` → fallow `ignorePatterns`
 - knip `ignoreDependencies` → fallow `ignoreDependencies`
+- knip `ignoreExportsUsedInFile` → fallow `ignoreExportsUsedInFile` (boolean and `{ type, interface }` object form both supported; fallow groups type aliases and interfaces under one issue, so the two type-kind fields behave identically)
 - Unmappable fields generate warnings with suggestions
 
 ### Step 3: Compare results
@@ -595,7 +621,7 @@ Focus on findings that are BOTH dead code and duplicated:
 
 ## Custom Plugin Setup
 
-For frameworks not covered by the 90 built-in plugins.
+For frameworks not covered by the 94 built-in plugins.
 
 ### Option 1: Inline framework config
 
@@ -693,13 +719,13 @@ Because Claude receives stderr as tool feedback on a blocked `PreToolUse` call,
 Install it automatically:
 
 ```bash
-fallow setup-hooks
+fallow hooks install --target agent
 ```
 
 Remove it later with:
 
 ```bash
-fallow setup-hooks --uninstall
+fallow hooks uninstall --target agent
 ```
 
 Manual files:
@@ -727,79 +753,14 @@ Manual files:
 
 ### `.claude/hooks/fallow-gate.sh`
 
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Generated by fallow setup-hooks.
-# Requires bash and jq. On Windows run via git-bash or WSL.
-# Blocks Claude Code git commit and git push when fallow audit returns verdict fail.
-# Runtime errors fail open with a single stderr notice so skips stay visible.
-
-if ! command -v jq >/dev/null 2>&1; then
-  echo "fallow-gate: jq not on PATH, skipping audit." >&2
-  exit 0
-fi
+Prefer `fallow hooks install --target agent` to install this file. The script is written and maintained by fallow itself; the canonical source is [`crates/cli/src/setup_hooks/fallow-gate.sh`](https://github.com/fallow-rs/fallow/blob/main/crates/cli/src/setup_hooks/fallow-gate.sh).
 
-INPUT="$(cat)"
-CMD="$(jq -r '.tool_input.command // empty' <<<"$INPUT")"
-
-if ! printf '%s\n' "$CMD" | grep -Eq '(^|[[:space:];|&()])git[[:space:]]+(commit|push)([[:space:]]|$)'; then
-  exit 0
-fi
-
-if command -v fallow >/dev/null 2>&1; then
-  RUNNER=(fallow)
-elif command -v npx >/dev/null 2>&1 && VER="$(npx --no-install fallow --version 2>/dev/null || true)" && [[ "$VER" == fallow* ]]; then
-  RUNNER=(npx --no-install fallow)
-else
-  echo "fallow-gate: fallow binary not found (tried PATH and npx --no-install), skipping audit." >&2
-  exit 0
-fi
-
-TMP_JSON="$(mktemp)"
-TMP_ERR="$(mktemp)"
-cleanup() {
-  rm -f "$TMP_JSON" "$TMP_ERR"
-}
-trap cleanup EXIT
-
-if "${RUNNER[@]}" audit --format json --quiet --explain >"$TMP_JSON" 2>"$TMP_ERR"; then
-  STATUS=0
-else
-  STATUS=$?
-fi
-
-VERDICT="$(jq -r '.verdict // empty' <"$TMP_JSON" 2>/dev/null || true)"
-IS_ERROR="$(jq -r '.error // false' <"$TMP_JSON" 2>/dev/null || echo false)"
-
-if [ "$VERDICT" = "fail" ]; then
-  cat "$TMP_JSON" >&2
-  exit 2
-fi
-
-if [ "$STATUS" -eq 2 ] || [ "$IS_ERROR" = "true" ]; then
-  MSG="$(jq -r '.message // empty' <"$TMP_JSON" 2>/dev/null || true)"
-  if [ -n "$MSG" ]; then
-    echo "fallow-gate: fallow audit runtime error ($MSG), skipping." >&2
-  else
-    echo "fallow-gate: fallow audit runtime error, skipping." >&2
-  fi
-  exit 0
-fi
-
-if [ "$STATUS" -ne 0 ]; then
-  ERR_LINE="$(sed -n '1p' "$TMP_ERR" 2>/dev/null || true)"
-  if [ -n "$ERR_LINE" ]; then
-    echo "fallow-gate: fallow audit exited $STATUS ($ERR_LINE), skipping." >&2
-  else
-    echo "fallow-gate: fallow audit exited $STATUS, skipping." >&2
-  fi
-  exit 0
-fi
-
-exit 0
-```
+Behavior you can rely on:
+- Runs only when the intercepted command matches `git commit` or `git push`; otherwise exits 0.
+- Resolves `fallow` from PATH first, then `npx --no-install fallow` as a fallback. Skips with a stderr notice if neither is available or if `jq` is missing.
+- Enforces a version floor via `FALLOW_GATE_MIN_VERSION` (default `2.46.0`). Binaries below the floor are blocked with an upgrade hint. Set the env var to the empty string to disable the check.
+- Runs `fallow audit --format json --quiet --explain` and, on verdict=`fail`, writes the full JSON envelope to stderr preceded by `fallow-gate: blocked by fallow <version> at <binary>` so the responsible binary is always identifiable.
+- On runtime error (`{"error": true, ...}`) or unexpected non-zero exit, fails open with a one-line stderr notice; warn verdicts pass through silently.
 
 Codex fallback (add to repo root `AGENTS.md`):
 
@@ -812,13 +773,13 @@ Keep `fallow audit` in CI alongside this local gate. The hook only runs for Clau
 ### Remove the hook
 
 ```bash
-fallow setup-hooks --uninstall
+fallow hooks uninstall --target agent
 ```
 
 Removes the fallow-gate handler from `.claude/settings.json` (preserving any other handlers in the same matcher group), deletes `.claude/hooks/fallow-gate.sh` if it still carries the `# Generated by fallow setup-hooks.` marker, and strips the managed block from `AGENTS.md`. Idempotent: a second run reports `unchanged` / `not present` and exits 0.
 
 Use `--force` to remove a hook script that the user has edited (the marker is no longer present). Use `--dry-run` to preview without touching files.
 
-### Distinguish from `fallow init --hooks`
+### Distinguish from `fallow hooks install --target git`
 
-`fallow init --hooks` is a different command: it scaffolds a shell-level Git pre-commit hook under `.git/hooks/` that runs `fallow` on changed files. That is the *human* enforcement path. `fallow setup-hooks` is the *agent* enforcement path, targeting `.claude/` and `AGENTS.md`. Both can live in the same repo: git hooks catch human commits, the setup-hooks gate catches agent commits.
+`fallow hooks install --target git` is a different target: it scaffolds a shell-level Git pre-commit hook under `.git/hooks/` that runs `fallow` on changed files. That is the *human* enforcement path. `fallow hooks install --target agent` is the *agent* enforcement path, targeting `.claude/` and `AGENTS.md`. Both can live in the same repo: git hooks catch human commits, the agent gate catches agent commits.