plugadvpl 0.3.4__tar.gz → 0.3.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugadvpl
-Version: 0.3.4
+Version: 0.3.6
 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.4 → plugadvpl-0.3.6}/plugadvpl/_version.py

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

{plugadvpl-0.3.4 → plugadvpl-0.3.6}/plugadvpl/lookups/lint_rules.json

@@ -90,10 +90,11 @@
     "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.",
+    "descricao": "Declarar variável Local/Static/Private/Public com nome de Public reservada do framework Protheus faz shadowing — sua função enxerga `\"\"`/`Nil` em vez do valor real. Cobertas (case-insensitive): `cFilAnt`, `cEmpAnt`, `cUserName`, `cModulo`, `cTransac`, `nProgAnt`, `oMainWnd`, `__cInternet`, `nUsado`, `PARAMIXB`, `aRotina`, `lMsErroAuto`, `lMsHelpAuto`. Detecta também declarações multi-var (`Local cVar1, cFilAnt, cVar2`) e TLPP-typed (`Local cFilAnt as character`).",
+    "fix_guidance": "Renomeie a variável local pra algo distinto (prefixo cliente, ex: `cMinhaFilial`). NUNCA crie Local/Private/Public/Static com o mesmo nome de uma reservada framework — não há motivo legítimo de override em código custom.",
     "detection_kind": "regex",
