simple_english 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7c05cc78b762e2b44f4c841ef5a78537e91d9bcd408ed8739fcc00f3538f14eb
+  data.tar.gz: 9abac46821a9260b3ec7312a1c258464e08a943262eaccab893383104479dcee
+SHA512:
+  metadata.gz: 6c4ac5c79f9a62c848ae37977dfb48ec2b815b27e5a38af7ab448a489206b14b8b26dec4f560b5115dd5be3c3688bfed254ebecbfd5e57c83c84d4a545367780
+  data.tar.gz: 699067a5a056a54186fe40d62ee17dd358492409dd86a76fc17cd2e1be8d110ee1147daa3ecb5f4d8b995cfd98f4108e96adbf6ed96603a43566ee820fd48729

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tony.hsu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,193 @@
+# simple_english
+
+> Write for human readers, not for reviewers or another AI.
+
+AI writes your docs and code comments in seconds. This linter cuts
+the slop it leaves behind. Every finding says what to write
+instead.
+
+```console
+$ printf 'You should leverage this tool in order to make sure that your docs are readable.' > note.md
+$ se note.md
+note.md:1: [SE_MODAL_RESTRICTED] Use can, will, or must. State the requirement exactly.
+note.md:1: [SE_SLOP_IN_ORDER_TO] Write "to".
+note.md:1: [SE_SLOP_LEVERAGE] Write "use".
+```
+
+Markdown prose plus code comments in Python, Ruby, JavaScript,
+TypeScript, Go, Rust, Java, C#, Kotlin, bash, and YAML. Output as plain
+text, JSON, or SARIF.
+
+## The rules
+
+- **Voice:** say who does the action.
+- **Tense:** simple tenses only, no present perfect.
+- **Modals:** `can`, `will`, `must` only.
+- **Punctuation:** no em-dashes, no semicolons.
+- **Contractions:** write every word in full.
+- **Sentence shape:** condition before command, no `-ing` phrase after a comma.
+- **Word choice:** about 50 substitution rules, from `leverage` to `in conclusion`. `make sure that` keeps its "that".
+- **Code comments:** same pattern rules, with line and column.
+- **Counts (Markdown only):** 20 words per sentence in list items, 25 in paragraphs, six sentences per paragraph at most.
+
+The full list, with a wrong and a right example for each rule:
+[docs/RULES.md](docs/RULES.md).
+
+## Install
+
+**Requirements:** Ruby 3.3 or newer, Java 11 or newer for
+LanguageTool. The Docker image bundles both.
+
+### Ruby gem
+
+```bash
+gem install simple_english
+se setup    # run once: downloads LanguageTool, locates Java, verifies both
+se README.md
+```
+
+`se setup` puts LanguageTool into `~/.cache/se` and touches nothing
+in your shell profile. Pass `--dir PATH` or set `SE_CACHE_DIR` to
+put the cache somewhere else. If `java` is not on PATH, set `SE_JAVA`
+to your java binary.
+
+### Container
+
+The image holds Ruby, Java, and LanguageTool, so it needs no setup:
+
+```bash
+docker run -v "$PWD":/work ghcr.io/tonycthsu/simple-english:latest docs/
+```
+
+Or keep the daemon in a container and lint through it:
+
+```bash
+docker run -d --name se-daemon -p 8181:8181 ghcr.io/tonycthsu/simple-english:latest serve
+SE_SERVER_URL=http://localhost:8181 se lint docs/
+```
+
+### Git repository
+
+Run `bundle install`, then use `bin/se`.
+
+## Usage
+
+Lint files, directories, or stdin. From a checkout, the same commands
+run through `bin/se`:
+
+```bash
+se README.md
+se docs/            # every .md, .py, .rb, .yaml, .yml, ... under docs/
+se - < notes.md     # stdin (Markdown)
+```
+
+Lint only what changed:
+
+```bash
+git diff --name-only --diff-filter=ACM main | xargs se
+```
+
+### Outputs
+
+Findings print as `file:line: [RULE_ID] message`. Code-comment findings also carry a column in `--format json` and `--format sarif`:
+
+```bash
+se --format json docs/
+se --format sarif src/ > results.sarif
+```
+
+### Exit codes
+
+- `0`: no findings
+- `1`: findings
+- `2`: setup error
+
+### CI
+
+Gate the docs in the pull request that changes them. The plain run
+fails the build on findings, and the SARIF report puts them inline:
+
+```yaml
+name: lint-docs
+on: [pull_request]
+permissions:
+  security-events: write
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ruby/setup-ruby@v1
+      - run: gem install simple_english
+      - run: se setup
+      - run: se --format sarif . > lint.sarif
+      - run: se .
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: lint.sarif
+        if: always()
+```
+
+## Config and suppressions
+
+### Config file
+
+`.simple-english.yml` in the working directory:
+
+```yaml
+ignore:
+  - vendor/**
+disabled-rules:
+  - SE_NO_EMDASH
+```
+
+`ignore` globs: `**` crosses directories, `*` stays in one segment.
+
+### Inline suppressions
+
+A line containing `se: ignore` suppresses findings reported on that
+line. Use `se: ignore=RULE1,RULE2` to scope it to rules. Pattern
+findings cite the line of the match, so put the directive on the line the
+finding reports.
+
+In Markdown:
+
+```markdown
+The daemon keeps it's own lock. <!-- se: ignore=SE_NO_CONTRACTIONS -->
+```
+
+In a code comment:
+
+```ruby
+# Don't touch this constant. se: ignore=SE_NO_CONTRACTIONS
+```
+
+## The daemon
+
+The first lint starts the daemon automatically (about 15 seconds
+once, then you need Java and one run of `se setup`). Later lints hit
+the running daemon and take milliseconds. To start it ahead of time:
+
+```bash
+se serve --port 8181 &
+```
+
+Any tool or language can lint through its HTTP API:
+
+```bash
+curl -d "text=Don't do this." http://localhost:8181/lint
+# [{"line":1,"column":null,"rule":"SE_NO_CONTRACTIONS","message":"..."}]
+```
+
+The full wire format: [docs/DAEMON.md](docs/DAEMON.md).
+
+## Scope
+
+The rule set comes from the Plain-mode rules of the MIT-licensed
+SimpleEnglish project. This tool does not check ASD-STE100 compliance.
+This repo holds no ASD-STE100 text. If you need full compliance, read
+the free standard at <https://www.asd-ste100.org/>.
+
+## Develop
+
+To change the linter, add rules, or run the tests, read [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

data/bin/se

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/simple_english/cli"
+
+exit(SimpleEnglish::CLI.start(ARGV) || 0)

data/docs/RULES.md

@@ -0,0 +1,496 @@
+# Rules
+
+Generated by `bin/render-rules`. Do not edit by hand. The source
+of truth is `rules/simple-english.xml` and
+`lib/simple_english/counts.rb`.
+
+## Pattern rules
+
+### SE_NO_CONTRACTIONS: No contractions
+
+Write the words in full. No contractions.
+
+- Wrong: You don't need this file.
+- Right: You do not need this file.
+
+### SE_NO_SEMICOLON: No semicolons
+
+Write two sentences, or name the relation.
+
+- Wrong: Start the tool; then read the log.
+- Right: Start the tool. Then read the log.
+
+### SE_NO_EMDASH: No em-dashes
+
+Write two sentences, or use a comma.
+
+- Wrong: The tool is fast—it also works.
+- Right: The tool is fast. It also works.
+
+### SE_MODAL_RESTRICTED: Only can, will, must
+
+Use can, will, or must. State the requirement exactly.
+
+- Wrong: You should restart the service.
+- Right: You must restart the service.
+
+### SE_ACTIVE_VOICE: Active voice
+
+Use the active voice. Say who does the action.
+
+- Wrong: The log was written by the worker.
+- Right: The worker wrote the log.
+
+### SE_PRESENT_PERFECT: Simple tenses only
+
+Use the simple past. Say when it happened.
+
+- Wrong: The job has completed.
+- Right: The job completed.
+
+### SE_ING_AFTER_COMMA: No -ing after a comma
+
+Start a new sentence instead of the -ing phrase.
+
+- Wrong: The tool runs, making it easy.
+- Right: The tool runs. It is easy.
+
+### SE_KEEP_THAT: make sure that
+
+Write "make sure that".
+
+- Wrong: Make sure the file exists.
+- Right: Make sure that the file exists.
+
+### SE_CONDITION_FIRST: Condition before command
+
+Put the condition first: "If the build fails, read the log."
+
+- Wrong: Read the log if the build fails.
+- Right: If the build fails, read the log.
+
+### SE_SLOP_LEVERAGE: use, not leverage
+
+Write use.
+
+- Wrong: Utilize the registry file.
+- Right: Use the registry file.
+
+### SE_SLOP_IN_ORDER_TO: to, not in order to
+
+Write to.
+
+- Wrong: Run the tool in order to build the file.
+- Right: Run the tool to build the file.
+
+### SE_SLOP_PRIOR_TO: before, not prior to
+
+Write before.
+
+- Wrong: Read the file prior to the upgrade.
+- Right: Read the file before the upgrade.
+
+### SE_SLOP_ENSURE: make sure that, not ensure
+
+Write make sure that.
+
+- Wrong: Ensure the file exists.
+- Right: Make sure that the file exists.
+
+### SE_SLOP_FUNCTIONALITY: function, not functionality
+
+Write function or feature.
+
+- Wrong: Add the functionality first.
+- Right: Add the function first.
+
+### SE_SLOP_ENABLES_YOU: you can, not enables you to
+
+Write you can.
+
+- Wrong: The tool enables you to build the file.
+- Right: You can build the file with the tool.
+
+### SE_SLOP_FACILITATE: help, not facilitate
+
+Write help or make possible.
+
+- Wrong: The tool facilitates the build.
+- Right: The tool helps the build.
+
+### SE_SLOP_DELVE: read, not delve into
+
+Write read or examine.
+
+- Wrong: Delve into the config file.
+- Right: Read the config file.
+
+### SE_SLOP_WHEN_IT_COMES: for, not when it comes to
+
+Write for.
+
+- Wrong: When it comes to builds, use the tool.
+- Right: For builds, use the tool.
+
+### SE_SLOP_IN_THE_EVENT: if, not in the event that
+
+Write if.
+
+- Wrong: In the event that the build fails, read the log.
+- Right: If the build fails, read the log.
+
+### SE_SLOP_DUE_TO_FACT: because, not due to the fact that
+
+Write because.
+
+- Wrong: Due to the fact that the port is closed, the tool fails.
+- Right: Because the port is not open, the tool fails.
+
+### SE_SLOP_AND_OR: no and/or
+
+Pick one. Or write "X, or Y, or both".
+
+- Wrong: Set the flag and/or the port.
+- Right: Set the flag, or the port, or both.
+
+### SE_SLOP_LATIN: no Latin abbreviations
+
+#### e.g.
+
+Write "for example", or name the items.
+
+- Wrong: Set the flag, e.g. the port.
+- Right: Set the flag, for example the port.
+
+#### i.e.
+
+Write "that is", or name the items.
+
+- Wrong: Set the flag, i.e. the port.
+- Right: Set the flag, that is the port.
+
+#### etc.
+
+Name the items.
+
+- Wrong: Set the flag, etc.
+- Right: Set the flag or the port.
+
+### SE_SLOP_OUT_OF_BOX: by default, not out of the box
+
+Write by default.
+
+- Wrong: The tool works out of the box.
+- Right: The tool works by default.
+
+### SE_SLOP_UNDER_HOOD: internally, not under the hood
+
+Write internally.
+
+- Wrong: Under the hood, the tool builds a file.
+- Right: Internally, the tool builds a file.
+
+### SE_SLOP_STREAMLINE: make simpler, not streamline
+
+Write make simpler or make faster.
+
+- Wrong: The tool streamlines the build.
+- Right: The tool makes the build simpler.
+
+### SE_SLOP_PLETHORA: many, not plethora
+
+Write many.
+
+- Wrong: The file has a plethora of rows.
+- Right: The file has many rows.
+
+### SE_SLOP_ADDRESSES: corrects, not addresses the issue
+
+Write corrects the fault or removes the error.
+
+- Wrong: The tool addresses the issue.
+- Right: The tool corrects the fault.
+
+### SE_SLOP_PIVOTAL: important, not pivotal
+
+Write important.
+
+- Wrong: The flag is crucial.
+- Right: The flag is important.
+
+### SE_SLOP_TAPESTRY: no tapestry, testament, synergy
+
+Delete it. State the fact.
+
+- Wrong: The design is a testament to the team.
+- Right: The design shows the work of the team.
+
+### SE_SLOP_INTERPLAY: interaction, not interplay
+
+Write interaction, or delete it.
+
+- Wrong: The interplay of the two tools is complex.
+- Right: The interaction of the two tools is complex.
+
+### SE_SLOP_INTRICATE: complex, not intricate
+
+Write complex.
+
+- Wrong: The config is intricate.
+- Right: The config is complex.
+
+### SE_SLOP_VIBRANT: delete vibrant, nuanced, multifaceted
+
+Delete it, or name the parts.
+
+- Wrong: The tool is nuanced.
+- Right: The tool reads three file types.
+
+### SE_SLOP_REALM: area, not realm or landscape
+
+Write area.
+
+- Wrong: In the realm of builds, use the tool.
+- Right: In the area of builds, use the tool.
+
+### SE_SLOP_GROUNDBREAKING: new, not groundbreaking
+
+Write new, or delete it.
+
+- Wrong: The tool is groundbreaking.
+- Right: The tool is new.
+
+### SE_SLOP_TRANSFORMATIVE: say what changes, not transformative
+
+Delete it. Say what changes.
+
+- Wrong: The tool is transformative.
+- Right: The tool cuts the build time in half.
+
+### SE_SLOP_REVOLUTIONIZE: change, not revolutionize
+
+Write change.
+
+- Wrong: The tool revolutionizes the build.
+- Right: The tool changes the build.
+
+### SE_SLOP_SHOWCASE: show, not showcase
+
+Write show.
+
+- Wrong: The log showcases the error.
+- Right: The log shows the error.
+
+### SE_SLOP_FOSTER: help, not foster
+
+Write help, support, or let.
+
+- Wrong: The tool fosters growth.
+- Right: The tool supports growth.
+
+### SE_SLOP_HARNESS: use, not harness
+
+Write use.
+
+- Wrong: Harness the API.
+- Right: Use the API.
+
+### SE_SLOP_ENHANCE: improve, not enhance
+
+Write improve.
+
+- Wrong: The tool enhances the build.
+- Right: The tool improves the build.
+
+### SE_SLOP_ELEVATE: increase, not elevate
+
+Write increase.
+
+- Wrong: The tool elevates the speed.
+- Right: The tool increases the speed.
+
+### SE_SLOP_FURTHERMORE: also, not furthermore
+
+Write also.
+
+- Wrong: Furthermore, the tool reads the log.
+- Right: The tool also reads the log.
+
+### SE_SLOP_EMBARK: start, not embark
+
+Write start or try.
+
+- Wrong: Embark on the build.
+- Right: Start the build.
+
+### SE_SLOP_METICULOUS: careful, not meticulous
+
+Write careful or carefully.
+
+- Wrong: The tool checks the file meticulously.
+- Right: The tool checks the file carefully.
+
+### SE_SLOP_HOLISTIC: full, not holistic
+
+Write full.
+
+- Wrong: The tool gives a holistic view.
+- Right: The tool gives a full view.
+
+### SE_SLOP_PARADIGM: model, not paradigm
+
+Write model.
+
+- Wrong: The tool changes the paradigm.
+- Right: The tool changes the model.
+
+### SE_SLOP_BOASTS: has, not boasts
+
+Write has.
+
+- Wrong: The tool boasts a log.
+- Right: The tool has a log.
+
+### SE_SLOP_NOTWITHSTANDING: but, not that being said
+
+Write but.
+
+- Wrong: The tool works. That being said, it is slow.
+- Right: The tool works, but it is slow.
+
+### SE_SLOP_NOTWITHSTANDING2: but, not notwithstanding
+
+Write but.
+
+- Wrong: Notwithstanding the log, the tool fails.
+- Right: The log exists, but the tool fails.
+
+### SE_SLOP_DELETE_ADVERBS: delete empty adverbs
+
+Delete it. It carries no fact.
+
+- Wrong: The tool works seamlessly.
+- Right: The tool works.
+
+### SE_SLOP_JUST: delete just
+
+Delete it. It carries no fact.
+
+- Wrong: The tool just works.
+- Right: The tool works.
+
+### SE_SLOP_DELETE_ADJ: delete empty adjectives
+
+Delete it, or give the measurable property.
+
+- Wrong: The tool is robust.
+- Right: The tool retries three times, then stops.
+
+### SE_SLOP_WORTH_NOTING: delete it is worth noting
+
+Delete it. State the fact.
+
+- Wrong: It is worth noting that the tool is slow.
+- Right: The tool is slow.
+
+### SE_SLOP_IMPORTANT_TO: delete it is important to
+
+Delete it. State the fact.
+
+- Wrong: It is important to read the log.
+- Right: Read the log.
+
+### SE_SLOP_DESIGNED_TO: delete is designed to
+
+Say what the tool does.
+
+- Wrong: The tool is designed to read logs.
+- Right: The tool reads logs.
+
+### SE_SLOP_AIMS_TO: delete aims to
+
+Say what the tool does.
+
+- Wrong: The tool aims to read logs.
+- Right: The tool reads logs.
+
+### SE_SLOP_AS_NEEDED: state the condition, not as needed
+
+State the condition.
+
+- Wrong: Restart the tool as needed.
+- Right: Restart the tool every day.
+
+### SE_SLOP_GRACEFULLY: say what it does, not gracefully handles
+
+Say what the tool does: "retries three times, then stops".
+
+- Wrong: The tool gracefully handles the error.
+- Right: The tool retries three times, then stops.
+
+### SE_SLOP_IN_CONCLUSION: delete in conclusion
+
+Delete it. State the fact.
+
+- Wrong: In conclusion, the tool works.
+- Right: The tool works.
+
+### SE_SLOP_IN_SUMMARY: delete in summary
+
+Delete it. State the fact.
+
+- Wrong: In summary, the tool works.
+- Right: The tool works.
+
+### SE_SLOP_AT_END_OF_DAY: delete at the end of the day
+
+Delete it. State the fact.
+
+- Wrong: At the end of the day, the tool works.
+- Right: The tool works.
+
+### SE_SLOP_NESTLED: give the location, not nestled
+
+Give the location.
+
+- Wrong: The file is nestled in the folder.
+- Right: The file sits in the folder.
+
+### SE_SLOP_BUSTLING: busy, not bustling
+
+Write busy.
+
+- Wrong: The bustling market has many files.
+- Right: The busy market has many files.
+
+### SE_SLOP_HOPE_HELPS: delete I hope this helps
+
+Delete it.
+
+- Wrong: I hope this helps. Read the log.
+- Right: Read the log.
+
+### SE_SLOP_DIVE_IN: delete let's dive in
+
+Delete it.
+
+- Wrong: let's dive in. Read the log.
+- Right: Read the log.
+
+## Counting rules
+
+These rules run in Ruby on Markdown text. Code comments do not use
+them. Procedural text is a list item. Descriptive text is every
+other paragraph.
+
+### SE_SENTENCE_TOO_LONG
+
+A sentence with more than 20 words in
+procedural text, or more than 25 words
+in descriptive text.
+
+### SE_PARAGRAPH_TOO_LONG
+
+A paragraph with more than 6
+sentences in descriptive text.
+