@fontdata/ai-harness 4.3.0 → 4.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/.claude-plugin/plugin.json +2 -2
  2. package/README.md +80 -2
  3. package/dist/config/config.js +37 -3
  4. package/dist/contratos/artefatos.js +13 -5
  5. package/dist/delphi/command.js +102 -1
  6. package/dist/delphi/encoding.js +112 -0
  7. package/dist/init.js +8 -2
  8. package/dist/install/perfis.js +14 -0
  9. package/dist/install/plan.js +29 -2
  10. package/dist/install/settings.js +40 -3
  11. package/dist/update/update.js +69 -7
  12. package/package.json +1 -1
  13. package/templates/catalog.json +3 -0
  14. package/templates/perfis/delphi/hooks/encoding.mjs +317 -0
  15. package/templates/perfis/delphi/rules/build-e-verificacao.md +59 -0
  16. package/templates/perfis/delphi/rules/dados/cnpj-alfanumerico-nao-extrair-so-numeros.md +65 -0
  17. package/templates/perfis/delphi/rules/dados/data-hora-sql-nunca-round-trip-textual.md +78 -0
  18. package/templates/perfis/delphi/rules/dados/datestyle-sessao-firedac-postgres.md +60 -0
  19. package/templates/perfis/delphi/rules/dados/ddl-tabela-nova-exige-trigger-de-log.md +68 -0
  20. package/templates/perfis/delphi/rules/dados/divisao-e-conversao-numerica.md +53 -0
  21. package/templates/perfis/delphi/rules/dados/fieldbyname-value-variant-cru-em-aritmetica.md +73 -0
  22. package/templates/perfis/delphi/rules/dados/filtro-condicional-sql-par-add-parambyname.md +72 -0
  23. package/templates/perfis/delphi/rules/dados/firedac.md +51 -0
  24. package/templates/perfis/delphi/rules/dados/macro-firedac-exige-entrada-macrodata.md +96 -0
  25. package/templates/perfis/delphi/rules/dados/sql-qualificacao-colunas.md +36 -0
  26. package/templates/perfis/delphi/rules/dados/tmeminifile-getstrings-nao-limpa-destino.md +89 -0
  27. package/templates/perfis/delphi/rules/encoding-eol.md +130 -0
  28. package/templates/perfis/delphi/rules/linguagem/dataset-nao-se-le-depois-do-laco-eof.md +56 -0
  29. package/templates/perfis/delphi/rules/linguagem/existencia-nunca-se-testa-por-campo-formatado.md +60 -0
  30. package/templates/perfis/delphi/rules/linguagem/float-nunca-comparado-por-igualdade-com-literal.md +55 -0
  31. package/templates/perfis/delphi/rules/linguagem/literal-enum-de-dfm-exige-unit-no-uses.md +84 -0
  32. package/templates/perfis/delphi/rules/linguagem/reaproveitar-funcao-existente-antes-de-criar.md +172 -0
  33. package/templates/perfis/delphi/rules/linguagem/sem-clipboard-debug.md +43 -0
  34. package/templates/perfis/delphi/rules/linguagem/validacao-em-onexit-nao-protege-a-gravacao.md +65 -0
  35. package/templates/perfis/delphi/rules/linguagem/variavel-inline-sai-de-escopo-ao-envolver-bloco.md +69 -0
  36. package/templates/perfis/delphi/rules/telas/foco-decisao-por-canfocus-nao-tabstop.md +40 -0
  37. package/templates/perfis/delphi/rules/telas/form-dinamico-liberar-em-toda-saida.md +80 -0
  38. package/templates/perfis/delphi/rules/telas/heranca-de-form-e-grade-de-selecao.md +58 -0
  39. package/templates/perfis/delphi/rules/threads-e-timers.md +131 -0
  40. package/templates/perfis/delphi/rules/try-finally-e-vazamento.md +109 -0
  41. package/templates/perfis/delphi/skills/conhecimento-delphi/SKILL.md +64 -0
  42. package/templates/perfis/delphi/skills/conhecimento-delphi/references/ATRIBUICAO.md +29 -0
  43. package/templates/perfis/delphi/skills/conhecimento-delphi/references/acbr-nfce-integracao.md +60 -0
  44. package/templates/perfis/delphi/skills/conhecimento-delphi/references/build-via-bat-com-log.md +86 -0
  45. package/templates/perfis/delphi/skills/conhecimento-delphi/references/class-var-vaza-para-campos-de-instancia.md +73 -0
  46. package/templates/perfis/delphi/skills/conhecimento-delphi/references/componentes-designer-vs-runtime.md +47 -0
  47. package/templates/perfis/delphi/skills/conhecimento-delphi/references/console-writeln-sem-flush-nao-loga.md +47 -0
  48. package/templates/perfis/delphi/skills/conhecimento-delphi/references/conversao-numerica-locale.md +47 -0
  49. package/templates/perfis/delphi/skills/conhecimento-delphi/references/delphi13-breaking-changes.md +41 -0
  50. package/templates/perfis/delphi/skills/conhecimento-delphi/references/dpr-uses-project-manager.md +62 -0
  51. package/templates/perfis/delphi/skills/conhecimento-delphi/references/dproj-dcc-debuginformation-nao-booleano.md +78 -0
  52. package/templates/perfis/delphi/skills/conhecimento-delphi/references/dproj-projectguid-valido.md +38 -0
  53. package/templates/perfis/delphi/skills/conhecimento-delphi/references/firedac-registro-drivers.md +94 -0
  54. package/templates/perfis/delphi/skills/conhecimento-delphi/references/horse-gbswagger-rotas-jwt.md +61 -0
  55. package/templates/perfis/delphi/skills/conhecimento-delphi/references/msb6003-command-line-too-long.md +52 -0
  56. package/templates/perfis/delphi/skills/conhecimento-delphi/references/recursos-rcdata.md +67 -0
  57. package/templates/skills/resolver-bug/SKILL.md +8 -2
