gstack/bin/gstack-diff-scope

#!/usr/bin/env bash
# gstack-diff-scope — categorize what changed in the diff against a base branch
# Usage: source <(gstack-diff-scope main)  → sets SCOPE_FRONTEND=true SCOPE_BACKEND=false ...
# Or:    gstack-diff-scope main           → prints SCOPE_*=... lines
# Or:    gstack-diff-scope <base> --head <sha> → the committed range <base>...<sha> only
#        (no working tree, no untracked files): what a receipt writer and the
#        merge queue compute for one commit, from any checkout (GSTA-147).
# Or:    gstack-diff-scope <base> --head <sha> --merged → the same for a head GitHub
#        already merged into the base (land resuming a true merge): the empty range
#        is the answer, so the base-contains-head refusal below does not apply.
#
# Output contract (#2526 — all-false must be distinguishable from "we could
# not look" and from "nothing matched"):
#   exit 0  changed-file set empty            → all false, legitimately nothing
#   exit 0  changed files, >=1 category match → flags
#   exit 2  changed files, ZERO matches       → flags + SCOPE_ERROR=unmatched
#           (+ the unmatched paths as comment lines, so a new top-level layout
#            trips loudly instead of silently disabling reviewers)
#   exit 2  base ref unresolvable             → all false + SCOPE_ERROR=no_base
#           (shallow CI checkout / missing fetch — a green here would mean
#            "we could not look"; also no default base when origin/HEAD
#            names the checked-out branch and nothing past it resolves)
#   exit 2  base is HEAD or contains it       → all false + SCOPE_ERROR=base_contains_head
#           (the branch has commits its real base lacks, so it would be
#            compared with itself, GST-774; the reason as a comment line)
# Every line is shell-safe for `source <(...)` consumers: assignments or
# `#`-comments only.
#
# The changed-file set is the UNION of committed diff + working tree +
# untracked files (#2299): /ship detects scope in Step 9, BEFORE it commits in
# Step 15, so uncommitted work must be visible or every scope-gated reviewer
# is skipped on the common start-work-then-ship flow.
set -euo pipefail

# Detect the repo's default branch when no arg is given (#703-class
# platform-agnostic rule, lib/default-base.ts): origin/HEAD unless it names the
# checked-out branch, its upstream or HEAD's commit (a PR flow's clone can point
# it at the PR branch, GST-511, GST-774) -> the PR's base (gh, 5 s) -> the
# remote's live HEAD (ls-remote, 5 s) -> origin/main -> origin/master -> main.
# An origin/HEAD skipped that way with nothing past it resolving leaves BASE
# empty, and that fails closed; so does a default-base.ts that cannot run.
GSTACK_BUN_CONFIG=/dev/null; case "${OSTYPE:-}" in msys*|cygwin*) if command -v cygpath >/dev/null 2>&1; then GSTACK_BUN_CONFIG=NUL; fi ;; esac
_default_base_ts() { bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)/lib/default-base.ts" "$@"; }
NO_DEFAULT=""
BASE="${1:-}"
if [ -z "$BASE" ]; then
  _rc=0
  _found=$(_default_base_ts default 2>/dev/null) || _rc=$?
  case "$_rc" in
    0) BASE="$_found" ;;
    1) BASE="main" ;;
    3) NO_DEFAULT="$_found" ;;
    *) NO_DEFAULT="lib/default-base.ts could not run (exit $_rc); pass the base explicitly" ;;
  esac
