caracterizar

Cria/Atualiza:

• tests/characterization/<file_stem>/ — suite de testes + snapshots + fakes auxiliares
• tests/characterization/<file_stem>/README.md — anotações de bugs preservados, fonte do oracle

Após: o user tem safety net que detecta regressão imediata em refactor. Gate refactor-safety-auditor muda de BLOCK → GO. Refactor pode prosseguir com cover-and-modify em vez de edit-and-pray.

Exemplos:

/caracterizar src/orders/handler.ts                        # caracterização completa, defaults
/caracterizar src/orders/handler.ts --symbol processOrder  # só um método
/caracterizar src/orders/handler.ts --gap-fill             # só preenche lacunas (re-rodar pós-refactor)
/caracterizar supabase/functions/webhook/index.ts \
  --fixtures-dir .planning/captured-payloads/webhook        # usa payloads reais

Pré-requisitos:

• Arquivo deve compilar/parsear no projeto atual
• Test framework instalado (Vitest, Jest, pytest, JUnit, go-test, etc.)
• (Recomendado) ferramenta de mutation testing instalada — Stryker (JS/TS), mutmut (Py), Pitest (Java)
• (Opcional) coverage tool com summary acessível (Istanbul/c8 para JS, coverage.py, JaCoCo)

Quando este comando é o caminho certo:

• Arquivo > 200 linhas com cobertura < 60% e mudança comportamental planejada
• Webhook/edge function/API pública sendo modificada
• Gate refactor-safety-auditor retornou BLOCK
• Refactor de monster method (cap 22) iniciando

Quando NÃO é o caminho:

• Arquivo trivial (< 50 linhas, sem branches significativas) — testes diretos sem ceremonial
• Mudança é apenas adicionar comportamento (sprout/wrap) — usar /refactor-seguro --mode=sprout
• Mudança é apenas mecânica (rename, extract-contiguous-block) — usar /refactor-seguro --mode=safe-extract
• Bug fix com TDD — TDD test do COMPORTAMENTO CORRETO é o caminho, não characterization

1. Parsear argumentos

# PT-BR: extrair primeiro positional como target_file
TARGET_FILE=$(echo "$ARGUMENTS" | awk '{print $1}')
SYMBOL=$(echo "$ARGUMENTS" | grep -oE -- '--symbol [^ ]+' | awk '{print $2}')
MIN_INPUTS=$(echo "$ARGUMENTS" | grep -oE -- '--min-inputs [0-9]+' | awk '{print $2}')
FIXTURES_DIR=$(echo "$ARGUMENTS" | grep -oE -- '--fixtures-dir [^ ]+' | awk '{print $2}')
OUTPUT_DIR=$(echo "$ARGUMENTS" | grep -oE -- '--output-dir [^ ]+' | awk '{print $2}')
GAP_FILL=false
NO_MUTATION=false

echo "$ARGUMENTS" | grep -qE -- '--gap-fill'     && GAP_FILL=true
echo "$ARGUMENTS" | grep -qE -- '--no-mutation'  && NO_MUTATION=true

[ -z "$MIN_INPUTS" ] && MIN_INPUTS=8

if [ -z "$TARGET_FILE" ]; then
  echo "ERROR: target_file é obrigatório."
  echo "Uso: /caracterizar <target_file> [opções]"
  exit 1
fi

if [ ! -f "$TARGET_FILE" ]; then
  echo "ERROR: arquivo não encontrado: $TARGET_FILE"
  exit 1
fi