enforce: Prohibit all # type: comments in codebase

- Add rule to ESSENTIAL_PROTOCOLS.md prohibiting # type: comments
- Rewrite check_type_ignores to fail on ANY # type: comment (zero tolerance)
- Convert 13 # type: comments in check.py to Python 3.12+ inline annotations
- Remove obsolete type_ignore_baseline.txt (no longer needed)
- Update test description in test_everything

All type annotations must use inline syntax: `x: int = value`
Not comment syntax: `x = value  # type: int`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: thomas-mangin

.claude/ESSENTIAL_PROTOCOLS.md

@@ -256,7 +256,7 @@ uv run pytest tests/unit/specific_test.py::test_function -v
 - Python 3.12+ syntax: `int | str` NOT `Union[int, str]`
 - NO code requiring mypy config changes
 - BGP APIs: keep `negotiated` parameter (stable API, unused OK)
-- Fix type errors at root cause, avoid `# type: ignore`
+- Fix type errors at root cause, NEVER use `# type:` comments
 - `cast()` is acceptable ONLY when preceded by runtime type check (isinstance/hasattr)
   - Example: `if isinstance(x, bool): return cast(T, x)` ✅
   - Example: `return cast(int, value)` without check ❌
@@ -278,6 +278,9 @@ uv run pytest tests/unit/specific_test.py::test_function -v
 ❌ **Prohibited:**
 - `Union[int, str]` instead of `int | str`
 - Adding mypy suppressions or relaxed settings
+- **ANY mypy `# type` comments** - includes `# type: ignore`, `# type: ignore[code]`, `# type: X`
+  - These are workarounds that hide problems instead of fixing them
+  - Fix the actual type issue at its source instead
 - Removing `negotiated` parameter from pack/unpack methods
 - Introducing asyncio (custom reactor pattern used)
 
@@ -307,7 +310,7 @@ When fixing bugs or refactoring code:
 
 ❌ **DON'T:**
 - Use `cast()` to silence type errors without fixing the underlying issue
-- Use `# type: ignore` to suppress valid warnings
+- Use ANY `# type:` comments (ignore, ignore[code], type annotations)
 - Apply workarounds that leave technical debt
 - Choose minimal changes over correct changes
 - Avoid touching other files when the fix belongs there
@@ -556,4 +559,4 @@ Before ending ANY session where you worked on a plan:
 
 ---
 
-**Updated:** 2025-12-15
+**Updated:** 2025-12-18

.claude/settings.local.json

@@ -139,5 +139,6 @@
         ]
       }
     ]
-  }
+  },
+  "outputStyle": "ExaBGP Terse"
 }

qa/bin/check_type_ignores

@@ -1,14 +1,18 @@
 #!/usr/bin/env python3
 """
-Check for type:ignore regression in the codebase.
+Check for prohibited # type: comments in the codebase.
 
-This script counts type:ignore comments and fails if the count increases
-beyond the baseline. Run with --update to set a new baseline.
+This script scans for ANY # type: comments and fails if found.
+All type annotations must use Python 3.12+ inline syntax.
+
+Prohibited patterns:
+  # type: ignore
+  # type: ignore[error-code]
+  # type: SomeType  (Python 2 style annotation)
 
 Usage:
-    ./qa/bin/check_type_ignores          # Check against baseline
-    ./qa/bin/check_type_ignores --update # Update baseline
-    ./qa/bin/check_type_ignores --show   # Show all type:ignore locations
+    ./qa/bin/check_type_ignores          # Check and fail if any found
+    ./qa/bin/check_type_ignores --show   # Show all locations
 """
 
 from __future__ import annotations
@@ -17,32 +21,29 @@ import argparse
 import re
 import sys
 from pathlib import Path
-from typing import Dict, List, Tuple
 
-# Baseline file location
-BASELINE_FILE = Path(__file__).parent.parent / 'type_ignore_baseline.txt'
 SRC_DIR = Path(__file__).parent.parent.parent / 'src' / 'exabgp'
 
-# Pattern to match type: ignore comments
-TYPE_IGNORE_PATTERN = re.compile(r'#\s*type:\s*ignore')
+# Pattern to match ANY # type: comment (ignore, type annotations, etc.)
+TYPE_COMMENT_PATTERN = re.compile(r'#\s*type\s*:')
 
 
-def find_type_ignores() -> Dict[str, List[Tuple[int, str]]]:
-    """Find all type:ignore comments in the codebase."""
-    results: Dict[str, List[Tuple[int, str]]] = {}
+def find_type_comments() -> dict[str, list[tuple[int, str]]]:
+    """Find all # type: comments in the codebase."""
+    results: dict[str, list[tuple[int, str]]] = {}
 
     for py_file in SRC_DIR.rglob('*.py'):
         # Skip vendored files
         if 'vendoring' in str(py_file):
             continue
 
         rel_path = str(py_file.relative_to(SRC_DIR.parent.parent))