@@ -0,0 +1,89 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ - "**/*.sql"
8
+ ---
9
+
10
+ # Regra (camada de dados): `TMemIniFile.GetStrings` não limpa o destino
11
+
12
+ Sempre `Clear` antes. Aplica-se a todo código que edita em memória um conteúdo de INI carregado num
13
+ `TStrings` e o grava de volta. Um caso comum é o override de parâmetros de componentes que guardam a
14
+ configuração como INI num `TStrings` (ex.: `Configuracoes.WebServices.Params` dos componentes ACBr).
15
+
16
+ ## O método só faz `Add`
17
+
18
+ Trecho de `System.IniFiles.pas` na RTL:
19
+
20
+ ```pascal
21
+ procedure TMemIniFile.GetStrings(const List: TStrings);
22
+ begin
23
+ List.BeginUpdate;
24
+ try
25
+ for I := 0 to FSections.Count - 1 do
26
+ begin
27
+ List.Add('[' + FSections.Names[I] + ']'); // só Add, nunca List.Clear
28
+ Strings := FSections.Sections[I];
29
+ for J := 0 to Strings.Count - 1 do
30
+ List.Add(Strings.Pairs[J]);
31
+ List.Add('');
32
+ end;
33
+ finally
34
+ List.EndUpdate;
35
+ end;
36
+ end;
37
+ ```
38
+
39
+ O nome sugere "obter" (substituir), mas o comportamento é **acrescentar**. Se o destino for o mesmo
40
+ `TStrings` que alimentou o `SetStrings`, o resultado é o conteúdo antigo seguido de uma segunda cópia
41
+ inteira, agora com as alterações.
42
+
43
+ ## Por que é silencioso e caro de achar
44
+
45
+ Com o INI duplicado, o próximo `SetStrings` cria **duas seções com o mesmo nome** (não mescla nem
46
+ substitui), e `ReadString` resolve pela **primeira**, que é a versão antiga. O `WriteString` "funcionou",
47
+ o INI em memória contém o valor novo, e mesmo assim quem lê recebe o valor velho.
48
+
49
+ Nada aparece em compilação, exceção ou log. O sintoma é a alteração simplesmente não ter efeito, o que
50
+ leva a investigar as hipóteses erradas (dado de origem, condição do `if`, ordem de chamada) antes de
51
+ suspeitar da RTL.
52
+
53
+ ## Padrão obrigatório
54
+
55
+ ```pascal
56
+ LIni := TMemIniFile.Create('');
57
+ try
58
+ LIni.SetStrings(<Destino>);
59
+ LIni.WriteString(<Secao>, <Chave>, <Valor>);
60
+ <Destino>.Clear; // GetStrings só faz Add; sem Clear o INI fica duplicado
61
+ LIni.GetStrings(<Destino>);
62
+ finally
63
+ LIni.Free;
64
+ end;
65
+ ```
66
+
67
+ - O `SetStrings` já copiou tudo para dentro do `TMemIniFile`, então limpar o destino antes do
68
+ `GetStrings` é seguro: a fonte dos dados passa a ser o `LIni`, não a lista.
69
+ - **Comente a linha do `Clear`** com o motivo. Sem o comentário ela parece supérflua, e alguém a remove
70
+ numa "limpeza" futura, ressuscitando o bug.
71
+ - `TStrings.Assign` não tem esse problema (faz `Clear` + `AddStrings`); é a alternativa quando se quer só
72
+ substituir o conteúdo por uma lista pronta.
73
+
74
+ ## Override de parâmetros em componentes ACBr
75
+
76
+ Nos componentes ACBr, `LerParamsIni` só recarrega o INI do resource quando `Params.Count = 0`. Por isso
77
+ um override gravado em `Configuracoes.WebServices.Params` sobrevive às leituras internas do componente, e
78
+ essa é a forma suportada de forçar provedor ou versão em runtime sem tocar no `.ini` em disco.
79
+
80
+ Depois do override, **dispare a resolução de novo** atribuindo outra vez a propriedade que a desencadeia
81
+ (no ACBrNFSeX, `CodigoMunicipio`): é ela que recalcula provedor, versão e layout. Trocar o provider "na mão"
82
+ deixa valores derivados (como o layout) com o estado anterior.
83
+
84
+ ## Antes de fechar
85
+
86
+ - Confirme o efeito **em runtime**, não por leitura do código: o valor lido depois do override tem de ser
87
+ o novo.
88
+ - Se o comportamento não mudar, a primeira hipótese é esta regra (seção duplicada no `TStrings`), não erro
89
+ no dado nem na condição.
@@ -0,0 +1,130 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dpr"
5
+ - "**/*.dpk"
6
+ - "**/*.inc"
7
+ - "**/*.dfm"
8
+ - "**/*.dproj"
9
+ ---
10
+
11
+ # Encoding e EOL dos fontes Delphi
12
+
13
+ Encoding e fim de linha (EOL) nunca mudam como efeito colateral de uma edição. Converter por engano corrompe os
14
+ acentos do arquivo inteiro (inclusive mensagens exibidas ao usuário) e reescreve o arquivo todo no diff,
15
+ escondendo a alteração real.
16
+
17
+ ## Formato por extensão
18
+
19
+ | Extensão | Encoding | EOL | Conduta |
20
+ |---|---|---|---|
21
+ | `.pas`, `.dpr`, `.dpk`, `.inc` | UTF-8 com BOM (`EF BB BF`) | CRLF | converter para UTF-8 com BOM antes de editar, se não estiver |
22
+ | `.dfm` texto | o que o arquivo já tem (em geral ASCII, acentos escapados) | o que o arquivo já tem | preservar encoding e EOL; nunca converter |
23
+ | `.dfm` binário (começa com `FF 0A 00` ou `TPF0`) | binário | — | não se edita como texto; abrir na IDE |
24
+ | `.dproj` | UTF-8 (XML) | o que o arquivo já tem | editar só as linhas necessárias |
25
+ | terceiros (ACBr, `modules/`) | o do fornecedor (ACBr em ISO-8859-1) | o do fornecedor | não converter nem reformatar |
26
+
27
+ Unit `.pas` sem BOM aparece com acentos quebrados na IDE. Unit criada por ferramenta sai em UTF-8 **sem** BOM:
28
+ falta só o BOM, e o `converter` só o acrescenta.
29
+
30
+ ## Antes de editar: detectar
31
+
32
+ ```
33
+ npx @fontdata/ai-harness delphi encoding detectar <arquivo>
34
+ ```
35
+
36
+ Mostra `utf8-bom`, `utf8-sem-bom`, `cp1252` ou `dfm-binario`, e o EOL (`crlf`, `lf`, `misto`).
37
+
38
+ - `utf8-bom` → edite direto.
39
+ - `utf8-sem-bom` ou `cp1252` em `.pas`/`.dpr`/`.dpk`/`.inc` → converta **antes** da primeira edição:
40
+
41
+ ```
42
+ npx @fontdata/ai-harness delphi encoding converter <arquivo>
43
+ ```
44
+
45
+ O `converter` lê o que não é UTF-8 como CP1252, grava UTF-8 com BOM e mantém o EOL de cada linha. Em UTF-8 sem
46
+ BOM só acrescenta o BOM; em UTF-8 com BOM não altera nenhum byte. Ele recusa `.dfm`.
47
+
48
+ Por quê converter antes: as ferramentas de edição regravam em UTF-8. Editar um `.pas` em CP1252 direto troca cada
49
+ acento por U+FFFD (`'Obrigat�rio'`), e isso não tem volta.
50
+
51
+ Se o arquivo já tem edição não commitada e pode ter sido corrompido, restaure antes de converter
52
+ (`git restore --source=HEAD -- <arquivo>`), mas só se não houver trabalho do usuário a preservar; havendo, pare e
53
+ avise.
54
+
55
+ A conversão é sob demanda, só no arquivo que a tarefa vai editar. Migrar o projeto inteiro é tarefa explícita, a
56
+ pedido do usuário.
57
+
58
+ ## `.dfm`: editar sim, converter nunca
59
+
60
+ Editar `.dfm` é permitido quando a tarefa pede (componente novo, propriedade, `TabOrder`), esteja ele em LF ou
61
+ CRLF. `.dfm` em CRLF em geral foi salvo pela IDE, e isso não impede a edição.
62
+
63
+ - Preserve o EOL existente: CRLF continua CRLF, LF continua LF.
64
+ - Altere só as linhas necessárias com `Edit`. Nunca regrave o `.dfm` inteiro por script: além do EOL, isso pode
65
+ capturar alteração concorrente no mesmo arquivo.
66
+ - Acento no `.dfm` texto fica escapado fora das aspas: `'Data da Emiss'#227'o'`. Gravar o acento cru em UTF-8
67
+ quebra o form na IDE.
68
+ - Meça o EOL **antes** da primeira edição e compare com esse número, não com o `HEAD`:
69
+
70
+ ```bash
71
+ grep -c $'\r' <arquivo.dfm> # 0 = LF; maior que 0 = CRLF
72
+ ```
73
+
74
+ ### Diff enorme no `.dfm`: descubra quem mudou antes de "corrigir"
75
+
76
+ O usuário pode ter salvo o `.dfm` pela IDE entre duas tarefas (a IDE grava em CRLF). Comparado com o `HEAD`, o
77
+ diff mostra o arquivo inteiro alterado sem que o agente tenha convertido nada. Sinais de gravação pela IDE:
78
+
79
+ - mudaram propriedades que só a IDE recalcula: `ExplicitWidth`, `ExplicitHeight`, `ExplicitLeft`, `ExplicitTop`,
80
+ `PixelsPerInch`, `TextHeight`;
81
+ - mudaram valores que nenhum agente tocou (larguras de coluna, posições);
82
+ - a contagem de CR já era maior que 0 antes da primeira edição.
83
+
84
+ Com sinal de IDE, o CRLF é o EOL existente e o conteúdo é trabalho do usuário: não remova CR (`tr -d '\r'`,
85
+ `sed`, `dos2unix`), não reverta para o `HEAD`, continue editando só as linhas do escopo e relate ao usuário o que
86
+ a IDE mudou. Só trate como conversão sua quando a contagem de CR antes da sua edição for diferente da contagem
87
+ depois, e desfaça só o que você introduziu.
88
+
89
+ ## Depois de editar: checar
90
+
91
+ ```
92
+ npx @fontdata/ai-harness delphi encoding checar <arquivo>
93
+ ```
94
+
95
+ Aponta, por linha, U+FFFD, dupla codificação, BOM ausente (em `.pas`/`.dpr`/`.dpk`/`.inc`) e EOL misto; sai com
96
+ código 1 se achar algo. Com `--todos`, confere todos os fontes Delphi versionados.
97
+
98
+ A dupla codificação (UTF-8 lido como CP1252 e gravado de novo em UTF-8: `ã` vira `ã`) não gera U+FFFD, então
99
+ só um grep a pega:
100
+
101
+ ```bash
102
+ grep -nE 'Ã[¡¢£¤§¨©ª­³´µº¼]|â€' <arquivo> # deve dar nada
103
+ ```
104
+
105
+ A classe cobre os acentos comuns em português (`á` á, `ã` ã, `ç` ç, `é` é, `ê` ê, `í` í, `ó` ó, `õ` õ,
106
+ `ú` ú, `â` â); o `checar` acima usa a faixa inteira.
107
+
108
+ Confira também `git diff --stat -- <arquivo>`: só as linhas tocadas devem aparecer. Em `.pas`/`.dpr`/`.dpk`/`.inc`,
109
+ dezenas de linhas de acento alteradas indicam encoding ou EOL convertido; desfaça e refaça a edição preservando os
110
+ bytes originais. Em `.dfm`, aplique antes a seção "Diff enorme no `.dfm`": o diff pode ser gravação da IDE, e
111
+ desfazer apagaria trabalho do usuário.
112
+
113
+ ## Rede de segurança: hook `delphi-encoding`
114
+
115
+ O hook `delphi-encoding` do perfil bloqueia `Edit`/`MultiEdit` em `.pas`, `.dpr`, `.dpk` e `.inc` que não está em
116
+ UTF-8 válido e mostra o comando `converter`. Depois da edição, avisa BOM ausente, U+FFFD novo, dupla codificação
117
+ nova e EOL misto novo; no `.dfm`, avisa só U+FFFD novo e EOL diferente do anterior. O hook é a rede; esta rule é
118
+ a conduta.
119
+
120
+ Pastas de terceiros ficam fora do hook e do `--todos` pela lista `delphi.ignorar` do `.ai-harness/config.json`
121
+ (padrão: `**/modules/**` e `**/ACBr*/**`). Se o hook bloquear uma unit de terceiro, acrescente a pasta dela à
122
+ lista em vez de converter o arquivo:
123
+
124
+ ```json
125
+ {
126
+ "delphi": {
127
+ "ignorar": ["**/modules/**", "**/ACBr*/**", "**/Terceiros/**"]
128
+ }
129
+ }
130
+ ```
@@ -0,0 +1,56 @@
1
+ ---
2
+ descricao: Campo de dataset não se lê depois de um laço First/while not Eof — capture o valor dentro do laço, no registro selecionado
3
+ paths:
4
+ - "**/*.pas"
5
+ - "**/*.dpr"
6
+ - "**/*.dpk"
7
+ - "**/*.inc"
8
+ ---
9
+
10
+ # Regra incondicional: depois de `while not Eof`, o cursor está na última linha — não na que você quer
11
+
12
+ Aplica-se a toda rotina que percorre um dataset (`TFDQuery`, `TFDMemTable`, `TClientDataSet`) com
13
+ `First; while not Eof do ... Next;`, típico para achar os registros marcados numa grade, e **depois** usa dados
14
+ "do registro escolhido".
15
+
16
+ ## O defeito: o `FieldByName` depois do laço não falha, só lê outro registro
17
+
18
+ No FireDAC, o `Next` sobre o último registro liga `Eof`, mas o cursor **continua no último registro**. O
19
+ `FieldByName` depois do laço devolve os valores da **última linha do dataset**, sem erro nenhum:
20
+
21
+ ```pascal
22
+ // ERRADO: o laço só marcou; nome e chave saem da ÚLTIMA linha da grade
23
+ QueryDocumentos.First;
24
+ while not QueryDocumentos.Eof do
25
+ begin
26
+ if QueryDocumentos.FieldByName('selecionado').AsBoolean then
27
+ LTelefone := QueryDocumentos.FieldByName('telefone').AsString;
28
+ QueryDocumentos.Next;
29
+ end;
30
+ LTexto.Add('Cliente: ' + QueryDocumentos.FieldByName('nome').AsString);
31
+ LArquivo := 'PDF\' + QueryDocumentos.FieldByName('chave').AsString + '.pdf';
32
+
33
+ // CERTO: tudo o que se usa depois é capturado no registro selecionado, dentro do laço
34
+ if QueryDocumentos.FieldByName('selecionado').AsBoolean then
35
+ begin
36
+ LTelefone := QueryDocumentos.FieldByName('telefone').AsString;
37
+ LNome := QueryDocumentos.FieldByName('nome').AsString;
38
+ LChave := QueryDocumentos.FieldByName('chave').AsString;
39
+ end;
40
+ ```
41
+
42
+ ## Por que escapa do teste
43
+
44
+ - Se o registro testado é o **último da grade**, o valor sai certo por acaso. É exatamente o que acontece ao testar
45
+ com o registro mais recente, que costuma ser a última linha.
46
+ - Um campo capturado dentro do laço e outro lido depois dele parecem simétricos no diff.
47
+ - Reposicionar com `First` depois do laço não resolve: volta para o **primeiro** registro, não para o selecionado,
48
+ e o laço pode ter desmarcado a seleção.
49
+ - Quando o valor lido errado é vazio (uma chave ausente na última linha), o defeito aparece longe dali, como um
50
+ arquivo sem nome ou um registro não encontrado.
51
+
52
+ ## Antes de fechar a alteração
53
+
54
+ - Para cada `while not Eof` tocado, procure `FieldByName` do **mesmo dataset** entre o fim do laço e o fim da rotina.
55
+ Cada um precisa de um `Locate` pela chave de negócio ou de uma variável capturada dentro do laço.
56
+ - Teste com o registro selecionado **no meio da grade**, nunca só na última linha.
@@ -0,0 +1,60 @@
1
+ ---
2
+ descricao: "Regra incondicional: existência de registro nunca se testa por campo formatado para exibição"
3
+ paths:
4
+ - "**/*.pas"
5
+ - "**/*.dpr"
6
+ - "**/*.dpk"
7
+ - "**/*.inc"
8
+ - "**/*.dfm"
9
+ ---
10
+
11
+ # Regra incondicional: existência de registro nunca se testa por campo formatado para exibição
12
+
13
+ Aplica-se a toda guarda que decide **se um registro relacionado existe** antes de fazer UPDATE,
14
+ DELETE, reabertura ou conversão a partir dele — documento de origem, nota principal, título
15
+ financeiro, ordem vinculada, e afins.
16
+
17
+ ## O que é proibido
18
+
19
+ Testar existência pelo `.Text` de um controle preenchido com zeros à esquerda (ou qualquer
20
+ formatação de exibição):
21
+
22
+ ```pascal
23
+ // PROIBIDO: completar '' com 9 zeros dá '000000000' — este teste é sempre True
24
+ EditNumeroVinculado.Text := CompletarZeros(FieldByName('numero_vinculado').AsString, 9);
25
+ ...
26
+ if EditNumeroVinculado.Text <> '' then
27
+ ParamByName('cod_filial').AsInteger := StrToInt(FilialVinculada); // StrToInt('')
28
+ ```
29
+
30
+ O `LEFT OUTER JOIN` devolve NULL, `AsString` devolve `''`, e a formatação de exibição **apaga a
31
+ diferença entre "não existe" e "existe com valor zero"**. A guarda deixa de guardar.
32
+
33
+ ## O que fazer
34
+
35
+ A existência se testa pela **chave vinda do dataset**, antes de qualquer formatação:
36
+
37
+ ```pascal
38
+ if (StrToIntDef(FilialVinculada, 0) > 0) and (Trim(SerieVinculada) <> '') then
39
+ ```
40
+
41
+ Se o campo de origem for opcional (`LEFT JOIN`, coluna anulável), prefira `FieldByName(...).IsNull`
42
+ ou a chave crua. E use `StrToIntDef(..., 0)` em vez de `StrToInt` ao converter qualquer valor que
43
+ possa vir de coluna anulável — `StrToInt('')` derruba o fluxo inteiro com uma mensagem que não diz
44
+ nada ao usuário ("'' is not a valid integer value").
45
+
46
+ ## Por que escapa da revisão
47
+
48
+ O teste `<> ''` parece defensivo — é exatamente o que se espera ver ali. A falha só aparece quando
49
+ o registro relacionado **não existe**, e o desenvolvedor testa com o caso em que ele existe. O erro
50
+ costuma chegar pelo suporte, e o mesmo padrão pode estar latente em outro ramo, disparando um UPDATE
51
+ com chave zero em vez de uma exceção.
52
+
53
+ ## Antes de fechar a alteração
54
+
55
+ - Para cada `if <Controle>.Text <> ''` numa guarda de existência, verifique **onde aquele `.Text`
56
+ foi atribuído**. Se houver preenchimento com zeros, `Format` ou máscara no caminho, a guarda está
57
+ quebrada.
58
+ - Teste os **dois** casos: com e sem o registro relacionado. O fluxo feliz não distingue os dois.
59
+ - `grep -n "StrToInt(" <unit>.pas` nos blocos tocados: nenhuma conversão de coluna anulável pode
60
+ usar `StrToInt` sem default.
@@ -0,0 +1,55 @@
1
+ ---
2
+ descricao: "Regra: valor Double nunca é comparado por igualdade com literal decimal — comparar em inteiros ou com tolerância"
3
+ paths:
4
+ - "**/*.pas"
5
+ - "**/*.dpr"
6
+ - "**/*.dpk"
7
+ - "**/*.inc"
8
+ ---
9
+
10
+ # Regra incondicional: valor `Double` nunca é comparado por igualdade com literal decimal
11
+
12
+ Aplica-se a toda comparação de alíquota, percentual, quantidade ou valor lido como `Double` (`AsFloat`, campo
13
+ `Double` de classe, retorno de função) contra um número com casas decimais: `= 0.65`, `= 1.65`, `<> 7.6`, `in`.
14
+
15
+ ## O defeito
16
+
17
+ No dcc32 Win32, o literal `0.65` é avaliado como `Extended` (80 bits). O `Double` lido do banco é a aproximação de 64
18
+ bits do mesmo número. Os dois não são iguais, e a comparação dá falso **sempre**, mesmo com a coluna `numeric(8,2)`
19
+ guardando exatamente `0.65`:
20
+
21
+ ```pascal
22
+ // PROIBIDO: nunca é verdadeiro em Win32 quando Percentual vem de AsFloat
23
+ if (Self.Percentual = 0.65) or (Self.Percentual = 1.65) then
24
+ Result := '01'
25
+ ```
26
+
27
+ O código compila, o ramo errado roda em silêncio e o resultado parece regra de negócio, não bug. Um defeito assim
28
+ pode passar anos em produção gerando o valor errado para todo registro com aquele número exato.
29
+
30
+ ## Padrão obrigatório
31
+
32
+ Compare em inteiros, na escala da coluna, ou com tolerância explícita:
33
+
34
+ ```pascal
35
+ // CERTO: centésimos inteiros (coluna com 2 casas)
36
+ var LPercentualCentesimos := Round(Self.Percentual * 100);
37
+ if (LPercentualCentesimos = 65) or (LPercentualCentesimos = 165) then
38
+
39
+ // CERTO: tolerância explícita
40
+ if SameValue(Self.Percentual, 0.65, 0.0001) then // System.Math
41
+ ```
42
+
43
+ - A comparação com **zero** é segura, porque zero é exato nos dois tipos.
44
+ - `Currency` é decimal de ponto fixo e não tem o problema, mas só quando os **dois** lados são `Currency`.
45
+ - Uma função de arredondamento que devolve `Double` não resolve: arredondar e depois comparar com literal mantém o
46
+ defeito.
47
+
48
+ ## Antes de fechar a alteração
49
+
50
+ ```bash
51
+ grep -nE "(AsFloat|Percentual|Aliquota|Valor)[A-Za-z]*\)? *(=|<>) *[0-9]+\.[0-9]" <unit>.pas
52
+ ```
53
+
54
+ Toda ocorrência entre `Double` e literal decimal usa o padrão acima. Teste com o valor exato do literal, como 0,65, e
55
+ não só com valores vizinhos.
@@ -0,0 +1,84 @@
1
+ ---
2
+ descricao: "Regra incondicional: valor de enum lido no `.dfm` NÃO prova que o identificador está visível — localize a unit que o declara"
3
+ paths:
4
+ - "**/*.pas"
5
+ - "**/*.dpr"
6
+ - "**/*.dpk"
7
+ - "**/*.inc"
8
+ - "**/*.dfm"
9
+ ---
10
+
11
+ # Regra incondicional: valor de enum lido no `.dfm` NÃO prova que o identificador está visível — localize a unit que o declara
12
+
13
+ Aplica-se a toda edição de `.pas` que passe a **atribuir em código** um valor de enumerado (ou
14
+ constante) que até então só era conhecido por aparecer num `.dfm` — típico ao começar a preencher em
15
+ runtime uma propriedade de componente de terceiro (ACBr, ReportBuilder, Rx) que estava definida
16
+ apenas em design-time.
17
+
18
+ ## O `.dfm` guarda o identificador como TEXTO e resolve por RTTI em runtime
19
+
20
+ Quando um `.dfm` traz uma linha como:
21
+
22
+ ```
23
+ Cedente.PIX.TipoChavePIX = tchNenhuma
24
+ ```
25
+
26
+ isso **não** significa que `tchNenhuma` seja alcançável a partir do `uses` daquela unit. O streaming
27
+ da VCL grava o nome do valor como **string** e o converte para o ordinal via **RTTI, em tempo de
28
+ execução** — a unit que **declara** o enum precisa apenas estar **linkada no executável** (o que
29
+ acontece transitivamente, pelo `uses` do próprio componente), **nunca** no `uses` da unit que hospeda
30
+ o `.dfm`.
31
+
32
+ Ou seja: o `.dfm` prova que o valor **existe em algum lugar do projeto**; não prova **nada** sobre
33
+ visibilidade em tempo de compilação. Na primeira linha de código que usar o literal, o build acusa:
34
+
35
+ ```
36
+ [dcc32 Error] E2003 Undeclared identifier: 'tchNenhuma'
37
+ ```
38
+
39
+ O engano é convidativo porque o raciocínio parece sólido ("está no `.dfm` desta unit, logo compila
40
+ aqui") e porque **o erro só aparece na compilação** — nenhuma leitura de código o revela.
41
+
42
+ ## Procedimento obrigatório
43
+
44
+ **Antes** de escrever a primeira atribuição, localize a unit que **declara** o identificador nos
45
+ fontes da biblioteca — não deduza pelo nome da unit "irmã" mais óbvia:
46
+
47
+ ```bash
48
+ # macOS/Linux (com os fontes da biblioteca acessíveis):
49
+ grep -rn "tchNenhuma" "<pasta-dos-fontes-da-biblioteca>" --include="*.pas"
50
+
51
+ # Windows:
52
+ findstr /S /C:"tchNenhuma" <pasta-dos-fontes-da-biblioteca>\*.pas
53
+ ```
54
+
55
+ Acrescente **essa** unit ao `uses` — na `implementation`, se os literais só aparecem no corpo dos
56
+ métodos (o caso normal); na `interface` apenas se o tipo entrar em alguma assinatura.
57
+
58
+ > **Exemplo:** no ACBr, `TACBrPIXTipoChave = (tchNenhuma, tchEmail, tchCPF, tchCNPJ, tchCelular,
59
+ > tchAleatoria)` é declarado em **`ACBrPIXBase.pas`** — **não** em `ACBrBoletoConversao`, que seria o
60
+ > palpite natural por ser a unit de conversões do `ACBrBoleto` e já estar no `uses`. A propriedade que o
61
+ > consome é `TACBrCedentePIX.TipoChavePIX: TACBrPIXTipoChave`, em `ACBrBoleto.pas`.
62
+
63
+ ## Ao adicionar a unit, confirme que os OUTROS builds continuam compilando
64
+
65
+ Quando o mesmo `.pas` é compilado por mais de um projeto (sob `{$ifdef ...}` ou com search paths
66
+ próprios), antes de acrescentar um `uses` **incondicional** verifique se a unit nova já é dependência
67
+ de algo que aqueles projetos inevitavelmente compilam:
68
+
69
+ ```bash
70
+ grep -n "ACBrPIXBase" "<pasta-dos-fontes-da-biblioteca>/ACBrBoleto/ACBrBoleto.pas"
71
+ ```
72
+
73
+ Se o **próprio componente** já faz `uses` dela, todo projeto que compila o componente já tem a unit no
74
+ search path → a inclusão é segura **sem guarda de define**. Se **não** for esse o caso, coloque o
75
+ `uses` sob a mesma guarda condicional usada pelos vizinhos, ou o build de outro projeto quebra sem
76
+ que nada neste repositório o denuncie.
77
+
78
+ ## O sintoma quando esta regra é ignorada
79
+
80
+ Um ciclo de build desperdiçado: a análise de impacto passa, a revisão de código aprova (o identificador
81
+ "existe", afinal), e o `E2003` só aparece quando o usuário compila na IDE — no fim da tarefa, quando
82
+ tudo já parecia entregue. Se o erro citar **todos** os literais de um mesmo enum (e não um ou outro
83
+ nome divergente), a causa é **esta** — falta a unit no `uses` —, e não nome de literal errado por
84
+ diferença de versão da biblioteca.
@@ -0,0 +1,172 @@
1
+ ---
2
+ descricao: "Regra incondicional: antes de criar qualquer rotina utilitária, PROCURE nas bibliotecas compartilhadas e no próprio sistema"
3
+ paths:
4
+ - "**/*.pas"
5
+ - "**/*.dpr"
6
+ - "**/*.dpk"
7
+ - "**/*.inc"
8
+ ---
9
+
10
+ # Regra incondicional: antes de criar qualquer rotina utilitária, PROCURE nas bibliotecas compartilhadas e no próprio sistema
11
+
12
+ Aplica-se a toda criação de `function`/`procedure` **utilitária** — validação de formato, extração,
13
+ máscara, conversão, cálculo de dígito, manipulação de string/data/arquivo — em qualquer `.pas` do
14
+ projeto, seja como método privado de um form, seja como rotina de DataModule. Complementa
15
+ [../dados/cnpj-alfanumerico-nao-extrair-so-numeros.md](../dados/cnpj-alfanumerico-nao-extrair-so-numeros.md).
16
+
17
+ ## A busca é obrigatória e vem ANTES da primeira linha do corpo
18
+
19
+ Escrever o helper leva dois minutos, e é exatamente por isso que ele é escrito sem busca. O custo
20
+ não está na escrita: está no **segundo lugar da verdade** que passa a existir para a mesma pergunta
21
+ — e que ninguém mantém junto quando a regra muda.
22
+
23
+ Ordem obrigatória, do compartilhado para o local:
24
+
25
+ 1. **Mapa do projeto.** Se o `CLAUDE.md`, o `harness-projeto.md` ou outra documentação do projeto lista
26
+ as bibliotecas utilitárias da casa e o que cada uma cobre, comece por ali.
27
+ 2. **Bibliotecas compartilhadas** (units utilitárias usadas por vários sistemas, no search path do
28
+ projeto):
29
+ ```bash
30
+ grep -rnE "^\s*(class )?(function|procedure) [A-Za-z]*<termo>" <pasta-das-bibliotecas> --include="*.pas"
31
+ ```
32
+ 3. **O próprio sistema — como as outras telas resolvem ISTO?**
33
+ ```bash
34
+ grep -rn "<termo>" --include="*.pas" . | head -30
35
+ ```
36
+ 4. **A RTL do Delphi** (`System.SysUtils`, `System.StrUtils`, `System.DateUtils`, `System.Math`,
37
+ `System.IOUtils`, `System.Character`): muita "rotina utilitária" já existe ali.
38
+
39
+ Procure por sinônimos (`SomenteNumeros`, `ExtrairNumeros`, `ApenasDigitos`, `OnlyNumbers`) e em
40
+ português e inglês. O passo 3 é o mais revelador e o mais pulado: mesmo sem função pronta, o
41
+ projeto costuma já ter um **idioma consagrado** para a pergunta, repetido em várias units.
42
+ Reproduzi-lo vale mais do que inventar uma variação.
43
+
44
+ > **Se a unit já tem uma biblioteca utilitária no `uses`, a busca nela é obrigatória sem qualquer
45
+ > desculpa.** A capacidade costuma estar a uma linha de distância, na unit já referenciada.
46
+
47
+ ## Código novo usa as bibliotecas `Fontdata.*`, nunca `BibMarco`
48
+
49
+ Vale para projetos que usam as bibliotecas `Fontdata` (confira se `Fontdata.Utils` ou `Fontdata.MessageDialog`
50
+ aparece no `uses` de alguma unit). Unit nova, e trecho novo dentro de unit legada (handler, rotina, método),
51
+ **não** chamam a `BibMarco`. O equivalente está nas bibliotecas `Fontdata`:
52
+
53
+ | `BibMarco` (legado) | Código novo |
54
+ |---|---|
55
+ | `Mensagem(msg, mtWarning, [mbOk], 0)` | `TMessageDialog.Warning(msg)` |
56
+ | `Mensagem(msg, mtInformation, [mbOk], 0)` | `TMessageDialog.Info(msg)` |
57
+ | `Mensagem(msg, mtError, [mbOk], 0)` | `TMessageDialog.Error(msg)` |
58
+ | `Mensagem(msg, mtConfirmation, [mbYes, mbNo], 0) = mrYes` | `TMessageDialog.Question(msg)` (`Boolean`) |
59
+ | `CompletaZeros(valor, n)` | `TUtils.CompletarZeros(valor, n)` |
60
+ | `ExtrairNumeros(texto)` | `TUtils.ExtrairNumeros(texto)` |
61
+
62
+ - `TMessageDialog` vem de `Fontdata.MessageDialog`, e `TUtils` de `Fontdata.Utils`. Os dois entram no `uses` da
63
+ `implementation`.
64
+ - O legado de uma unit existente **não** é migrado por tabela: só o trecho que a task cria ou reescreve segue o
65
+ padrão novo. A `BibMarco` continua no `uses` enquanto o legado da unit a usar.
66
+ - Função da `BibMarco` sem equivalente em `Fontdata.*` vira pergunta ao usuário. Não recrie a função na unit
67
+ nova.
68
+
69
+ ## Helpers de componente das bibliotecas `Fontdata`
70
+
71
+ Vale para projetos que já têm `Bibliotecas\Helpers` no search path do `.dproj`. Confira antes:
72
+
73
+ ```bash
74
+ grep -n "Bibliotecas\\\\Helpers" *.dproj
75
+ ```
76
+
77
+ As units de helper fazem `uses Fontdata.Utils`, então `Bibliotecas\Utils` também precisa estar no search path.
78
+ Se algum dos caminhos não aparece, **não** acrescente ao `.dproj` por conta própria: pergunte ao usuário.
79
+
80
+ Uma unit por framework, no `uses` da `implementation`:
81
+
82
+ | Framework | Unit | Helpers que ela declara |
83
+ |---|---|---|
84
+ | VCL | `Fontdata.Helpers.VCL` | `TCheckBox`, `TCustomEdit`, `TCustomLabel` |
85
+ | FMX | `Fontdata.Helpers.FMX` | `TCheckBox`, `TSwitch`, `TCustomEdit` |
86
+ | UniGUI | `Fontdata.Helpers.UniGUI` | `TUniCheckBox`, `TUniCustomEdit` |
87
+
88
+ Label só tem helper na VCL. `TSwitch` só na FMX. `Replace` só existe na VCL (edit e label); FMX e UniGUI não têm.
89
+
90
+ | Código manual | Helper | Semântica exata |
91
+ |---|---|---|
92
+ | `StrToCurrDef(Edit.Text, 0)` / `StrToFloat(...)` | `Edit.AsCurrency` / `Edit.AsFloat` | `TUtils.ConverterValor(Text)`: tira `R`, `$` e `%` em qualquer posição, os espaços só das pontas e **todos** os `.`; qualquer `(`, em qualquer posição, torna o valor negativo; vazio vira `0`; depois `StrToFloat` (ver armadilhas) |
93
+ | `StrToIntDef(Edit.Text, 0)` | `Edit.AsInteger` | `StrToIntDef(TUtils.ExtrairNumeros(Text), 0)` |
94
+ | `Edit.Text := CurrToStr(v)` (e `FloatToStr`, `IntToStr`, `DateToStr`, `TimeToStr`, `DateTimeToStr`) | `Edit.AsCurrency := v` (e `AsFloat`, `AsInteger`, `AsDate`, `AsTime`, `AsDateTime`) | o setter chama exatamente essa função da RTL |
95
+ | `StrToDateDef(Edit.Text, Date)` | `Edit.AsDate` | `StrToDateDef(Text, DateOf(Now))` |
96
+ | `StrToTimeDef(Edit.Text, Time)` | `Edit.AsTime` | `StrToTimeDef(Text, TimeOf(Now))` |
97
+ | `StrToDateTimeDef(Edit.Text, Now)` | `Edit.AsDateTime` | `StrToDateTimeDef(Text, Now)` |
98
+ | `Edit.Text = ''` | `Edit.IsEmpty` / `Edit.NotIsEmpty` | compara o texto **sem** `Trim` |
99
+ | `Trim(Edit.Text) = ''` | `Edit.Trim = ''` | **não** é `Edit.IsEmpty`: `' '` não é vazio para `IsEmpty` |
100
+ | `TUtils.ExtrairNumeros(Edit.Text)` | `Edit.ExtractNumbers` | a mesma chamada |
101
+ | `QuotedStr(Edit.Text)` | `Edit.QuotedString` | `String.QuotedString` (aspas simples, duplicando as internas) |
102
+ | `Edit.Text = 'X'` / `Pos('X', Edit.Text) > 0` | `Edit.Equals('X')` / `Edit.Contains('X')` (e `NotEquals`, `NotContains`) | diferencia maiúsculas de minúsculas |
103
+ | `UpperCase`, `LowerCase`, `Copy`, `Length` sobre o texto | `Edit.ToUpper`, `Edit.ToLower`, `Edit.Substring(i[, n])`, `Edit.Length` | métodos de `String`; `Substring` começa em **0**, `Copy` em 1 |
104
+ | `if CheckBox.Checked then 'S' else 'N'` (e o inverso) | `CheckBox.Value` (FMX: também `Switch.Value`) | leitura devolve `'S'`/`'N'`; escrita marca só com `'S'` exato |
105
+ | `StrToCurrDef(Label.Caption, 0)` e afins (só VCL) | `Label.AsCurrency`, `Label.IsEmpty`... | os mesmos métodos do edit, sobre `Caption` |
106
+
107
+ ### Armadilhas
108
+
109
+ - **`AsDate`, `AsTime` e `AsDateTime` não validam.** Texto inválido ou vazio devolve a data de hoje, a hora atual
110
+ ou `Now`, sem erro. Nunca use para validar entrada: valide antes (`TryStrToDate` ou a validação da tela) e só
111
+ depois leia pelo helper.
112
+ - **`AsCurrency` e `AsFloat` levantam exceção.** Ao contrário do que o `Def` do código manual sugere, texto não
113
+ numérico (`'abc'`) gera `EConvertError` do `StrToFloat`; só o vazio vira `0`. E `AsCurrency` passa por `Double`.
114
+ - **Dependem do locale.** `ConverterValor` remove todo `.` (milhar no padrão brasileiro) e deixa a vírgula para o
115
+ `StrToFloat` com o `DecimalSeparator` da máquina: `'1.50'` vira `150`, e numa máquina com separador `.` o
116
+ `'1,50'` falha. Os setters (`CurrToStr`, `DateToStr`...) e `AsDate`/`AsTime` também seguem as configurações
117
+ regionais.
118
+ - **`AsInteger` extrai dígitos antes de converter.** `'-5'` vira `5`, `'1,50'` vira `150`, `'abc'` vira `0`. Não
119
+ serve para número com sinal ou decimal.
120
+ - **`CheckBox.Value := 's'` desmarca.** A comparação com `'S'` diferencia maiúsculas.
121
+ - **Só um class helper por classe vale num escopo**: o da última unit do `uses` vence. Um segundo helper de
122
+ `TCustomEdit` (ou de `TCheckBox`, `TCustomLabel`) no projeto desliga este, e os métodos "somem" sem aviso claro. Um helper de classe descendente (ex.: `TEdit`) também esconde o de
123
+ `TCustomEdit` nas variáveis daquele tipo.
124
+ Antes de criar helper próprio para essas classes, procure os existentes (`grep -rn "class helper for" --include="*.pas" .`).
125
+ - **Nomes que coincidem com outros.** `Edit.Equals('X')` compara texto, não é o `TObject.Equals(Obj)`;
126
+ `Edit.Length` e `Edit.Trim` são do helper e devolvem o tamanho / o texto aparado, não alteram o componente.
127
+ Dentro de um método do form, `Trim(...)` e `Length(...)` sem qualificador continuam sendo da RTL. Leia com atenção.
128
+
129
+ O legado **não** é migrado: só código novo ou reescrito usa o helper, como na tabela de `Fontdata.*` acima. Antes
130
+ de trocar uma conversão manual, compare o caso de borda (vazio, inválido, negativo) conforme a seção seguinte.
131
+
132
+ ## Reaproveitar não é copiar a chamada — é preservar a SEMÂNTICA
133
+
134
+ A rotina existente quase nunca tem exatamente o contrato do helper que você ia escrever. **Compare
135
+ os casos de borda antes de substituir**, um a um: string vazia, `nil`, zero, negativo, acento,
136
+ valor fora de faixa.
137
+
138
+ O caso de borda que costuma divergir é o **vazio**:
139
+
140
+ ```pascal
141
+ // helper local removido: False para vazio
142
+ Result := ATexto <> '';
143
+ if not Result then Exit;
144
+
145
+ // ExtrairNumeros(''): devolve '' — logo ExtrairNumeros(T) = T é TRUE para vazio
146
+ // -> o guard de vazio faz parte da substituição, não é redundância:
147
+ if (Texto <> '') and (ExtrairNumeros(Texto) = Texto) then
148
+ ```
149
+
150
+ Sem esse cuidado, a "simplificação" muda o comportamento em silêncio — e o caminho quebrado é
151
+ justamente o do campo em branco, que o teste do fluxo feliz nunca exercita.
152
+
153
+ ## Quando criar é a resposta certa
154
+
155
+ Criar rotina nova é legítimo quando a busca **foi feita** e mostrou que nada cobre o caso. Nesse
156
+ caso, decida **onde** ela mora antes de escrevê-la:
157
+
158
+ | A rotina serve... | Mora em |
159
+ |---|---|
160
+ | só a esta tela, e depende do estado dela | método privado do próprio form |
161
+ | a este módulo (fiscal, estoque, financeiro) | o DataModule ou a unit do módulo |
162
+ | a qualquer sistema da casa, sem depender deste | a biblioteca compartilhada — **se for outro repositório, exige aprovação do usuário** |
163
+
164
+ Um helper genérico (sem nenhuma dependência do form) nascendo como método privado de um form é
165
+ sinal de que a pergunta de "onde mora" não foi feita.
166
+
167
+ ## Antes de fechar a alteração
168
+
169
+ - Para **cada** rotina nova declarada no diff, registre na resposta **qual busca foi feita** e o que
170
+ ela retornou. "Não encontrei nada" só vale acompanhado do comando que produziu o vazio.
171
+ - Se a rotina nova reproduz um idioma que já existe em outras units, **use o idioma existente** — a
172
+ consistência vale mais que a marginal elegância da versão nova.