fix(required_arg_missing): suppress calls inside if __name__ == "__main__" blocks

Entry-point calls like `if __name__ == "__main__": main()` are called with
no args because argparse/click reads from sys.argv inside the function body.
These 16 violations in ray-project/ray CI scripts were all this pattern.

Also suppresses cross-file name collisions where a local main() with no
required args is matched to an unrelated main(required_arg) elsewhere.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Your Name

extractor.py

@@ -76,6 +76,7 @@ class CallSite:
     is_method_call: bool = False  # True when call is obj.method(...) — receiver is implicit
     has_var_args: bool = False   # True when call uses *args spread — positional coverage unknown
     has_var_kwargs: bool = False  # True when call uses **kwargs spread — kwarg coverage unknown
+    is_in_main_block: bool = False  # True when inside `if __name__ == "__main__":` body
     model_name: Optional[str] = None
     caller_name: Optional[str] = (
         None  # qualified name of the enclosing function, if any
@@ -414,6 +415,7 @@ def __init__(self, file_path: str) -> None:
         self.call_sites: list[CallSite] = []
         self._class_stack: list[str] = []  # class names (mirrors _FunctionVisitor)
         self._func_stack: list[str] = []  # qualified function names within classes
+        self._in_main_block: bool = False  # inside `if __name__ == "__main__":` body
 
     def visit_ClassDef(self, node: ast.ClassDef) -> None:
         self._class_stack.append(node.name)
@@ -430,6 +432,32 @@ def _enter_func(self, node):
     visit_FunctionDef = _enter_func
     visit_AsyncFunctionDef = _enter_func
 
+    def visit_If(self, node: ast.If) -> None:
+        # Detect `if __name__ == "__main__":` (both orderings of the comparison)
+        def _is_main_guard(test):
+            if not isinstance(test, ast.Compare):
+                return False
+            if len(test.ops) != 1 or not isinstance(test.ops[0], ast.Eq):
+                return False
+            lhs, rhs = test.left, test.comparators[0]
+            def _is_dunder_name(n): return isinstance(n, ast.Name) and n.id == "__name__"
+            def _is_main_str(n): return isinstance(n, ast.Constant) and n.value == "__main__"
+            return (_is_dunder_name(lhs) and _is_main_str(rhs)) or (
+                _is_main_str(lhs) and _is_dunder_name(rhs)
+            )
+
+        if _is_main_guard(node.test):
+            old = self._in_main_block
+            self._in_main_block = True
+            for stmt in node.body:
+                self.visit(stmt)
+            self._in_main_block = old
+            # else branch is not a __main__ guard
+            for stmt in node.orelse:
+                self.visit(stmt)
+        else:
+            self.generic_visit(node)
+
     def visit_Call(self, node: ast.Call) -> None:
         site = self._make_site(node)
         if site:
@@ -490,6 +518,7 @@ def _make_site(self, node: ast.Call) -> Optional[CallSite]:
                 caller_name=caller,
                 has_var_args=has_var_args,
                 has_var_kwargs=has_var_kwargs,
+                is_in_main_block=self._in_main_block,
             )
         return None
 

failure_mode.py

@@ -472,6 +472,10 @@ def _check_required_arg(
     # calling main() with no args reads from sys.argv. Not a missing-arg bug.
     if func.is_click_command:
         return []
+    # `if __name__ == "__main__": main()` — entry point call, args come from
+    # the runtime / argparse inside the function body, not the call site.
+    if call.is_in_main_block:
+        return []
     # Only non-kwonly required args can be covered by positional args.
     # Enumerate positional-only required args separately so a kwonly arg at
     # index i is never falsely marked covered because positional_count > i.

test_checker.py

@@ -2051,3 +2051,41 @@ async def _prepare_request(self, method: str) -> dict:
     violations = check_codebase(tmp_path)
     ma = [v for v in violations if v.context == "missing_await" and "clients.py" in v.file]
     assert len(ma) == 0, f"Expected 0 missing_await for dual sync/async client, got {len(ma)}: {[(v.line, v.call) for v in ma]}"
+
+
+def test_main_in_dunder_main_block_not_flagged(tmp_path):
+    """`if __name__ == "__main__": main()` must not be flagged as required_arg_missing."""
+    _write_src(
+        tmp_path,
+        "cli_tool.py",
+        """
+        import argparse
+
+        def main(config: str, verbose: bool = False) -> None:
+            print(config, verbose)
+
+        if __name__ == "__main__":
+            main()
+        """,
+    )
+    violations = check_codebase(tmp_path)
+    ra = [v for v in violations if v.context == "required_arg_missing" and "cli_tool.py" in v.file]
+    assert len(ra) == 0, f"Expected 0 required_arg_missing in __main__ block, got {len(ra)}: {[(v.line, v.call) for v in ra]}"
+
+
+def test_main_called_outside_dunder_block_still_flagged(tmp_path):
+    """The same missing-arg call outside __main__ block IS a real bug."""
+    _write_src(
+        tmp_path,
+        "caller.py",
+        """
+        def main(config: str) -> None:
+            print(config)
+
+        def run_pipeline():
+            main()  # missing required arg — real bug
+        """,
+    )
+    violations = check_codebase(tmp_path)
+    ra = [v for v in violations if v.context == "required_arg_missing" and "caller.py" in v.file]
+    assert len(ra) == 1, f"Expected 1 required_arg_missing outside __main__ block, got {len(ra)}"