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 currently decodes files with UTF-8 and ignores invalid byte sequences. That keeps the implementation simple and resilient, but it means binary-heavy repositories may want to rely more on glob and size rules.

Regex execution

Patterns are user-controlled. Policyglass does not yet provide sandboxing or regex complexity guards, so maintainers should avoid pathological expressions.

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.