Architecture

Policyglass is organized by concern instead of framework layers.

Modules

policyglass.policy

Parses YAML and validates the configuration into typed dataclasses.

policyglass.scanner

Walks the filesystem, applies rules, and returns a structured ScanReport.

policyglass.formatters

Renders reports into human-friendly text or automation-friendly JSON.

policyglass.cli

Thin Typer wrapper around the core API.

Design priorities

1. explicit behavior over clever abstraction
2. deterministic scan ordering for stable output and tests
3. typed structures across the public API
4. small modules with focused responsibilities
5. rule evaluation that is easy to extend without breaking existing output

Tradeoffs

Text decoding

Content scanning reads at most the configured byte budget plus one sentinel byte, then decodes UTF-8 while ignoring invalid byte sequences. Files over budget produce a controlled failing finding rather than being partially searched. Because an accepted file is searched as one bounded value, regex matches have whole-file semantics without chunk-boundary exceptions.

Regex execution

Patterns are user-controlled and may have pathological backtracking behavior. Policyglass uses the regex engine's enforceable per-search timeout and reports timeout as a controlled failing finding. This bounds an individual search, not aggregate work across arbitrarily many files or patterns.

Rule scope

The first release intentionally does not include negated allowlists, inline suppressions, or remote policy fetches. Those features add power but also semantic complexity.