devrites 5.11.0 → 5.12.0

package/engine/internal/acceptance/exec.go

@@ -0,0 +1,131 @@
+package acceptance
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"runtime"
+	"time"
+)
+
+// MaxOutputBytes caps each side of a check's captured output before the
+// canonical matcher string is built; an overflow fails the gate rather than
+// truncating into a match.
+const MaxOutputBytes = 1 << 20
+
+// DefaultTimeout bounds one check execution.
+const DefaultTimeout = 120 * time.Second
+
+// RunOutcome is one executed oracle: the process result plus the canonical
+// output string used for EXPECT matching and the evidence fingerprint.
+type RunOutcome struct {
+	ExitCode    int
+	Output      string
+	OutputBytes int
+	Err         error // process failed to start, timed out, or overflowed
+	TimedOut    bool
+}
+
+// shellCommand returns the platform shell invocation for one CHECK string.
+// CHECK lines are code: they run with the checker's ambient permissions,
+// environment, and PATH. This package executes only commands approved against
+// the workspace's vetted test-plan.md vocabulary.
+func shellCommand(ctx context.Context, check, cwd string) *exec.Cmd {
+	var cmd *exec.Cmd
+	if runtime.GOOS == "windows" {
+		comspec := cmdComspec()
+		// #nosec G204 -- check is a vetted test-plan.md preflight command; running
+		// the approved command text is this package's purpose.
+		cmd = exec.CommandContext(ctx, comspec, "/C", check)
+	} else {
+		// #nosec G204 -- check is a vetted test-plan.md preflight command; running
+		// the approved command text is this package's purpose.
+		cmd = exec.CommandContext(ctx, "/bin/sh", "-c", check)
+	}
+	cmd.Dir = cwd
+	return cmd
+}
+
+func cmdComspec() string {
+	if comspec := os.Getenv("ComSpec"); comspec != "" {
+		return comspec
+	}
+	return `C:\Windows\System32\cmd.exe`
+}
+
+// limitedBuffer captures at most MaxOutputBytes and records overflow.
+type limitedBuffer struct {
+	buf      bytes.Buffer
+	overflow bool
+}
+
+func (b *limitedBuffer) Write(p []byte) (int, error) {
+	if b.buf.Len()+len(p) > MaxOutputBytes {
+		keep := MaxOutputBytes - b.buf.Len()
+		b.buf.Write(p[:keep])
+		b.overflow = true
+		return len(p), nil
+	}
+	return b.buf.Write(p)
+}
+
+// Execute runs one CHECK under the platform shell in cwd and returns the
+// canonical outcome. The canonical matcher string is all stdout, one synthetic
+// newline when both streams are nonempty, then all stderr.
+func Execute(ctx context.Context, check, cwd string, timeout time.Duration) RunOutcome {
+	if timeout <= 0 {
+		timeout = DefaultTimeout
+	}
+	ctx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	cmd := shellCommand(ctx, check, cwd)
+	configureProcessGroup(cmd)
+	stdout := &limitedBuffer{}
+	stderr := &limitedBuffer{}
+	cmd.Stdout = stdout
+	cmd.Stderr = stderr
+
+	startErr := cmd.Start()
+	if startErr != nil {
+		return RunOutcome{Err: fmt.Errorf("check could not start: %v", startErr)}
+	}
+	waitErr := cmd.Wait()
+	if ctx.Err() == context.DeadlineExceeded {
+		terminateProcessTree(cmd)
+		return RunOutcome{Err: fmt.Errorf("check timed out after %s", timeout), TimedOut: true}
+	}
+	if stdout.overflow || stderr.overflow {
+		return RunOutcome{Err: fmt.Errorf("check output exceeded %d bytes", MaxOutputBytes)}
+	}
+	out, errText := stdout.buf.String(), stderr.buf.String()
+	canonical := out
+	if out != "" && errText != "" {
+		canonical += "\n"
+	}
+	canonical += errText
+	if len(canonical) > MaxOutputBytes {
+		return RunOutcome{Err: fmt.Errorf("check output exceeded %d bytes after decoding", MaxOutputBytes)}
+	}
+	exit := 0
+	if waitErr != nil {
+		if exitErr, ok := waitErr.(*exec.ExitError); ok {
+			exit = exitErr.ExitCode()
+		} else {
+			return RunOutcome{Err: fmt.Errorf("check did not complete: %v", waitErr), ExitCode: -1, Output: canonical, OutputBytes: len(canonical)}
+		}
+	}
+	return RunOutcome{ExitCode: exit, Output: canonical, OutputBytes: len(canonical)}
+}
+
+// terminateProcessTree kills the whole process group on unix; on other
+// platforms it kills only the immediate child (CommandContext already requests
+// it). Implemented in the platform files as killGroup.
+func terminateProcessTree(cmd *exec.Cmd) {
+	if cmd.Process == nil {
+		return
+	}
+	killGroup(cmd)
+}

