ste: the ASD-STE100 validator

ste validates text against ASD-STE100 Simplified Technical English. Two forms ship from one spec: a Go CLI and library, and a Node.js CLI and library with zero dependencies. Both are AI-native. Each command can emit JSON. The exit codes are stable. Error messages name the next action.

An ASD-STE100 Issue 9 dictionary ships with each CLI and needs no flag. THIRD_PARTY_NOTICES.md names the source and the terms for the data. Supply your own file with --dictionary or STE_DICTIONARY. Use --no-dictionary to turn the dictionary rules off. A sample dictionary stays for demos and tests: --sample-dictionary.

Install

Go CLI:

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

Node.js CLI, from npm or from GitHub:

npm install -g @probelabs/ste        # from the npm registry
npm install -g github:probelabs/ste  # from GitHub

Go library:

import "github.com/probelabs/ste"

Node.js library:

const ste = require("@probelabs/ste");

The Node.js form needs Node.js version 18 or more. It has no dependencies.

Use

ste check manual.md                          # pretty output with source lines
ste check --format json docs/*.md            # ste-diagnostics/v1 JSON
ste check --format sarif docs/*.md           # SARIF 2.1.0 for code scanning
ste check --format text docs/*.md            # one line for each finding
cat procedure.txt | ste check -              # read from stdin
ste rules                                    # list the rule catalog
ste dictionary inspect my-dictionary.json    # validate a dictionary file

The Node.js CLI is the same command:

node node/bin/ste.js check manual.md
npx @probelabs/ste check manual.md

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

When a rule knows an approved alternative, the finding names it. The pretty format shows it below the source line. The JSON output carries it as suggestion.

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

Go:

dict, _ := ste.FullDictionary() // embedded Issue 9 dictionary
env := &ste.Env{Dict: dict, Opts: ste.DefaultOptions()}
v := ste.NewValidator(env, rules.Catalog()...)
diags := v.Validate(ste.ParseMarkdown("Remove the valve."))

Node.js:

const ste = require("@probelabs/ste");
const { catalog } = require("@probelabs/ste/node/src/rules/rules.js");

const dict = ste.fullDictionary(); // embedded Issue 9 dictionary
const v = ste.newValidator(
  { dict, opts: ste.defaultOptions() },
  ...catalog()
);
const diags = v.validate(ste.parseMarkdown("Remove the valve."));

Each library reads a ste-dictionary/v1 file: ste.LoadDictionary(path) in Go, ste.loadDictionary(path) in Node.js.

Two forms of one spec

The project holds the same spec in two forms: the Go source in ste.go, cmd/ste/, and internal/, and a Node.js form in node/. Both give the same rule catalog, the same message text, the same exit code set, and the same output format set. The embedded dictionary is the same data.

The Node.js form is a ReqProof Mirror of the Go source, and the release gate holds the parity. The next section shows how.

Verification with proof

This project uses ReqProof for the specs, the verification, and the release gate:

• Keep the specs in specs/, in four-layer form: stakeholder, system, software, and interface requirements. Each requirement carries a formal FRETish sentence, not prose alone.
• Map the code to the requirements with Implements: and Verifies: annotation text on each function and each test.
• Keep MC/DC witness rows for the decision logic of each requirement. Make each mcdc:ignore:defensive row a reviewed item.
• Map each Go component to its node/ target with one of the eight Mirror files in proof/mirrors/.
• Keep the full verification ledger of the source in each Mirror: implements, verifies, obligation evidence, MC/DC witness, and known-issue cell sets.
• Run proof audit as the release gate: 209 checks, zero errors, zero warnings. The gate has mirror_complete, so a target that drops a cell the source holds fails the gate.

proof status                 # requirement coverage
proof mirror status          # Go -> Node.js parity, all mirrors
proof audit --no-cache       # the release gate: 0 errors, 0 warnings

The tool checks its own prose. scripts/dogfood.sh runs ste on this README, the architecture document, and the specs with the sample dictionary, and the run must stay clean.

go test ./...                      # Go test suite
node --test node/test/*.test.js    # Node.js test suite
proof validate
./scripts/dogfood.sh

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"]}
  ]
}

License

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