-    "status": "planned"
+    "status": "active",
+    "impl_function": "_check_bp008_shadowed_reserved"
   },
   {
     "regra_id": "SEC-001",
@@ -192,13 +193,14 @@
   },
   {
     "regra_id": "PERF-005",
-    "titulo": "RecCount() > 0 para checar existência (use !Eof())",
+    "titulo": "RecCount() 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.",
+    "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`/`DbGoTop` é O(1). A regra detecta os padrões `RecCount() > 0`, `RecCount() >= 1`, `RecCount() != 0` e `RecCount() <> 0` (legacy), incluindo variante com alias-call `SA1->(RecCount()) > 0`. NÃO sinaliza limites de business reais (`RecCount() > 100`) nem armazenamento (`nTotal := RecCount()`).",
+    "fix_guidance": "Substitua `If RecCount() > 0` por `If !Eof()` ou `If !<alias>->(Eof())`. Em SQL embarcado, use `SELECT COUNT(*) FROM ... LIMIT 1` ou subquery `WHERE EXISTS (...)`.",
     "detection_kind": "regex",
-    "status": "planned"
+    "status": "active",
+    "impl_function": "_check_perf005_reccount_for_existence"
   },
   {
     "regra_id": "PERF-006",

{plugadvpl-0.3.4 → plugadvpl-0.3.6}/plugadvpl/parsing/lint.py

@@ -673,11 +673,134 @@ def _check_mod002_public_declaration(
     return findings
 
 
+# --- BP-008: shadowing de variável reservada -------------------------------
+
+# Variáveis Public criadas pelo framework Protheus que NÃO devem ser declaradas
+# como Local/Static/Private/Public em fonte custom. Comparação é case-insensitive
+# (ADVPL trata identificadores assim).
+_BP008_RESERVED_VARS: frozenset[str] = frozenset(
+    name.upper()
+    for name in (
+        # Contexto de empresa/filial/usuario
+        "cFilAnt", "cEmpAnt", "cUserName", "cModulo", "cTransac", "nProgAnt",
+        # Janela principal e flags de execucao
+        "oMainWnd", "__cInternet", "nUsado",
+        # PE / MVC / ExecAuto
+        "PARAMIXB", "aRotina", "lMsErroAuto", "lMsHelpAuto",
+    )
+)
+
+# Detecta declaração: linha começa com (Local|Static|Private|Public) seguido de
+# pelo menos um identificador. Captura group 1 = keyword, group 2 = resto da linha.
+_BP008_DECL_RE = re.compile(
+    r"^[ \t]*(Local|Static|Private|Public)\b[ \t]+(.+)$",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+# Em "cVar1, cFilAnt, cVar2 := 'x' as character", separadores são vírgula top-level.
+# Pra cada peça, o identificador é o primeiro token alfanumérico (antes de :=, as, espaço).
+_BP008_VAR_RE = re.compile(r"^[ \t]*([A-Za-z_][A-Za-z0-9_]*)")
+
+
+def _check_bp008_shadowed_reserved(
+    arquivo: str, parsed: dict[str, Any], content: str
+) -> list[dict[str, Any]]:
+    """BP-008 (critical): Local/Static/Private/Public com nome de variável reservada framework.
+
+    Declarar variável local com nome de Public reservada (cFilAnt, cEmpAnt, PARAMIXB, etc.)
+    faz shadowing — sua função enxerga "" / Nil em vez do valor real do framework.
+    Bug clássico: programador declara `Local cFilAnt := ""` no início e depois usa cFilAnt
+    achando que tem o valor da filial atual.
+    """
+    findings: list[dict[str, Any]] = []
+    stripped = strip_advpl(content, strip_strings=True)
+    funcoes = parsed.get("funcoes", []) or []
+
+    for m_decl in _BP008_DECL_RE.finditer(stripped):
+        keyword = m_decl.group(1)
+        rest = m_decl.group(2)
+        # Split por vírgula top-level (declarações ADVPL não têm vírgulas dentro de
+        # argumentos de função aqui, pois é só lado esquerdo de declaração).
+        for piece in rest.split(","):
+            m_var = _BP008_VAR_RE.match(piece)
+            if not m_var:
+                continue
+            var_name = m_var.group(1)
+            if var_name.upper() not in _BP008_RESERVED_VARS:
+                continue
+            # Match — calcula linha + funcao + snippet
+            offset = m_decl.start()
+            linha = _line_at(stripped, offset)
+            funcao = _funcao_at_line(funcoes, linha)
+            findings.append(
+                {
+                    "arquivo": arquivo,
+                    "funcao": funcao,
+                    "linha": linha,
+                    "regra_id": "BP-008",
+                    "severidade": "critical",
+                    "snippet": _snippet_at_line(content, linha),
+                    "sugestao_fix": (
+                        f"`{keyword} {var_name}` faz shadowing da variável reservada "
+                        f"`{var_name}` do framework Protheus. Renomeie para algo distinto "
+                        f"(ex: prefixo cliente). Toda função vê valor vazio em vez do real."
+                    ),
+                }
+            )
+    return findings
+
+
+# --- PERF-005: RecCount() para checar existência ---------------------------
+
+# Detecta `RecCount() > 0`, `RecCount() >= 1`, `RecCount() != 0`, `RecCount() <> 0`
+# (com ou sem alias-call `SA1->(RecCount())`). NÃO detecta:
+# - `RecCount() > 100` (limite específico, intencional)
+# - `nTotal := RecCount()` (armazena, não checa)
+# Padrão de comparação: > 0, >= 1, != 0, <> 0 (case-insensitive operadores).
+_PERF005_RE = re.compile(
+    r"\bRecCount\s*\(\s*\)\s*\)?\s*"        # RecCount() possivelmente fechando alias->()
+    r"(?:>\s*0(?!\d)|>=\s*1(?!\d)|!=\s*0(?!\d)|<>\s*0(?!\d))",
+    re.IGNORECASE,
+)
+
+
+def _check_perf005_reccount_for_existence(
+    arquivo: str, parsed: dict[str, Any], content: str
+) -> list[dict[str, Any]]:
+    """PERF-005 (warning): RecCount() > 0 / >= 1 / != 0 / <> 0 para checar existência.
+
+    RecCount() força full scan do alias. Para apenas verificar se existe pelo
+    menos 1 registro, ``!Eof()`` após DbSeek/DbGoTop é O(1).
+    """
+    findings: list[dict[str, Any]] = []
+    stripped = strip_advpl(content, strip_strings=True)
+    funcoes = parsed.get("funcoes", []) or []
+
+    for m in _PERF005_RE.finditer(stripped):
+        linha = _line_at(stripped, m.start())
+        funcao = _funcao_at_line(funcoes, linha)
+        findings.append(
+            {
+                "arquivo": arquivo,
+                "funcao": funcao,
+                "linha": linha,
+                "regra_id": "PERF-005",
+                "severidade": "warning",
+                "snippet": _snippet_at_line(content, linha),
+                "sugestao_fix": (
+                    "RecCount() força full scan da tabela. Para checar existência, "
+                    "use !Eof() após DbSeek/DbGoTop (O(1)) ou subquery EXISTS em SQL."
+                ),
+            }
+        )
+    return findings
+
+
 # --- Orchestrator -------------------------------------------------------------
 
 
 def lint_source(parsed: dict[str, Any], content: str) -> list[dict[str, Any]]:
-    """Aplica as 13 regras single-file. Retorna list[Finding] ordenada por linha.
+    """Aplica as 15 regras single-file. Retorna list[Finding] ordenada por linha.
 
     Args:
         parsed: dict produzido por parse_source() (com funcoes, sql_embedado, etc.).
@@ -695,11 +818,13 @@ def lint_source(parsed: dict[str, Any], content: str) -> list[dict[str, Any]]:
     findings.extend(_check_bp004_pergunte_no_check(arquivo, parsed, content))
     findings.extend(_check_bp005_too_many_params(arquivo, parsed, content))
     findings.extend(_check_bp006_mixed_reclock_rawapi(arquivo, parsed, content))
+    findings.extend(_check_bp008_shadowed_reserved(arquivo, parsed, content))
     findings.extend(_check_sec001_rpcsetenv_in_restful(arquivo, parsed, content))
     findings.extend(_check_sec002_user_function_no_prefix(arquivo, parsed, content))
     findings.extend(_check_perf001_select_star(arquivo, parsed, content))
     findings.extend(_check_perf002_no_notdel(arquivo, parsed, content))
     findings.extend(_check_perf003_no_xfilial(arquivo, parsed, content))
+    findings.extend(_check_perf005_reccount_for_existence(arquivo, parsed, content))
     findings.extend(_check_mod001_conout_instead_fwlogmsg(arquivo, parsed, content))
     findings.extend(_check_mod002_public_declaration(arquivo, parsed, content))
 

{plugadvpl-0.3.4 → plugadvpl-0.3.6}/tests/unit/test_lint.py

@@ -447,3 +447,255 @@ class TestLintSourceIntegration:
         )
         findings = lint_source(_parsed_for(src), src)
         assert findings == []
+
+
+# --- BP-008: shadowing de variável reservada framework ----------------------
+
+
+class TestBP008ShadowedReserved:
+    """BP-008 (critical): Local/Static/Private/Public com nome de reservada TOTVS."""
+
+    def test_positive_local_cFilAnt(self) -> None:
+        src = (
+            "User Function XYZBad()\n"
+            "    Local cFilAnt := '01'\n"   # shadow!
+            "    ConOut(cFilAnt)\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        bp008 = [f for f in findings if f["regra_id"] == "BP-008"]
+        assert len(bp008) == 1
+        assert bp008[0]["severidade"] == "critical"
+        assert "cFilAnt" in bp008[0]["snippet"] or "cFilAnt" in bp008[0]["sugestao_fix"]
+
+    def test_positive_static_cEmpAnt_case_insensitive(self) -> None:
+        src = (
+            "User Function XYZBad()\n"
+            "    static CEMPANT := ''\n"   # ADVPL is case-insensitive
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "BP-008" in _ids(findings)
+
+    def test_positive_private_lMsErroAuto(self) -> None:
+        src = (
+            "User Function XYZBad()\n"
+            "    Private lMsErroAuto := .F.\n"   # reserved exec auto flag
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "BP-008" in _ids(findings)
+
+    def test_positive_public_PARAMIXB(self) -> None:
+        src = (
+            "User Function XYZBad()\n"
+            "    Public PARAMIXB := {}\n"   # PE arg array, never override
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "BP-008" in _ids(findings)
+
+    def test_positive_multi_var_decl(self) -> None:
+        """Local cVar1, cFilAnt, cVar2 := ... — BP-008 pega o cFilAnt no meio."""
+        src = (
+            "User Function XYZBad()\n"
+            "    Local cVar1, cFilAnt, cVar2 := 'x'\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "BP-008" in _ids(findings)
+
+    def test_positive_tlpp_typed_decl(self) -> None:
+        """Local cFilAnt as character — TLPP type annotation, ainda shadow."""
+        src = (
+            "User Function XYZBad()\n"
+            "    Local cFilAnt as character\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "BP-008" in _ids(findings)
+
+    def test_negative_similar_name(self) -> None:
+        """cFilAntiga não é cFilAnt — não deve match."""
+        src = (
+            "User Function XYZGood()\n"
+            "    Local cFilAntiga := '01'\n"
+            "    Local cFilAntx   := '02'\n"
+            "    Local nProgAntx  := 0\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "BP-008" not in _ids(findings)
+
+    def test_negative_reserved_in_string(self) -> None:
+        """'cFilAnt' dentro de string literal não deve match."""
+        src = (
+            "User Function XYZGood()\n"
+            "    Local cMsg := 'cFilAnt is reserved'\n"
+            "    ConOut(cMsg)\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "BP-008" not in _ids(findings)
+
+    def test_negative_reserved_in_comment(self) -> None:
+        """// Local cFilAnt não deve match."""
+        src = (
+            "User Function XYZGood()\n"
+            "    // Local cFilAnt — comentario explicativo\n"
+            "    Local cMinhaVar := '01'\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "BP-008" not in _ids(findings)
+
+    def test_negative_use_without_declare(self) -> None:
+        """Usar cFilAnt sem declarar como Local NÃO é shadow — é uso correto."""
+        src = (
+            "User Function XYZGood()\n"
+            "    ConOut('Filial atual: ' + cFilAnt)\n"
+            "    DbSelectArea('SA1')\n"
+            "    DbSeek(xFilial('SA1') + cFilAnt)\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "BP-008" not in _ids(findings)
+
+    def test_positive_reports_correct_line(self) -> None:
+        """Snippet/linha apontam pra linha correta."""
+        src = (
+            "User Function XYZBad()\n"   # 1
+            "    Local cVarOk := '01'\n" # 2
+            "    Local cEmpAnt := '99'\n"  # 3 — shadow aqui
+            "Return\n"                   # 4
+        )
+        findings = lint_source(_parsed_for(src), src)
+        bp008 = [f for f in findings if f["regra_id"] == "BP-008"]
+        assert len(bp008) == 1
+        assert bp008[0]["linha"] == 3
+
+
+# --- PERF-005: RecCount() para checar existência ---------------------------
+
+
+class TestPERF005ReccountForExistence:
+    """PERF-005 (warning): RecCount() > 0 / >= 1 / != 0 / <> 0 — use !Eof()."""
+
+    def test_positive_reccount_gt_zero(self) -> None:
+        src = (
+            "User Function XYZBad()\n"
+            "    DbSelectArea('SA1')\n"
+            "    DbGoTop()\n"
+            "    If RecCount() > 0\n"   # full scan
+            "        ConOut('tem')\n"
+            "    EndIf\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        perf = [f for f in findings if f["regra_id"] == "PERF-005"]
+        assert len(perf) == 1
+        assert perf[0]["severidade"] == "warning"
+
+    def test_positive_reccount_gte_one(self) -> None:
+        src = (
+            "User Function XYZBad()\n"
+            "    If RecCount() >= 1\n"
+            "    EndIf\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "PERF-005" in _ids(findings)
+
+    def test_positive_reccount_neq_zero(self) -> None:
+        src = (
+            "User Function XYZBad()\n"
+            "    If RecCount() != 0\n"
+            "    EndIf\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "PERF-005" in _ids(findings)
+
+    def test_positive_reccount_diff_legacy(self) -> None:
+        """ADVPL legacy != é <> — também detecta."""
+        src = (
+            "User Function XYZBad()\n"
+            "    If RecCount() <> 0\n"
+            "    EndIf\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "PERF-005" in _ids(findings)
+
+    def test_positive_alias_call(self) -> None:
+        """SA1->(RecCount()) > 0 também é o anti-pattern."""
+        src = (
+            "User Function XYZBad()\n"
+            "    If SA1->(RecCount()) > 0\n"
+            "    EndIf\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "PERF-005" in _ids(findings)
+
+    def test_negative_reccount_specific_threshold(self) -> None:
+        """RecCount() > 100 (limite de business, intencional) NÃO é PERF-005."""
+        src = (
+            "User Function XYZGood()\n"
+            "    If RecCount() > 100\n"
+            "        ConOut('muitos')\n"
+            "    EndIf\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "PERF-005" not in _ids(findings)
+
+    def test_negative_reccount_assignment(self) -> None:
+        """nTotal := RecCount() — só armazena, não checa existência."""
+        src = (
+            "User Function XYZGood()\n"
+            "    Local nTotal := RecCount()\n"
+            "    ConOut(cValToChar(nTotal))\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "PERF-005" not in _ids(findings)
+
+    def test_negative_reccount_in_string(self) -> None:
+        """'RecCount() > 0' dentro de string não match."""
+        src = (
+            "User Function XYZGood()\n"
+            "    Local cMsg := 'Use RecCount() > 0 com cuidado'\n"
+            "    ConOut(cMsg)\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "PERF-005" not in _ids(findings)
+
+    def test_negative_reccount_in_comment(self) -> None:
+        """// RecCount() > 0 — comentário não match."""
+        src = (
+            "User Function XYZGood()\n"
+            "    // RecCount() > 0 era usado em codigo legado\n"
+            "    If !Eof()\n"
+            "        ConOut('tem')\n"
+            "    EndIf\n"
+            "Return\n"
+        )
+        findings = lint_source(_parsed_for(src), src)
+        assert "PERF-005" not in _ids(findings)
+
+    def test_positive_reports_correct_line(self) -> None:
+        src = (
+            "User Function XYZBad()\n"   # 1
+            "    DbSelectArea('SA1')\n"  # 2
+            "    DbGoTop()\n"             # 3
+            "    If RecCount() > 0\n"     # 4 — match
+            "    EndIf\n"                 # 5
+            "Return\n"                    # 6
+        )
+        findings = lint_source(_parsed_for(src), src)
+        perf = [f for f in findings if f["regra_id"] == "PERF-005"]
+        assert len(perf) == 1
+        assert perf[0]["linha"] == 4
+        assert "Eof" in perf[0]["sugestao_fix"]

{plugadvpl-0.3.4 → plugadvpl-0.3.6}/tests/unit/test_lint_catalog_consistency.py

@@ -63,21 +63,29 @@ def impl() -> dict[str, dict[str, str]]:
     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_catalog_has_minimum_total(catalog: dict) -> None:
+    """Sanity check: catálogo deve ter pelo menos 35 regras (mais é OK, menos não)."""
+    assert len(catalog) >= 35, (
+        f"catálogo encolheu: encontrou {len(catalog)} regras, mínimo esperado 35. "
+        "Não remova regras planned sem ticket de discussão."
     )
 
 
 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."""
+    """Toda regra active no catálogo deve ter `_check_*` correspondente em lint.py.
+
+    Test dinâmico (não hardcoded): quantos active no JSON deve == quantos
+    `_check_*` em lint.py. Não precisa atualizar quando promove planned→active.
+    """
     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."
+    assert n_active == len(impl), (
+        f"catalog active={n_active}, impl _check_*={len(impl)} — "
+        f"toda regra active precisa ter _check_* correspondente, e vice-versa"
+    )
+    # Sanity floor: nunca deve cair abaixo do baseline conhecido (v0.3.4 = 24).
+    assert len(impl) >= 24, (
+        f"esperava pelo menos 24 funções _check_*, encontrou {len(impl)}. "
+        "Regrediu? Verifique se algum detector foi removido sem aviso."
     )