feat(semantic-gate): compare vars BY NAME, and tighten tolerances to 1.00

Counting has a ceiling, and it is lower than it looks: renaming or retyping a
variable keeps the count identical, so the check passes at ANY tolerance --
1.00 included. Measured on a real 27-POU project: renaming one variable left
the count at 62 -> 62 and every count-based check stayed green.

That is the "wrong identifier" class: a name that crosses a boundary and no
longer matches on the other side. It does not raise an error anywhere -- it
just silently returns nothing, which is indistinguishable from "not there yet".

What changed:

- count_st_vars() now returns _var_names, parsed from the declaration
  (`name [, name2] [AT %addr] : type [:= init] ;`).
- count_xml_vars() now returns _var_names from the XML <variable name="...">.
- validate_semantic() emits VARS_MISSING_BY_NAME listing the names declared in
  the ST that are absent from the XML. Identifiers are compared case-folded
  (IEC 61131-3 is case-insensitive) and reported as written.
- Default tolerances 0.75/0.70 -> 1.00/1.00. That 25%/30% slack was never used:
  on the same real project ST and XML match 1:1 on every POU, so 1.00 costs
  zero red and removes room for a real loss to hide in.

Deliberate limit, to avoid false positives: the by-name comparison only runs
when the .st declares exactly ONE POU, because count_st_vars scans the whole
FILE while count_xml_vars scans a single POU. With 2+ POUs the sets are not
comparable, and a gate that cries wolf is a gate that gets skipped.

Proven by mutation, both directions:
- renaming a variable in a real .st: count 62 -> 62 (count-based check blind,
  as predicted), by-name check FAILS naming the variable;
- disabling the by-name comparison in production code: exactly 1 of 19 tests
  fails, and it is the one that asserts the rename -- surgical, not coupled.

Tests: 15 -> 19.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: efranceschetti

python/lib/plcopen_validation/semantic_gate.py

@@ -21,8 +21,13 @@
 
 NS = "{http://www.plcopen.org/xml/tc6_0200}"
 
-DEFAULT_VARS_TOLERANCE = 0.75       # if XML < 75% of the ST vars → fail
-DEFAULT_INITS_TOLERANCE = 0.7       # if XML < 70% of the ST inits → fail
+# Tolerances were 0.75/0.70 — a 25%/30% slack that was never used: measured against a real
+# 27-POU project, ST and XML match 1:1 on every POU, so 1.00 costs zero red and removes room
+# for a real loss to hide in. Note the ceiling of what counting can do: renaming a variable
+# keeps the count identical and passes at ANY tolerance, 1.00 included — that is what the
+# by-name comparison below is for.
+DEFAULT_VARS_TOLERANCE = 1.0        # if the XML has FEWER vars than the ST → fail
+DEFAULT_INITS_TOLERANCE = 1.0       # idem for initial values
 
 
 def count_st_vars(st_path: Path) -> dict[str, Any]:
@@ -77,6 +82,7 @@ def count_st_vars(st_path: Path) -> dict[str, Any]:
     total_vars = 0
     init_vars = 0
     array_init_vars = 0
+    var_names: list[str] = []
     for line in text_clean.splitlines():
         s = line.strip()
         if re.match(r"^VAR(_\w+)?\s*(CONSTANT|RETAIN|PERSISTENT)?\s*$", s, re.IGNORECASE):
@@ -91,9 +97,18 @@ def count_st_vars(st_path: Path) -> dict[str, Any]:
                 init_vars += 1
                 if "[" in s.split(":=")[1] or s.split(":=")[1].strip().startswith("("):
                     array_init_vars += 1
+            # Declared names, for comparison BY NAME (not by count).
+            # IEC 61131-3: `name [, name2] [AT %addr] : type [:= init] ;`
+            decl = s.split(":")[0]
+            decl = re.sub(r"\s+AT\s+%[IQM][XWBD]?[\d.]+", "", decl, flags=re.IGNORECASE)
+            for nome in decl.split(","):
+                nome = nome.strip()
+                if re.match(r"^[A-Za-z_]\w*$", nome):
+                    var_names.append(nome)
     counts["total_var_decls"] = total_vars
     counts["vars_with_init"] = init_vars
     counts["vars_with_array_init"] = array_init_vars
