test: add crucible cli tests and docs

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>

Author: joshua-temple

cmd/crucible/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to the crucible CLI are documented here. This module is
+versioned independently of the `state` module.
+
+## 0.1.0
+
+Initial release.
+
+- `lint` runs static analysis over an IR and exits non-zero on findings.
+- `render` emits a Mermaid or DOT diagram of a machine.
+- `diff` classifies the changes between two IRs and recommends a semver bump.
+- `validate` confirms an IR loads and assembles.
+- `eject` generates typed Go behavior stubs from an IR.
+- `version` (and `-version`) prints the CLI version.
+- Commands read an IR file path or `-` for stdin.

cmd/crucible/README.md

@@ -0,0 +1,87 @@
+# crucible
+
+A headless command-line tool for the crucible state-machine IR. It lints,
+renders, diffs, validates, and ejects a machine's serialized IR JSON without
+running any behavior. Every command reads an IR JSON file path, or `-` for
+stdin.
+
+## Behavior-free operation
+
+A serialized IR carries behavior references by name only; the kernel binds those
+names to real implementations when it assembles a machine. Commands that need an
+assembled machine (`lint`, `render`, `validate`) do not have the host's real
+guards, actions, reducers, and services. They register a deterministic no-op stub
+for every referenced name first, so the machine assembles from its structure
+alone. The stubs never run during these commands (no instance is cast and no
+event is fired), so the structural view is exactly what the IR describes.
+
+## Commands
+
+### lint
+
+```
+crucible lint <ir.json>
+```
+
+Runs every static analysis check and prints the findings. Exits non-zero when
+the analysis reports any finding, so it can gate CI.
+
+### render
+
+```
+crucible render <ir.json> [-format mermaid|dot]
+```
+
+Renders the machine as a Mermaid `stateDiagram-v2` (the default) or as Graphviz
+DOT. Output is text. For an SVG, pipe the DOT through Graphviz (`crucible render
+m.json -format dot | dot -Tsvg`); native SVG rendering is a future addition.
+
+### diff
+
+```
+crucible diff <old.json> <new.json>
+```
+
+Classifies the changes between two serialized IRs, prints the recommended semver
+bump (`major`, `minor`, or `patch`), and lists the breaking and additive changes
+separately.
+
+### validate
+
+```
+crucible validate <ir.json>
+```
+
+Confirms the IR loads and assembles cleanly. A malformed JSON document or a
+structural defect the lint rejects exits non-zero with a message on stderr; a
+clean machine exits zero.
+
+### eject
+
+```
+crucible eject <ir.json> [-package name] [-o outfile]
+```
+
+Generates typed Go behavior stubs for every referenced guard, action, reducer,
+and service, plus a `Provide` function that registers them. Writes to `outfile`
+or, by default, to stdout.
+
+### version
+
+```
+crucible version
+crucible -version
+```
+
+Prints the CLI version.
+
+## Exit codes
+
+- `0` success
+- `1` runtime or load error, and lint findings
+- `2` usage error
+
+## Versioning
+
+The crucible CLI is versioned independently of the `state` module. It is not part
+of the `state` v1 freeze, so it can move at its own pace.

cmd/crucible/cmd_test.go

