/click-path-audit — Auditoria de Fluxo Comportamental

Encontre bugs que a leitura estática de código não detecta: efeitos colaterais de interação de estado, condições de corrida entre chamadas sequenciais e manipuladores que se anulam silenciosamente.

O Problema Que Isso Resolve

Verificações tradicionais de depuração:

• A função existe? (conexão ausente)
• Ela trava? (erros de tempo de execução)
• Ela retorna o tipo correto? (fluxo de dados)

Mas NÃO verifica:

• O estado final da interface do usuário corresponde ao que o rótulo do botão promete?
• A função B anula silenciosamente o que a função A acabou de fazer?
• O estado compartilhado (Zustand/Redux/context) tem efeitos colaterais que cancelam a ação pretendida?

Exemplo real: Um botão "Novo E-mail" chamado setComposeMode(true) e depois selectThread(null). Ambos funcionavam individualmente. Mas selectThread teve um efeito colateral que redefiniu composeMode: false. O botão não fez nada. 54 bugs foram encontrados por depuração sistemática — este foi perdido.

Como Funciona

Para CADA ponto de interação na área alvo:

1. IDENTIFY the handler (onClick, onSubmit, onChange, etc.)
2. TRACE every function call in the handler, IN ORDER
3. For EACH function call:
   a. What state does it READ?
   b. What state does it WRITE?
   c. Does it have SIDE EFFECTS on shared state?
   d. Does it reset/clear any state as a side effect?
4. CHECK: Does any later call UNDO a state change from an earlier call?
5. CHECK: Is the FINAL state what the user expects from the button label?
6. CHECK: Are there race conditions (async calls that resolve in wrong order)?

Passos de Execução

Passo 1: Mapear Armazenamentos de Estado

Antes de auditar qualquer ponto de interação, construa um mapa de efeitos colaterais de cada ação do armazenamento de estado:

For each Zustand store / React context in scope:
  For each action/setter:
    - What fields does it set?
    - Does it RESET other fields as a side effect?
    - Document: actionName → {sets: [...], resets: [...]}

Esta é a referência crítica. O bug do "Novo E-mail" ficou invisível sem saber que selectThread redefine composeMode.

Formato de saída:

STORE: emailStore
  setComposeMode(bool) → sets: {composeMode}
  selectThread(thread|null) → sets: {selectedThread, selectedThreadId, messages, drafts, selectedDraft, summary} RESETS: {composeMode: false, composeData: null, redraftOpen: false}
  setDraftGenerating(bool) → sets: {draftGenerating}
  ...

DANGEROUS RESETS (actions that clear state they don't own):
  selectThread → resets composeMode (owned by setComposeMode)
  reset → resets everything

Passo 2: Auditar Cada Ponto de Interação

Para cada botão/alternância/envio de formulário na área alvo:

TOUCHPOINT: [Button label] in [Component:line]
  HANDLER: onClick → {
    call 1: functionA() → sets {X: true}
    call 2: functionB() → sets {Y: null} RESETS {X: false}  ← CONFLICT
  }
  EXPECTED: User sees [description of what button label promises]
  ACTUAL: X is false because functionB reset it
  VERDICT: BUG — [description]

Verifique cada um destes padrões de bug:

Padrão 1: Anulação Sequencial

handler() {
  setState_A(true)     // sets X = true
  setState_B(null)     // side effect: resets X = false
}
// Result: X is false. First call was pointless.

Padrão 2: Corrida Assíncrona

handler() {
  fetchA().then(() => setState({ loading: false }))
  fetchB().then(() => setState({ loading: true }))
}
// Result: final loading state depends on which resolves first

Padrão 3: Fechamento Obsoleto

const [count, setCount] = useState(0)
const handler = useCallback(() => {
  setCount(count + 1)  // captures stale count
  setCount(count + 1)  // same stale count — increments by 1, not 2
}, [count])

Padrão 4: Transição de Estado Ausente

// Button says "Save" but handler only validates, never actually saves
// Button says "Delete" but handler sets a flag without calling the API
// Button says "Send" but the API endpoint is removed/broken

Padrão 5: Caminho Morto Condicional

handler() {
  if (someState) {        // someState is ALWAYS false at this point
    doTheActualThing()    // never reached
  }
}

Padrão 6: Interferência do useEffect

// Button sets stateX = true
// A useEffect watches stateX and resets it to false
// User sees nothing happen

Passo 3: Relatar

Para cada bug encontrado:

CLICK-PATH-NNN: [severidade: CRÍTICO/ALTO/MÉDIO/BAIXO]
  Ponto de Interação: [Rótulo do botão] em [arquivo:linha]
  Padrão: [Anulação Sequencial / Corrida Assíncrona / Fechamento Obsoleto / Transição Ausente / Caminho Morto / Interferência do useEffect]

…