plugadvpl 0.3.2__tar.gz → 0.3.4__tar.gz

{plugadvpl-0.3.2 → plugadvpl-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugadvpl
-Version: 0.3.2
+Version: 0.3.4
 Summary: CLI que indexa fontes ADVPL/Protheus em SQLite com FTS5 para análise por LLM (companheiro do plugin Claude Code plugadvpl)
 Project-URL: Homepage, https://github.com/JoniPraia/plugadvpl
 Project-URL: Issues, https://github.com/JoniPraia/plugadvpl/issues

{plugadvpl-0.3.2 → plugadvpl-0.3.4}/plugadvpl/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.2'
-__version_tuple__ = version_tuple = (0, 3, 2)
+__version__ = version = '0.3.4'
+__version_tuple__ = version_tuple = (0, 3, 4)
 
 __commit_id__ = commit_id = None

{plugadvpl-0.3.2 → plugadvpl-0.3.4}/plugadvpl/db.py

@@ -11,7 +11,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from pathlib import Path
 
-SCHEMA_VERSION = "2"
+SCHEMA_VERSION = "3"
 
 
 # Mapeamento {filename JSON -> (tabela, colunas em ordem)}.
@@ -34,7 +34,7 @@ _LOOKUP_FILES: dict[str, tuple[str, list[str]]] = {
         "lint_rules",
         [
             "regra_id", "titulo", "severidade", "categoria", "descricao",
-            "fix_guidance", "detection_kind",
+            "fix_guidance", "detection_kind", "status", "impl_function",
         ],
     ),
     "sql_macros.json": (

plugadvpl-0.3.4/plugadvpl/lookups/lint_rules.json

@@ -0,0 +1,376 @@
+[
+  {
+    "regra_id": "BP-001",
+    "titulo": "RecLock sem MsUnlock pareado no mesmo escopo de função",
+    "severidade": "critical",
+    "categoria": "best-practice",
+    "descricao": "Toda chamada `RecLock` deve ter um `MsUnlock` correspondente no mesmo escopo lógico. Esquecer o unlock mantém o registro travado até a sessão morrer, bloqueando outros usuários e gerando deadlocks. A regra detecta `RecLock` cuja contrapartida `MsUnlock` não aparece no mesmo bloco/função (incluindo branches de erro).",
+    "fix_guidance": "Pareie `RecLock` com `MsUnlock` em todos os caminhos (sucesso e erro). Em fluxos com risco, use `Begin Transaction`/`End Transaction` (rollback automático faz unlock).",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_bp001_reclock_unbalanced"
+  },
+  {
+    "regra_id": "BP-002",
+    "titulo": "BEGIN TRANSACTION sem END TRANSACTION pareado dentro do mesmo escopo",
+    "severidade": "critical",
+    "categoria": "best-practice",
+    "descricao": "Conta opens vs closes de `BEGIN TRANSACTION` por função; se opens > closes, reporta os opens extras. Sem `End Transaction`, em caso de exceção fica estado inconsistente (master sem detail, etc.); atomicidade quebrada.",
+    "fix_guidance": "Pareie `Begin Transaction` com `End Transaction`. Use `DisarmTransaction()` antes do `Break` em `Recover`. NUNCA misture funções de manutenção AdvPL básicas com Framework dentro do mesmo bloco.",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_bp002_transaction_unbalanced"
+  },
+  {
+    "regra_id": "BP-002b",
+    "titulo": "Variáveis declaradas como Private ou Public em vez de Local",
+    "severidade": "warning",
+    "categoria": "best-practice",
+    "descricao": "Variáveis devem ser declaradas como `Local` exceto quando há necessidade explícita de escopo mais amplo. `Private` e `Public` poluem a call stack e podem ser sobrescritas acidentalmente por funções chamadas.",
+    "fix_guidance": "Substitua `Private`/`Public` por `Local` quando possível. Usos legítimos de `Private`: passar variáveis para models MVC ou frameworks legados que esperam por elas (`MV_PAR*`).",
+    "detection_kind": "regex",
+    "status": "planned"
+  },
+  {
+    "regra_id": "BP-003",
+    "titulo": "MsExecAuto sem checar lMsErroAuto nas linhas seguintes",
+    "severidade": "error",
+    "categoria": "best-practice",
+    "descricao": "Após chamar `MsExecAuto`, é obrigatório checar `lMsErroAuto` nas próximas N linhas. Sem isso, erro silencioso: rotina executou com falha, fluxo segue como se OK. Bug em massa em ETLs e jobs de inclusão automática.",
+    "fix_guidance": "Declare `Private lMsErroAuto := .F.` antes da chamada. Logo após `MsExecAuto(...)`, faça `If lMsErroAuto; MostraErro() ...; Return .F.; EndIf` ou capture via `GetAutoGRLog()`.",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_bp003_msexecauto_no_check"
+  },
+  {
+    "regra_id": "BP-004",
+    "titulo": "Pergunte(...) sem uso subsequente de MV_PAR*",
+    "severidade": "warning",
+    "categoria": "best-practice",
+    "descricao": "Detecta `Pergunte(\"GRUPO\", .F./.T.)` sem nenhum uso de `MV_PAR01..MV_PARxx` nas linhas seguintes. Sintoma: chamou Pergunte mas não usou as respostas, ou usou as antigas em memória. Frequentemente é cópia-cola esquecida.",
+    "fix_guidance": "Use `MV_PAR01..MV_PARxx` após o `Pergunte`, OU remova a chamada se não for necessária. Para fluxos novos, prefira `ParamBox()` (Code Analysis aprova; SX1 está deprecated). Em Pergunte aninhado, salve/restaure o estado das MV_PAR.",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_bp004_pergunte_no_check"
+  },
+  {
+    "regra_id": "BP-005",
+    "titulo": "Função declarada com mais de 6 parâmetros",
+    "severidade": "warning",
+    "categoria": "best-practice",
+    "descricao": "Code smell universal: funções com mais de 6 parâmetros indicam acoplamento excessivo, dificultam testes e são propensas a bug por ordem de args trocada.",
+    "fix_guidance": "Refatore: agrupe params relacionados em objeto/array, divida em funções menores com responsabilidades específicas, ou use named params via JSON.",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_bp005_too_many_params"
+  },
+  {
+    "regra_id": "BP-006",
+    "titulo": "Mistura RecLock + dbAppend()/DbRLock raw na mesma função",
+    "severidade": "error",
+    "categoria": "best-practice",
+    "descricao": "TOTVS proíbe: APIs básicas de manutenção (`dbAppend`, `dbDelete`, `dbRecall`) NÃO podem ser misturadas com Framework (`RecLock`, `MsUnlock`) — semântica de lock conflita, integridade transacional quebra.",
+    "fix_guidance": "Use APENAS Framework (RecLock+MsUnlock) dentro de fluxo ERP Protheus. APIs raw (dbAppend etc.) só fora de ambiente Protheus (utilitários offline, scripts de migração).",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_bp006_mixed_reclock_rawapi"
+  },
+  {
+    "regra_id": "BP-007",
+    "titulo": "Função sem header Protheus.doc",
+    "severidade": "info",
+    "categoria": "best-practice",
+    "descricao": "Funções (User Function, Static Function, Method) deveriam ter header Protheus.doc com `@type`, `@author`, `@since`, `@param`, `@return`. Falta de doc dificulta manutenção e impede geração automática de documentação.",
+    "fix_guidance": "Adicione bloco `/*/{Protheus.doc} <NOME>` ... `/*/` antes da função, com pelo menos `@type function`, `@author`, `@since`.",
+    "detection_kind": "regex",
+    "status": "planned"
+  },
+  {
+    "regra_id": "BP-008",
+    "titulo": "Shadowing de variável reservada (cFilAnt, cEmpAnt, PARAMIXB, etc.)",
+    "severidade": "critical",
+    "categoria": "best-practice",
+    "descricao": "Declarar variável Local/Static/Private com nome de Public reservada do framework (`cFilAnt`, `cEmpAnt`, `cUserName`, `PARAMIXB`, `aRotina`, `lMsErroAuto`, `__cInternet`, `nUsado`, etc.) faz shadowing — sua função enxerga `\"\"`/`Nil` em vez do valor real do framework.",
+    "fix_guidance": "Renomeie a variável local pra algo distinto (prefixo cliente). NUNCA crie Local/Private/Public com o mesmo nome de uma reservada framework.",
+    "detection_kind": "regex",
+    "status": "planned"
+  },
+  {
+    "regra_id": "SEC-001",
+    "titulo": "RpcSetEnv dentro de classe que herda de WSRESTFUL",
+    "severidade": "critical",
+    "categoria": "security",
+    "descricao": "Em REST, o framework já entrega o ambiente Protheus via autenticação HTTP + `PrepareIn` configurado no AppServer.ini. `RpcSetEnv` em endpoint REST bypassa o controle de empresa/filial via TenantId, vaza credenciais hardcoded e mata auditoria — não há rastro de quem realmente fez a operação.",
+    "fix_guidance": "Remova `RpcSetEnv`/`RpcClearEnv` do endpoint REST. Configure `PrepareIn=99,01` + `Security=1` no `[HTTPURI]` do appserver.ini. Cliente passa empresa/filial no header `TenantId`. Veja `[[advpl-webservice]]`.",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_sec001_rpcsetenv_in_restful"
+  },
+  {
+    "regra_id": "SEC-002",
+    "titulo": "User Function sem prefixo cliente (2-3 letras) ou padrão PE oficial",
+    "severidade": "warning",
+    "categoria": "security",
+    "descricao": "User Functions devem começar com prefixo institucional (ex: `XYZNomeFn`) para evitar colisão com customizações de outros parceiros instaladas no mesmo RPO. Exceção: nomes de PE oficiais TOTVS (`MT100LOK`, `MA440PGN`, etc.) seguem padrão fixado pela TOTVS.",
+    "fix_guidance": "Adicione prefixo de 2-3 letras do cliente (`XYZ`, `MGF`, etc.) ao nome. Para PEs, mantenha o nome fixo TOTVS — exceção justificada.",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_sec002_user_function_no_prefix"
+  },
+  {
+    "regra_id": "SEC-003",
+    "titulo": "Dados sensíveis (PII/credenciais) em ConOut ou FwLogMsg",
+    "severidade": "warning",
+    "categoria": "security",
+    "descricao": "Logs com CPF/CNPJ/senha/token vão pro `console.log` do AppServer e ficam visíveis a qualquer um com acesso ao servidor. Vazamento de PII viola LGPD.",
+    "fix_guidance": "Mascarar dados sensíveis antes de logar (`***.***.***-XX` para CPF). NUNCA logue senha, token, ou body REST cru com PII. Use `FwLogMsg` com category específica que possa ser desabilitada em produção.",
+    "detection_kind": "regex",
+    "status": "planned"
+  },
+  {
+    "regra_id": "SEC-004",
+    "titulo": "Credenciais hardcoded em código fonte",
+    "severidade": "warning",
+    "categoria": "security",
+    "descricao": "Senhas, tokens, connection strings hardcoded no .prw são vazadas ao versionamento git, expostas a qualquer dev com acesso ao repo. Particularmente crítico em Jobs (`RpcSetEnv(\"01\", \"0101\", \"admin\", \"totvs\")`).",
+    "fix_guidance": "Mova credenciais para `MV_*` em SX6 (encrypted via `EncryptPwd`), variável de ambiente, ou cofre dedicado. Em JOB, leia via `SuperGetMV(\"MV_XYZUSR\")` em runtime.",
+    "detection_kind": "regex",
+    "status": "planned"
+  },
+  {
+    "regra_id": "SEC-005",
+    "titulo": "Uso de função TOTVS restrita/interna (lookup funcoes_restritas)",
+    "severidade": "critical",
+    "categoria": "security",
+    "descricao": "TOTVS mantém ~195 funções/classes/variáveis internas que NÃO devem ser usadas em customização: não documentadas, não suportadas, podem ser removidas/alteradas sem aviso. Algumas têm compilação bloqueada desde 12.1.33.",
+    "fix_guidance": "Substitua por equivalente público documentado em TDN. Consulte tabela `funcoes_restritas` (cataloga as 195 conhecidas). Use `/plugadvpl:find function <nome>` para checar se uma função é restrita.",
+    "detection_kind": "lookup",
+    "status": "planned"
+  },
+  {
+    "regra_id": "PERF-001",
+    "titulo": "SELECT * em BeginSql ou TCQuery",
+    "severidade": "warning",
+    "categoria": "performance",
+    "descricao": "`SELECT *` traz todas as colunas mesmo quando você precisa de 3 — desperdiça banda BD↔AppServer, força full row scan em alguns planos do otimizador. Bug colateral: em `BeginSql`, `*` como primeiro caractere de linha é interpretado como comentário pelo pré-processador.",
+    "fix_guidance": "Liste explicitamente as colunas necessárias: `SELECT F2_DOC, F2_SERIE, F2_EMISSAO FROM ...`. Combine com `TCSetField` para tipagem pós-query.",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_perf001_select_star"
+  },
+  {
+    "regra_id": "PERF-002",
+    "titulo": "SQL contra tabela Protheus sem %notDel% (registros deletados aparecem)",
+    "severidade": "error",
+    "categoria": "performance",
+    "descricao": "Protheus usa soft-delete via coluna `D_E_L_E_T_`. Query sem filtro `%notDel%` traz registros logicamente apagados, gerando bug em totais, contagens e listagens. Em `BeginSql`, a macro expande para `<alias>.D_E_L_E_T_ = ' '` em runtime.",
+    "fix_guidance": "Adicione `<alias>.%notDel%` no `WHERE` para CADA tabela ADVPL no `FROM`/`JOIN`. Ex: `AND SA1.%notDel%` + `AND SD1.%notDel%`.",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_perf002_no_notdel"
+  },
+  {
+    "regra_id": "PERF-003",
+    "titulo": "SQL contra tabela Protheus sem %xfilial% (cross-filial data leak)",
+    "severidade": "error",
+    "categoria": "performance",
+    "descricao": "Cross-filial leak: usuário da filial 01 enxerga dados da filial 02 quando query não filtra por filial. Bug grave em ambientes compartilhados (afeta segurança + performance).",
+    "fix_guidance": "Adicione `WHERE <alias>.<TBL>_FILIAL = %xfilial:<TBL>%` para cada tabela filializada. Ex: `WHERE SA1.A1_FILIAL = %xfilial:SA1%`. Tabelas com `X2_MODO='C'` (compartilhada) não precisam — `xFilial` retorna vazio nesses casos.",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_perf003_no_xfilial"
+  },
+  {
+    "regra_id": "PERF-004",
+    "titulo": "Concatenação de string com + ou += em loop",
+    "severidade": "warning",
+    "categoria": "performance",
+    "descricao": "Em ADVPL, string é imutável. Cada `cVar += \"x\"` aloca string nova, copia conteúdo antigo + \"x\", descarta o anterior. 1.000 concatenações = 1.000 alocações, ~500.000 chars copiados. Comportamento O(n²).",
+    "fix_guidance": "Acumule em array e faça `FwArrayJoin()` (R26+) ou `Array2String()` (legacy) no final. Comportamento vira O(n).",
+    "detection_kind": "regex",
+    "status": "planned"
+  },
+  {
+    "regra_id": "PERF-005",
+    "titulo": "RecCount() > 0 para checar existência (use !Eof())",
+    "severidade": "warning",
+    "categoria": "performance",
+    "descricao": "`RecCount()` força full scan do alias para contar todos os registros. Para apenas verificar se existe pelo menos 1 registro, `!Eof()` após `DbSeek` ou `DbGoTop` é O(1).",
+    "fix_guidance": "Substitua `If RecCount() > 0` por `If !Eof()` ou `If !<alias>->(Eof())`. Em SQL, use `SELECT COUNT(*) FROM ... LIMIT 1` ou subquery EXISTS.",
+    "detection_kind": "regex",
+    "status": "planned"
+  },
+  {
+    "regra_id": "PERF-006",
+    "titulo": "Query com WHERE/ORDER BY em coluna sem índice (cross-file SIX)",
+    "severidade": "info",
+    "categoria": "performance",
+    "descricao": "WHERE/ORDER BY em coluna fora dos índices SIX da tabela força full table scan. Particularmente caro em tabelas grandes (SF1, SD2, SE1, SF3).",
+    "fix_guidance": "Adicione índice custom no SIX (`INDICE >= 21`) ou refatore query para usar coluna indexada. Use `/plugadvpl:tables <T>` para ver índices existentes.",
+    "detection_kind": "cross-file",
+    "status": "planned"
+  },
+  {
+    "regra_id": "MOD-001",
+    "titulo": "ConOut(...) em vez de FwLogMsg(...) (Code Analysis acusa)",
+    "severidade": "warning",
+    "categoria": "modernization",
+    "descricao": "`ConOut` é flagged no Code Analysis TOTVS — saída sem estrutura, dificulta análise de log centralizado. `FwLogMsg` é estruturado (syslog-style: severity/transactionId/group/category/step/msgId) e pode ir pro servidor de logs centralizado quando habilitado via `FWLOGMSG_DEBUG` no appserver.ini.",
+    "fix_guidance": "Substitua `ConOut(\"INFO: msg\")` por `FwLogMsg(\"INFO\", \"TX-001\", \"MGFFAT\", \"REL\", \"Step1\", \"OK\")`. Para debug rápido em desenvolvimento, ConOut ainda é OK.",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_mod001_conout_instead_fwlogmsg"
+  },
+  {
+    "regra_id": "MOD-002",
+    "titulo": "Declaração Public (polui escopo global)",
+    "severidade": "warning",
+    "categoria": "modernization",
+    "descricao": "Variáveis Public poluem o escopo global, dificultam debug (qualquer função pode mexer), causam vazamento de estado entre threads. NUNCA declare Public — só TOTVS framework cria (`cFilAnt`, `cEmpAnt`, etc.).",
+    "fix_guidance": "Use `Local` (95% dos casos) ou `Static` (constante por fonte). `Private` só para padrões legados específicos (`MV_PAR*` injetadas por `Pergunte`).",
+    "detection_kind": "regex",
+    "status": "active",
+    "impl_function": "_check_mod002_public_declaration"
+  },
+  {
+    "regra_id": "MOD-003",
+    "titulo": "Funções com prefixo comum candidatas a virar classe",
+    "severidade": "info",
+    "categoria": "modernization",
+    "descricao": "Conjuntos de Static Function com mesmo prefixo (`_AppCalc`, `_AppFmt`, `_AppGet`) e operando sobre os mesmos dados são candidatos a refatoração para `Class ... Method`. OOP melhora encapsulamento e testabilidade.",
+    "fix_guidance": "Identifique funções com prefixo comum + dados compartilhados. Refatore para `Class TApp` com `Data` (dados) + `Method` (operações). Em TLPP, use `class` com modificadores `public/private/protected`.",
+    "detection_kind": "cross-file",
+    "status": "planned"
+  },
+  {
+    "regra_id": "MOD-004",
+    "titulo": "Uso de AxCadastro/Modelo2/Modelo3 em vez de MVC",
+    "severidade": "info",
+    "categoria": "modernization",
+    "descricao": "`AxCadastro`, `Modelo2`, `Modelo3` são wrappers procedurais legados (R10/R11) que não plugam no framework MVC moderno (eventos, validações cruzadas, FWMVCRotAuto pra testes automatizados). Customizações novas em R12+ devem ser MVC.",
+    "fix_guidance": "Refatore para padrão MVC: `MenuDef()` + `ModelDef()` + `ViewDef()` + `FWMBrowse`. Veja `[[advpl-mvc]]` e `[[advpl-refactoring]]` padrão 4.",
+    "detection_kind": "regex",
+    "status": "planned"
+  },
+  {
+    "regra_id": "SX-001",
+    "titulo": "X3_VALID chama User Function (U_xxx) que não existe nos fontes indexados",
+    "severidade": "warning",
+    "categoria": "best-practice",
+    "descricao": "Validação SX3 (`X3_VALID = \"U_XYZVALID()\"`) referencia User Function não encontrada nos fontes do projeto. Validação quebrada em runtime — campo aceita qualquer valor.",
+    "fix_guidance": "Crie a User Function referenciada nos fontes ou ajuste o `X3_VALID` para função existente. Requer `/plugadvpl:ingest` (fontes) + `/plugadvpl:ingest-sx` (dicionário) antes.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx001_x3_valid_unknown_func"
+  },
+  {
+    "regra_id": "SX-002",
+    "titulo": "SX7 X7_CDOMIN aponta pra campo que não existe em SX3 (campos)",
+    "severidade": "error",
+    "categoria": "best-practice",
+    "descricao": "Gatilho SX7 com destino (`X7_CDOMIN`) referenciando campo que não existe na SX3. Em runtime, gatilho dispara erro ou silenciosamente falha sem atualizar nada.",
+    "fix_guidance": "Apague o gatilho ou crie o campo destino na SX3. Verifique também typos no `X7_CDOMIN`.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx002_x7_destino_inexistente"
+  },
+  {
+    "regra_id": "SX-003",
+    "titulo": "Parâmetro SX6 (MV_*) declarado mas zero referências em fontes",
+    "severidade": "warning",
+    "categoria": "modernization",
+    "descricao": "Parâmetro custom `MV_*` cadastrado no SX6 mas nenhum fonte do projeto faz `GetMV`/`SuperGetMV` por ele. Parâmetro morto ocupa configurador, confunde admin.",
+    "fix_guidance": "Remova o parâmetro do SX6 (script com `PutMV` revertendo) ou use onde foi planejado. Se intencional para uso externo, documente em `X6_DESCRIC`.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx003_mv_param_unused_in_fontes"
+  },
+  {
+    "regra_id": "SX-004",
+    "titulo": "Grupo SX1 sem Pergunte() correspondente em nenhum fonte",
+    "severidade": "warning",
+    "categoria": "modernization",
+    "descricao": "Grupo de pergunta (`X1_GRUPO`) cadastrado no SX1 mas nenhum fonte faz `Pergunte(\"GRUPO\", ...)`. Pergunta órfã, ocupa cadastro sem uso.",
+    "fix_guidance": "Remova o grupo do SX1 ou implemente o uso. Se intencional para uso futuro, marque com X1_DESCR explicativo.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx004_pergunta_unused_in_fontes"
+  },
+  {
+    "regra_id": "SX-005",
+    "titulo": "Campo SX3 custom (X3_PROPRI='U') sem referências em fontes/SX/SX7",
+    "severidade": "info",
+    "categoria": "modernization",
+    "descricao": "Campo custom (`X3_PROPRI = 'U'`) sem nenhuma referência em fontes, validações de outros campos, ou regras de gatilhos. Provável legado, ocupa espaço em cadastro e polui browse.",
+    "fix_guidance": "Considere remover do SX3 (script de delete) ou implementar uso pendente. Se intencional para futura customização, documente.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx005_campo_usado_zero_refs"
+  },
+  {
+    "regra_id": "SX-006",
+    "titulo": "X3_VALID faz BeginSql/TCQuery (anti-pattern de performance)",
+    "severidade": "warning",
+    "categoria": "performance",
+    "descricao": "Validação X3_VALID com SQL embarcado executa query a CADA Loose Focus do campo. Em telas com muitos campos validados, custa segundos de UI per row.",
+    "fix_guidance": "Substitua por `ExistCpo(<alias>, <chave>, <ordem>)` ou `Posicione()` com cache. Se precisa de SQL complexo, mova para User Function que cacheia resultado em `Static`.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx006_perf_sql_in_x3_valid"
+  },
+  {
+    "regra_id": "SX-007",
+    "titulo": "X3_VALID chama função listada em funcoes_restritas TOTVS",
+    "severidade": "critical",
+    "categoria": "security",
+    "descricao": "Validação SX3 chama função interna/restrita TOTVS (lookup `funcoes_restritas`). Quebra em release-bump da TOTVS, não suportada, pode ser removida sem aviso.",
+    "fix_guidance": "Substitua por equivalente público documentado em TDN. Veja `/plugadvpl:find function <nome>` para confirmar se é restrita.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx007_restricted_func_in_x3_valid"
+  },
+  {
+    "regra_id": "SX-008",
+    "titulo": "Tabela compartilhada (X2_MODO='C') usa xFilial em X3_VALID",
+    "severidade": "warning",
+    "categoria": "best-practice",
+    "descricao": "Tabela com `X2_MODO='C'` (compartilhada entre filiais) tem campo SX3 cuja `X3_VALID` usa `xFilial(...)`. Inconsistência: tabela compartilhada não filia, mas validação filtra. Resulta em comportamento imprevisível dependendo da filial ativa.",
+    "fix_guidance": "Remova `xFilial` do `X3_VALID` (tabela é compartilhada, valor de filial não importa) OU mude `X2_MODO` para `E` (Exclusiva) se a tabela realmente filia.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx008_xfilial_in_modo_c"
+  },
+  {
+    "regra_id": "SX-009",
+    "titulo": "Campo obrigatório (X3_OBRIGAT='X') com X3_INIT vazio/zero",
+    "severidade": "warning",
+    "categoria": "best-practice",
+    "descricao": "Campo marcado como obrigatório mas com inicializador (`X3_INIT`) que retorna vazio (`\"\"`, `Space(N)`, `0`, `Nil`, `.F.`). Usuário sempre vai precisar redigitar. UX ruim.",
+    "fix_guidance": "Inicialize com valor sensato (ex: `\"01\"` para campo de filial, `Date()` para data atual, `cFilAnt` para filial). Se realmente não há default, documente em `X3_DESCRIC`.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx009_obrigat_with_empty_init"
+  },
+  {
+    "regra_id": "SX-010",
+    "titulo": "Gatilho SX7 X7_TIPO='P' (Pesquisar) sem X7_SEEK='S' válido",
+    "severidade": "error",
+    "categoria": "best-practice",
+    "descricao": "Gatilho do tipo Pesquisar (P) requer `X7_SEEK='S'` para indicar que faz `DbSeek` no alias antes de avaliar a regra. Sem isso, runtime falha ou retorna valor errado silenciosamente.",
+    "fix_guidance": "Marque `X7_SEEK='S'` e configure `X7_ALIAS`/`X7_ORDEM`/`X7_CHAVE`. Ou troque `X7_TIPO` para `S` (Secundário) se não precisa de SEEK.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx010_pesquisar_sem_seek"
+  },
+  {
+    "regra_id": "SX-011",
+    "titulo": "X3_F3 aponta pra alias SXB (consulta) que não existe",
+    "severidade": "error",
+    "categoria": "best-practice",
+    "descricao": "Campo SX3 com `X3_F3 = \"SA1XYZ\"` referenciando consulta SXB inexistente. F3 (lupa) quebra em runtime quando usuário pressiona F3 no campo.",
+    "fix_guidance": "Crie a consulta na SXB (4 tipos de registro: 1/2/3/4) ou remova o `X3_F3`. Verifique typo no alias.",
+    "detection_kind": "cross-file",
+    "status": "active",
+    "impl_function": "_check_sx011_x3_f3_consulta_inexistente"
+  }
+]

plugadvpl-0.3.4/plugadvpl/migrations/003_lint_rules_status.sql

@@ -0,0 +1,18 @@
+-- Migration 003 — adiciona colunas status e impl_function em lint_rules.
+--
+-- Contexto: lookups/lint_rules.json passou a documentar (a) quais regras estão
+-- realmente implementadas em parsing/lint.py vs. quais estão catalogadas-mas-não-
+-- detectadas, e (b) qual função _check_<id>_<tópico> implementa cada regra ativa.
+-- Antes desta migration o catálogo e a impl divergiam (issue #1) — após esta
+-- migration o teste de regressão tests/integration/test_lint_catalog_consistency.py
+-- protege contra novo drift.
+--
+-- ALTER TABLE ADD COLUMN é não-destrutivo em SQLite (registros existentes recebem
+-- o DEFAULT). Re-executar não falha pois o block é envolvido em IF NOT EXISTS-
+-- semantic via PRAGMA table_info check no orquestrador da migration.
+
+ALTER TABLE lint_rules ADD COLUMN status         TEXT DEFAULT 'active';
+ALTER TABLE lint_rules ADD COLUMN impl_function  TEXT DEFAULT '';
+
+-- Index opcional pra queries do tipo "liste todas as planned"
+CREATE INDEX IF NOT EXISTS idx_lint_rules_status ON lint_rules(status);

plugadvpl-0.3.4/tests/unit/test_lint_catalog_consistency.py

@@ -0,0 +1,150 @@
+"""Garante que lookups/lint_rules.json e parsing/lint.py não voltem a divergir.
+
+Issue #1 documentou drift histórico (10 severidades + 15 títulos diferentes
+entre catálogo e implementação) corrigido em v0.3.4. Este teste é guardião:
+qualquer commit futuro que adicione/remova/renomeie uma regra precisa atualizar
+ambas as fontes de verdade ou o teste falha.
+
+Estratégia:
+
+1. Lê o catálogo lookups/lint_rules.json (35 regras esperadas, 24 active + 11 planned).
+2. Extrai os docstrings das funções _check_* em parsing/lint.py via regex —
+   procura o padrão `def _check_<id>_<topico>(...):` seguido de docstring iniciando
+   com `<ID>-<n> (<severity>):` (ver constante DEF_RE abaixo).
+3. Para cada regra_id que aparece em ambas as fontes:
+
+   - severidade do catálogo deve bater com severidade do docstring impl
+   - catálogo deve marcar a regra como status='active'
+   - catálogo deve apontar impl_function para o nome real da função
+
+4. Para cada regra status='active' no catálogo, deve existir a _check_* correspondente.
+5. Para cada regra status='planned' no catálogo, NÃO deve existir _check_*
+   (caso contrário a regra foi implementada e o status precisa ser atualizado).
+"""
+from __future__ import annotations
+
+import json
+import re
+from importlib import resources as ir
+from pathlib import Path
+
+import pytest
+
+# Mesma regex usada no audit script tmp/audit_lint_drift.py — extrai (fn_name, id, severity, summary).
+DEF_RE = re.compile(
+    r'^def\s+(_check_[a-z0-9_]+)\s*\([^)]*\)[^:]*:\s*\n\s+"""'
+    r'([A-Z]+-[0-9]+[a-z]?)\s+\(([a-z]+)\):\s*([^\n]+)',
+    re.MULTILINE,
+)
+
+
+@pytest.fixture(scope="module")
+def catalog() -> dict[str, dict]:
+    """Carrega lookups/lint_rules.json indexado por regra_id."""
+    text = ir.files("plugadvpl").joinpath("lookups/lint_rules.json").read_text(
+        encoding="utf-8"
+    )
+    rules = json.loads(text)
+    return {r["regra_id"]: r for r in rules}
+
+
+@pytest.fixture(scope="module")
+def impl() -> dict[str, dict[str, str]]:
+    """Extrai dict[regra_id] = {fn, severidade, summary} dos docstrings de lint.py."""
+    text = ir.files("plugadvpl").joinpath("parsing/lint.py").read_text(encoding="utf-8")
+    out: dict[str, dict[str, str]] = {}
+    for m in DEF_RE.finditer(text):
+        fn_name, regra_id, severity, summary = m.groups()
+        out[regra_id] = {
+            "fn": fn_name,
+            "severidade": severity.lower(),
+            "summary": summary.strip().rstrip(".").strip(),
+        }
+    return out
+
+
+def test_catalog_has_expected_total(catalog: dict) -> None:
+    """Sanity check: número total de regras catalogadas (24 active + 11 planned = 35)."""
+    assert len(catalog) == 35, (
+        f"esperava 35 regras catalogadas, encontrou {len(catalog)}. "
+        "Se adicionou/removeu regra intencional, atualize este teste."
+    )
+
+
+def test_active_count_matches_impl(catalog: dict, impl: dict) -> None:
+    """24 regras active no catálogo devem bater com 24 funções _check_* no impl."""
+    n_active = sum(1 for r in catalog.values() if r.get("status") == "active")
+    assert n_active == 24, f"esperava 24 active, encontrou {n_active}"
+    assert len(impl) == 24, (
+        f"esperava 24 funções _check_* em lint.py, encontrou {len(impl)}. "
+        "Se adicionou/removeu detector, atualize este teste e o catálogo."
+    )
+
+
+def test_active_rules_have_impl_function(catalog: dict, impl: dict) -> None:
+    """Toda regra active no catálogo precisa ter `impl_function` apontando pra fn real."""
+    for rid, rule in catalog.items():
+        if rule.get("status") != "active":
+            continue
+        assert rule.get("impl_function"), (
+            f"regra {rid} marcada como active mas sem impl_function no catálogo"
+        )
+        assert rid in impl, (
+            f"regra {rid} marcada active no catálogo mas não há _check_* "
+            f"correspondente em lint.py"
+        )
+        assert rule["impl_function"] == impl[rid]["fn"], (
+            f"regra {rid}: catálogo aponta impl_function='{rule['impl_function']}' "
+            f"mas a função real é '{impl[rid]['fn']}'"
+        )
+
+
+def test_severity_matches_between_catalog_and_impl(catalog: dict, impl: dict) -> None:
+    """Severidade do catálogo deve bater com severidade declarada no docstring impl."""
+    drifts = []
+    for rid, impl_data in impl.items():
+        if rid not in catalog:
+            drifts.append(f"{rid}: existe em lint.py mas NÃO no catálogo")
+            continue
+        cat_sev = catalog[rid].get("severidade", "?")
+        if cat_sev != impl_data["severidade"]:
+            drifts.append(
+                f"{rid}: catálogo='{cat_sev}' impl='{impl_data['severidade']}'"
+            )
+    assert not drifts, "Drift de severidade detectado:\n  - " + "\n  - ".join(drifts)
+
+
+def test_planned_rules_have_no_impl(catalog: dict, impl: dict) -> None:
+    """Regras planned no catálogo NÃO devem ter _check_* — se tiver, marque como active."""
+    leaks = []
+    for rid, rule in catalog.items():
+        if rule.get("status") == "planned" and rid in impl:
+            leaks.append(
+                f"{rid}: marcada planned mas existe {impl[rid]['fn']} em lint.py — "
+                "mude status para 'active' e adicione impl_function"
+            )
+    assert not leaks, "Regras planned com impl real:\n  - " + "\n  - ".join(leaks)
+
+
+def test_planned_rules_have_no_impl_function(catalog: dict) -> None:
+    """Regras planned não devem ter `impl_function` setado (deve ser '' ou ausente)."""
+    for rid, rule in catalog.items():
+        if rule.get("status") == "planned":
+            assert not rule.get("impl_function"), (
+                f"regra {rid} marcada planned mas tem impl_function='{rule['impl_function']}' "
+                "— remova o campo ou marque como active"
+            )
+
+
+def test_all_rules_have_required_fields(catalog: dict) -> None:
+    """Schema mínimo: toda regra precisa de regra_id/titulo/severidade/categoria/descricao/status."""
+    required = ["regra_id", "titulo", "severidade", "categoria", "descricao", "status"]
+    for rid, rule in catalog.items():
+        for field in required:
+            assert field in rule, f"regra {rid} sem campo obrigatório '{field}'"
+        assert rule["status"] in ("active", "planned"), (
+            f"regra {rid}: status='{rule['status']}' inválido (use 'active' ou 'planned')"
+        )
+        assert rule["severidade"] in ("critical", "error", "warning", "info"), (
+            f"regra {rid}: severidade='{rule['severidade']}' inválida"
+        )