fi
HEAD_REF=""
MERGED_HEAD=false
if [ "${2:-}" = "--head" ]; then HEAD_REF="${3:-}"; fi
if [ -n "$HEAD_REF" ] && [ "${4:-}" = "--merged" ]; then MERGED_HEAD=true; fi
# A bare branch name reads origin's tracking branch, by its full ref, when that
# shares history with HEAD: /ship merges against origin/<base>, and a linked
# worktree or a Capy clone never moves the local branch, so a stale one widens
# the scope (#3650). A remote-qualified name is taken as given.
_NOT_BRANCH='^[0-9a-f]{7,64}$|[~^]|@\{|^[A-Z_]*HEAD$|^refs/'
_QUALIFIED=false
case "$BASE" in origin/*) _QUALIFIED=true ;; esac
for _remote in $(git remote 2>/dev/null); do
  case "$BASE" in "$_remote"/*) _QUALIFIED=true ;; esac
done
if [[ ! "$BASE" =~ $_NOT_BRANCH ]] && [ "$_QUALIFIED" = false ] \
  && git rev-parse --verify -q "refs/remotes/origin/${BASE}^{commit}" >/dev/null 2>&1 \
  && git merge-base "refs/remotes/origin/${BASE}" "${HEAD_REF:-HEAD}" >/dev/null 2>&1; then
  BASE="refs/remotes/origin/${BASE}"
fi

# The base as a commit (GST-884, mirroring lib/gate-diff/git.ts resolveBase from
# GST-883): a branch name reads refs/remotes/<base> (origin/main as given), then
# refs/remotes/origin/<base> that shares history with the head, then refs/heads/<base>
# that does, then another remote's twin that does, then refs/heads/<base> as it is,
# all by full ref name and in resolveBase's order, so a stale local main never widens
# the scope and a tag named main or origin/main cannot stand in for the branch.
# A sha, a relative ref (HEAD~1, main^2, @{u}) or a full refs/ name resolves as
# given. Prints nothing when nothing resolves.
_is_branch_name() {
  case "$1" in refs/*|*~*|*^*|*@\{*|HEAD|*_HEAD) return 1 ;; esac
  [[ ! "$1" =~ ^[0-9a-f]{7,64}$ ]]
}
_commit() { git rev-parse --verify -q "$1^{commit}" 2>/dev/null; }
_resolve_base() {
  local ref="$1" head="$2" sha loc remote
  if ! _is_branch_name "$ref"; then _commit "$ref"; return; fi
  sha=$(_commit "refs/remotes/$ref") && { echo "$sha"; return; }
  loc=$(_commit "refs/heads/$ref")
  for remote in $(git remote 2>/dev/null | grep -x origin) ${loc:+:local} $(git remote 2>/dev/null | grep -vx origin); do
    if [ "$remote" = :local ]; then sha=$loc; else sha=$(_commit "refs/remotes/$remote/$ref") || continue; fi
    git merge-base "$sha" "$head" >/dev/null 2>&1 && { echo "$sha"; return; }
  done
  [ -n "$loc" ] && { echo "$loc"; return; }
  _commit "$ref"
}

FRONTEND=false
BACKEND=false
PROMPTS=false
TESTS=false
DOCS=false
CONFIG=false
MIGRATIONS=false
API=false
AUTH=false

# Test-file paths, the same rule the test-bootstrap resolver counts as
# TESTFILES (scripts/resolvers/testing.ts; test/diff-scope.test.ts keeps the two
# identical). Nested test dirs and Python's test_*.py / tests.py were missed by
# the root-anchored globs alone (#3335).
TEST_PATH_RE='(^|/)(tests?|spec|__tests__)/|(^|/)tests?\.py$|(^|/)test_[^/]+\.py$|_test\.(go|py|rb|ts|js|exs|dart)$|\.(test|spec)\.[jt]sx?$|_spec\.rb$|Test\.(java|kt)$'

# Data files (lib/review-depth.ts DATA_PATH) outside the config locations its
# DATA_CONFIG and agent-prose rules keep code: .github/, config/, dotfiles,
# *.config.*, .gstack/. Case-insensitive, as DATA_PATH is.
DATA_FILE_RE='\.(json|jsonl|ndjson|csv|tsv|png|jpe?g|gif|webp|bmp|ico|avif)$'
DATA_CONFIG_RE='(^|/)\.github/|(^|/)config/|(^|/)\.[^/]+$|(^|/)[^/]+\.config\.[^/]+$|^\.gstack/'
_session_data() {
  local r=1
  shopt -s nocasematch
  if [[ "$1" =~ $DATA_FILE_RE ]] && [[ ! "$1" =~ $DATA_CONFIG_RE ]]; then r=0; fi
  shopt -u nocasematch
  return "$r"
}

_print_flags() {
  echo "SCOPE_FRONTEND=$FRONTEND"
  echo "SCOPE_BACKEND=$BACKEND"
  echo "SCOPE_PROMPTS=$PROMPTS"
  echo "SCOPE_TESTS=$TESTS"
  echo "SCOPE_DOCS=$DOCS"
  echo "SCOPE_CONFIG=$CONFIG"
  echo "SCOPE_MIGRATIONS=$MIGRATIONS"
  echo "SCOPE_API=$API"
  echo "SCOPE_AUTH=$AUTH"
}

if [ -z "$BASE" ]; then
  _print_flags
  echo "SCOPE_ERROR=no_base"
  echo "# ${NO_DEFAULT}"
  exit 2
fi

# Base reachability (#2526): a shallow CI checkout or an unfetched ref makes
# `git diff` return an empty list — all-false with exit 0, a green that means
# "we could not look". Distinguish it before diffing. A branch name that does
# not resolve here reads its origin twin (_resolve_base; a PR checkout has no local main).
BASE_SHA=$(_resolve_base "$BASE" "${HEAD_REF:-HEAD}" || true)
if [ -z "$BASE_SHA" ]; then
  _print_flags
  echo "SCOPE_ERROR=no_base"
  echo "# base ref '${BASE}' is not resolvable — shallow checkout or missing fetch. Run: git fetch origin ${BASE}"
  exit 2
fi

# A base that is the head or already contains it reads the branch against
# itself, all false with exit 0 (GST-774). lib/default-base.ts decides whether
# that is the base branch itself or a fresh branch (today's output) or a
# refusal; it is asked only when git says the base contains the head.
if [ "$MERGED_HEAD" = false ] && git merge-base --is-ancestor "${HEAD_REF:-HEAD}" "${BASE_SHA}" >/dev/null 2>&1; then
  _rc=0
  _why=$(_default_base_ts check "$BASE" "${HEAD_REF:-HEAD}" gstack-diff-scope 2>/dev/null) || _rc=$?
  if [ "$_rc" -ne 0 ]; then
    _print_flags
    echo "SCOPE_ERROR=base_contains_head"
    echo "# ${_why:-lib/default-base.ts could not check the base (exit $_rc) (BASE_CONTAINS_HEAD)}"
    exit 2
  fi
fi

# Changed files, NUL-delimited (#2526 minor: `git diff --name-only` octal-quotes
# non-ASCII paths, and the trailing quote defeats extension globs; -z avoids it).
FILES_LIST=()
_collect() {
  local f
  while IFS= read -r -d '' f; do
    [ -n "$f" ] && FILES_LIST+=("$f")
  done
}
if [ -n "$HEAD_REF" ] || [ "${2:-}" = "--head" ]; then
  if ! git rev-parse --verify -q "${HEAD_REF}^{commit}" >/dev/null 2>&1; then
    _print_flags
    echo "SCOPE_ERROR=no_head"
    echo "# --head '${HEAD_REF}' is not a commit in this repository"
    exit 2
  fi
  if ! git merge-base "${BASE_SHA}" "${HEAD_REF}" >/dev/null 2>&1; then
    _print_flags
    echo "SCOPE_ERROR=no_merge_base"
    echo "# '${BASE}' and '${HEAD_REF}' share no merge base"
    exit 2
  fi
  _collect < <(git diff -z "${BASE_SHA}...${HEAD_REF}" --name-only 2>/dev/null)
else
# Committed diff vs base (merge-base form; two-dot fallback when no merge base).
_collect < <(git diff -z "${BASE_SHA}...HEAD" --name-only 2>/dev/null || git diff -z "${BASE_SHA}" --name-only 2>/dev/null || true)
# Working-tree changes (staged + unstaged). `git diff HEAD` fails on a repo
# with no commits; tolerated.
_collect < <(git diff -z HEAD --name-only 2>/dev/null || true)
# Untracked files: a brand-new component/migration/test is exactly what a
# reviewer should see, and /ship commits it in Step 15 regardless.
_collect < <(git ls-files -z --others --exclude-standard 2>/dev/null || true)
fi

if [ "${#FILES_LIST[@]}" -eq 0 ]; then
  _print_flags
  exit 0
fi

UNMATCHED=()

# Categories are INDEPENDENT booleans (#2299): a single first-match-wins case
# made them mutually exclusive, so Button.test.jsx set FRONTEND but not TESTS
# while util.test.ts set TESTS but not BACKEND — same intent, opposite result,
# purely from arm ordering. Each category now gets its own case; only BACKEND
# stays deliberately exclusive of frontend component/view files.
for f in ${FILES_LIST[@]+"${FILES_LIST[@]}"}; do
  m_frontend=false; m_prompts=false; m_tests=false; m_docs=false
  m_config=false; m_migrations=false; m_api=false; m_auth=false; m_backend=false

  # Frontend: CSS, views, components, templates
  case "$f" in
    *.css|*.scss|*.less|*.sass|*.pcss) m_frontend=true ;;
    *.tsx|*.jsx|*.vue|*.svelte|*.astro) m_frontend=true ;;
    *.erb|*.haml|*.slim|*.hbs|*.ejs) m_frontend=true ;;
    *.html) m_frontend=true ;;
    # Dart: the extension cannot tell a Flutter widget from a repository or a
    # pure-Dart server, so it is BOTH frontend and backend (BACKEND set below).
    # A skipped reviewer is invisible; an extra one (design-lite included) is a
    # visible pass that costs a review.
    *.dart) m_frontend=true ;;
    tailwind.config.*|postcss.config.*) m_frontend=true ;;
    app/views/*|*/components/*|styles/*|css/*|app/assets/stylesheets/*) m_frontend=true ;;
  esac

  # Prompts: prompt builders, system prompts, generation services
  case "$f" in
    *prompt_builder*|*generation_service*|*writer_service*|*designer_service*) m_prompts=true ;;
    *evaluator*|*scorer*|*classifier_service*|*analyzer*) m_prompts=true ;;
    *voice*.rb|*writing*.rb|*prompt*.rb|*token*.rb) m_prompts=true ;;
    app/services/chat_tools/*|app/services/x_thread_tools/*) m_prompts=true ;;
    config/system_prompts/*) m_prompts=true ;;
  esac

  # Tests
  case "$f" in
    *.test.*|*.spec.*|*_test.*|*_spec.*) m_tests=true ;;
    test/*|tests/*|spec/*|__tests__/*|cypress/*|e2e/*) m_tests=true ;;
    conftest.py|*/conftest.py) m_tests=true ;;
  esac
  if [[ "$f" =~ $TEST_PATH_RE ]]; then m_tests=true; fi

  # Docs
  case "$f" in
    *.md) m_docs=true ;;
  esac

  # Config
  case "$f" in
    package.json|package-lock.json|yarn.lock|bun.lock|bun.lockb) m_config=true ;;
    Gemfile|Gemfile.lock) m_config=true ;;
    *.yml|*.yaml) m_config=true ;;
    .github/*) m_config=true ;;
    requirements.txt|pyproject.toml|go.mod|Cargo.toml|composer.json) m_config=true ;;
    pubspec.lock|*/pubspec.lock) m_config=true ;;
  esac

  # Migrations: database migration files. Bare migrations/* covers a
  # root-level migrations dir (#2526); db/data covers the Rails data_migrate
  # gem's DATA migrations (#2455) — arbitrary Ruby run unattended against
  # production data, strictly higher-risk than a schema migration (they also
  # match BACKEND below via their extension, as ordinary app code should).
  case "$f" in
    db/migrate/*|migrations/*|*/migrations/*|alembic/*|prisma/migrations/*) m_migrations=true ;;
    db/data/*|data_migrations/*|*/data_migrations/*) m_migrations=true ;;
  esac

  # API: routes, controllers, endpoints, GraphQL/OpenAPI schemas. Bare api/*
  # covers root-level serverless layouts (Vercel functions, Next.js pages/api
  # at root) that */api/* silently missed (#2526).
  case "$f" in
    api/*|*/api/*|*controller*|*route*|*endpoint*) m_api=true ;;
    *.graphql|*.gql|openapi.*|swagger.*) m_api=true ;;
  esac

  # Auth: authentication, authorization, sessions, permissions. A data file
  # named for sessions (recovered-sessions.jsonl, GST-911) holds rows, not
  # session handling, so it is not auth; session config still is.
  case "$f" in
    *auth*|*jwt*|*oauth*|*permission*|*role*) m_auth=true ;;
    *session*) _session_data "$f" || m_auth=true ;;
  esac

  # Backend: code that isn't a frontend component/view file. Includes ESM/CJS
  # (.mjs/.cjs) and explicit-module TS (.mts/.cts) — #1810: these matched no
  # category, so an ESM/CJS-only PR skipped the backend reviewer entirely.
  if [ "$m_frontend" = false ]; then
    case "$f" in
      *.rb|*.py|*.go|*.rs|*.java|*.php|*.ex|*.exs) m_backend=true ;;
      *.ts|*.js|*.mjs|*.cjs|*.mts|*.cts) m_backend=true ;;
    esac
  fi
  case "$f" in
    *.dart) m_backend=true ;;
  esac

  [ "$m_frontend" = true ] && FRONTEND=true
  [ "$m_prompts" = true ] && PROMPTS=true
  [ "$m_tests" = true ] && TESTS=true
  [ "$m_docs" = true ] && DOCS=true
  [ "$m_config" = true ] && CONFIG=true
  [ "$m_migrations" = true ] && MIGRATIONS=true
  [ "$m_api" = true ] && API=true
  [ "$m_auth" = true ] && AUTH=true
  [ "$m_backend" = true ] && BACKEND=true

  if [ "$m_frontend" = false ] && [ "$m_prompts" = false ] && [ "$m_tests" = false ] \
    && [ "$m_docs" = false ] && [ "$m_config" = false ] && [ "$m_migrations" = false ] \
    && [ "$m_api" = false ] && [ "$m_auth" = false ] && [ "$m_backend" = false ]; then
    UNMATCHED+=("$f")
  fi
done

_print_flags

# Changed files but ZERO category matches (#2526): a classifier bug, an
# unrecognised layout, or a new top-level directory would otherwise present
# as "no reviewers needed" with the skip invisible. Trip loudly instead.
if [ "$FRONTEND" = false ] && [ "$BACKEND" = false ] && [ "$PROMPTS" = false ] \
  && [ "$TESTS" = false ] && [ "$DOCS" = false ] && [ "$CONFIG" = false ] \
  && [ "$MIGRATIONS" = false ] && [ "$API" = false ] && [ "$AUTH" = false ]; then
  echo "SCOPE_ERROR=unmatched"
  printf '%s\n' ${UNMATCHED[@]+"${UNMATCHED[@]}"} | sort -u | head -50 | while IFS= read -r u; do
    [ -n "$u" ] && printf '# unmatched: %s\n' "$u"
  done
  exit 2
fi