implementado biome para ia

2026-03-04 14:36:50 -03:00 · 2026-03-04 14:36:50 -03:00 · b132aa8005
commit b132aa8005
parent 0a6ce2e323
5 changed files with 441 additions and 78 deletions
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@ -4,8 +4,10 @@
    "source.fixAll.biome": "always"
  },
  "editor.defaultFormatter": "biomejs.biome",
+  "editor.formatOnSave": true,
+
  "[javascript]": {
-    "editor.defaultFormatter": "vscode.typescript-language-features"
+    "editor.defaultFormatter": "biomejs.biome"
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
@ -23,6 +25,21 @@
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[vue]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  }
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[css]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[html]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "typescript.suggest.autoImports": true,
+  "typescript.updateImportsOnFileMove.enabled": "always",
+
+  "editor.rulers": [100],
+  "files.eol": "\n",
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true
 }
--- a/AGENTS.md
+++ b/AGENTS.md
@ -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)
--- a/Documentos/biome.json
+++ b/Documentos/biome.json
@ -6,12 +6,20 @@
    "enabled": true,
    "rules": {
      "recommended": true,
+
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error",
        "noEmptyPattern": "off",
-        "useExhaustiveDependencies": "off"
+        "useExhaustiveDependencies": "off",
+        "noVoidTypeReturn": "error",
+        "noVueDataObjectDeclaration": "error",
+        "noVueDuplicateKeys": "error",
+        "noVueReservedKeys": "error",
+        "noVueReservedProps": "error",
+        "noVueSetupPropsReactivityLoss": "warn"
      },
+
      "style": {
        "noParameterAssign": "error",
        "useAsConstAssertion": "error",
@ -21,44 +29,127 @@
        "useSingleVarDeclarator": "error",
        "noUnusedTemplateLiteral": "error",
        "useNumberNamespace": "error",
-        "noInferrableTypes": "error"
+        "noInferrableTypes": "error",
+        "useArrayLiterals": "error",
+        "useConsistentArrayType": {
+          "level": "error",
+          "options": { "syntax": "shorthand" }
+        },
+        "useShorthandAssign": "error",
+        "noNonNullAssertion": "warn"
      },
+
      "suspicious": {
        "noDebugger": "off",
        "noDoubleEquals": "off",
        "noExplicitAny": "off",
        "noApproximativeNumericConstant": "off",
-        "noAsyncPromiseExecutor": "off"
+        "noAsyncPromiseExecutor": "off",
+        "noEmptyBlockStatements": "warn",
+        "noConsole": "off",
+        "noArrayIndexKey": "warn"
      },
+
      "complexity": {
        "noUselessConstructor": "off",
        "noBannedTypes": "off",
        "useLiteralKeys": "off",
        "useArrowFunction": "warn",
        "useDateNow": "off",
-        "noUselessFragments": "off"
+        "noUselessFragments": "off",
+        "noExcessiveCognitiveComplexity": {
+          "level": "warn",
+          "options": { "maxAllowedComplexity": 20 }
+        }
      },
+
      "performance": {
-        "noAccumulatingSpread": "off"
+        "noAccumulatingSpread": "off",
+        "noDelete": "warn"
      },
+
      "a11y": {
-        "useSemanticElements": "off"
+        "useSemanticElements": "off",
+        "useAltText": "warn",
+        "useButtonType": "warn"
+      },
+
+      "security": {
+        "noDangerouslySetInnerHtml": "warn"
+      },
+
+      "nursery": {
+        "noVueArrowFuncInWatch": "warn",
+        "noVueVIfWithVFor": "error",
+        "useVueConsistentDefinePropsDeclaration": "warn",
+        "useVueConsistentVBindStyle": "warn",
+        "useVueConsistentVOnStyle": "warn",
+        "useVueDefineMacrosOrder": "warn",
+        "useVueVForKey": "error",
+        "useVueValidTemplateRoot": "error",
+        "useVueValidVBind": "error",
+        "useVueValidVIf": "error",
+        "useVueValidVElse": "error",
+        "useVueValidVElseIf": "error",
+        "useVueValidVOn": "warn",
+        "useVueValidVHtml": "warn"
      }
    }
  },
+
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
-    "indentWidth": 2
+    "indentWidth": 2,
+    "lineWidth": 100,
+    "lineEnding": "lf"
  },
+
  "javascript": {
+    "globals": [
+      "defineProps",
+      "defineEmits",
+      "defineExpose",
+      "withDefaults",
+      "defineModel",
+      "defineOptions",
+      "defineSlots"
+    ],
+    "parser": {
+      "unsafeParameterDecoratorsEnabled": true
+    },
    "formatter": {
      "enabled": true,
      "semicolons": "asNeeded",
      "arrowParentheses": "always",
      "bracketSameLine": false,
      "trailingCommas": "all",
-      "attributePosition": "multiline"
+      "attributePosition": "multiline",
+      "quoteStyle": "double",
+      "jsxQuoteStyle": "double",
+      "bracketSpacing": true
+    }
+  },
+
+  "css": {
+    "formatter": {
+      "enabled": true,
+      "indentStyle": "space",
+      "indentWidth": 2,
+      "lineWidth": 100,
+      "quoteStyle": "double"
+    },
+    "linter": {
+      "enabled": true
+    }
+  },
+
+  "html": {
+    "formatter": {
+      "enabled": true,
+      "indentStyle": "space",
+      "indentWidth": 2,
+      "lineWidth": 100
    }
  }
 }
