ste.go

// Package ste validates text against ASD-STE100 Simplified Technical English.
//
// The package exposes a small stable API: build a Document from source text,
// configure a Validator with rules and an Env, and read the resulting
// Diagnostics. The CLI in cmd/ste is a thin wrapper over this API.
package ste

// Implements: SW-REQ-029

import (
	"sort"

	"github.com/probelabs/ste/internal/dictionary"
	"github.com/probelabs/ste/internal/markup"
	"github.com/probelabs/ste/internal/text"
)

// Implements: SYS-REQ-004, INT-REQ-001, SW-REQ-008

// Severity ranks a Diagnostic.
type Severity int

const (
	// SeverityError is a hard STE violation.
	SeverityError Severity = iota
	// SeverityWarning is a likely violation or a heuristic finding.
	SeverityWarning
	// SeverityInfo is advisory.
	SeverityInfo
)

// String returns the lowercase severity name used in machine output.
func (s Severity) String() string {
	switch s {
	case SeverityError:
		return "error"
	case SeverityWarning:
		return "warning"
	default:
		return "info"
	}
}

// SeverityFromString parses a severity name.
func SeverityFromString(s string) (Severity, bool) {
	switch s {
	case "error":
		return SeverityError, true
	case "warning":
		return SeverityWarning, true
	case "info":
		return SeverityInfo, true
	default:
		return SeverityError, false
	}
}

// Diagnostic is one rule finding with a 1-based source location.
type Diagnostic struct {
	Rule     string   `json:"rule"`
	Severity Severity `json:"-"`
	Message  string   `json:"message"`
	// Suggestion is an imperative fix when the rule knows one.
	Suggestion string `json:"suggestion,omitempty"`
	Line       int    `json:"line"`
	Column     int    `json:"column"`
	// Length is the span width in runes for caret highlighting (0 = 1).
	Length int `json:"length,omitempty"`
}

// Word is one token with its 1-based source position.
type Word = text.Word

// Sentence is one sentence of source text.
type Sentence = text.Sentence

// Document is parsed source text ready for validation.
type Document struct {
	Source    string
	Sentences []Sentence
}

// Parse splits plain source text into sentences.
func Parse(source string) *Document {
	return &Document{Source: source, Sentences: text.Split(source, nil)}
}

// ParseSteps splits plain source text into sentences, marking sentences that
// start on one of the given 1-based lines as procedure steps. Hosts whose
// fields are procedure-shaped (acceptance-criterion text governed as one
// instruction per step) mark every line, which scopes the imperative rules
// the way a list-item document would. Positions refer to the source.
func ParseSteps(source string, stepLines map[int]bool) *Document {
	return &Document{Source: source, Sentences: text.Split(source, stepLines)}
}

// ParseMarkdown strips markdown syntax, then splits into sentences. List
// items become procedure steps. Positions refer to the original source.
func ParseMarkdown(source string) *Document {
	clean := markup.Clean(source)
	return &Document{Source: source, Sentences: text.Split(clean.Text, clean.StepLines)}
}

// Dictionary is the approved-word dictionary type.
type Dictionary = dictionary.Dictionary

// Entry is one dictionary word: its part of speech, approval status, approved
// alternatives, and approved inflected forms. Hosts build entries in memory
// to overlay project vocabulary on a loaded dictionary; see
// Dictionary.MergeEntries.
type Entry = dictionary.Entry

// LoadDictionary reads a ste-dictionary/v1 JSON dictionary file.
func LoadDictionary(path string) (*Dictionary, error) {
	return dictionary.Load(path)
}

// SampleDictionary returns the embedded sample dictionary for tests and demos.
func SampleDictionary() (*Dictionary, error) {
	return dictionary.Sample()
}

// FullDictionary returns the embedded ASD-STE100 Issue 9 dictionary. It is
// the default dictionary of the CLI. See THIRD_PARTY_NOTICES.md for
// provenance and attribution.
func FullDictionary() (*Dictionary, error) {
	return dictionary.Full()
}

// Options tune the rule catalog. The zero value is invalid; use
// DefaultOptions.
type Options struct {
	// InstructionWords is the word limit for an instruction sentence.
	InstructionWords int
	// DescriptiveWords is the word limit for a descriptive sentence.
	DescriptiveWords int
	// NounClusterWords is the limit for consecutive nouns.
	NounClusterWords int
	// ParagraphSentences is the sentence limit for a descriptive paragraph.
	ParagraphSentences int
	// Units are the approved units of measurement.
	Units []string
	// AllowedPunctuation lists the approved punctuation marks.
	AllowedPunctuation []rune
}

// DefaultOptions returns the ASD-STE100 default limits and lists.
func DefaultOptions() Options {
	return Options{
		InstructionWords:   20,
		DescriptiveWords:   25,
		NounClusterWords:   3,
		ParagraphSentences: 10,
		Units: []string{"mm", "cm", "m", "km", "kg", "g", "N", "kPa", "MPa",
			"V", "A", "W", "°C", "min", "s", "h", "l", "ml"},
		AllowedPunctuation: []rune{'.', ',', ':', '-', '\'', '(', ')', '"', '?', '/'},
	}
}

// Env carries the run context every rule sees.
type Env struct {
	Dict *Dictionary
	Opts Options
}

// Rule is one deterministic ASD-STE100 checker. Rules register with the
// catalog in internal/rules; the engine executes every registered rule.
type Rule interface {
	// ID is the stable rule identifier, for example "sentence-length".
	ID() string
	// Section is the ASD-STE100 writing-rule section the rule maps to.
	Section() string
	// Description is one STE sentence that states what the rule checks.
	Description() string
	// Check examines a Document. env.Dict may be nil; rules that need a
	// dictionary must report nothing when it is nil.
	Check(d *Document, env *Env) []Diagnostic
}

// Validator runs a set of rules over Documents.
type Validator struct {
	env   *Env
	rules []Rule
}

// NewValidator builds a Validator. Rules execute in the order given.
func NewValidator(env *Env, rules ...Rule) *Validator {
	return &Validator{env: env, rules: rules}
}

// Validate runs every registered rule and returns diagnostics sorted by
// source position, then rule id. The result is deterministic. Findings of the
// word-form rule family (approved-words, approved-form, ing-form) are folded
// to one per token: they describe a single defect — a word outside its
// approved dictionary entry — from three angles.
func (v *Validator) Validate(d *Document) []Diagnostic {
	var diags []Diagnostic
	for _, r := range v.rules {
		diags = append(diags, r.Check(d, v.env)...)
	}
	diags = dedupeWordForms(diags)
	sort.SliceStable(diags, func(i, j int) bool {
		if diags[i].Line != diags[j].Line {
			return diags[i].Line < diags[j].Line
		}
		if diags[i].Column != diags[j].Column {
			return diags[i].Column < diags[j].Column
		}
		return diags[i].Rule < diags[j].Rule
	})
	return diags
}