ste: the ASD-STE100 validator

ste validates text against ASD-STE100 Simplified Technical English. It is a Go library and a CLI. The CLI is AI-native. Each command can emit JSON. The exit codes are stable. Error messages name the next action.

ASD licenses the official ASD-STE100 dictionary. This project does not ship it. Supply your licensed dictionary as a ste-dictionary/v1 JSON file with --dictionary or STE_DICTIONARY. A starter dictionary ships for demos and tests. Use --sample-dictionary to enable it.

Install

go install github.com/probelabs/ste/cmd/ste@latest

Use

ste check manual.md                          # findings as text
ste check --format json docs/*.md            # ste-diagnostics/v1 JSON
ste check --format sarif docs/*.md           # SARIF 2.1.0 for code scanning
cat procedure.txt | ste check -              # read from stdin
ste rules                                    # list the rule catalog
ste dictionary inspect my-dictionary.json    # validate a dictionary file

Exit codes: 0 no findings, 1 findings, 2 execution error. Errors on stderr carry a hint: line. The hint names the next action.

The CLI parses markdown files as markdown. The parser ignores code fences, inline code, comments, and tables. List items count as procedure steps. Use --plain or --markdown to override detection.

Project config

The CLI reads ste.yaml from the working directory upward. Use --config to give a path or --no-config to disable discovery.

technical_names: [ReqProof, SARIF]
limits:
  instruction_words: 20
  descriptive_words: 25
rules:
  disable: [passive-voice]
  severity:
    noun-cluster: info

Rules

Run ste rules for the live catalog. Each rule names its ASD-STE100 section. Rules that decide from the dictionary emit errors. Rules that use a heuristic emit warnings.

Library

dict, _ := ste.LoadDictionary("ste.json")
env := &ste.Env{Dict: dict, Opts: ste.DefaultOptions()}
v := ste.NewValidator(env, rules.Catalog()...)
diags := v.Validate(ste.ParseMarkdown("Remove the valve."))

Dictionary format (ste-dictionary/v1)

{
  "schema": "ste-dictionary/v1",
  "entries": [
    {"word": "use", "part_of_speech": "verb", "approved": true,
     "forms": ["uses", "used"]},
    {"word": "utilize", "part_of_speech": "verb", "approved": false,
     "alternatives": ["use"]}
  ]
}

Development

Requirements and verification use ReqProof. The specs live in specs/. The code carries Implements: and Verifies: annotations. proof audit is the project health gate.

go test ./...
proof validate
proof status
./scripts/dogfood.sh   # the tool checks its own docs and specs

License

MIT. ASD-STE100 is a specification of ASD. This project has no affiliation with ASD.