diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a6389b3..b9455bf 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -58,7 +58,7 @@ jobs: # Settings -> Environments before relying on it as a real gate. environment: name: release - url: https://pypi.org/p/ste100 + url: https://pypi.org/p/ste100-linter permissions: # Required for PyPI Trusted Publishing (OIDC). Do not add a # PYPI_API_TOKEN secret -- Trusted Publishing replaces it. diff --git a/CHANGELOG.md b/CHANGELOG.md index b0fa8cb..1eaf8db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ once the first tagged release ships. ## [Unreleased] +## [0.1.0] - 2026-08-25 + +First tagged release. Everything below shipped in it. + ### Added - The ASD-STE100 writing-quality linter, split out of the Veistra monorepo's @@ -44,6 +48,17 @@ once the first tagged release ships. - `tests/run_wrapping_tests.py`: regression tests pinning the invariant that a paragraph lints identically whether it is hard-wrapped or on one line. +- Third-party attribution for the redistributed word lists: `NOTICE` and + `THIRD-PARTY-LICENSES.md` at the repository root, plus a `sources` block + inside `hedges.json`, `filler.json`, `vague.json` and `ai_tells.json` + recording the upstream project, URL, copyright holder and licence for each + shipped table. Both files ship in the wheel under `.dist-info/licenses/`. +- Contributor documentation: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, + `SECURITY.md`, issue and pull-request templates, and a Dependabot + configuration for GitHub Actions. +- `tests/run_wrapping_tests.py`: a regression suite pinning the invariant that + a paragraph lints the same when hard-wrapped and when left on one line. + ### Changed - **Rule IDs are now `STE-*` rather than `VEI-*`.** `VEI` stood for Veistra, @@ -97,6 +112,15 @@ once the first tagged release ships. - `--format`, `--fix`, `--explain`, `--baseline`, `--stats` and `--today` had no `--help` text, or leaked an internal specification reference. +- **Hard-wrapped Markdown defeated the T5 atomicity analysis.** Sentence units + were built from each physical line, so a sentence spanning a line break was + analysed as several fragments. `STE-T5-MULTI-0001` and the sentence word + budget stopped firing entirely, `STE-T5-NOSHAL-0001` and `STE-T5-EARS-0001` + produced false positives on the fragments, and a five-sentence paragraph was + counted as nine. Units are now built per paragraph, and a `spans` table maps + each offset back to its true source line and column so `--fix` and the VS + Code `problemMatcher` still navigate correctly. + ### Known issues - The shipped rule tables were calibrated for strict specification writing diff --git a/README.md b/README.md index f8f33e4..f042d32 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,159 @@ +
+ # STE-Linter +### Catch ambiguity before your readers do. + +A writing linter for technical documentation, in the spirit of
+**[ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/)**. + [![CI](https://img.shields.io/github/actions/workflow/status/Firelight-Innovations/STE-Linter/ci.yml?branch=main&label=CI)](https://github.com/Firelight-Innovations/STE-Linter/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/ste100-linter.svg)](https://pypi.org/project/ste100-linter/) [![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/) +[![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](#install) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) -A writing linter for technical documentation, in the spirit of [ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/). +**[Install](#install)** · **[Quick start](#quick-start)** · **[Rule catalogue](docs/rules.md)** · **[Wiki](https://github.com/Firelight-Innovations/STE-Linter/wiki)** -A spell-checker asks whether a word is a word. This asks whether a sentence can be misread by someone who has to act on it. +
-It reads Markdown and CSV and reports the words and sentence shapes that make technical writing imprecise. Hedges that let a rule mean anything. References with no antecedent. Sentences carrying three demands at once. Filler that survives deletion without loss. +--- -No dependencies. No build step. One command. +A spell-checker asks whether a word is a word. +**STE-Linter asks whether a sentence can be misread by someone who has to act on it.** -Given a file like this: +It reads Markdown and CSV and reports the words and sentence shapes that make technical +writing imprecise. Hedges that let a rule mean anything. References with no antecedent. +Sentences carrying three demands at once. Filler that survives deletion without loss. -```markdown -# Shutdown +**No dependencies. No build step. No network. One command.** + +## What it catches + +Every finding belongs to one of six tests. Each asks a different question about a sentence. + +```mermaid +flowchart LR + A["Markdown / CSV"] --> B["Mask code, URLs,
tables and links"] + B --> C["Split into
real sentences"] + C --> D{"Six tests"} + + D --> T1["T1 · Replaceable
utilize, in order to"] + D --> T2["T2 · Unfalsifiable
robust, appropriate"] + D --> T3["T3 · Optional
should, as required"] + D --> T4["T4 · Referentially open
It, this, faster"] + D --> T5["T5 · Non-atomic
two shalls, and/or"] + D --> T6["T6 · Zero-information
filler, weasel, AI tells"] + + T1 --> E["error · warning · review"] + T2 --> E + T3 --> E + T4 --> E + T5 --> E + T6 --> E + + style A fill:#1f6feb,stroke:#1f6feb,color:#ffffff + style D fill:#8250df,stroke:#8250df,color:#ffffff + style E fill:#1a7f37,stroke:#1a7f37,color:#ffffff +``` + +## See it work -The operator shall utilize the panel in order to shut the reactor down. +Three sentences of ordinary-looking documentation: -The system shall be robust and shall handle errors as appropriate. +```markdown +# Recovery -It responds faster when the cache is warm. +The operator should utilize the appropriate procedure to restore the system +as required. It is important to note that the system will handle errors and +the controller shall reset the link and it shall log the event. ``` +Every one of the six tests fires. This is the real output, with only the indented source-snippet line under each finding removed for length: + ```console -$ ste100 requirements.md -ste100: 1 files, 6 errors, 4 warnings, 1 review -smell_density=3.3333 ari_grade=5.71 passive_ratio=0.0 budget_violations=0 -requirements.md:3:20 ERROR T1 STE-T1-SUB-0104 -- Replaceable: 'utilize' -> 'use'. - ...operator shall utilize the panel in o... -requirements.md:3:38 ERROR T1 STE-T1-SUB-0122 -- Replaceable: 'in order to' -> 'to'. - ...lize the panel in order to shut the react... -requirements.md:5:1 ERROR T5 STE-T5-MULTI-0001 -- Non-atomic: 2 'shall' imperatives in one sentence. - The system shall be robust and shall handle e... -requirements.md:5:21 WARNING T2 STE-T2-VAG-0059 -- Unfalsifiable: 'robust' with no number, unit, or named acceptance condition. - ...ystem shall be robust and shall hand... -requirements.md:5:21 ERROR T6 STE-T6-FILL-0251 -- Zero-information (filler/intensifier): 'robust'. - ...ystem shall be robust and shall hand... -requirements.md:5:52 ERROR T3 STE-T3-ESC-0002 -- Optional (escape clause): 'as appropriate'. - ...handle errors as appropriate. -requirements.md:5:55 ERROR T1 STE-T1-SUB-0233 -- Replaceable: 'appropriate' -> 'proper'. - ...ndle errors as appropriate. -requirements.md:5:55 WARNING T2 STE-T2-VAG-0015 -- Unfalsifiable: 'appropriate' with no number, unit, or named acceptance condition. - ...ndle errors as appropriate. -requirements.md:7:1 WARNING T4 STE-T4-PRO-0008 -- Referentially open: pronoun 'It' with no clear antecedent in this unit. - It responds faste... -requirements.md:7:13 WARNING T4 STE-T4-COMP-0003 -- Referentially open: comparative 'faster' with no stated baseline. - It responds faster when the cache... +$ ste100 --profile spec guide.md +ste100: 1 files, 9 errors, 4 warnings, 1 review +smell_density=6.5 ari_grade=10.66 passive_ratio=0.0 budget_violations=0 +guide.md:3:14 ERROR T3 STE-T3-HDG-0106 -- Optional (hedge): 'should'. +guide.md:3:21 ERROR T1 STE-T1-SUB-0104 -- Replaceable: 'utilize' -> 'use'. +guide.md:3:33 ERROR T1 STE-T1-SUB-0233 -- Replaceable: 'appropriate' -> 'proper'. +guide.md:3:33 WARNING T2 STE-T2-VAG-0015 -- Unfalsifiable: 'appropriate' with no number, unit, or named acceptance condition. +guide.md:4:1 ERROR T3 STE-T3-ESC-0006 -- Optional (escape clause): 'as required'. +guide.md:4:14 ERROR T1 STE-T1-SUB-0328 -- Replaceable: 'It is' -> ''. +guide.md:4:14 WARNING T4 STE-T4-PRO-0008 -- Referentially open: pronoun 'It' with no clear antecedent in this unit. +guide.md:4:14 ERROR T5 STE-T5-MULTI-0001 -- Non-atomic: 2 'shall' imperatives in one sentence. +guide.md:4:14 ERROR T6 STE-T6-AI-0004 -- Zero-information (AI tell, hedging_opener): 'It is important to note that'. +guide.md:4:38 WARNING T4 STE-T4-PRO-0017 -- Referentially open: pronoun 'that' with no clear antecedent in this unit. +guide.md:4:54 ERROR T3 STE-T3-HDG-0143 -- Optional (hedge): 'will'. +guide.md:5:37 ERROR T5 STE-T5-COMB-0001 -- Non-atomic: second combinator 'and' in one sentence (spec profile). +guide.md:5:41 WARNING T4 STE-T4-PRO-0008 -- Referentially open: pronoun 'it' with no clear antecedent in this unit. ``` -Three sentences, all six tests. Try it now, with nothing installed: +Every finding carries a file, a line, a column, a stable rule ID, and a reason. +`--explain` tells you where a rule comes from; `--fix` applies the unambiguous ones. + +## Three ways to run it + + + + + + + + + + + + +
⌨️ Command line🤖 AI agent skill🔌 HELVE tool
+ +For humans, editors and CI. + +```bash +pipx install ste100-linter +ste100 docs/ +``` + +Exit `0` clean, `1` on error-tier +findings, `2` on tool failure — +so it drops straight into CI. + +[CLI Reference →](https://github.com/Firelight-Innovations/STE-Linter/wiki/CLI-Reference) + + + +Lets Claude lint and rewrite prose +before it hands work back. + +```bash +mkdir -p ~/.claude/skills +cp -r .claude/skills/ste100-lint \ + ~/.claude/skills/ste100-lint +``` + +Works in Claude Code and any agent +that reads `SKILL.md`. + +[Agent Skill →](https://github.com/Firelight-Innovations/STE-Linter/wiki/Agent-Skill) + + + +Newline-delimited JSON-RPC over +stdio, for tool hosts. + +```bash +ste100-helve --helve-rpc +``` + +Declared by `helve-tool.toml`. +stdout stays protocol-pure. + +[Integrations →](https://github.com/Firelight-Innovations/STE-Linter/wiki/Integrations) + +
+ +Try it right now, with nothing installed: ```bash git clone https://github.com/Firelight-Innovations/STE-Linter.git @@ -99,9 +201,11 @@ Those citations name the INCOSE requirements guides, the NASA Systems Engineerin The bulk word tables come from a different lineage, and their attribution is coarser. **Only the T1 substitution table carries a per-entry `source` field.** `--explain` reports it for a T1 rule. -The T2 vague-term, T3 hedge, and T6 filler and AI-tell tables record no source at all, per entry or per table. Their provenance is documented for the table as a whole in [docs/rules.md](docs/rules.md) — not in the data, and not in `--explain` output. +The T2 vague-term, T3 hedge, and T6 filler and AI-tell tables carry their provenance at the table level instead. Each file has a `sources` block naming the upstream project, its URL, copyright holder and licence, and which shipped table it feeds. That is real attribution, though coarser than T1's: it tells you where a table came from, not which upstream contributed an individual word. A prose summary of the same ground is in [docs/rules.md](docs/rules.md). + +`--explain` does not yet surface either kind of source for these tests — it prints the raw table entry, which for T2, T3 and T6 is an ID and a pattern. That gap is tracked in [#10](https://github.com/Firelight-Innovations/STE-Linter/issues/10). -Third-party attribution for the upstream word lists is in [NOTICE](NOTICE), and in `THIRD-PARTY-LICENSES.md` where the repository root carries one. +Third-party attribution for the upstream word lists is in [NOTICE](NOTICE) and [THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md). Both ship in the wheel under `.dist-info/licenses/`. **This is not a grammar checker and not a style guide.** It will not catch a factual error or an awkward paragraph. It catches a bounded, well-defined set of ambiguity patterns, and stays quiet about everything else.