+    counts["_var_names"] = var_names
 
     return dict(counts)
 
@@ -118,6 +133,7 @@ def count_xml_vars(xml_root: etree._Element, pou_name: str) -> dict[str, Any]:
         counts["total_inits"] = 0
         return dict(counts)
 
+    var_names: list[str] = []
     for kind in ["inputVars", "outputVars", "inOutVars", "localVars",
                  "externalVars", "globalVars"]:
         blocks = interface.findall(f"{NS}{kind}")
@@ -128,10 +144,13 @@ def count_xml_vars(xml_root: etree._Element, pou_name: str) -> dict[str, Any]:
             vars_in_block = block.findall(f"{NS}variable")
             var_count += len(vars_in_block)
             for v in vars_in_block:
+                if v.get("name"):
+                    var_names.append(v.get("name"))
                 if v.find(f"{NS}initialValue") is not None:
                     init_count += 1
         counts[f"{kind}_var_count"] = var_count
         counts[f"{kind}_init_count"] = init_count
+    counts["_var_names"] = var_names
 
     counts["total_vars"] = sum(v for k, v in counts.items() if k.endswith("_var_count"))
     counts["total_inits"] = sum(v for k, v in counts.items() if k.endswith("_init_count"))
@@ -207,6 +226,29 @@ def validate_semantic(
             st_total = st_counts.get("total_var_decls", 0)
             xml_total = xml_counts.get("total_vars", 0)
 
+            # Comparison BY NAME — catches what counting never will: a renamed or
+            # retyped variable keeps the count identical and slips through every
+            # tolerance level. Only runs when the .st declares exactly ONE POU,
+            # because count_st_vars scans the whole FILE while count_xml_vars scans a
+            # single POU; with 2+ POUs the sets are not comparable and we would emit
+            # false positives — and a gate that cries wolf is a gate that gets skipped.
+            if len(pou_names) == 1:
+                st_names = st_counts.get("_var_names") or []
+                xml_names = xml_counts.get("_var_names") or []
+                # IEC 61131-3 identifiers are case-insensitive; compare folded, report as written.
+                xml_fold = {n.lower() for n in xml_names}
+                faltando = [n for n in st_names if n.lower() not in xml_fold]
+                if faltando:
+                    amostra = ", ".join(faltando[:8])
+                    resto = f" (+{len(faltando) - 8})" if len(faltando) > 8 else ""
+                    errors.append(ValidationError(
+                        line=None,
+                        location=f"{st.name}::{pou_name}",
+                        code="VARS_MISSING_BY_NAME",
+                        message=(f"{len(faltando)} var(s) declared in the ST are absent from the "
+                                 f"XML by name: {amostra}{resto}"),
+                    ))
+
             if st_total > 0 and xml_total < st_total * vars_tolerance:
                 pct = (xml_total * 100 // st_total) if st_total else 0
                 errors.append(ValidationError(

python/tests/test_semantic_gate.py

@@ -231,3 +231,106 @@ def test_semantic_source_dir_inexistente(tmp_path: Path) -> None:
     report = validate_semantic(xml, tmp_path / "no_src")
     assert not report.valid
     assert report.errors[0].code == "DIR_NOT_FOUND"
+
+
+# ─────────────────────── comparison BY NAME (not by count) ────────────────
+#
+# Counting has a ceiling: a renamed or retyped variable keeps the count identical and
+# passes at ANY tolerance, 1.00 included. Measured on a real 27-POU project: renaming a
+# single variable inside one POU left the count at 62 → 62 and every count-based check
+# stayed green. These tests pin the by-name comparison that does catch it.
+
+
+def test_count_st_vars_coleta_os_nomes_declarados(tmp_path: Path) -> None:
+    """Names come from the declaration: with AT %, and several per line."""
+    st = tmp_path / "PRG_N.st"
+    st.write_text("""PROGRAM PRG_N
+VAR
+    bStart AT %IX0.0 : BOOL;
+    iA, iB, iC : INT;
+    rValue : REAL := 3.14;
+END_VAR
+iA := 1;
+END_PROGRAM""", encoding="utf-8")
+    nomes = count_st_vars(st)["_var_names"]
+    assert nomes == ["bStart", "iA", "iB", "iC", "rValue"], nomes
+
+
+def test_semantic_detecta_rename_que_a_contagem_nao_ve(tmp_path: Path) -> None:
+    """The whole point: same count, different name. This is the 'wrong tag' class —
+    an identifier that crosses a boundary and no longer matches on the other side."""
+    src = _make_source_dir(tmp_path, {"PRG_X.st": """PROGRAM PRG_X
+VAR
+    iA : INT;
+    iRENOMEADA : INT;
+    iC : INT;
+END_VAR
+iA := 1;
+END_PROGRAM"""})
+    # XML still carries the OLD name — count matches (3 = 3), name does not
+    vars_xml = "".join([
+        f'<variable name="i{n}"><type><INT/></type></variable>' for n in ("A", "B", "C")
+    ])
+    xml = _make_xml_with_pou(tmp_path, "PRG_X", vars_xml=vars_xml)
+
+    report = validate_semantic(xml, src)
+    assert not report.valid, "a rename with matching count must NOT pass"
+    erro = next(e for e in report.errors if e.code == "VARS_MISSING_BY_NAME")
+    assert "iRENOMEADA" in erro.message, erro.message
+    # and prove the count-based check was blind to it, even at the strictest tolerance
+    assert not any(e.code == "VARS_MISSING" for e in report.errors)
+
+
+def test_semantic_by_name_ignora_caixa(tmp_path: Path) -> None:
+    """IEC 61131-3 identifiers are case-insensitive: iValue == IVALUE."""
+    src = _make_source_dir(tmp_path, {"PRG_X.st": """PROGRAM PRG_X
+VAR
+    iValue : INT;
+END_VAR
+iValue := 1;
+END_PROGRAM"""})
+    xml = _make_xml_with_pou(
+        tmp_path, "PRG_X", vars_xml='<variable name="IVALUE"><type><INT/></type></variable>')
+    report = validate_semantic(xml, src)
+    assert report.valid, [e.message for e in report.errors]
+
+
+def test_semantic_by_name_nao_dispara_com_dois_pous_no_arquivo(tmp_path: Path) -> None:
+    """count_st_vars scans the whole FILE, count_xml_vars scans ONE POU: with 2+ POUs the
+    sets are not comparable, and a false positive here would teach people to skip the gate."""
+    src = _make_source_dir(tmp_path, {"DOIS.st": """PROGRAM PRG_A
+VAR
+    iDoA : INT;
+END_VAR
+iDoA := 1;
+END_PROGRAM
+
+PROGRAM PRG_B
+VAR
+    iDoB : INT;
+END_VAR
+iDoB := 1;
+END_PROGRAM"""})
+    xml = tmp_path / "dois.xml"
+    xml.write_text('''<?xml version="1.0" encoding="utf-8"?>
+<project xmlns="http://www.plcopen.org/xml/tc6_0200" xmlns:xhtml="http://www.w3.org/1999/xhtml">
+  <fileHeader companyName="" productName="X" productVersion="X" creationDateTime="2026-01-01T00:00:00"/>
+  <contentHeader name="t" modificationDateTime="2026-01-01T00:00:00">
+    <coordinateInfo><fbd><scaling x="1" y="1"/></fbd><ld><scaling x="1" y="1"/></ld><sfc><scaling x="1" y="1"/></sfc></coordinateInfo>
+  </contentHeader>
+  <types><dataTypes/><pous>
+    <pou name="PRG_A" pouType="program">
+      <interface><localVars><variable name="iDoA"><type><INT/></type></variable></localVars></interface>
+      <body><ST><xhtml:p><![CDATA[(* x *)]]></xhtml:p></ST></body>
+    </pou>
+    <pou name="PRG_B" pouType="program">
+      <interface><localVars><variable name="iDoB"><type><INT/></type></variable></localVars></interface>
+      <body><ST><xhtml:p><![CDATA[(* x *)]]></xhtml:p></ST></body>
+    </pou>
+  </pous></types>
+  <instances><configurations/></instances>
+</project>''', encoding="utf-8")
+
+    report = validate_semantic(xml, src)
+    assert not any(e.code == "VARS_MISSING_BY_NAME" for e in report.errors), \
+        "must not compare names when the file declares more than one POU"