# 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` | **Sempre use arrow function** — `function` é erro |
| `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 `function` nomeada — sempre arrow function (`const fn = () => {}`)
- ❌ 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)