PR-1.4: Scanner Interface + Registry (~110 LOC + 100 tests)

[xiaoqi-7]

Summary

Phase 1.4: Extensible scanner architecture for pattern detection. Defines the base Scanner interface and a registry system for managing multiple scanner implementations.

Components

ScanResult Dataclass

• Immutable result object with fields: scanner_name, pattern, found, match_index, match_text
• Constructor validation ensures consistency:
  • If found=True: match_index ≥ 0 and match_text is non-empty
  • If found=False: match_index = -1 and match_text is empty
• Prevents invalid state from propagating through the system

Scanner Abstract Base Class

All pattern detectors inherit from this base:

• name property: Unique identifier for this scanner
• pattern property: Pattern string being searched for
• scan(content: str) → ScanResult: Execute the scan

ScannerRegistry

Central registry for managing multiple scanner instances:

• register(scanner): Add a scanner (rejects duplicate names)
• unregister(name): Remove scanner by name
• get(name): Lookup a specific scanner
• list_scanners(): Get all scanner names in registration order
• scan(content, scanner_name=None):
  • If scanner_name specified: scan with only that scanner
  • If None: scan with all registered scanners
  • Returns list of ScanResult objects

Design Principles

1. Separation of concerns: Scanners are completely independent
2. Extensibility: New scanners can be added by implementing the Scanner interface
3. Fail-fast validation: ScanResult construction validates consistency
4. Registry pattern: Centralized management of scanner instances
5. Bulk scanning: Can execute all scanners in one operation

Test Coverage

23 tests, 100% pass rate

• ScanResult tests (6): Validation of found/not-found consistency
• Registry tests (15): Register, unregister, get, list, scan single/bulk
• Integration tests (2): Realistic multi-scanner security scanning scenario, dynamic registration

Use Case Example

registry = ScannerRegistry()
registry.register(APIKeyScanner("sk-", 12))
registry.register(PasswordScanner(["password", "passwd"]))
registry.register(TokenScanner("token"))

# Scan with all scanners
results = registry.scan("API key: sk-123456789 password: secret123")
for result in results:
    if result.found:
        print(f"Detected {result.pattern} by {result.scanner_name}")

Files Changed

• scanners/interface.py - ScanResult & Scanner interface (~60 LOC)
• scanners/registry.py - ScannerRegistry implementation (~50 LOC)
• tests/test_scanner_interface.py - Comprehensive test suite (~110 tests)

Dependencies

• Depends on: PR-1.1 (Skeleton), PR-1.2 (SSE Parser), PR-1.3 (Logical Stream)
• Blocks: PR-1.5 (GuardEngine), PR-1.6 (BanSubstrings Scanner)

Next Steps

PR-1.5 will implement the GuardEngine coordinator that uses this registry to orchestrate scanning.