R23-T053: Add input validation to ciphers/porta_cipher.py - #63

Description

ciphers/porta_cipher.py had no input validation: bad keys or text crashed with confusing errors (IndexError, KeyError, AttributeError) and one case (ß as a key) silently gave a wrong result. This PR adds clear TypeError/ValueError messages, documents the input contract, and adds a doctest for every new error path.

Related Issue

Fixes: #53

Type of Change

• Bug Fix
• New Feature
• UI/UX Improvement
• Performance Improvement
• Tests
• Documentation
• Refactoring / Maintenance
• CI/CD

Changes Made

• Added validate_letters(name, value, allow_empty=False): TypeError for non-str, ValueError for empty or non-ASCII-letter input, naming the offending character.
• generate_table validates the key; encrypt validates the text (decrypt inherits both).
• Documented the input contract in the docstrings (non-empty ASCII-letter key, ASCII-letter text, case-insensitive, empty text returns '').
• Added doctests for every new error path (original 5 doctests unchanged; 27 doctests total).
• Added work/R23-T053/PROBE.md (18 bad inputs, before vs after) and probe_bad_inputs.py.

Screenshots / Recordings

Not applicable (no UI changes).

Testing

• python -m pytest --doctest-modules ciphers/porta_cipher.py -> passed (27 doctests)
• python -m doctest -v ciphers/porta_cipher.py -> 27 passed, 0 failed
• ruff check ciphers/porta_cipher.py -> all checks passed
• python work/R23-T053/probe_bad_inputs.py -> every bad input now raises a clear error

Checklist

• I have tested my changes locally.
• I have added or updated tests, if needed.
• I have updated documentation, if needed.
• I have followed the project's coding guidelines.
• I have run the relevant tests and checks.
• I have addressed previous review feedback, if applicable.

Additional Notes

Findings (before -> after): empty key IndexError -> ValueError; digit/space/non-ASCII key KeyError -> ValueError; None/int/bytes key AttributeError/KeyError -> TypeError; text with space/digit "substring not found" -> ValueError naming the character; ß key silently accepted (upper() gives 'SS') -> ValueError. Full table in work/R23-T053/PROBE.md.