-        matches: List[Tuple[int, str]] = []
+        matches: list[tuple[int, str]] = []
 
         try:
             with open(py_file, 'r', encoding='utf-8') as f:
                 for line_num, line in enumerate(f, 1):
-                    if TYPE_IGNORE_PATTERN.search(line):
+                    if TYPE_COMMENT_PATTERN.search(line):
                         matches.append((line_num, line.rstrip()))
         except Exception as e:
             print(f'Error reading {py_file}: {e}', file=sys.stderr)
@@ -54,31 +55,13 @@ def find_type_ignores() -> Dict[str, List[Tuple[int, str]]]:
     return results
 
 
-def count_ignores(results: Dict[str, List[Tuple[int, str]]]) -> int:
-    """Count total number of type:ignore comments."""
+def count_comments(results: dict[str, list[tuple[int, str]]]) -> int:
+    """Count total number of # type: comments."""
     return sum(len(matches) for matches in results.values())
 
 
-def read_baseline() -> int:
-    """Read the baseline count from file."""
-    if not BASELINE_FILE.exists():
-        return -1
-    try:
-        with open(BASELINE_FILE, 'r') as f:
-            return int(f.read().strip())
-    except (ValueError, IOError):
-        return -1
-
-
-def write_baseline(count: int) -> None:
-    """Write the baseline count to file."""
-    with open(BASELINE_FILE, 'w') as f:
-        f.write(f'{count}\n')
-    print(f'Baseline updated: {count} type:ignore comments')
-
-
-def show_ignores(results: Dict[str, List[Tuple[int, str]]]) -> None:
-    """Display all type:ignore locations."""
+def show_comments(results: dict[str, list[tuple[int, str]]]) -> None:
+    """Display all # type: comment locations."""
     for filepath in sorted(results.keys()):
         matches = results[filepath]
         print(f'\n{filepath}:')
@@ -87,44 +70,34 @@ def show_ignores(results: Dict[str, List[Tuple[int, str]]]) -> None:
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser(description='Check type:ignore regression')
-    parser.add_argument('--update', action='store_true', help='Update baseline')
+    parser = argparse.ArgumentParser(description='Check for prohibited # type: comments')
     parser.add_argument('--show', action='store_true', help='Show all locations')
     args = parser.parse_args()
 
-    results = find_type_ignores()
-    current_count = count_ignores(results)
+    results = find_type_comments()
+    current_count = count_comments(results)
 
     if args.show:
-        show_ignores(results)
-        print(f'\nTotal: {current_count} type:ignore comments in {len(results)} files')
-        return 0
-
-    if args.update:
-        write_baseline(current_count)
+        if results:
+            show_comments(results)
+            print(f'\nTotal: {current_count} # type: comments in {len(results)} files')
+        else:
+            print('No # type: comments found')
         return 0
 
-    # Check mode
-    baseline = read_baseline()
-
-    if baseline < 0:
-        print(f'No baseline found. Current count: {current_count}')
-        print('Run with --update to create baseline')
-        return 1
-
-    print(f'type:ignore count: {current_count} (baseline: {baseline})')
-
-    if current_count > baseline:
-        print(f'FAIL: {current_count - baseline} new type:ignore comments added')
+    # Check mode - fail if ANY # type: comments found
+    if current_count > 0:
+        print(f'FAIL: Found {current_count} prohibited # type: comments in {len(results)} files')
+        print()
+        print('All # type: comments are prohibited. Use Python 3.12+ inline annotations instead:')
+        print('  Bad:  x = value  # type: int')
+        print('  Good: x: int = value')
+        print()
         print('Run with --show to see all locations')
         return 1
-    elif current_count < baseline:
-        print(f'IMPROVEMENT: {baseline - current_count} type:ignore comments removed')
-        print('Consider running --update to lower the baseline')
-        return 0
-    else:
-        print('OK: No regression')
-        return 0
+
+    print('OK: No # type: comments found')
+    return 0
 
 
 if __name__ == '__main__':

qa/bin/test_everything

@@ -180,7 +180,7 @@ TEST_DESCRIPTIONS: dict[str, str] = {
     'encoding': 'Functional encoding tests',
     'api': 'Functional API tests',
     'cli': 'Functional CLI tests',
-    'type-ignore': 'Type ignore regression check',
+    'type-ignore': 'Prohibited # type: comments check',
 }
 
 # Ordered list of test names

qa/type_ignore_baseline.txt