@@ -0,0 +1,229 @@
+package main
+
+import (
+	"bytes"
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// runCmd invokes the CLI dispatcher in-process and returns the exit code with
+// captured stdout and stderr, so every command is tested without a subprocess.
+func runCmd(args ...string) (code int, stdout, stderr string) {
+	var out, errBuf bytes.Buffer
+	code = run(args, &out, &errBuf)
+	return code, out.String(), errBuf.String()
+}
+
+func TestRender(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{"mermaid default", []string{"render", "testdata/clean.json"}, "stateDiagram-v2"},
+		{"dot flag", []string{"render", "testdata/clean.json", "-format", "dot"}, "digraph"},
+		{"flag before path", []string{"render", "-format", "dot", "testdata/clean.json"}, "digraph"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			code, out, errOut := runCmd(tc.args...)
+			if code != exitOK {
+				t.Fatalf("exit = %d, want %d (stderr: %s)", code, exitOK, errOut)
+			}
+			if !strings.Contains(out, tc.want) {
+				t.Fatalf("render output missing %q:\n%s", tc.want, out)
+			}
+		})
+	}
+}
+
+func TestRender_UnknownFormat(t *testing.T) {
+	code, _, errOut := runCmd("render", "testdata/clean.json", "-format", "svg")
+	if code != exitUsage {
+		t.Fatalf("exit = %d, want %d", code, exitUsage)
+	}
+	if !strings.Contains(errOut, "unknown -format") {
+		t.Fatalf("stderr missing format error: %s", errOut)
+	}
+}
+
+func TestDiff(t *testing.T) {
+	cases := []struct {
+		name     string
+		old, new string
+		wantBump string
+	}{
+		{"additive change is minor", "testdata/old.json", "testdata/new_minor.json", "bump: minor"},
+		{"breaking change is major", "testdata/old.json", "testdata/new_major.json", "bump: major"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			code, out, errOut := runCmd("diff", tc.old, tc.new)
+			if code != exitOK {
+				t.Fatalf("exit = %d, want %d (stderr: %s)", code, exitOK, errOut)
+			}
+			if !strings.Contains(out, tc.wantBump) {
+				t.Fatalf("diff output missing %q:\n%s", tc.wantBump, out)
+			}
+		})
+	}
+}
+
+func TestDiff_SplitsBreakingAndAdditive(t *testing.T) {
+	code, out, _ := runCmd("diff", "testdata/old.json", "testdata/new_major.json")
+	if code != exitOK {
+		t.Fatalf("exit = %d, want %d", code, exitOK)
+	}
+	if !strings.Contains(out, "breaking (2)") {
+		t.Errorf("want 2 breaking changes:\n%s", out)
+	}
+	if !strings.Contains(out, "additive (1)") {
+		t.Errorf("want 1 additive change:\n%s", out)
+	}
+}
+
+func TestValidate(t *testing.T) {
+	cases := []struct {
+		name string
+		path string
+		want int
+	}{
+		{"clean IR validates", "testdata/clean.json", exitOK},
+		{"malformed JSON fails", "testdata/malformed.json", exitError},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			code, _, errOut := runCmd("validate", tc.path)
+			if code != tc.want {
+				t.Fatalf("exit = %d, want %d (stderr: %s)", code, tc.want, errOut)
+			}
+			if tc.want == exitError && strings.TrimSpace(errOut) == "" {
+				t.Fatalf("expected a clear stderr message on failure")
+			}
+		})
+	}
+}
+
+func TestLint(t *testing.T) {
+	cases := []struct {
+		name string
+		path string
+		want int
+	}{
+		{"clean IR has no findings", "testdata/clean.json", exitOK},
+		{"defective IR reports findings", "testdata/defect.json", exitFindings},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			code, out, errOut := runCmd("lint", tc.path)
+			if code != tc.want {
+				t.Fatalf("exit = %d, want %d (stderr: %s)", code, tc.want, errOut)
+			}
+			if tc.want == exitFindings && !strings.Contains(out, "unreachable_state") {
+				t.Fatalf("expected an unreachable_state finding:\n%s", out)
+			}
+		})
+	}
+}
+
+func TestEject_StdoutContainsKeyIdents(t *testing.T) {
+	code, out, errOut := runCmd("eject", "testdata/clean.json", "-package", "machine")
+	if code != exitOK {
+		t.Fatalf("exit = %d, want %d (stderr: %s)", code, exitOK, errOut)
+	}
+	for _, want := range []string{
+		"package machine",
+		"func Provide(reg *state.Registry[",
+		`reg.Guard("hasItems"`,
+		`reg.Action("notify"`,
+		`reg.Service("charge"`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("ejected source missing %q:\n%s", want, out)
+		}
+	}
+	// The generated source must be parseable Go.
+	if _, err := parser.ParseFile(token.NewFileSet(), "gen.go", out, parser.AllErrors); err != nil {
+		t.Fatalf("ejected source does not parse: %v\n%s", err, out)
+	}
+}
+
+func TestEject_WritesOutfile(t *testing.T) {
+	dir := t.TempDir()
+	out := filepath.Join(dir, "gen.go")
+	code, _, errOut := runCmd("eject", "testdata/clean.json", "-package", "machine", "-o", out)
+	if code != exitOK {
+		t.Fatalf("exit = %d, want %d (stderr: %s)", code, exitOK, errOut)
+	}
+	b, err := os.ReadFile(out)
+	if err != nil {
+		t.Fatalf("read output: %v", err)
+	}
+	if !strings.Contains(string(b), "package machine") {
+		t.Fatalf("outfile missing package decl:\n%s", b)
+	}
+}
+
+func TestVersion(t *testing.T) {
+	for _, args := range [][]string{{"version"}, {"-version"}, {"--version"}} {
+		code, out, _ := runCmd(args...)
+		if code != exitOK {
+			t.Fatalf("%v exit = %d, want %d", args, code, exitOK)
+		}
+		if strings.TrimSpace(out) != version {
+			t.Fatalf("%v printed %q, want %q", args, strings.TrimSpace(out), version)
+		}
+	}
+}
+
+func TestUsageErrors(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+	}{
+		{"no args", nil},
+		{"unknown subcommand", []string{"frobnicate"}},
+		{"lint missing path", []string{"lint"}},
+		{"diff one path", []string{"diff", "testdata/old.json"}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			code, _, _ := runCmd(tc.args...)
+			if code != exitUsage {
+				t.Fatalf("exit = %d, want %d", code, exitUsage)
+			}
+		})
+	}
+}
+
+func TestStdinInput(t *testing.T) {
+	// render reading from "-" exercises the stdin path; swap os.Stdin for the
+	// duration so the dispatcher's hard-wired os.Stdin reads the fixture.
+	b, err := os.ReadFile("testdata/clean.json")
+	if err != nil {
+		t.Fatalf("read fixture: %v", err)
+	}
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatalf("pipe: %v", err)
+	}
+	orig := os.Stdin
+	os.Stdin = r
+	t.Cleanup(func() { os.Stdin = orig })
+	go func() {
+		_, _ = w.Write(b)
+		_ = w.Close()
+	}()
+
+	code, out, errOut := runCmd("render", "-")
+	if code != exitOK {
+		t.Fatalf("exit = %d, want %d (stderr: %s)", code, exitOK, errOut)
+	}
+	if !strings.Contains(out, "stateDiagram-v2") {
+		t.Fatalf("stdin render missing diagram:\n%s", out)
+	}
+}