--- a/README.md
+++ b/README.md
@ -1,93 +1,120 @@
-## ✅ Uso do BiomeJS para Autoformatação
+# `p-comuns` — Pacote Compartilhado e-licencie

-Este guia mostra como configurar o [BiomeJS](https://biomejs.dev) para formatar e analisar código JavaScript/TypeScript no seu projeto.
+Pacote de tipos, utilitários e configurações compartilhadas entre todos os subprojetos da plataforma **e-licencie** (back-end Node.js, front-end Vue 3 / TSX).

 ---

-### 1. Incluir o pacote de configuração comum
+## ✅ Configuração do BiomeJS nos Subprojetos

-Certifique-se de que o pacote `p-comuns` (ou outro com a configuração compartilhada) esteja disponível no seu projeto. Ele deve conter o arquivo `Documentos/biome.json`.
+Este guia mostra como usar a configuração base do Biome disponível neste pacote (`Documentos/biome.json`). Todos os subprojetos herdam essas regras via `extends`.

-pnpm up p-comuns
-
---
-
-### 2. Instalar o Biome com `pnpm`
+### 1. Adicionar o `p-comuns` como dependência

 ```bash
-pnpm add --save-dev --save-exact @biomejs/biome@2.1.4
+pnpm add --save-dev p-comuns
+# ou atualizar se já existir:
+pnpm up p-comuns
+```
+
+---
+
+### 2. Instalar o Biome
+
+```bash
+pnpm add --save-dev --save-exact @biomejs/biome@2.4.0
 ```

 > 🎯 Use `--save-exact` para garantir consistência de versões entre ambientes.

 ---

-### 3. Criar o arquivo de configuração na raiz do projeto
-
-Crie um arquivo chamado `biome.json` com o seguinte conteúdo:
+### 3. Criar `biome.json` na raiz do subprojeto

 ```json
 {
-  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
-  "extends": ["./node_modules/p-comuns/Documentos/biome.json"],
+  "$schema": "node_modules/@biomejs/biome/configuration_schema.json",
+  "extends": ["node_modules/p-comuns/Documentos/biome.json"],
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
  "files": {
-    "includes": ["src/**/*.{js,ts,jsx,tsx}"]
+    "includes": ["**/*.{ts,tsx,vue}"]
  }
 }
 ```

-> ⚠️ Verifique o caminho correto do `extends` relativo à raiz do seu projeto. Use `./` sempre que possível para evitar erros de resolução.
+> `vcs.useIgnoreFile: true` faz o Biome respeitar o `.gitignore` automaticamente — arquivos como `dist/`, `node_modules/` etc. são ignorados sem configuração adicional.

 ---

-### 4. Adicionar script no `package.json`
-
-Inclua o comando abaixo em `"scripts"`:
+### 4. Adicionar scripts no `package.json`

 ```json
 {
  "scripts": {
    "biome": "pnpm exec biome check --write",
+    "check": "pnpm run biome && npx tsc --noEmit"
  }
 }
 ```

-Isso permite executar:
-
-```bash
-pnpm biome
-```
-
-> O comando irá **formatar e aplicar as regras de lint** nos arquivos do diretório `src/`.
-
 ---

-### ✅ Dica extra: formatar todos os arquivos
-
-Se quiser aplicar o Biome a todo o projeto (não só `src/`), altere o include:
+### 5. Configurar o VS Code (`.vscode/settings.json`)

 ```json
-"includes": ["**/*.{js,ts,jsx,tsx}"]
-```
-
-
-
-adicionar em .vscode/settings.json
-
 {
  "editor.defaultFormatter": "biomejs.biome",
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports.biome": "always",
+    "source.fixAll.biome": "always"
+  },
  "[javascript]": { "editor.defaultFormatter": "biomejs.biome" },
  "[javascriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
  "[typescript]": { "editor.defaultFormatter": "biomejs.biome" },
  "[typescriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
+  "[vue]": { "editor.defaultFormatter": "biomejs.biome" },
+  "[css]": { "editor.defaultFormatter": "biomejs.biome" },
  "[json]": { "editor.defaultFormatter": "biomejs.biome" },
  "[jsonc]": { "editor.defaultFormatter": "biomejs.biome" },
-  "[vue]": {"editor.defaultFormatter": "octref.vetur"},
-  "editor.codeActionsOnSave": {
-    "source.organizeImports.biome": "always",
-    "source.fixAll.biome": "always"
-  }
+  "editor.rulers": [100],
+  "files.eol": "\n",
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true
 }