@@ -129,12 +129,12 @@ def check_generation(neighbors: dict[str, Neighbor]) -> bool:
             )
             pack1 = packed[0]
 
-            _packed = packed  # type: list[bytes]
-            _pack1 = pack1  # type: bytes
+            _packed: list[bytes] = packed
+            _pack1: bytes = pack1
             log.debug(lazymsg('parsed route requires {count} updates', count=len(_packed)), 'parser')
             log.debug(lazymsg('update size is {size}', size=len(_pack1)), 'parser')
 
-            _str1 = str1  # type: str
+            _str1: str = str1
             log.debug(lazymsg('parsed route {route}', route=_str1), 'parser')
             log.debug(lazymsg('parsed hex   {hex}', hex=od(_pack1)), 'parser')
 
@@ -159,8 +159,8 @@ def check_generation(neighbors: dict[str, Neighbor]) -> bool:
                 str2 = route2.extensive()
                 pack2 = list(UpdateCollection([routed], [], update.attributes).messages(negotiated_out))[0]
 
-                _str2 = str2  # type: str
-                _pack2 = pack2  # type: bytes
+                _str2: str = str2
+                _pack2: bytes = pack2
                 log.debug(lazymsg('recoded route {route}', route=_str2), 'parser')
                 log.debug(lazymsg('recoded hex   {hex}', hex=od(_pack2)), 'parser')
 
@@ -199,8 +199,8 @@ def check_generation(neighbors: dict[str, Neighbor]) -> bool:
                         skip = True
                     else:
                         log.debug(lazymsg('check.strings.different'), 'parser')
-                        _str1r = str1r  # type: str
-                        _str2r = str2r  # type: str
+                        _str1r: str = str1r
+                        _str2r: str = str2r
                         log.debug(lazymsg('[{s}]', s=_str1r), 'parser')
                         log.debug(lazymsg('[{s}]', s=_str2r), 'parser')
                         return False
@@ -211,8 +211,8 @@ def check_generation(neighbors: dict[str, Neighbor]) -> bool:
                     log.debug(lazymsg('check.encoding.skip reason=non_transitive_attributes'), 'parser')
                 elif pack1 != pack2:
                     log.debug(lazymsg('check.encoding.different'), 'parser')
-                    _pack1_cmp = pack1  # type: bytes
-                    _pack2_cmp = pack2  # type: bytes
+                    _pack1_cmp: bytes = pack1
+                    _pack2_cmp: bytes = pack2
                     log.debug(lazymsg('[{hex}]', hex=od(_pack1_cmp)), 'parser')
                     log.debug(lazymsg('[{hex}]', hex=od(_pack2_cmp)), 'parser')
                     return False
@@ -309,7 +309,7 @@ def _make_nlri(neighbor: Neighbor, routes: str) -> list[NLRI]:
     nlris: list[NLRI] = []
     try:
         while announced:
-            _announced = announced  # type: Buffer
+            _announced: Buffer = announced
             log.debug(lazymsg('parsing NLRI {announced}', announced=_announced), 'parser')
             nlri_parsed, announced = NLRI.unpack_nlri(afi, safi, announced, Action.ANNOUNCE, addpath, negotiated_in)
             if nlri_parsed is not NLRI.INVALID:
@@ -318,7 +318,7 @@ def _make_nlri(neighbor: Neighbor, routes: str) -> list[NLRI]:
         log.error(lazymsg('nlri.parse.failed afi={a} safi={s}', a=afi, s=safi), 'parser')
         from exabgp.debug import string_exception
 
-        _exc_nlri = exc  # type: BaseException
+        _exc_nlri: BaseException = exc
         log.error(lazymsg('nlri.parse.error error={msg}', msg=string_exception(_exc_nlri)), 'parser')
         if getenv().debug.pdb:
             raise
@@ -400,7 +400,7 @@ def _make_update(neighbor: Neighbor, raw: bytes) -> UpdateCollection | None:
             if kind == BGP_MSG_UPDATE:
                 log.debug(lazymsg('message.type type=update'), 'parser')
             else:
-                _kind = kind  # type: int
+                _kind: int = kind
                 log.debug(lazymsg('message.type.abort type={kind} expected=update', kind=_kind), 'parser')
                 return None
         else:
@@ -577,6 +577,6 @@ def _get_dummy_negotiated() -> Negotiated:
 
 def check_notification(raw: bytes) -> bool:
     notification = Notification.unpack_message(raw[18:], _get_dummy_negotiated())
-    _notification = notification  # type: Notification
+    _notification: Notification = notification
     log.info(lazymsg('notification.decoded notification={notification}', notification=_notification), 'parser')
     return True