devrites 2.6.0 → 3.0.0

package/engine/internal/lib/specvalidate.go

@@ -0,0 +1,391 @@
+// Package lib holds native Go implementations of the deterministic, zero-token
+// workflow checks DevRites used to run as individual .sh helpers. Each exported
+// function owns its logic outright — it does not shell out — and reproduces the
+// legacy behavior (stdout + exit code) exactly, verified in the CLI test suite
+// by golden assertions or, transitionally, a bash-parity comparison.
+package lib
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// Spec-grammar validator — deterministic lint of the structured
+// Requirement/Scenario acceptance grammar in a spec.md. A port of
+// spec-validate.sh; see standards/spec-grammar.md for the grammar.
+//
+// Exit codes: 0 valid (or no structured requirements — nothing to lint) ·
+// 1 grammar violation(s) · 2 usage · 5 missing spec.md.
+var (
+	reqHeaderRe  = regexp.MustCompile(`^[[:space:]]*###[[:space:]]+[Rr]equirement:`)
+	reqPrefixRe  = regexp.MustCompile(`^[[:space:]]*###[[:space:]]+[Rr]equirement:[[:space:]]*`)
+	scenHeaderRe = regexp.MustCompile(`^[[:space:]]*####[[:space:]]+[Ss]cenario:`)
+	scenPrefixRe = regexp.MustCompile(`^[[:space:]]*####[[:space:]]+[Ss]cenario:[[:space:]]*`)
+	trailWSRe    = regexp.MustCompile(`[[:space:]]+$`)
+	shallRe      = regexp.MustCompile(`(^|[^A-Za-z])(SHALL|MUST)([^A-Za-z]|$)`)
+	whenRe       = regexp.MustCompile(`(^|[^A-Za-z])WHEN([^A-Za-z]|$)`)
+	thenRe       = regexp.MustCompile(`(^|[^A-Za-z])THEN([^A-Za-z]|$)`)
+	reqIDRe      = regexp.MustCompile(`REQ-[0-9]+`)
+	acBareIDRe   = regexp.MustCompile(`AC-[0-9]+`)
+)
+
+// SpecValidate lints the structured grammar in a spec.md. arg is a workspace dir
+// (its spec.md is linted) or a direct spec.md path. against, when non-empty, is a
+// capability-ledger root (`.devrites/specs`) the spec's delta sections are
+// cross-checked against (an ADDED requirement must not already exist in its
+// capability's ledger; a MODIFIED/REMOVED one must). cwd relativizes the printed
+// path, matching the bash ${spec#"$PWD"/}. It writes to stdout/stderr and returns
+// the process exit code.
+func SpecValidate(arg, against, cwd string, stdout, stderr io.Writer) int {
+	spec, code, ok := resolveSpecPath("spec-validate", arg, stderr)
+	if !ok {
+		return code
+	}
+
+	reqs, scens, findings, err := lintSpec(spec)
+	findings = append(findings, lintEdgeProhibitionTables(spec)...)
+	if err != nil {
+		fmt.Fprintf(stderr, "spec-validate: %v\n", err)
+		return 2
+	}
+
+	rel := strings.TrimPrefix(spec, cwd+"/")
+
+	if reqs == 0 && len(findings) == 0 {
+		fmt.Fprintf(stdout, "spec-validate: %s uses the simple acceptance form (no \"### Requirement:\" blocks) — nothing to lint\n", rel)
+		return 0
+	}
+
+	// Delta cross-check (opt-in via --against): a spec written as deltas against a
+	// living ledger must classify each requirement correctly. Skipped for a flat
+	// snapshot (no delta sections) — there is nothing to reconcile.
+	if against != "" {
+		findings = append(findings, checkAgainstLedger(spec, against, defaultCapability(arg))...)
+	}
+
+	if len(findings) > 0 {
+		for _, f := range findings {
+			fmt.Fprintln(stderr, f)
+		}
+		fmt.Fprintf(stderr, "spec-validate: %s — %d requirement(s) / %d scenario(s); %d grammar error(s) (see standards/spec-grammar.md)\n",
+			rel, reqs, scens, len(findings))
+		return 1
+	}
+
+	fmt.Fprintf(stdout, "spec-validate: OK — %s: %d requirement(s) / %d scenario(s) well-formed (SHALL + WHEN/THEN, unique headers)\n",
+		rel, reqs, scens)
+	return 0
+}
+
+// lintSpec walks the spec once, mirroring the single awk pass in spec-validate.sh:
+// it counts requirements and scenarios and collects ERROR findings in encounter
+// order. `file` is used verbatim in the finding messages (the awk FILE var).
+func lintEdgeProhibitionTables(file string) []string {
+	data, err := os.ReadFile(file)
+	if err != nil {
+		return nil
+	}
+	text := string(data)
+	knownText := sectionBody(text, "Requirements") + "\n" + sectionBody(text, "Acceptance criteria")
+	known := map[string]bool{}
+	for _, id := range reqIDRe.FindAllString(knownText, -1) {
+		known[id] = true
+	}
+	for _, id := range acBareIDRe.FindAllString(knownText, -1) {
+		known[id] = true
+	}
+	var findings []string
+	for _, row := range markdownTableRows(sectionBody(text, "Edge Coverage")) {
+		if len(row) < 4 {
+			continue
+		}
+		id, target, status, reason := row[0], row[1], strings.ToLower(row[3]), ""
+		if len(row) > 4 {
+			reason = strings.TrimSpace(row[4])
+		}
+		if !tableTargetKnown(target, known) && !(status == "dismissed" && reason != "") {
+			findings = append(findings, fmt.Sprintf("ERROR:%s: Edge Coverage %q targets no known REQ/AC and is not dismissed with a reason", file, id))
+		}
+	}
+	for _, row := range markdownTableRows(sectionBody(text, "Prohibitions (must-NOT)")) {
+		if len(row) < 4 {
+			continue
+		}
+		id, target, status, proof := row[0], row[1], strings.ToLower(row[2]), strings.TrimSpace(row[3])
+		if !tableTargetKnown(target, known) {
+			findings = append(findings, fmt.Sprintf("ERROR:%s: Prohibition %q targets no known REQ/AC", file, id))
+		}
+		if status == "resolved/test" && proof == "" {
+			findings = append(findings, fmt.Sprintf("ERROR:%s: Prohibition %q is resolved/test but has no linked test/evidence", file, id))
+		}
+	}
+	return findings
+}
+
+func sectionBody(text, heading string) string {
+	start := -1
+	lines := strings.Split(text, "\n")
+	for i, line := range lines {
+		if strings.EqualFold(strings.TrimSpace(line), "## "+heading) {
+			start = i + 1
+			break
+		}
+	}
+	if start < 0 {
+		return ""
+	}
+	end := len(lines)
+	for i := start; i < len(lines); i++ {
+		t := strings.TrimSpace(lines[i])
+		if strings.HasPrefix(t, "## ") && !strings.HasPrefix(t, "###") {
+			end = i
+			break
+		}
+	}
+	return strings.Join(lines[start:end], "\n")
+}
+
+func markdownTableRows(body string) [][]string {
+	var rows [][]string
+	for _, line := range strings.Split(body, "\n") {
+		line = strings.TrimSpace(line)
+		if !strings.HasPrefix(line, "|") || !strings.HasSuffix(line, "|") || strings.Contains(line, "---") {
+			continue
+		}
+		parts := strings.Split(strings.Trim(line, "|"), "|")
+		for i := range parts {
+			parts[i] = strings.TrimSpace(parts[i])
+		}
+		if len(parts) > 0 && (strings.EqualFold(parts[0], "Edge ID") || strings.EqualFold(parts[0], "Prohibition ID")) {
+			continue
+		}
+		rows = append(rows, parts)
+	}
+	return rows
+}
+
+func tableTargetKnown(target string, known map[string]bool) bool {
+	for id := range known {
+		if strings.Contains(target, id) {
+			return true
+		}
+	}
+	return false
+}
+
+func lintSpec(file string) (reqCount, scenCount int, findings []string, err error) {
+	f, err := os.Open(file)
+	if err != nil {
+		return 0, 0, nil, fmt.Errorf("read spec: %w", err)
+	}
+	defer f.Close()
+
+	var (
+		curReq        string // "" = not inside a requirement
+		reqLine       int
+		sawShall      bool
+		scenInReq     int
+		looseWhenThen bool
+
+		inScenario bool
+		scenName   string
+		scenLine   int
+		scenWhen   bool
+		scenThen   bool
+
+		seen = map[string]int{} // lowercased requirement name → first line
+	)
+
+	closeScenario := func() {
+		if inScenario {
+			if !scenWhen {
+				findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement \"%s\" > Scenario \"%s\" (line %d) has no WHEN line", file, curReq, scenName, scenLine))
+			}
+			if !scenThen {
+				findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement \"%s\" > Scenario \"%s\" (line %d) has no THEN line", file, curReq, scenName, scenLine))
+			}
+			inScenario = false
+		}
+	}
+	closeRequirement := func() {
+		closeScenario()
+		if curReq != "" {
+			if !sawShall {
+				findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement \"%s\" (line %d) has no SHALL/MUST statement", file, curReq, reqLine))
+			}
+			if scenInReq == 0 {
+				if looseWhenThen {
+					findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement \"%s\" (line %d) has WHEN/THEN lines but no \"#### Scenario:\" header — wrap them in a scenario", file, curReq, reqLine))
+				} else {
+					findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement \"%s\" (line %d) has no \"#### Scenario:\" block", file, curReq, reqLine))
+				}
+			}
+		}
+	}
+
+	sc := newLineScanner(f)
+	nr := 0
+	for sc.Scan() {
+		line := sc.Text()
+		nr++
+		switch {
+		case reqHeaderRe.MatchString(line):
+			closeRequirement()
+			reqCount++
+			name := trailWSRe.ReplaceAllString(reqPrefixRe.ReplaceAllString(line, ""), "")
+			curReq = name
+			reqLine = nr
+			sawShall = shallRe.MatchString(line)
+			scenInReq = 0
+			looseWhenThen = false
+			key := strings.ToLower(name)
+			if first, dup := seen[key]; dup {
+				findings = append(findings, fmt.Sprintf("ERROR:%s: duplicate Requirement header \"%s\" (lines %d and %d) — headers must be unique", file, name, first, nr))
+			} else {
+				seen[key] = nr
+			}
+		case scenHeaderRe.MatchString(line):
+			closeScenario()
+			if curReq == "" {
+				findings = append(findings, fmt.Sprintf("ERROR:%s: Scenario at line %d is not under any \"### Requirement:\"", file, nr))
+			}
+			sName := trailWSRe.ReplaceAllString(scenPrefixRe.ReplaceAllString(line, ""), "")
+			inScenario = true
+			scenCount++
+			scenInReq++
+			scenName = sName
+			scenLine = nr
+			scenWhen = false
+			scenThen = false
+		default:
+			if curReq != "" {
+				if shallRe.MatchString(line) {
+					sawShall = true
+				}
+				hasWhen := whenRe.MatchString(line)
+				hasThen := thenRe.MatchString(line)
+				if inScenario {
+					if hasWhen {
+						scenWhen = true
+					}
+					if hasThen {
+						scenThen = true
+					}
+				} else if hasWhen || hasThen {
+					looseWhenThen = true
+				}
+			}
+		}
+	}
+	if err := sc.Err(); err != nil {
+		return 0, 0, nil, fmt.Errorf("scan %s: %w", file, err)
+	}
+	closeRequirement()
+	return reqCount, scenCount, findings, nil
+}
+
+// maxScanLine caps the line length the section scanners accept. It sits far above
+// any realistic spec line, so lines are effectively unbounded (matching awk's
+// no-limit record read) without pre-allocating the buffer.
+const maxScanLine = 1 << 30
+
+// newLineScanner returns a bufio.Scanner that splits on newlines (stripping a
+// trailing CR like awk with RS="\n") and tolerates very long lines.
+func newLineScanner(r io.Reader) *bufio.Scanner {
+	sc := bufio.NewScanner(r)
+	sc.Buffer(make([]byte, 0, 64*1024), maxScanLine)
+	return sc
+}
+
+func resolveSpecPath(command, arg string, stderr io.Writer) (string, int, bool) {
+	if arg == "" {
+		fmt.Fprintf(stderr, "usage: devrites-engine %s <workspace-dir | spec.md path>\n", command)
+		return "", 2, false
+	}
+
+	var spec string
+	switch {
+	case isDir(arg):
+		spec = arg + "/spec.md" // string concat, not filepath.Join — preserve the exact path bytes
+	case isFile(arg):
+		spec = arg
+	default:
+		fmt.Fprintf(stderr, "%s: no such workspace or file: %s\n", command, arg)
+		return "", 2, false
+	}
+	if !isFile(spec) {
+		fmt.Fprintf(stderr, "%s: no spec.md at %s\n", command, spec)
+		return "", 5, false
+	}
+	return spec, 0, true
+}
+
+// checkAgainstLedger cross-checks a delta spec's requirements against the
+// capability ledger rooted at ledgerRoot (`.devrites/specs`). For each requirement
+// carrying a delta kind it resolves the capability (the section tag, or defaultCap
+// when untagged) and confirms presence matches kind: ADDED must be absent from that
+// capability's ledger spec, MODIFIED/REMOVED must be present. Flat requirements (no
+// delta kind) are ignored. An unseeded capability reads as an empty key set, so the
+// first ADDED against a brand-new capability passes cleanly.
+func checkAgainstLedger(spec, ledgerRoot, defaultCap string) []string {
+	doc, err := ParseSpec(spec)
+	if err != nil || !doc.HasDelta {
+		return nil
+	}
+	cache := map[string]map[string]bool{}
+	keysFor := func(capability string) map[string]bool {
+		if k, ok := cache[capability]; ok {
+			return k
+		}
+		k := requirementKeys(ledgerRoot + "/" + capability + "/spec.md")
+		cache[capability] = k
+		return k
+	}
+	var findings []string
+	for _, r := range doc.Requirements {
+		if r.Kind == "" {
+			continue
+		}
+		capability := r.Capability
+		if capability == "" {
+			capability = defaultCap
+		}
+		exists := keysFor(capability)[r.Key]
+		switch r.Kind {
+		case DeltaAdded:
+			if exists {
+				findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement %q (line %d) is marked ADDED but already exists in ledger capability %q — use MODIFIED, or drop the delta", spec, r.Name, r.HeaderLine, capability))
+			}
+		case DeltaModified, DeltaRemoved:
+			if !exists {
+				findings = append(findings, fmt.Sprintf("ERROR:%s: Requirement %q (line %d) is marked %s but is absent from ledger capability %q — use ADDED, or fix the capability tag", spec, r.Name, r.HeaderLine, strings.ToUpper(r.Kind), capability))
+			}
+		}
+	}
+	return findings
+}
+
+// defaultCapability derives the fallback capability for an untagged delta section:
+// the workspace slug — the basename of the workspace dir, or of the spec.md's
+// parent directory when a bare file path was given.
+func defaultCapability(arg string) string {
+	if isDir(arg) {
+		return filepath.Base(arg)
+	}
+	return filepath.Base(filepath.Dir(arg))
+}
+
+func isDir(p string) bool {
+	fi, err := os.Stat(p)
+	return err == nil && fi.IsDir()
+}
+
+func isFile(p string) bool {
+	fi, err := os.Stat(p)
+	return err == nil && fi.Mode().IsRegular()
+}