+```
+
+> 💡 **Biome formata Vue `.vue` nativamente desde a v2.3** — não precisa do Prettier ou Vetur para formatação!
+
+---
+
+## 🔑 Regras da configuração base (Documentos/biome.json)
+
+### O que está ativado:
+
+| Categoria | Regras notáveis |
+|-----------|----------------|
+| **Correctness** | `noUnusedVariables`, `noUnusedImports`, `noVueSetupPropsReactivityLoss` |
+| **Vue 3 específico** | `noVueVIfWithVFor`, `useVueVForKey`, `noVueDuplicateKeys`, `noVueReservedKeys` |
+| **Style** | `useAsConstAssertion`, `useSelfClosingElements`, `useConsistentArrayType` (shorthand `T[]`) |
+| **Nursery Vue** | `noVueArrowFuncInWatch`, `useVueDefineMacrosOrder`, `useVueConsistentVBindStyle` |
+| **Security** | `noDangerouslySetInnerHtml` (warn) |
+
+### Globals do Vue (sem necessidade de importar):
+
+`defineProps`, `defineEmits`, `defineExpose`, `withDefaults`, `defineModel`, `defineOptions`, `defineSlots`
+
+### Formatação:
+
+- Indentação: **2 espaços**
+- Linha máxima: **100 caracteres**
+- Aspas: **duplas**
+- Ponto-e-vírgula: **apenas quando necessário**
+- Trailing comma: **sempre**
+- Line ending: **LF (`\n`)**

 ---

@ -96,29 +123,21 @@ adicionar em .vscode/settings.json
 O sistema `tipoFiltro26` foi projetado para gerar automaticamente a tipagem de filtros compatíveis com operadores padrão do PostgreSQL, a partir de um tipo base `T`.

 **Principais características:**
- Tipagem forte e segura (Typescript)
+- Tipagem forte e segura (TypeScript)
 - Suporte a aninhamento de objetos
 - Operadores lógicos `E` (AND) e `OU` (OR)
 - Validação de operadores permitidos por tipo de dado (string, number, boolean)

 ### Estrutura do Filtro

-O filtro segue uma estrutura onde chaves representam campos (simples ou aninhados) e valores representam condições com operadores específicos.
-
 #### 1. Campos Simples
 ```typescript
-{
-  idade: { ">=": 18 }
-}
+{ idade: { ">=": 18 } }
 ```

 #### 2. Campos Aninhados
 ```typescript
-{
-  carro: {
-    ano: { "=": 2020 }
-  }
-}
+{ carro: { ano: { "=": 2020 } } }
 ```

 #### 3. Operadores Lógicos
@ -143,7 +162,7 @@ O filtro segue uma estrutura onde chaves representam campos (simples ou aninhado
 }
 ```

-#### 4. Exemplo Complexo Complet
+#### 4. Exemplo Complexo Completo
 ```typescript
 {
  idade: { ">=": 18 },
@ -161,21 +180,23 @@ O filtro segue uma estrutura onde chaves representam campos (simples ou aninhado

 ### Operadores Suportados (`operadores26`)

-Os operadores são fornecidos pelo enum `operadores26` e são restritos pelo tipo do campo:
-
-*   **Number**: `=`, `!=`, `>`, `>=`, `<`, `<=`, `in`
-*   **String**: `=`, `!=`, `like`, `in`
-*   **Boolean**: `=`, `!=`, `in`
-
-> **Nota:** Atualmente não há suporte automático para `null`, `date`, `jsonb` ou `arrays` como tipos de campo raiz (exceto arrays dentro do operador `in`).
+- **Number**: `=`, `!=`, `>`, `>=`, `<`, `<=`, `in`
+- **String**: `=`, `!=`, `like`, `in`
+- **Boolean**: `=`, `!=`, `in`

 ### Validação em Tempo de Execução (Zod)

-O sistema inclui um validador Zod `zFiltro26` para validação estrutural dos objetos de filtro recebidos (ex: via API).
-
 ```typescript
-import { zFiltro26 } from './tipoFiltro.26';
+import { zFiltro26 } from "p-comuns"

 // Valida a estrutura (não checa existência de colunas no DB)
-zFiltro26.parse(objetoFiltro);
+zFiltro26.parse(objetoFiltro)
 ```
+
+---
+
+## 📚 Veja também
+
+- [`AGENTS.md`](./AGENTS.md) — Guia para assistentes de IA (padrões, convenções, arquitetura)
+- [Biome 2.x Docs](https://biomejs.dev)
+- [Vue 3 Composition API](https://vuejs.org/guide/composition-api)
--- a/biome.json
+++ b/biome.json
@ -2,6 +2,6 @@
  "$schema": "node_modules/@biomejs/biome/configuration_schema.json",
  "extends": ["Documentos/biome.json"],
  "files": {
-    "includes": ["src/**/*.{js,ts,jsx,tsx}"]
+    "includes": ["src/**/*.{js,ts,jsx,tsx,vue}"]
  }
 }