feat: add forward-reference hints when exec fails on later-defined objects

When a statement fails because it references an object defined later in
the same script, the error now includes a hint suggesting reordering:

  hint: Module.NewEdit is defined later in this script — move its
        CREATE statement before this one

ExecuteProgram does a first pass to collect all defined names, then
tracks which have been created so far. On error, it checks if any
not-yet-created name appears in the message.

Closes #53

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

mdl/executor/executor.go

@@ -413,10 +413,18 @@ func (e *Executor) executeInner(stmt ast.Statement) error {
 
 // ExecuteProgram runs all statements in a program.
 func (e *Executor) ExecuteProgram(prog *ast.Program) error {
+	// Collect all names defined in the script for forward-reference hints.
+	allDefined := newScriptContext()
+	allDefined.collectDefinitions(prog)
+
+	// Track which names have been created so far.
+	created := newScriptContext()
+
 	for _, stmt := range prog.Statements {
 		if err := e.Execute(stmt); err != nil {
-			return err
+			return annotateForwardRef(err, stmt, created, allDefined)
 		}
+		created.collectSingle(stmt)
 	}
 	return e.finalizeProgramExecution()
 }

mdl/executor/validate.go

@@ -70,6 +70,85 @@ func (sc *scriptContext) collectDefinitions(prog *ast.Program) {
 	}
 }
 
+// collectSingle records the object defined by a single statement.
+func (sc *scriptContext) collectSingle(stmt ast.Statement) {
+	switch s := stmt.(type) {
+	case *ast.CreateModuleStmt:
+		sc.modules[s.Name] = true
+	case *ast.CreateEntityStmt:
+		if s.Name.Module != "" {
+			sc.entities[s.Name.String()] = true
+		}
+	case *ast.CreateViewEntityStmt:
+		if s.Name.Module != "" {
+			sc.entities[s.Name.String()] = true
+		}
+	case *ast.CreateExternalEntityStmt:
+		if s.Name.Module != "" {
+			sc.entities[s.Name.String()] = true
+		}
+	case *ast.CreateEnumerationStmt:
+		if s.Name.Module != "" {
+			sc.enumerations[s.Name.String()] = true
+		}
+	case *ast.CreateMicroflowStmt:
+		if s.Name.Module != "" {
+			sc.microflows[s.Name.String()] = true
+		}
+	case *ast.CreatePageStmtV3:
+		if s.Name.Module != "" {
+			sc.pages[s.Name.String()] = true
+		}
+	case *ast.CreateSnippetStmtV3:
+		if s.Name.Module != "" {
+			sc.snippets[s.Name.String()] = true
+		}
+	}
+}
+
+// allNames returns all defined names across all categories.
+func (sc *scriptContext) allNames() []string {
+	var names []string
+	for n := range sc.entities {
+		names = append(names, n)
+	}
+	for n := range sc.enumerations {
+		names = append(names, n)
+	}
+	for n := range sc.microflows {
+		names = append(names, n)
+	}
+	for n := range sc.pages {
+		names = append(names, n)
+	}
+	for n := range sc.snippets {
+		names = append(names, n)
+	}
+	return names
+}
+
+// annotateForwardRef checks if a failed statement's error references an object
+// that is defined later in the script. If so, it appends a hint to reorder.
+func annotateForwardRef(err error, _ ast.Statement, created, allDefined *scriptContext) error {
+	msg := err.Error()
+	// Check each name that is defined in the script but not yet created.
+	for _, name := range allDefined.allNames() {
+		if created.has(name) {
+			continue // already created before this statement
+		}
+		if strings.Contains(msg, name) {
+			return fmt.Errorf("%w\n  hint: %s is defined later in this script — move its CREATE statement before this one", err, name)
+		}
+	}
+	return err
+}
+
+// has returns true if the name exists in any category.
+func (sc *scriptContext) has(name string) bool {
+	return sc.modules[name] || sc.entities[name] || sc.enumerations[name] ||
+		sc.microflows[name] || sc.pages[name] || sc.snippets[name]
+}
+
 // ValidateProgram validates all statements in a program, skipping references
 // to objects that are defined within the script itself.
 func (e *Executor) ValidateProgram(prog *ast.Program) []error {