devrites 2.6.1 → 3.0.0

package/engine/internal/lib/ledger.go

@@ -0,0 +1,298 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"strings"
+)
+
+// The capability ledger — DevRites' living "what the system does now" layer.
+// Each capability owns `<root>/specs/<capability>/spec.md`, a flat list of proven
+// Requirement blocks. A feature's spec.md carries deltas (ADDED/MODIFIED/REMOVED,
+// per standards/spec-grammar.md); on ship, `ledger sync` folds those deltas in.
+// The store lives outside `work/`, so close-out's archival never touches it.
+//
+// The fold is a plain upsert/delete keyed on requirement header identity, and so
+// is idempotent: re-syncing the same feature is a no-op. ADDED vs MODIFIED is a
+// classification the spec-validate `--against` check enforces at the spec gate —
+// the fold itself does not need the distinction, which keeps re-runs safe.
+//
+// Exit codes: 0 ok · 1 grammar violation (validate) or nothing to do where a
+// target was expected · 2 usage.
+
+// ledgerSpecsDir is the ledger root under the .devrites root.
+func ledgerSpecsDir(root string) string { return root + "/specs" }
+
+func ledgerCapabilityPath(root, capability string) string {
+	return ledgerSpecsDir(root) + "/" + capability + "/spec.md"
+}
+
+// Ledger dispatches the `ledger <sub>` command family.
+func Ledger(root string, args []string, stdout, stderr io.Writer) int {
+	switch argAt(args, 0) {
+	case "sync":
+		return ledgerSync(root, args[1:], stdout, stderr, false)
+	case "diff":
+		return ledgerSync(root, args[1:], stdout, stderr, true)
+	case "validate":
+		return ledgerValidate(root, stdout, stderr)
+	case "list":
+		return ledgerList(root, stdout, stderr)
+	case "show":
+		return ledgerShow(root, args[1:], stdout, stderr)
+	default:
+		fmt.Fprintln(stderr, "usage: devrites-engine ledger <sync|diff|validate|list|show> [args]")
+		return 2
+	}
+}
+
+// capabilityFold is the planned change to one capability's ledger spec.
+type capabilityFold struct {
+	capability string
+	blocks     []Requirement // resolved ordered blocks after the fold
+	added      []string
+	modified   []string
+	removed    []string
+}
+
+func (f capabilityFold) touched() bool {
+	return len(f.added)+len(f.modified)+len(f.removed) > 0
+}
+
+// planFold reads a workspace spec and computes, per capability, the resolved
+// ledger blocks and the change summary. dryRun only affects whether the caller
+// writes; the plan is identical.
+func planFold(root, workspaceDir string, stderr io.Writer) ([]capabilityFold, int) {
+	spec := workspaceDir + "/spec.md"
+	if !isFile(spec) {
+		fmt.Fprintf(stderr, "ledger: no spec.md at %s\n", spec)
+		return nil, 5
+	}
+	doc, err := ParseSpec(spec)
+	if err != nil {
+		fmt.Fprintf(stderr, "ledger: %v\n", err)
+		return nil, 2
+	}
+	defaultCap := defaultCapability(workspaceDir)
+
+	// Group the feature's requirements by capability, preserving encounter order.
+	order := []string{}
+	byCap := map[string][]Requirement{}
+	for _, r := range doc.Requirements {
+		capability := r.Capability
+		if capability == "" {
+			capability = defaultCap
+		}
+		if _, seen := byCap[capability]; !seen {
+			order = append(order, capability)
+		}
+		byCap[capability] = append(byCap[capability], r)
+	}
+
+	var folds []capabilityFold
+	for _, capability := range order {
+		fold := foldCapability(root, capability, byCap[capability])
+		folds = append(folds, fold)
+	}
+	return folds, 0
+}
+
+// foldCapability applies one capability's deltas onto its existing ledger spec.
+// A requirement with no delta kind (a flat feature spec) folds as ADDED. ADDED and
+// MODIFIED are both an upsert (replace in place if the header exists, else append);
+// REMOVED deletes. Ordering: existing blocks keep their position, new blocks append.
+func foldCapability(root, capability string, deltas []Requirement) capabilityFold {
+	existing, _ := ParseSpec(ledgerCapabilityPath(root, capability))
+	var blocks []Requirement
+	idx := map[string]int{}
+	if existing != nil {
+		for _, r := range existing.Requirements {
+			idx[r.Key] = len(blocks)
+			blocks = append(blocks, r)
+		}
+	}
+
+	fold := capabilityFold{capability: capability}
+	for _, d := range deltas {
+		switch d.Kind {
+		case DeltaRemoved:
+			if i, ok := idx[d.Key]; ok {
+				blocks = append(blocks[:i], blocks[i+1:]...)
+				delete(idx, d.Key)
+				// Reindex entries after the removed slot.
+				for k, v := range idx {
+					if v > i {
+						idx[k] = v - 1
+					}
+				}
+				fold.removed = append(fold.removed, d.Name)
+			}
+		default: // added, modified, or "" (flat) → upsert
+			if i, ok := idx[d.Key]; ok {
+				blocks[i] = d
+				fold.modified = append(fold.modified, d.Name)
+			} else {
+				idx[d.Key] = len(blocks)
+				blocks = append(blocks, d)
+				fold.added = append(fold.added, d.Name)
+			}
+		}
+	}
+	fold.blocks = blocks
+	return fold
+}
+
+// renderLedgerSpec assembles a capability's ledger spec.md from its resolved blocks.
+func renderLedgerSpec(capability string, blocks []Requirement) string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "# Capability: %s\n\n", capability)
+	b.WriteString("<!-- Managed by `devrites-engine ledger`. The living record of proven behavior\n")
+	b.WriteString("for this capability, folded from feature specs on ship. Change it through a\n")
+	b.WriteString("feature's spec deltas (ADDED/MODIFIED/REMOVED), not by hand. -->\n\n")
+	for i, r := range blocks {
+		if i > 0 {
+			b.WriteString("\n")
+		}
+		b.WriteString(strings.TrimRight(r.Raw, "\n"))
+		b.WriteString("\n")
+	}
+	return b.String()
+}
+
+func ledgerSync(root string, args []string, stdout, stderr io.Writer, dryRun bool) int {
+	workspaceDir := argAt(args, 0)
+	if workspaceDir == "" {
+		fmt.Fprintln(stderr, "usage: devrites-engine ledger sync|diff <workspace-dir>")
+		return 2
+	}
+	folds, code := planFold(root, workspaceDir, stderr)
+	if code != 0 {
+		return code
+	}
+
+	verb := "sync"
+	if dryRun {
+		verb = "diff"
+	}
+	any := false
+	for _, f := range folds {
+		if !f.touched() {
+			continue
+		}
+		any = true
+		fmt.Fprintf(stdout, "ledger %s: capability %q — +%d added, ~%d modified, -%d removed\n",
+			verb, f.capability, len(f.added), len(f.modified), len(f.removed))
+		for _, n := range f.added {
+			fmt.Fprintf(stdout, "  + %s\n", n)
+		}
+		for _, n := range f.modified {
+			fmt.Fprintf(stdout, "  ~ %s\n", n)
+		}
+		for _, n := range f.removed {
+			fmt.Fprintf(stdout, "  - %s\n", n)
+		}
+		if dryRun {
+			continue
+		}
+		if err := writeLedgerCapability(root, f); err != nil {
+			fmt.Fprintf(stderr, "ledger: %v\n", err)
+			return 1
+		}
+	}
+	if !any {
+		fmt.Fprintf(stdout, "ledger %s: no changes — the ledger already reflects this feature\n", verb)
+	}
+	return 0
+}
+
+func writeLedgerCapability(root string, f capabilityFold) error {
+	dir := ledgerSpecsDir(root) + "/" + f.capability
+	if len(f.blocks) == 0 {
+		// The last requirement was removed — drop the now-empty capability spec.
+		_ = os.Remove(ledgerCapabilityPath(root, f.capability))
+		return nil
+	}
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return fmt.Errorf("create capability dir: %w", err)
+	}
+	return os.WriteFile(dir+"/spec.md", []byte(renderLedgerSpec(f.capability, f.blocks)), 0o644)
+}
+
+func ledgerValidate(root string, stdout, stderr io.Writer) int {
+	caps := ledgerCapabilities(root)
+	if len(caps) == 0 {
+		fmt.Fprintln(stdout, "ledger validate: no capabilities in the ledger yet — nothing to lint")
+		return 0
+	}
+	violations := 0
+	for _, capability := range caps {
+		spec := ledgerCapabilityPath(root, capability)
+		reqs, scens, findings, err := lintSpec(spec)
+		if err != nil {
+			fmt.Fprintf(stderr, "ledger validate: %s: %v\n", capability, err)
+			violations++
+			continue
+		}
+		if len(findings) > 0 {
+			for _, f := range findings {
+				fmt.Fprintln(stderr, f)
+			}
+			violations += len(findings)
+			continue
+		}
+		fmt.Fprintf(stdout, "ledger validate: OK — %s: %d requirement(s) / %d scenario(s)\n", capability, reqs, scens)
+	}
+	if violations > 0 {
+		fmt.Fprintf(stderr, "ledger validate: %d grammar error(s) across the ledger (see standards/spec-grammar.md)\n", violations)
+		return 1
+	}
+	return 0
+}
+
+func ledgerList(root string, stdout, stderr io.Writer) int {
+	caps := ledgerCapabilities(root)
+	if len(caps) == 0 {
+		fmt.Fprintln(stdout, "ledger: empty — no proven capabilities recorded yet")
+		return 0
+	}
+	for _, capability := range caps {
+		doc, err := ParseSpec(ledgerCapabilityPath(root, capability))
+		n := 0
+		if err == nil {
+			n = len(doc.Requirements)
+		}
+		fmt.Fprintf(stdout, "%-40s %d requirement(s)\n", capability, n)
+	}
+	return 0
+}
+
+func ledgerShow(root string, args []string, stdout, stderr io.Writer) int {
+	capability := argAt(args, 0)
+	if capability == "" {
+		fmt.Fprintln(stderr, "usage: devrites-engine ledger show <capability>")
+		return 2
+	}
+	data, err := os.ReadFile(ledgerCapabilityPath(root, capability))
+	if err != nil {
+		fmt.Fprintf(stderr, "ledger: no such capability %q in the ledger\n", capability)
+		return 1
+	}
+	_, _ = stdout.Write(data)
+	return 0
+}
+
+// ledgerCapabilities lists capability names (sorted) that have a spec.md.
+func ledgerCapabilities(root string) []string {
+	entries, err := os.ReadDir(ledgerSpecsDir(root))
+	if err != nil {
+		return nil
+	}
+	var caps []string
+	for _, e := range entries {
+		if e.IsDir() && isFile(ledgerCapabilityPath(root, e.Name())) {
+			caps = append(caps, e.Name())
+		}
+	}
+	return caps
+}

