Add canonical vibes fmt command and CI check

Author: mgomes

.github/workflows/test.yml

@@ -37,6 +37,10 @@ jobs:
         if: runner.os != 'Windows'
         run: just lint
 
+      - name: Check Vibe formatting
+        if: runner.os != 'Windows'
+        run: go run ./cmd/vibes fmt -check .
+
       - name: Run tests (Windows)
         if: runner.os == 'Windows'
         shell: pwsh
@@ -52,6 +56,11 @@ jobs:
             exit 1
           }
 
+      - name: Check Vibe formatting (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: go run ./cmd/vibes fmt -check .
+
       - name: Run golangci-lint (Windows)
         if: runner.os == 'Windows'
         shell: pwsh

README.md

@@ -176,6 +176,7 @@ This repository uses [Just](https://github.com/casey/just) for common tasks:
 - `just test` runs the full Go test suite (`go test ./...`).
 - `just bench` runs the core execution benchmarks (`go test ./vibes -run '^$' -bench '^BenchmarkExecution' -benchmem`).
 - `just lint` checks formatting (`gofmt`) and runs `golangci-lint` with a generous timeout.
+- `vibes fmt <path>` applies canonical formatting to `.vibe` files (`-check` for CI, `-w` to write).
 - `vibes analyze <script.vibe>` runs script-level lint checks (e.g., unreachable statements).
 - Add new recipes in the `Justfile` as workflows grow.
 

ROADMAP.md

@@ -319,7 +319,7 @@ Goal: improve day-to-day developer productivity and interpreter robustness.
 
 ### Tooling
 
-- [ ] Add canonical formatter command and CI check.
+- [x] Add canonical formatter command and CI check.
 - [ ] Add language server protocol (LSP) prototype (hover, completion, diagnostics).
 - [x] Add static analysis command for script-level linting.
 - [x] Improve REPL inspection commands (globals/functions/types).

cmd/vibes/fmt.go

@@ -0,0 +1,128 @@
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+func fmtCommand(args []string) error {
+	fs := flag.NewFlagSet("fmt", flag.ContinueOnError)
+	fs.SetOutput(new(flagErrorSink))
+	write := fs.Bool("w", false, "write result to source files instead of stdout")
+	check := fs.Bool("check", false, "fail if any source file needs formatting")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+
+	targets := fs.Args()
+	if len(targets) == 0 {
+		return errors.New("vibes fmt: path required")
+	}
+
+	files, err := collectVibeFiles(targets)
+	if err != nil {
+		return err
+	}
+	if len(files) == 0 {
+		return nil
+	}
+
+	changedCount := 0
+	for _, path := range files {
+		originalBytes, err := os.ReadFile(path)
+		if err != nil {
+			return fmt.Errorf("read %s: %w", path, err)
+		}
+		original := string(originalBytes)
+		formatted := formatVibeSource(original)
+		changed := formatted != original
+		if changed {
+			changedCount++
+		}
+
+		switch {
+		case *write && changed:
+			info, err := os.Stat(path)
+			if err != nil {
+				return fmt.Errorf("stat %s: %w", path, err)
+			}
+			if err := os.WriteFile(path, []byte(formatted), info.Mode().Perm()); err != nil {
+				return fmt.Errorf("write %s: %w", path, err)
+			}
+		case !*write && !*check:
+			fmt.Print(formatted)
+		}
+	}
+
+	if *check && changedCount > 0 {
+		return fmt.Errorf("vibes fmt: %d file(s) need formatting", changedCount)
+	}
+
+	return nil
+}
+
+func collectVibeFiles(targets []string) ([]string, error) {
+	seen := make(map[string]struct{})
+	files := make([]string, 0)
+	addFile := func(path string) {
+		if filepath.Ext(path) != ".vibe" {
+			return
+		}
+		abs, err := filepath.Abs(path)
+		if err != nil {
+			return
+		}
+		if _, ok := seen[abs]; ok {
+			return
+		}
+		seen[abs] = struct{}{}
+		files = append(files, abs)
+	}
+
+	for _, target := range targets {
+		info, err := os.Stat(target)
+		if err != nil {
+			return nil, fmt.Errorf("stat %s: %w", target, err)
+		}
+		if !info.IsDir() {
+			addFile(target)
+			continue
+		}
+		err = filepath.WalkDir(target, func(path string, entry fs.DirEntry, walkErr error) error {
+			if walkErr != nil {
+				return walkErr
+			}
+			if entry.IsDir() {
+				return nil
+			}
+			addFile(path)
+			return nil
+		})
+		if err != nil {
+			return nil, fmt.Errorf("walk %s: %w", target, err)
+		}
+	}
+
+	sort.Strings(files)
+	return files, nil
+}
+
+func formatVibeSource(source string) string {
+	normalized := strings.ReplaceAll(source, "\r\n", "\n")
+	normalized = strings.ReplaceAll(normalized, "\r", "\n")
+
+	lines := strings.Split(normalized, "\n")
+	for i, line := range lines {
+		lines[i] = strings.TrimRight(line, " \t")
+	}
+
+	joined := strings.Join(lines, "\n")
+	joined = strings.TrimRight(joined, "\n")
+	return joined + "\n"
+}

cmd/vibes/fmt_test.go

@@ -0,0 +1,88 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestFmtCommandRequiresPath(t *testing.T) {
+	err := fmtCommand(nil)
+	if err == nil {
+		t.Fatalf("expected path required error")
+	}
+	if !strings.Contains(err.Error(), "path required") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFmtCommandCheckDetectsUnformattedFiles(t *testing.T) {
+	path := writeVibeFile(t, "def run()  \n  1\t \nend")
+	err := fmtCommand([]string{"-check", path})
+	if err == nil {
+		t.Fatalf("expected formatting check failure")
+	}
+	if !strings.Contains(err.Error(), "need formatting") {
+		t.Fatalf("unexpected check error: %v", err)
+	}
+}
+
+func TestFmtCommandWriteFormatsFileInPlace(t *testing.T) {
+	path := writeVibeFile(t, "def run()  \n  1\t \nend")
+	if err := fmtCommand([]string{"-w", path}); err != nil {
+		t.Fatalf("fmt -w failed: %v", err)
+	}
+
+	updated, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read formatted file: %v", err)
+	}
+	if got := string(updated); got != "def run()\n  1\nend\n" {
+		t.Fatalf("unexpected formatted output: %q", got)
+	}
+}
+
+func TestFmtCommandPrintsFormattedOutput(t *testing.T) {
+	path := writeVibeFile(t, "def run()  \n  1\t \nend")
+	out, err := captureStdout(t, func() error {
+		return fmtCommand([]string{path})
+	})
+	if err != nil {
+		t.Fatalf("fmt command failed: %v", err)
+	}
+	if out != "def run()\n  1\nend\n" {
+		t.Fatalf("unexpected stdout output: %q", out)
+	}
+}
+
+func TestFmtCommandFormatsDirectories(t *testing.T) {
+	root := t.TempDir()
+	first := filepath.Join(root, "a.vibe")
+	second := filepath.Join(root, "nested", "b.vibe")
+	if err := os.MkdirAll(filepath.Dir(second), 0o755); err != nil {
+		t.Fatalf("mkdir nested: %v", err)
+	}
+	if err := os.WriteFile(first, []byte("def run()  \n  1  \nend"), 0o644); err != nil {
+		t.Fatalf("write first file: %v", err)
+	}
+	if err := os.WriteFile(second, []byte("def run()  \n  2\t\nend"), 0o644); err != nil {
+		t.Fatalf("write second file: %v", err)
+	}
+
+	if err := fmtCommand([]string{"-w", root}); err != nil {
+		t.Fatalf("fmt directory failed: %v", err)
+	}
+	if err := fmtCommand([]string{"-check", root}); err != nil {
+		t.Fatalf("expected no formatting diffs after write, got %v", err)
+	}
+}
+
+func writeVibeFile(t *testing.T, content string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "script.vibe")
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write vibe file: %v", err)
+	}
+	return path
+}

