Primitives

Prose is built from a small set of shared primitives that each carry a single responsibility. A rule reads source through Source, walks the AST through one of the shared walkers, emits Edit lists, and surfaces diagnostics through the Pipeline. Every rule in the catalog composes from the named pieces below, so a new rule lands as a thin walker plus the per-rule decision rather than a from-scratch implementation. The padding math, the comment-attachment, and the conflict discipline live once and downstream rules consume them.

The graph below traces how a source flows through the primitive set, with each node marking one primitive and each edge marking a consumer relationship (A → B reads as "A is consumed by B"). The graph nodes match the registries below, and hovering a node previews the primitive's one-line role.

IIIanalysis

• BindingAnalysis
• Cache
• ColonTargets
• Docstring
• SuppressionMap
• Walker

IIorchestration

• Aligner
• Orderer
• Pipeline

Ibase

• Edit
• RuleId
• Source

Hover a tile to see what it draws from and what it feeds into.

The Surface

Public Primitives

Reachable from a downstream Rust consumer in 0.2.x:

1. Source · parsed-text wrapper bundling original text, AST, tokens, line index, and the suppression / binding tables. Every rule reads through this value
2. Pipeline · runs the registered rules in deterministic order against a Source, reparsing between rules
3. RuleId · canonical kebab-case slug identifying each rule across CLI flags, config tables, suppression directives, and diagnostic output

Crate-Internal Primitives

pub(crate) in 0.2.x and stabilizing toward 1.0, where consumer-implemented rules become reachable:

1. BindingAnalysis · per-Source table indexing every write and read of every name in every lexical scope
2. SuppressionMap · per-Source index of # fmt: off / # fmt: skip / # yapf / # prose: ignore[...] directives
3. Aligner · shared alignment math, consumed by
   align-colons
   ,
   align-comparisons
   ,
   align-equals
   ,
   align-imports
   ,
   align-match-case
4. Orderer · sibling reorder helper preserving attached comments, consumed by
   alphabetize
5. ColonTargets · walker that finds every : alignment context, consumed by
   align-colons
   and
   strip-align-padding
6. Edit · the Edit { range, content } shape every rule emits and the Pipeline applies
7. Docstring · PEP 257 docstring walker, consumed by
   docstring-wrap
   ,
   docstring-frame
   ,
   docstring-expand
8. Walker · ignore-aware filesystem walker, consumed by the path-mode CLI
9. Cache · user-level content-addressed cache, consumed by prose check and prose format to skip the pipeline on unchanged source

Reading Order

For a downstream Rust consumer integrating Prose through the public surface, the load-bearing reads are Source (input), Pipeline (runner), and RuleId (slug type). The three together cover construction, execution, and the slug shape that flows through every CLI flag and config table.

For a rule author working inside the Prose crate, the reading path starts at Edit (the unit every rule emits) and walks through Pipeline (the runner the rule registers with). From there, the right walker primitive depends on what the rule does:

• Aligner for rules that pad to a column.
• Orderer for rules that reorder siblings.
• ColonTargets for rules that align around : contexts.
• Docstring for rules over PEP 257 docstrings.
• BindingAnalysis for rules that ask binding-shaped questions.

Source is the input every walker reads against, and SuppressionMap is the filter every emission passes through.

The Rules page walks every rule each primitive shows up under, the Configuration reference covers the [tool.prose] table that drives the Pipeline's rule selection, and the Pipeline Order reference covers the deterministic order rules fire in.