safe point before auto-import cleanup

docs/clean-auto-imports.md

@@ -0,0 +1,136 @@
+# clean-auto-imports.js
+
+Script para remover imports manuais redundantes do projeto, considerando que o projeto usa `unplugin-auto-import` e `unplugin-vue-components` com `PrimeVueResolver`.
+
+---
+
+## Por que esse script existe
+
+O projeto tem `vite.config.mjs` configurado com:
+
+- **`unplugin-auto-import`** → auto-importa todas as APIs do Vue (`ref`, `computed`, `watch`, `onMounted`, etc.) em qualquer arquivo `.vue` ou `.js`
+- **`unplugin-vue-components` + `PrimeVueResolver`** → auto-importa componentes do PrimeVue usados nos templates `.vue`
+
+Com isso, manter os imports manuais desses símbolos é redundante. O script limpa tudo de uma vez.
+
+---
+
+## Como usar
+
+### Dry-run (só lista o que seria alterado, sem escrever nada)
+
+```bash
+node scripts/clean-auto-imports.js --dry-run
+```
+
+### Aplicar as mudanças
+
+```bash
+node scripts/clean-auto-imports.js
+```
+
+### Após rodar, verificar se está tudo ok
+
+```bash
+npm run dev
+```
+
+---
+
+## O que o script remove
+
+### Em arquivos `.vue` e `.js`
+
+Qualquer símbolo Vue dentro de `import { ... } from 'vue'` que já é auto-importado:
+
+```js
+// Antes
+import { ref, computed, onMounted, watch } from 'vue'
+
+// Depois (linha removida completamente)
+```
+
+Lista completa dos símbolos removidos:
+
+`computed`, `createApp`, `customRef`, `defineAsyncComponent`, `defineComponent`, `effectScope`, `getCurrentInstance`, `getCurrentScope`, `h`, `inject`, `isProxy`, `isReactive`, `isReadonly`, `isRef`, `isShallow`, `markRaw`, `nextTick`, `onActivated`, `onBeforeMount`, `onBeforeUnmount`, `onBeforeUpdate`, `onDeactivated`, `onErrorCaptured`, `onMounted`, `onUnmounted`, `onUpdated`, `provide`, `reactive`, `readonly`, `ref`, `resolveComponent`, `shallowReactive`, `shallowReadonly`, `shallowRef`, `toRaw`, `toRef`, `toRefs`, `toValue`, `triggerRef`, `unref`, `useAttrs`, `useCssModule`, `useCssVars`, `useId`, `useModel`, `useSlots`, `useTemplateRef`, `watch`, `watchEffect`, `watchPostEffect`, `watchSyncEffect`
+
+Tipos também removidos de `import type { ... } from 'vue'`:
+
+`Component`, `ComputedRef`, `ComponentPublicInstance`, `DirectiveBinding`, `InjectionKey`, `PropType`, `Ref`, `ShallowRef`, `MaybeRef`, `MaybeRefOrGetter`, `VNode`, `WritableComputedRef`, e outros.
+
+### Somente em arquivos `.vue`
+
+Default imports de componentes PrimeVue:
+
+```js
+// Antes
+import Button from 'primevue/button'
+import DataTable from 'primevue/datatable'
+import Select from 'primevue/select'
+
+// Depois (linhas removidas)
+```
+
+---
+
+## O que o script NÃO remove
+
+### `main.js` é ignorado completamente
+
+O arquivo de bootstrap do app nunca é tocado.
+
+### Serviços e plugins do PrimeVue são mantidos
+
+```js
+import PrimeVue from 'primevue/config'             // mantido
+import ConfirmationService from 'primevue/confirmationservice'  // mantido
+import ToastService from 'primevue/toastservice'   // mantido
+```
+
+### Composables do PrimeVue são mantidos
+
+```js
+import { useToast } from 'primevue/usetoast'       // mantido
+import { useConfirm } from 'primevue/useconfirm'   // mantido
+```
+
+### Aliases Vue são mantidos se o original não está na lista
+
+```js
+import { ref as vRef } from 'vue'  // "ref" está na lista → removido
+import { defineProps as dp } from 'vue'  // "defineProps" não está → mantido
+```
+
+### Imports de outros pacotes não são tocados
+
+```js
+import { useRouter } from 'vue-router'   // mantido (não é do 'vue')
+import { useAuthStore } from '@/stores'  // mantido (local)
+import { useFeriados } from '@/composables/useFeriados'  // mantido
+```
+
+### Imports de componentes PrimeVue em arquivos `.js` são mantidos
+
+O `PrimeVueResolver` só funciona em templates `.vue`. Se um `.js` importa um componente PrimeVue, provavelmente está sendo usado programaticamente — o script não toca esses casos.
+
+---
+
+## Troubleshooting
+
+**Erro "X is not defined" após rodar o script**
+
+Isso indica que o símbolo estava sendo usado fora do escopo que o auto-import alcança. Basta re-adicionar o import manualmente no arquivo específico.
+
+**Quero revertir tudo**
+
+Use o git:
+
+```bash
+git checkout src/
+```
+
+---
+
+## Quando rodar novamente
+
+O script é seguro para rodar múltiplas vezes (idempotente). Se novos arquivos forem criados com imports manuais, basta rodar novamente.