package/engine/internal/acceptance/exec_unix.go

@@ -0,0 +1,22 @@
+//go:build !windows
+
+package acceptance
+
+import (
+	"os/exec"
+	"syscall"
+)
+
+// configureProcessGroup puts the check in its own process group so a timeout
+// can signal the shell plus every descendant it spawned.
+func configureProcessGroup(cmd *exec.Cmd) {
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+}
+
+func killGroup(cmd *exec.Cmd) {
+	// #nosec G204 -- PID comes from the child this process just started; the
+	// negative form signals the process group it leads.
+	if cmd.Process != nil {
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+	}
+}

package/engine/internal/acceptance/exec_windows.go

@@ -0,0 +1,16 @@
+//go:build windows
+
+package acceptance
+
+import "os/exec"
+
+// configureProcessGroup is a no-op on Windows: CommandContext already wires
+// the kill to the child handle, and a detached supervisor is beyond the
+// stdlib-only engine boundary.
+func configureProcessGroup(cmd *exec.Cmd) {}
+
+func killGroup(cmd *exec.Cmd) {
+	if cmd.Process != nil {
+		_ = cmd.Process.Kill()
+	}
+}

package/engine/internal/acceptance/ledger.go

@@ -0,0 +1,259 @@
+// Package acceptance implements the machine-checked acceptance ledger: the
+// gates.md contract that turns each required outcome into a decidable gate.
+// A runnable gate pairs a vetted CHECK command with an EXPECT oracle and passes
+// only on exit 0 plus a match; recorded evidence is bound to the exact oracle
+// definition so edited commands silently keep stale passes. The package owns
+// parsing, non-executing status reduction, linting, and execution; it never
+// judges whether an English title matches its oracle.
+package acceptance
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/devrites/devrites/internal/markdowntext"
+)
+
+// GatesFile is the canonical acceptance-ledger artifact name inside a feature
+// workspace.
+const GatesFile = "gates.md"
+
+const maxGateIDLen = 64
+
+// Gate is one parsed acceptance gate. Runnable gates carry Check and Expect;
+// manual gates carry neither.
+type Gate struct {
+	ID       string
+	Title    string
+	Checked  bool
+	Check    string
+	Expect   string
+	Cwd      string
+	Evidence string
+	Line     int // 1-based line of the "- [ ]" row in the original text
+}
+
+// Document is a parsed ledger. Errors is fail-closed: any entry means the
+// ledger cannot produce a completion certificate.
+type Document struct {
+	Gates     []*Gate
+	Abandoned map[string]string // gate id -> reason
+	Errors    []string
+	Warnings  []string
+	newline   string // "\r\n" when the source used CRLF
+}
+
+var (
+	gateLineRE      = regexp.MustCompile(`^\s*- \[([ xX])\] ([^\s:]+): (.*)$`)
+	attrLineRE      = regexp.MustCompile(`^(\s+)(CHECK|EXPECT|CWD|EVIDENCE):(.*)$`)
+	unindentedAttr  = regexp.MustCompile(`^(CHECK|EXPECT|CWD|EVIDENCE):`)
+	abandonLineRE   = regexp.MustCompile(`^ABANDON: (\S+)\s*(.*)$`)
+	indentedAbandon = regexp.MustCompile(`^\s+ABANDON:`)
+	expectSlashRE   = regexp.MustCompile(`^/(.*)/([ims]*)$`)
+)
+
+// Expectation is a compiled EXPECT oracle: a substring or a /regex/ with the
+// optional i/m/s flags mapped onto Go's inline flag syntax.
+type Expectation struct {
+	Kind     string // "substring" or "regex"
+	Literal  string
+	Regex    *regexp.Regexp
+	PathLike bool // regex whose pattern reads as a literal path (lint signal)
+}
+
+// ParseLedger strictly parses a gates.md document. Fenced code blocks are
+// masked per CommonMark fence rules so documentation examples never become
+// gates; masked text keeps byte offsets and line numbers aligned with the
+// source for evidence writeback.
+func ParseLedger(text string) *Document {
+	doc := &Document{Abandoned: map[string]string{}}
+	newline := "\n"
+	if strings.Contains(text, "\r\n") {
+		newline = "\r\n"
+	}
+	doc.newline = newline
+	structural, err := markdowntext.Structural([]byte(text))
+	if err != nil {
+		doc.Errors = append(doc.Errors, "ledger is not valid Markdown text: "+err.Error())
+		return doc
+	}
+	lines := strings.Split(strings.ReplaceAll(string(structural), "\r\n", "\n"), "\n")
+
+	var current *Gate
+	seen := map[string]bool{}
+	flush := func() { current = nil }
+
+	for i, line := range lines {
+		lineno := i + 1
+		if match := gateLineRE.FindStringSubmatch(line); match != nil {
+			id := match[2]
+			if len(id) > maxGateIDLen {
+				doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: gate id %q exceeds %d characters", lineno, id, maxGateIDLen))
+				continue
+			}
+			if seen[id] {
+				doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: duplicate gate id %q", lineno, id))
+				continue
+			}
+			seen[id] = true
+			current = &Gate{ID: id, Title: strings.TrimSpace(match[3]), Checked: match[1] != " ", Line: lineno}
+			doc.Gates = append(doc.Gates, current)
+			continue
+		}
+		if match := attrLineRE.FindStringSubmatch(line); match != nil {
+			value := strings.TrimSpace(match[3])
+			if current == nil {
+				doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: %s attribute has no gate", lineno, match[2]))
+				continue
+			}
+			switch match[2] {
+			case "CHECK":
+				current.Check = unquoteCode(value)
+			case "EXPECT":
+				current.Expect = value
+			case "CWD":
+				current.Cwd = value
+			case "EVIDENCE":
+				current.Evidence = value
+			}
+			continue
+		}
+		if unindentedAttr.MatchString(line) {
+			doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: attribute must be indented beneath its gate: %q", lineno, strings.TrimSpace(line)))
+			continue
+		}
+		if match := abandonLineRE.FindStringSubmatch(line); match != nil {
+			reason := strings.TrimSpace(match[2])
+			if reason == "" {
+				doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: ABANDON %s needs a non-blank reason", lineno, match[1]))
+				continue
+			}
+			doc.Abandoned[match[1]] = reason
+			continue
+		}
+		if indentedAbandon.MatchString(line) {
+			doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: ABANDON: must start at column 1", lineno))
+			continue
+		}
+		// Any non-blank, non-structural line ends gate attribute scope.
+		if strings.TrimSpace(line) != "" {
+			flush()
+		}
+	}
+
+	if len(doc.Gates) == 0 && len(doc.Errors) == 0 {
+		doc.Errors = append(doc.Errors, "ledger declares no gates")
+	}
+	for id := range doc.Abandoned {
+		if !seen[id] {
+			doc.Errors = append(doc.Errors, fmt.Sprintf("ABANDON names unknown gate id %q", id))
+		}
+	}
+	for _, gate := range doc.Gates {
+		switch {
+		case gate.Check == "" && gate.Expect == "":
+			// Manual gate: judged by human evidence.
+		case gate.Check != "" && gate.Expect != "":
+			if _, err := CompileExpect(gate.Expect); err != nil {
+				doc.Errors = append(doc.Errors, fmt.Sprintf("gate %s: %v", gate.ID, err))
+			}
+		default:
+			doc.Errors = append(doc.Errors, fmt.Sprintf("gate %s is a partial runnable gate: CHECK and EXPECT must both be present or both absent", gate.ID))
+		}
+		if gate.Cwd != "" {
+			if err := validateLedgerCwd(gate.Cwd); err != nil {
+				doc.Errors = append(doc.Errors, fmt.Sprintf("gate %s: %v", gate.ID, err))
+			}
+		}
+		if gate.Check != "" && gate.Evidence == "" {
+			doc.Warnings = append(doc.Warnings, fmt.Sprintf("gate %s has no EVIDENCE line; the runner inserts one", gate.ID))
+		}
+	}
+	return doc
+}
+
+// unquoteCode unwraps one markdown code span: `cmd` becomes cmd. Writers copy
+// commands from the backticked preflight table; approval and execution bind
+// the command text, not its markdown decoration.
+func unquoteCode(s string) string {
+	if len(s) >= 2 && s[0] == '`' && s[len(s)-1] == '`' {
+		return s[1 : len(s)-1]
+	}
+	return s
+}
+
+// validateLedgerCwd requires a repository-relative working directory with no
+// traversal or absolute anchor.
+func validateLedgerCwd(cwd string) error {
+	if cwd == "" {
+		return nil
+	}
+	if strings.HasPrefix(cwd, "/") || regexp.MustCompile(`^[A-Za-z]:[\\/]`).MatchString(cwd) || strings.HasPrefix(cwd, `\\`) {
+		return fmt.Errorf("CWD must be repository-relative, not absolute: %q", cwd)
+	}
+	for _, seg := range strings.FieldsFunc(cwd, func(r rune) bool { return r == '/' || r == '\\' }) {
+		if seg == ".." {
+			return fmt.Errorf("CWD must not contain traversal: %q", cwd)
+		}
+	}
+	return nil
+}
+
+// CompileExpect parses an EXPECT value into its oracle. A /pattern/flags form
+// is a regular expression; every other value is a literal substring.
+func CompileExpect(expect string) (Expectation, error) {
+	if match := expectSlashRE.FindStringSubmatch(expect); match != nil {
+		pattern, flags := match[1], match[2]
+		prefix := ""
+		for _, f := range flags {
+			switch f {
+			case 'i':
+				prefix += "i"
+			case 'm':
+				prefix += "m"
+			case 's':
+				prefix += "s"
+			default:
+				return Expectation{}, fmt.Errorf("EXPECT regex has unsupported flag %q", string(f))
+			}
+		}
+		compiled, err := regexp.Compile(prefixFlags(prefix, pattern))
+		if err != nil {
+			return Expectation{}, fmt.Errorf("EXPECT regex is invalid: %v", err)
+		}
+		return Expectation{
+			Kind:     "regex",
+			Literal:  expect,
+			Regex:    compiled,
+			PathLike: strings.Contains(pattern, "/"),
+		}, nil
+	}
+	if expect == "" {
+		return Expectation{}, fmt.Errorf("EXPECT is empty")
+	}
+	return Expectation{Kind: "substring", Literal: expect}, nil
+}
+
+func prefixFlags(flags, pattern string) string {
+	if flags == "" {
+		return pattern
+	}
+	return "(?" + flags + ")" + pattern
+}
+
+// Matches reports whether the canonical combined output satisfies the oracle.
+func (e Expectation) Matches(output string) bool {
+	if e.Kind == "regex" {
+		return e.Regex.MatchString(output)
+	}
+	return strings.Contains(output, e.Literal)
+}
+
+// Newline returns the document's original line-ending style for writeback.
+func (d *Document) Newline() string {
+	if d.newline == "" {
+		return "\n"
+	}
+	return d.newline
+}

