mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-10 12:47:04 +00:00
kevinveenbirkenbachandClaude Opus 5
406b106356
Every rule so far named a construct to protect, and every run found one that had been forgotten: paths, underscores, bracketed URLs, then the bracket itself. 7338 sources still reached the translator carrying markup, and one in eight came back broken. Mask the delimiters themselves, so nothing a translator would reformat is left in the text: emphasis, backticks, brackets, braces, parentheses, double quotes, quoted identifiers and digits. Single quotes stay exposed on purpose, because 1419 of the 1494 sources that carry one are English contractions, and masking those would hand over fragments instead of words. Costs nothing: the 2606 entries that end up without translatable text were already empty under the old rules, and the newly masked ones are galaxy_tags lists and JSON fragments. Two defects survive masking because they alter no protected span, so unmask repairs them against the source: a translator reading a trailing span as sentence-final swallows the boundary behind it, gluing the next sentence to a code span, and it spaces out emphasis, which markdown then renders literally. The standing checks assert the property rather than enumerate constructs, and cover core and docs, where before only the span-parity check did, which is why none of this was ever caught. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Shared Utilities (utils/)
This directory contains shared Python helpers used by custom modules and plugins.
Purpose
Use utils/ for reusable code that should not be duplicated across:
library/modules,plugins/action/,plugins/filter/,plugins/lookup/.
Typical shared utilities:
- API clients,
- validation/conversion helpers,
- path and configuration helpers,
- cross-plugin/module domain logic.
- Shared HTTP(S) connection handler for multiple modules.
- Common validation or transformation functions for user input.
- Utility functions for interacting with Docker, LDAP, etc.
- Grouped helper packages such as
utils/domains/for related domain logic.
Design Guidelines
- Keep helpers focused and composable.
- Avoid side effects during import.
- Prefer explicit function/class APIs over implicit globals.
- Keep dependencies minimal so modules/plugins stay lightweight.
Example Import
from utils.domains.primary_domain import get_primary_domain
What Does Not Belong Here
- Standalone executable modules (put in
library/). - Ansible plugin entrypoints (put in
plugins/*).
References
- Module utilities: https://docs.ansible.com/ansible/latest/dev_guide/developing_module_utilities.html
- Plugin development: https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html