cmd/vibes/main.go

@@ -26,6 +26,8 @@ func runCLI(args []string) error {
 	switch args[1] {
 	case "run":
 		return runCommand(args[2:])
+	case "fmt":
+		return fmtCommand(args[2:])
 	case "analyze":
 		return analyzeCommand(args[2:])
 	case "repl":
@@ -100,6 +102,7 @@ func printUsage() {
 	fmt.Fprintf(os.Stderr, "Usage: %s <command> [flags] [args...]\n\n", prog)
 	fmt.Fprintln(os.Stderr, "Commands:")
 	fmt.Fprintln(os.Stderr, "  run <script>    Execute a script file")
+	fmt.Fprintln(os.Stderr, "  fmt <path>      Canonical formatting for .vibe files")
 	fmt.Fprintln(os.Stderr, "  analyze <script> Analyze a script for lint issues")
 	fmt.Fprintln(os.Stderr, "  repl            Start interactive REPL")
 	fmt.Fprintln(os.Stderr, "  help            Show this help message")

examples/basics/functions_and_calls.vibe

@@ -21,4 +21,3 @@ def max_value(a, b)
     b
   end
 end
-

examples/capabilities/iteration.vibe

@@ -8,4 +8,3 @@ def total_raised_for_player(player_id)
   end
   total
 end
-