Add static analyze command for script linting

Author: mgomes

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 analyze <script.vibe>` runs script-level lint checks (e.g., unreachable statements).
 - Add new recipes in the `Justfile` as workflows grow.
 
 CI also publishes benchmark artifacts via `.github/workflows/benchmarks.yml` on

ROADMAP.md

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

cmd/vibes/analyze.go

@@ -0,0 +1,156 @@
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+
+	"github.com/mgomes/vibescript/vibes"
+)
+
+type lintWarning struct {
+	Function string
+	Pos      vibes.Position
+	Message  string
+}
+
+func analyzeCommand(args []string) error {
+	fs := flag.NewFlagSet("analyze", flag.ContinueOnError)
+	fs.SetOutput(new(flagErrorSink))
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+
+	remaining := fs.Args()
+	if len(remaining) == 0 {
+		return errors.New("vibes analyze: script path required")
+	}
+
+	scriptPath, err := filepath.Abs(remaining[0])
+	if err != nil {
+		return fmt.Errorf("resolve script path: %w", err)
+	}
+	input, err := os.ReadFile(scriptPath)
+	if err != nil {
+		return fmt.Errorf("read script: %w", err)
+	}
+
+	engine := vibes.MustNewEngine(vibes.Config{})
+	script, err := engine.Compile(string(input))
+	if err != nil {
+		return fmt.Errorf("analysis compile failed: %w", err)
+	}
+
+	warnings := analyzeScriptWarnings(script)
+	if len(warnings) == 0 {
+		fmt.Println("No issues found")
+		return nil
+	}
+
+	for _, warning := range warnings {
+		line := warning.Pos.Line
+		column := warning.Pos.Column
+		if line <= 0 {
+			line = 1
+		}
+		if column <= 0 {
+			column = 1
+		}
+		fmt.Printf("%s:%d:%d: %s (%s)\n", scriptPath, line, column, warning.Message, warning.Function)
+	}
+
+	return fmt.Errorf("analysis found %d issue(s)", len(warnings))
+}
+
+func analyzeScriptWarnings(script *vibes.Script) []lintWarning {
+	warnings := make([]lintWarning, 0)
+	for _, fn := range script.Functions() {
+		lintStatements(fn.Name, fn.Body, &warnings)
+	}
+
+	sort.SliceStable(warnings, func(i, j int) bool {
+		if warnings[i].Pos.Line != warnings[j].Pos.Line {
+			return warnings[i].Pos.Line < warnings[j].Pos.Line
+		}
+		if warnings[i].Pos.Column != warnings[j].Pos.Column {
+			return warnings[i].Pos.Column < warnings[j].Pos.Column
+		}
+		return warnings[i].Function < warnings[j].Function
+	})
+
+	return warnings
+}
+
+func lintStatements(function string, statements []vibes.Statement, warnings *[]lintWarning) bool {
+	terminated := false
+	for _, stmt := range statements {
+		if terminated {
+			*warnings = append(*warnings, lintWarning{
+				Function: function,
+				Pos:      stmt.Pos(),
+				Message:  "unreachable statement",
+			})
+			continue
+		}
+		if statementTerminates(function, stmt, warnings) {
+			terminated = true
+		}
+	}
+	return terminated
+}
+
+func statementTerminates(function string, stmt vibes.Statement, warnings *[]lintWarning) bool {
+	switch typed := stmt.(type) {
+	case *vibes.ReturnStmt, *vibes.RaiseStmt:
+		return true
+	case *vibes.IfStmt:
+		return ifStatementTerminates(function, typed, warnings)
+	case *vibes.ForStmt:
+		lintStatements(function, typed.Body, warnings)
+		return false
+	case *vibes.WhileStmt:
+		lintStatements(function, typed.Body, warnings)
+		return false
+	case *vibes.UntilStmt:
+		lintStatements(function, typed.Body, warnings)
+		return false
+	case *vibes.TryStmt:
+		bodyTerminated := lintStatements(function, typed.Body, warnings)
+		rescueTerminated := false
+		if len(typed.Rescue) > 0 {
+			rescueTerminated = lintStatements(function, typed.Rescue, warnings)
+		}
+		ensureTerminated := false
+		if len(typed.Ensure) > 0 {
+			ensureTerminated = lintStatements(function, typed.Ensure, warnings)
+		}
+		if ensureTerminated {
+			return true
+		}
+		if len(typed.Rescue) == 0 {
+			return false
+		}
+		return bodyTerminated && rescueTerminated
+	default:
+		return false
+	}
+}
+
+func ifStatementTerminates(function string, stmt *vibes.IfStmt, warnings *[]lintWarning) bool {
+	consequentTerminated := lintStatements(function, stmt.Consequent, warnings)
+	if len(stmt.Alternate) == 0 {
+		return false
+	}
+
+	elseIfAllTerminated := true
+	for _, elseIf := range stmt.ElseIf {
+		if !ifStatementTerminates(function, elseIf, warnings) {
+			elseIfAllTerminated = false
+		}
+	}
+	alternateTerminated := lintStatements(function, stmt.Alternate, warnings)
+	return consequentTerminated && elseIfAllTerminated && alternateTerminated
+}

cmd/vibes/main.go

@@ -26,6 +26,8 @@ func runCLI(args []string) error {
 	switch args[1] {
 	case "run":
 		return runCommand(args[2:])
+	case "analyze":
+		return analyzeCommand(args[2:])
 	case "repl":
 		return runREPL()
 	case "help", "-h", "--help":
@@ -98,6 +100,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, "  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")
 	fmt.Fprintln(os.Stderr, "")

cmd/vibes/main_test.go

@@ -71,6 +71,43 @@ func TestRunCommandRequiresScriptPath(t *testing.T) {
 	}
 }
 
+func TestAnalyzeCommandNoIssues(t *testing.T) {
+	scriptPath := writeScript(t, `def run()
+  value = 1
+  value
+end`)
+
+	out, err := captureStdout(t, func() error {
+		return analyzeCommand([]string{scriptPath})
+	})
+	if err != nil {
+		t.Fatalf("analyzeCommand failed: %v", err)
+	}
+	if !strings.Contains(out, "No issues found") {
+		t.Fatalf("unexpected analyze output: %q", out)
+	}
+}
+
+func TestAnalyzeCommandReportsUnreachableStatements(t *testing.T) {
+	scriptPath := writeScript(t, `def run()
+  return 1
+  2
+end`)
+
+	out, err := captureStdout(t, func() error {
+		return analyzeCommand([]string{scriptPath})
+	})
+	if err == nil {
+		t.Fatalf("expected analyze command to report lint failures")
+	}
+	if !strings.Contains(err.Error(), "analysis found 1 issue(s)") {
+		t.Fatalf("unexpected analyze error: %v", err)
+	}
+	if !strings.Contains(out, "unreachable statement") {
+		t.Fatalf("expected unreachable statement warning, got %q", out)
+	}
+}
+
 func TestComputeModulePathsIncludesScriptDirAndDedupesExtras(t *testing.T) {
 	scriptDir := t.TempDir()
 	scriptPath := filepath.Join(scriptDir, "main.vibe")

vibes/execution.go

@@ -4268,6 +4268,20 @@ func (s *Script) Function(name string) (*ScriptFunction, bool) {
 	return fn, ok
 }
 
+// Functions returns compiled functions in deterministic name order.
+func (s *Script) Functions() []*ScriptFunction {
+	names := make([]string, 0, len(s.functions))
+	for name := range s.functions {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	out := make([]*ScriptFunction, 0, len(names))
+	for _, name := range names {
+		out = append(out, s.functions[name])
+	}
+	return out
+}
+
 func (s *Script) bindFunctionOwnership() {
 	for _, fn := range s.functions {
 		fn.owner = s