cmd/crucible/stub_test.go

@@ -0,0 +1,31 @@
+package main
+
+import (
+	"os"
+	"testing"
+
+	"github.com/stablekernel/crucible/state"
+)
+
+// TestStubRegistry_EnumeratesEveryBehavior loads the clean fixture (which
+// references two guards, two actions, one reducer, and one service) and confirms
+// Provide(stubRegistry).Quench succeeds, proving every referenced name was
+// stubbed. An unstubbed name would panic Quench with an *UnboundRefError.
+func TestStubRegistry_EnumeratesEveryBehavior(t *testing.T) {
+	b, err := os.ReadFile("testdata/clean.json")
+	if err != nil {
+		t.Fatalf("read fixture: %v", err)
+	}
+	ir, err := state.LoadFromJSON[string, string, any](b)
+	if err != nil {
+		t.Fatalf("load IR: %v", err)
+	}
+
+	m, err := quench(ir)
+	if err != nil {
+		t.Fatalf("quench with stubs: %v", err)
+	}
+	if m == nil {
+		t.Fatal("quench returned a nil machine")
+	}
+}

cmd/crucible/testdata/clean.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","name":"orders","states":[{"name":"cart","transitions":[{"from":"cart","to":"paying","on":"checkout","guards":[{"name":"hasItems"}],"assigns":[{"name":"applyTotal"}]}],"onEntry":[{"name":"logEntry"}]},{"name":"paying","transitions":[{"from":"paying","to":"done","on":"paid","guards":[{"name":"isPaid"}],"effects":[{"name":"notify"}]}],"invoke":[{"src":{"name":"charge"},"onDone":"paid","onError":"failed"}]},{"name":"done","isFinal":true}],"initial":"cart","hasInitial":true}

cmd/crucible/testdata/defect.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","name":"withdefect","states":[{"name":"a","transitions":[{"from":"a","to":"b","on":"go"}]},{"name":"b","isFinal":true},{"name":"orphan","transitions":[{"from":"orphan","to":"orphan","on":"noop"}]}],"initial":"a","hasInitial":true}

cmd/crucible/testdata/malformed.json

@@ -0,0 +1 @@
+{ this is not valid json

cmd/crucible/testdata/new_major.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","name":"flow","states":[{"name":"a","transitions":[{"from":"a","to":"c","on":"go"}]},{"name":"c","isFinal":true}],"initial":"a","hasInitial":true}

cmd/crucible/testdata/new_minor.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","name":"flow","states":[{"name":"a","transitions":[{"from":"a","to":"b","on":"go"},{"from":"a","to":"a","on":"reset"}]},{"name":"b","isFinal":true}],"initial":"a","hasInitial":true}

cmd/crucible/testdata/old.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","name":"flow","states":[{"name":"a","transitions":[{"from":"a","to":"b","on":"go"}]},{"name":"b","isFinal":true}],"initial":"a","hasInitial":true}