README

Which prose checks and formatting commands can other products use?

Binds: architecture, code

The package installs the plain-english-docs-lint command. A caller can import the library modules (prose, simple_english, python_prose, swift_prose) with the Python standard library alone.

Who it is for

The library is for a review or a hook that judges the prose of a change against Simplified Technical English. Long and vague sentences reach pages, comments and commit messages. The library checks Markdown, Python comments and docstrings, and Swift doc comments. It returns problems and changes no input. A review or a hook is the caller, and it decides which findings block.

Pure checks return problems without changing input

plain_english_docs_lint.prose owns the Problem result and report formatting. simple_english checks text against its hard rules and advisory patterns. python_prose extracts comments and docstrings before it applies those rules. swift_prose extracts Swift doc comments, and comments that hold their lines alone, before it applies those rules. Consumers decide which findings block their workflow.

Python formatting leaves runtime strings alone

plain-english-docs-lint exposes audit, candidates, check, and format. Each command accepts the arguments shown by its help. check and audit read each path with the rules of its suffix. A .py file goes to python_prose, and a .swift file goes to swift_prose. Any other suffix stops the command with an error. Formatting changes standalone comments and real docstrings. A line inside a string belongs to the string, even where it reads like a comment. Formatting leaves such a line as it is. Candidate reporting names each string literal outside a docstring that reads like prose. It rewrites none of them. The repository’s lb prose commands forward to these same entry points.

Patterns from AminBlg/SimpleEnglish retain their source attribution. The dash and the trailing condition are hard rules. Slop words and term rotation stay advisory. A hard problem and an advisory signal remain separate results.

Public results carry source locations

Problem(line, message) is a named tuple. Its line is an integer and its message is text. A line of zero describes the whole input. prose.report(found, empty, noun) returns one report string.

simple_english.problems(text) returns hard problems. simple_english.PROMOTED holds the messages of the dash and the trailing condition. A consumer that reads a whole file reports those two on the lines that a change writes. Every other hard problem counts on any line. simple_english.audit(text) returns advisory signals. python_prose.problems(source) and python_prose.audit(source) return the same result shape with Python source line numbers. python_prose.format_source(source) returns the formatted source string. python_prose.texts(source) returns Text(line, value) records. python_prose.candidates(source) returns Candidate(line, words, preview) records. swift_prose.problems(source), swift_prose.audit(source) and swift_prose.texts(source) return the same shapes with Swift source line numbers. None of these pure calls changes a file.