implementado biome para ia
This commit is contained in:
parent
0a6ce2e323
commit
b132aa8005
5 changed files with 441 additions and 78 deletions
234
AGENTS.md
Normal file
234
AGENTS.md
Normal file
|
|
@ -0,0 +1,234 @@
|
|||
# AGENTS.md — Guia para Assistentes de IA
|
||||
|
||||
> **Este arquivo descreve os padrões, convenções e arquitetura do projeto `p-comuns`.**
|
||||
> Leia este arquivo antes de sugerir ou gerar qualquer código.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Visão Geral do Projeto
|
||||
|
||||
`p-comuns` é um **pacote compartilhado** (npm monorepo-like) usado como dependência em todos os subprojetos da plataforma **e-licencie**. Ele provê:
|
||||
|
||||
- Tipos TypeScript compartilhados (rotas, filtros, situações, UUIDs...)
|
||||
- Utilitários de back-end (postgres, cache em memória, dayjs...)
|
||||
- Utilitários de front-end (Vue 3 + TSX)
|
||||
- Constantes e enums globais
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Stack Tecnológica
|
||||
|
||||
| Camada | Tecnologia | Versão |
|
||||
|--------|-----------|--------|
|
||||
| Linguagem | TypeScript | ~5.9.x |
|
||||
| Runtime (back) | Node.js | ≥20 |
|
||||
| Framework (front) | Vue 3 | Composition API + `<script setup>` |
|
||||
| JSX/TSX | Vue TSX / React-like TSX | via `jsxRuntime` |
|
||||
| Linter/Formatter | Biome | 2.4.x |
|
||||
| Bundler | tsup | 8.x |
|
||||
| Package manager | pnpm | com workspaces |
|
||||
| Validação | Zod | 4.x |
|
||||
| Utilitários de data | dayjs | 1.11.x |
|
||||
|
||||
---
|
||||
|
||||
## 📁 Estrutura do `src/`
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts # Entry point — exporta tudo que é público
|
||||
├── constantes.ts # Constantes globais (enums, valores fixos)
|
||||
├── situacoes.ts # Status/situações dos processos
|
||||
├── tipagemRotas.ts # Tipagem forte de rotas da API
|
||||
├── tipoFiltro.26.ts # Sistema de filtros tipados (operadores PG)
|
||||
├── uuid.ts # Geração e validação de UUIDs
|
||||
├── dayjs26.ts # Wrapper do dayjs com locale e plugins
|
||||
├── extensoes.ts # Extensões de tipos nativos
|
||||
├── texto_busca.ts # Utilitários de busca em texto
|
||||
├── variaveisComuns.ts # Variáveis de ambiente compartilhadas
|
||||
├── postgres.ts # Cliente PostgreSQL base
|
||||
├── cacheMemoria.ts # Cache em memória (Map com TTL)
|
||||
├── aleatorio.ts # Utilitários de aleatoriedade
|
||||
├── consulta.ts # Helpers de consulta SQL
|
||||
├── instalarAmbiente.ts # Setup de ambiente (dev/prod)
|
||||
├── graficosPilao.ts # Tipos para gráficos do PILÃO
|
||||
├── ecosistema/ # Tipos do ecossistema de módulos
|
||||
└── testes/ # Testes unitários (Vitest)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📐 Convenções de Código
|
||||
|
||||
### TypeScript
|
||||
|
||||
- **Strict mode** SEMPRE ligado (`"strict": true`)
|
||||
- **Sem `any` explícito** — use tipos genéricos ou `unknown`
|
||||
- **Sem `!` (non-null assertion)** — trate o `null`/`undefined` explicitamente
|
||||
- **Arrays**: usar `T[]` em vez de `Array<T>` (shorthand)
|
||||
- **Imports** ordenados automaticamente pelo Biome
|
||||
- **Enums** sempre com inicializadores explícitos
|
||||
- **Parâmetros** não podem ser reatribuídos
|
||||
|
||||
### Nomenclatura
|
||||
|
||||
```typescript
|
||||
// Tipos e interfaces: PascalCase
|
||||
type TipoUsuario = { ... }
|
||||
interface IRepositorio { ... }
|
||||
|
||||
// Constantes: camelCase (sem SCREAMING_SNAKE_CASE, exceto enums legados)
|
||||
const configuracaoBase = { ... }
|
||||
|
||||
// Funções: camelCase, verbos
|
||||
const calcularTotal = (itens: Item[]) => { ... }
|
||||
const buscarUsuarioPorId = async (id: UUID) => { ... }
|
||||
|
||||
// Arquivos: camelCase para utilitários, PascalCase para componentes Vue
|
||||
// ✅ tipoFiltro.ts, variaveisComuns.ts
|
||||
// ✅ MeuComponente.vue, BotaoAcao.vue
|
||||
```
|
||||
|
||||
### Vue 3 (Composition API)
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
// Sempre usar <script setup lang="ts">
|
||||
// Macros globais disponíveis (sem import): defineProps, defineEmits,
|
||||
// defineExpose, withDefaults, defineModel, defineOptions, defineSlots
|
||||
|
||||
const props = defineProps<{
|
||||
titulo: string
|
||||
itens: Item[]
|
||||
}>()
|
||||
|
||||
const emit = defineEmits<{
|
||||
selecionar: [item: Item]
|
||||
fechar: []
|
||||
}>()
|
||||
</script>
|
||||
```
|
||||
|
||||
- **Sem Vue Options API** — sempre Composition API
|
||||
- **Props não devem ser desestruturadas** (quebra reatividade Vue 3)
|
||||
- **`v-for` sempre com `:key`** — use o ID do item, nunca o índice!
|
||||
- **`v-if` e `v-for` nunca no mesmo elemento** — use `<template v-for>`
|
||||
- **Atributos em multiline** quando há mais de 2 props
|
||||
|
||||
### TSX (componentes em `.tsx`)
|
||||
|
||||
```tsx
|
||||
// Componente funcional Vue em TSX
|
||||
import { defineComponent, ref } from "vue"
|
||||
|
||||
export const MeuComponente = defineComponent({
|
||||
props: {
|
||||
titulo: { type: String, required: true },
|
||||
},
|
||||
setup(props) {
|
||||
const contador = ref(0)
|
||||
return () => (
|
||||
<div class="meu-componente">
|
||||
<h1>{props.titulo}</h1>
|
||||
<button onClick={() => contador.value++}>{contador.value}</button>
|
||||
</div>
|
||||
)
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Biome — Regras de Lint Importantes
|
||||
|
||||
### Erros (bloqueiam o build)
|
||||
|
||||
| Regra | Descrição |
|
||||
|-------|-----------|
|
||||
| `noUnusedVariables` | Variáveis definidas e não usadas |
|
||||
| `noUnusedImports` | Imports não utilizados |
|
||||
| `noVoidTypeReturn` | Função `void` retornando valor |
|
||||
| `noVueDataObjectDeclaration` | Vue 2 `data: {}` — usar função |
|
||||
| `noVueDuplicateKeys` | Chaves duplicadas em objetos Vue |
|
||||
| `noVueSetupPropsReactivityLoss` | Desestruturar `props` em `setup()` |
|
||||
| `noVueVIfWithVFor` | `v-if` + `v-for` no mesmo elemento |
|
||||
| `useVueVForKey` | `v-for` sem `:key` |
|
||||
| `useVueValidTemplateRoot` | Template sem raiz única (Vue 2) |
|
||||
|
||||
### Warnings (code smells — corrija quando possível)
|
||||
|
||||
| Regra | Descrição |
|
||||
|-------|-----------|
|
||||
| `useArrowFunction` | Prefira arrow functions |
|
||||
| `noNonNullAssertion` | Evite `!` — trate o null |
|
||||
| `noDelete` | `delete obj.prop` é lento |
|
||||
| `noEmptyBlockStatements` | Blocos `{}` vazios |
|
||||
| `noArrayIndexKey` | `:key` com índice do array |
|
||||
| `noDangerouslySetInnerHtml` | `innerHTML` perigoso |
|
||||
| `noExcessiveCognitiveComplexity` | Função muito complexa (max: 20) |
|
||||
|
||||
---
|
||||
|
||||
## 📦 Como Outros Projetos Consomem Este Pacote
|
||||
|
||||
```json
|
||||
// biome.json do subprojeto (ex: PILAO-FRONT)
|
||||
{
|
||||
"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
|
||||
"extends": ["./node_modules/p-comuns/Documentos/biome.json"],
|
||||
"files": {
|
||||
"includes": ["src/**/*.{js,ts,jsx,tsx,vue}"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// .vscode/settings.json do subprojeto
|
||||
{
|
||||
"editor.defaultFormatter": "biomejs.biome",
|
||||
"editor.formatOnSave": true,
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.organizeImports.biome": "always",
|
||||
"source.fixAll.biome": "always"
|
||||
},
|
||||
"[vue]": { "editor.defaultFormatter": "biomejs.biome" },
|
||||
"[typescript]": { "editor.defaultFormatter": "biomejs.biome" },
|
||||
"[typescriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
|
||||
"editor.rulers": [100],
|
||||
"files.eol": "\n"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Scripts
|
||||
|
||||
```bash
|
||||
pnpm biome # Formata + lint com auto-fix
|
||||
pnpm check # biome + tsc --noEmit (sem emitir arquivos)
|
||||
pnpm build # Bump de versão + biome + tsup + pack
|
||||
pnpm teste # Vitest (testes unitários)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ O que NÃO fazer
|
||||
|
||||
- ❌ Não use `eslint` — o projeto usa Biome
|
||||
- ❌ Não use `prettier` — o projeto usa Biome
|
||||
- ❌ Não use `var` — sempre `const` ou `let`
|
||||
- ❌ Não use Vue Options API — sempre Composition API
|
||||
- ❌ Não desestrure `props` diretamente (quebra reatividade)
|
||||
- ❌ Não use `any` — use `unknown` + type narrowing
|
||||
- ❌ Não use índice como `:key` no `v-for`
|
||||
- ❌ Não quebre linhas com mais de 100 caracteres
|
||||
- ❌ Não use ponto-e-vírgula no final (Biome removerá)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Referências
|
||||
|
||||
- [Biome 2.x Docs](https://biomejs.dev)
|
||||
- [Vue 3 Composition API](https://vuejs.org/guide/composition-api)
|
||||
- [Zod v4](https://zod.dev)
|
||||
- [tsup](https://tsup.egoist.dev)
|
||||
Loading…
Add table
Add a link
Reference in a new issue