package/engine/internal/lib/specvalidate_test.go

@@ -0,0 +1,185 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestSpecValidateCharacterization(t *testing.T) {
+	work := t.TempDir()
+	writeSpec(t, work, "valid", `### Requirement: Export
+The system SHALL export reports.
+#### Scenario: happy path
+- **WHEN** export is requested **THEN** a file is returned
+`)
+	writeSpec(t, work, "flat", `# Spec
+## Acceptance criteria
+- [ ] export returns a CSV
+`)
+	writeSpec(t, work, "nothen", `### Requirement: Export
+The system SHALL export reports.
+#### Scenario: happy path
+- **WHEN** export is requested
+`)
+
+	for _, tc := range []struct {
+		name       string
+		arg        string
+		wantCode   int
+		wantStdout string
+		wantStderr string
+	}{
+		{name: "valid", arg: filepath.Join(work, "valid"), wantCode: 0, wantStdout: "well-formed"},
+		{name: "flat", arg: filepath.Join(work, "flat"), wantCode: 0, wantStdout: "simple acceptance form"},
+		{name: "missing then", arg: filepath.Join(work, "nothen"), wantCode: 1, wantStderr: "has no THEN line"},
+		{name: "missing arg", wantCode: 2, wantStderr: "usage: devrites-engine spec-validate"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+			code := SpecValidate(tc.arg, "", work, stdout, stderr)
+			if code != tc.wantCode {
+				t.Fatalf("SpecValidate code=%d, want %d; stdout=%q stderr=%q", code, tc.wantCode, stdout.String(), stderr.String())
+			}
+			if tc.wantStdout != "" && !strings.Contains(stdout.String(), tc.wantStdout) {
+				t.Fatalf("stdout=%q, want substring %q", stdout.String(), tc.wantStdout)
+			}
+			if tc.wantStderr != "" && !strings.Contains(stderr.String(), tc.wantStderr) {
+				t.Fatalf("stderr=%q, want substring %q", stderr.String(), tc.wantStderr)
+			}
+		})
+	}
+}
+
+func TestSpecValidateEdgeAndProhibitionTables(t *testing.T) {
+	work := t.TempDir()
+	writeSpec(t, work, "ok", `## Requirements
+- REQ-001: The system MUST export.
+
+## Acceptance criteria
+- [ ] AC-001: export works. (REQ-001)
+
+## Edge Coverage
+| Edge ID | Requirement/AC | Class | Status | Reason/backstop |
+| --- | --- | --- | --- | --- |
+| EDGE-001 | AC-001 | empty input | covered | test: TestExportEmpty |
+| EDGE-002 | n/a | timezone | dismissed | no dates involved |
+
+## Prohibitions (must-NOT)
+| Prohibition ID | Requirement/AC | Status | Test/evidence |
+| --- | --- | --- | --- |
+| PROH-001 | REQ-001 | resolved/test | evidence.md#export |
+`)
+	writeSpec(t, work, "bad", `## Requirements
+- REQ-001: The system MUST export.
+
+## Acceptance criteria
+- [ ] AC-001: export works. (REQ-001)
+
+## Edge Coverage
+| Edge ID | Requirement/AC | Class | Status | Reason/backstop |
+| --- | --- | --- | --- | --- |
+| EDGE-001 | AC-999 | empty input | covered | |
+
+## Prohibitions (must-NOT)
+| Prohibition ID | Requirement/AC | Status | Test/evidence |
+| --- | --- | --- | --- |
+| PROH-001 | REQ-001 | resolved/test | |
+`)
+
+	for _, tc := range []struct {
+		name, slug, want string
+		code             int
+	}{
+		{name: "ok", slug: "ok", code: 0},
+		{name: "bad", slug: "bad", code: 1, want: "Edge Coverage \"EDGE-001\" targets no known REQ/AC"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+			code := SpecValidate(filepath.Join(work, tc.slug), "", work, stdout, stderr)
+			if code != tc.code {
+				t.Fatalf("code=%d want %d; stdout=%q stderr=%q", code, tc.code, stdout.String(), stderr.String())
+			}
+			if tc.want != "" && !strings.Contains(stderr.String(), tc.want) {
+				t.Fatalf("stderr=%q, want %q", stderr.String(), tc.want)
+			}
+		})
+	}
+}
+
+func TestSpecValidateAgainstLedger(t *testing.T) {
+	// Seed a capability ledger: theming already holds "Dark mode".
+	ledger := t.TempDir()
+	writeSpec(t, ledger, "theming", `### Requirement: Dark mode honors the system preference
+The system SHALL default to the OS colour-scheme.
+#### Scenario: first load
+- **WHEN** a visitor loads the app **THEN** the theme matches the OS setting
+`)
+
+	work := t.TempDir()
+	// Correct: MODIFIED an existing requirement, ADD a genuinely new one.
+	writeSpec(t, work, "ok", `## MODIFIED Requirements — capability: theming
+### Requirement: Dark mode honors the system preference
+The system SHALL default to the OS colour-scheme and persist an override.
+#### Scenario: stored override
+- **WHEN** a visitor has toggled the theme **THEN** the stored choice wins
+
+## ADDED Requirements — capability: theming
+### Requirement: A theme toggle is reachable from settings
+The system SHALL expose a theme control in settings.
+#### Scenario: toggle present
+- **WHEN** settings opens **THEN** a theme control is shown
+`)
+	// Wrong: ADD something that already exists; MODIFY something absent.
+	writeSpec(t, work, "wrong", `## ADDED Requirements — capability: theming
+### Requirement: Dark mode honors the system preference
+The system SHALL default to the OS colour-scheme.
+#### Scenario: first load
+- **WHEN** a visitor loads the app **THEN** the theme matches the OS
+
+## MODIFIED Requirements — capability: theming
+### Requirement: Nonexistent behavior
+The system SHALL do a thing it never did before.
+#### Scenario: x
+- **WHEN** y **THEN** z
+`)
+
+	for _, tc := range []struct {
+		name       string
+		slug       string
+		wantCode   int
+		wantStderr []string
+	}{
+		{name: "reconciled deltas pass", slug: "ok", wantCode: 0},
+		{name: "misclassified deltas fail", slug: "wrong", wantCode: 1, wantStderr: []string{
+			"marked ADDED but already exists in ledger capability \"theming\"",
+			"marked MODIFIED but is absent from ledger capability \"theming\"",
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+			code := SpecValidate(filepath.Join(work, tc.slug), ledger, work, stdout, stderr)
+			if code != tc.wantCode {
+				t.Fatalf("code=%d want %d; stdout=%q stderr=%q", code, tc.wantCode, stdout.String(), stderr.String())
+			}
+			for _, want := range tc.wantStderr {
+				if !strings.Contains(stderr.String(), want) {
+					t.Fatalf("stderr=%q, want substring %q", stderr.String(), want)
+				}
+			}
+		})
+	}
+}
+
+func writeSpec(t *testing.T, work, slug, content string) {
+	t.Helper()
+	dir := filepath.Join(work, slug)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "spec.md"), []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}