package/engine/internal/lib/ledger_test.go

@@ -0,0 +1,162 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestLedgerSyncFoldLifecycle(t *testing.T) {
+	root := t.TempDir()     // the .devrites root
+	wsParent := t.TempDir() // holds feature workspaces
+	capSpec := ledgerCapabilityPath(root, "theming")
+
+	sync := func(t *testing.T, slug, content string) (int, string, string) {
+		t.Helper()
+		writeSpec(t, wsParent, slug, content)
+		stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+		code := Ledger(root, []string{"sync", filepath.Join(wsParent, slug)}, stdout, stderr)
+		return code, stdout.String(), stderr.String()
+	}
+	read := func(t *testing.T) string {
+		t.Helper()
+		b, err := os.ReadFile(capSpec)
+		if err != nil {
+			t.Fatalf("read ledger spec: %v", err)
+		}
+		return string(b)
+	}
+
+	// 1. ADD a new requirement — seeds the capability.
+	code, out, errs := sync(t, "add-dark-mode", `## 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
+`)
+	if code != 0 {
+		t.Fatalf("sync add code=%d stderr=%q", code, errs)
+	}
+	if !strings.Contains(out, "+1 added") {
+		t.Fatalf("want +1 added, got %q", out)
+	}
+	if !strings.Contains(read(t), "Dark mode honors the system preference") {
+		t.Fatal("ledger missing the added requirement")
+	}
+
+	// 2. Re-sync the SAME feature — idempotent (ADDED becomes an in-place upsert).
+	code, out, _ = sync(t, "add-dark-mode-again", `## 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
+`)
+	if code != 0 || strings.Contains(out, "+1 added") {
+		t.Fatalf("re-sync should upsert, not re-add: %q", out)
+	}
+
+	// 3. MODIFY the requirement — replaces in place.
+	_, out, _ = sync(t, "persist-choice", `## 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
+`)
+	if !strings.Contains(out, "~1 modified") {
+		t.Fatalf("want ~1 modified, got %q", out)
+	}
+	if body := read(t); !strings.Contains(body, "persist an override") || strings.Contains(body, "matches the OS") {
+		t.Fatalf("modify did not replace the block: %q", body)
+	}
+
+	// 4. REMOVE it — the empty capability spec is dropped.
+	_, out, _ = sync(t, "drop-dark-mode", `## REMOVED Requirements — capability: theming
+### Requirement: Dark mode honors the system preference
+Removed — theming moved to a plugin.
+`)
+	if !strings.Contains(out, "-1 removed") {
+		t.Fatalf("want -1 removed, got %q", out)
+	}
+	if _, err := os.Stat(capSpec); !os.IsNotExist(err) {
+		t.Fatal("emptied capability spec should be removed")
+	}
+}
+
+func TestLedgerDiffDoesNotWrite(t *testing.T) {
+	root := t.TempDir()
+	wsParent := t.TempDir()
+	writeSpec(t, wsParent, "feat", `## ADDED Requirements — capability: billing
+### Requirement: Invoices export as PDF
+The system SHALL export an invoice as a PDF.
+#### Scenario: export
+- **WHEN** export is clicked **THEN** a PDF is produced
+`)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	code := Ledger(root, []string{"diff", filepath.Join(wsParent, "feat")}, stdout, stderr)
+	if code != 0 {
+		t.Fatalf("diff code=%d stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "+1 added") {
+		t.Fatalf("diff should preview the add: %q", stdout.String())
+	}
+	if _, err := os.Stat(ledgerCapabilityPath(root, "billing")); !os.IsNotExist(err) {
+		t.Fatal("diff must not write the ledger")
+	}
+}
+
+func TestLedgerListAndShow(t *testing.T) {
+	root := t.TempDir()
+	wsParent := t.TempDir()
+	writeSpec(t, wsParent, "feat", `## ADDED Requirements — capability: search
+### Requirement: Results rank by relevance
+The system SHALL rank results by relevance.
+#### Scenario: ranking
+- **WHEN** a query runs **THEN** the top hit is the most relevant
+`)
+	Ledger(root, []string{"sync", filepath.Join(wsParent, "feat")}, &bytes.Buffer{}, &bytes.Buffer{})
+
+	stdout := &bytes.Buffer{}
+	if code := Ledger(root, []string{"list"}, stdout, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("list code=%d", code)
+	}
+	if !strings.Contains(stdout.String(), "search") || !strings.Contains(stdout.String(), "1 requirement") {
+		t.Fatalf("list output=%q", stdout.String())
+	}
+
+	stdout.Reset()
+	if code := Ledger(root, []string{"show", "search"}, stdout, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("show code=%d", code)
+	}
+	if !strings.Contains(stdout.String(), "Results rank by relevance") {
+		t.Fatalf("show output=%q", stdout.String())
+	}
+}
+
+func TestLedgerMultiCapabilityFold(t *testing.T) {
+	root := t.TempDir()
+	wsParent := t.TempDir()
+	// One feature touches two capabilities in a single sync.
+	writeSpec(t, wsParent, "feat", `## ADDED Requirements — capability: theming
+### Requirement: Theme toggle exists
+The system SHALL expose a theme toggle.
+#### Scenario: toggle
+- **WHEN** settings opens **THEN** a toggle is shown
+
+## ADDED Requirements — capability: settings-ui
+### Requirement: Settings groups appearance controls
+The system SHALL group appearance controls together.
+#### Scenario: grouping
+- **WHEN** settings opens **THEN** appearance controls are grouped
+`)
+	code := Ledger(root, []string{"sync", filepath.Join(wsParent, "feat")}, &bytes.Buffer{}, &bytes.Buffer{})
+	if code != 0 {
+		t.Fatalf("multi-cap sync code=%d", code)
+	}
+	for _, capability := range []string{"theming", "settings-ui"} {
+		if _, err := os.Stat(ledgerCapabilityPath(root, capability)); err != nil {
+			t.Fatalf("capability %q not folded: %v", capability, err)
+		}
+	}
+}

package/engine/internal/lib/mutationgate.go

@@ -0,0 +1,85 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+)
+
+// MutationGate advises whether the slice's tests are strong enough to back "done".
+// Coverage says a line ran; mutation testing says it is actually checked. Running a
+// mutation suite is slow, so this does not run one: it detects which runner the
+// project has, prints the command to run it scoped to the changed files, and leaves
+// the resulting score for /rite-seal to band. With no runner installed it prints a
+// hand-mutation note instead — a project without mutation tooling is never blocked.
+//
+// Exit codes: 0 advisory printed · 2 no active workspace. (Turning a low score into
+// a NO-GO is /rite-seal's job against the recorded score, so this always exits 0
+// once it has a workspace.)
+func MutationGate(root string, args []string, stdout, stderr io.Writer) int {
+	slug := slugOrActive(root, args)
+	if slug == "" {
+		fmt.Fprintln(stderr, "mutation-gate: no active workspace.")
+		return 2
+	}
+	d := featureDir(root, slug)
+	if !isDir(d) {
+		fmt.Fprintf(stderr, "mutation-gate: no workspace at %s.\n", d)
+		return 2
+	}
+
+	// Config files are looked up relative to the repo root, falling back to the
+	// working directory when this is not a git repo.
+	cwd, _ := os.Getwd()
+	base := gitToplevel(cwd)
+	if base == "" {
+		base = "."
+	}
+
+	enforce := os.Getenv("DEVRITES_MUTATION")
+	if enforce == "" {
+		enforce = "advisory"
+	}
+	minScore := os.Getenv("DEVRITES_MUTATION_MIN")
+	if minScore == "" {
+		minScore = "60"
+	}
+
+	// Detect the mutation runner. A stryker config commits the project to stryker:
+	// if its config is present but npx is not, the tool stays unset (no fall-through
+	// to the other runners) — the project chose stryker, it just is not installed.
+	tool := ""
+	if isFile(base+"/stryker.conf.json") || isFile(base+"/stryker.config.js") || isFile(base+"/stryker.config.mjs") {
+		if _, err := exec.LookPath("npx"); err == nil {
+			tool = "stryker"
+		}
+	} else if _, err := exec.LookPath("mutmut"); err == nil {
+		tool = "mutmut"
+	} else if _, err := exec.LookPath("cosmic-ray"); err == nil {
+		tool = "cosmic-ray"
+	} else if _, err := exec.LookPath("pitest"); err == nil || isFile(base+"/pom.xml") {
+		tool = "pitest"
+	}
+
+	if tool == "" {
+		fmt.Fprintln(stdout, "mutation-gate: no mutation runner detected (stryker / mutmut / cosmic-ray / pitest) — advisory skipped.")
+		fmt.Fprintln(stdout, "  Strengthen the criticals by hand-mutating (flip a comparison, drop a guard) and confirming a test goes red (standards/testing.md).")
+		return 0
+	}
+
+	fmt.Fprintf(stdout, "mutation-gate: detected '%s'. Run it scoped to the slice's changed files and read the mutation score:\n", tool)
+	switch tool {
+	case "stryker":
+		fmt.Fprintln(stdout, `  npx stryker run --mutate "$(git diff --name-only HEAD | paste -sd, -)"`)
+	case "mutmut":
+		fmt.Fprintln(stdout, `  mutmut run --paths-to-mutate "$(git diff --name-only HEAD | tr '\n' ' ')" && mutmut results`)
+	case "cosmic-ray":
+		fmt.Fprintln(stdout, "  (configure session over the changed files, then: cosmic-ray exec ... && cr-report ...)")
+	case "pitest":
+		fmt.Fprintln(stdout, "  mvn org.pitest:pitest-maven:mutationCoverage -DtargetClasses=<changed>")
+	}
+	fmt.Fprintln(stdout, "  Record the score + any survived mutants in evidence.md; a survivor is a behaviour no test checks (a finding for the test reviewer).")
+	fmt.Fprintf(stdout, "  Mode: %s (DEVRITES_MUTATION=enforce makes a score < %s%% a NO-GO).\n", enforce, minScore)
+	return 0
+}