package/engine/internal/acceptance/lint.go

@@ -0,0 +1,115 @@
+package acceptance
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// Finding is one advisory lint observation: a lexical sign that an oracle may
+// be unable to fail honestly. Findings are prompts to sharpen a gate, not
+// proof the outcome is wrong.
+type Finding struct {
+	Level   string // "error" or "warn"
+	Gate    string
+	Rule    string
+	Message string
+}
+
+var (
+	fixedOutputRE = regexp.MustCompile(`^\s*(?:(?:echo|printf)(?:\s+[^&|;]*)?|true|:|exit\s+0)\s*$`)
+	weakExpect    = map[string]bool{
+		"ok": true, "okay": true, "done": true, "pass": true, "passed": true,
+		"success": true, "successful": true, "succeeded": true, "complete": true,
+		"completed": true, "finished": true, "yes": true, "true": true,
+		"0": true, "good": true, "fine": true, "working": true,
+	}
+	activityStartRE = regexp.MustCompile(`(?i)^(work(ing)? on|improve|enhance|handle|support|ensure|make sure|try|attempt|look (at|into)|investigate|consider|review|refactor|clean ?up|polish|update|tidy|address|deal with|add support)\b`)
+)
+
+// LintLedger audits oracle quality without executing anything: fixed-output
+// commands, expectations that also appear in failure output, path-shaped
+// regexes, activity titles, unmeasured numbers, and mostly-manual ledgers.
+// approved is the vetted (command, cwd) surface; a runnable CHECK outside it
+// is an authoring error because the runner can never execute it.
+func LintLedger(doc *Document, approved []ApprovedCommand) []Finding {
+	var findings []Finding
+	add := func(level, gate, rule, format string, args ...any) {
+		findings = append(findings, Finding{Level: level, Gate: gate, Rule: rule, Message: fmt.Sprintf(format, args...)})
+	}
+	for _, err := range doc.Errors {
+		add("error", "", "parse", "%s", err)
+	}
+
+	live := 0
+	runnable := 0
+	for _, gate := range doc.Gates {
+		if _, abandoned := doc.Abandoned[gate.ID]; abandoned {
+			continue
+		}
+		live++
+		if gate.Check == "" {
+			add("warn", gate.ID, "manual-gate",
+				"no CHECK, so this outcome is judged by hand and its evidence is only as good as the reader")
+			if regexp.MustCompile(`\d`).MatchString(gate.Title) {
+				add("warn", gate.ID, "unmeasured-number",
+					"title states a number that nothing measures: %q", gate.Title)
+			}
+		} else {
+			runnable++
+			if fixedOutputRE.MatchString(gate.Check) {
+				add("warn", gate.ID, "tautological-check",
+					"CHECK looks like a fixed-output command: %q; use an oracle that observes the named outcome", gate.Check)
+			}
+			if approved != nil && !Approved(gate.Check, gate.Cwd, approved) {
+				add("error", gate.ID, "unapproved-check",
+					"CHECK %q with CWD %q matches no Build-entry preflight row in test-plan.md; the runner refuses it", gate.Check, gate.Cwd)
+			}
+		}
+		if gate.Expect != "" {
+			if weakExpect[strings.ToLower(strings.TrimSpace(gate.Expect))] {
+				add("warn", gate.ID, "weak-expect",
+					"EXPECT %q also appears in failure output; match a line only success can print", gate.Expect)
+			}
+			if expectation, err := CompileExpect(gate.Expect); err == nil && expectation.Kind == "regex" && expectation.PathLike {
+				add("warn", gate.ID, "path-read-as-regex",
+					"EXPECT %q looks like a literal path but is read as a regular expression, so its dots are wildcards", gate.Expect)
+			}
+		}
+		if activityStartRE.MatchString(gate.Title) {
+			add("warn", gate.ID, "activity-not-outcome",
+				"names an activity, not an outcome a stranger could judge: %q", gate.Title)
+		}
+	}
+	if live > 0 && runnable*2 < live {
+		add("warn", "", "mostly-manual",
+			"%d/%d gates are runnable; a mostly manual ledger is prose with checkboxes", runnable, live)
+	}
+	seen := map[string]string{}
+	for _, gate := range doc.Gates {
+		if _, abandoned := doc.Abandoned[gate.ID]; abandoned || gate.Check == "" {
+			continue
+		}
+		key := normalizeCommand(gate.Check) + "\x00" + strings.Join(strings.Fields(gate.Expect), " ") + "\x00" + normalizeApprovedCwd(gate.Cwd)
+		if first, ok := seen[key]; ok {
+			add("warn", gate.ID, "duplicate-oracle",
+				"same CHECK+EXPECT+CWD as %s: two gates running one oracle is one method counted twice, not broader coverage", first)
+			continue
+		}
+		seen[key] = gate.ID
+	}
+	return findings
+}
+
+// LintCounts summarizes findings for exit-code decisions: errors always fail;
+// warnings fail only under strict.
+func LintCounts(findings []Finding) (errors, warnings int) {
+	for _, finding := range findings {
+		if finding.Level == "error" {
+			errors++
+		} else {
+			warnings++
+		}
+	}
+	return errors, warnings
+}