devrites 3.2.27 → 4.0.0

package/engine/internal/lib/ledger.go

@@ -1,311 +0,0 @@
-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, err := foldCapability(root, capability, byCap[capability])
-		if err != nil {
-			fmt.Fprintf(stderr, "ledger: %v\n", err)
-			return nil, 2
-		}
-		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, error) {
-	path := ledgerCapabilityPath(root, capability)
-	var existing *SpecDoc
-	if _, err := os.Stat(path); err == nil {
-		existing, err = ParseSpec(path)
-		if err != nil {
-			return capabilityFold{}, fmt.Errorf("read capability %s: %w", capability, err)
-		}
-	} else if !os.IsNotExist(err) {
-		return capabilityFold{}, fmt.Errorf("inspect capability %s: %w", capability, err)
-	}
-	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, nil
-}
-
-// 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

@@ -1,186 +0,0 @@
-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)
-		}
-	}
-}
-
-func TestLedgerSyncDoesNotOverwriteUnreadableCapability(t *testing.T) {
-	root := t.TempDir()
-	capability := ledgerCapabilityPath(root, "billing")
-	if err := os.MkdirAll(capability, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	wsParent := t.TempDir()
-	writeSpec(t, wsParent, "feat", `## ADDED Requirements — capability: billing
-### Requirement: Invoice export
-The system SHALL export invoices.
-`)
-	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
-	code := Ledger(root, []string{"sync", filepath.Join(wsParent, "feat")}, stdout, stderr)
-	if code != 2 {
-		t.Fatalf("sync code=%d, want 2; stdout=%q stderr=%q", code, stdout.String(), stderr.String())
-	}
-	if !strings.Contains(stderr.String(), "read capability billing") {
-		t.Fatalf("stderr=%q, want capability read error", stderr.String())
-	}
-	if info, err := os.Stat(capability); err != nil || !info.IsDir() {
-		t.Fatalf("capability was overwritten: info=%v err=%v", info, err)
-	}
-}

package/engine/internal/lib/mutationgate.go

@@ -1,89 +0,0 @@
-package lib
-
-import (
-	"errors"
-	"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 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, err := gitToplevel(cwd)
-	if errors.Is(err, errNotGitRepository) {
-		base = "."
-	} else if err != nil {
-		fmt.Fprintf(stderr, "mutation-gate: cannot resolve git worktree; using current directory: %v\n", err)
-		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
-}