pkg: Update with new main() requirements across dogfooding and exmaples

Author: antonsynd

build_tools/sharpy_dogfood/prompts.py

@@ -203,10 +203,21 @@ def get_code_generation_prompt(
 
     return f"""You are generating Sharpy code for compiler testing (dogfooding).
 
+## CRITICAL: Program Entry Point Requirement
+
+Every executable Sharpy program MUST have a `main()` function as its entry point:
+- All executable statements (print, variable assignments, function calls) must be inside `main()`
+- Only declarations (classes, functions, type aliases, static fields with type annotations) can be at module level
+- Module-level variables require explicit type annotations: `counter: int = 0`
+
 ## CRITICAL: Allowed Features (Phases 0.1.0-0.1.10 ONLY)
 
 ### ✅ ALLOWED - Use these features:
 
+#### Program Structure
+- **Entry point**: `def main():` is REQUIRED for all executable code
+- **Module-level declarations**: classes, functions, constants, static fields (with type annotation)
+
 #### Variables & Types (0.1.3)
 - **Variables**: `x: int = 42` or `x = 42` (type inference)
 - **Types**: `int`, `str`, `bool`, `float` (primitive types)
@@ -326,9 +337,10 @@ def increment(self) -> None:
     def get(self) -> int:
         return self.value
 
-c = Counter(10)
-c.increment()
-print(c.get())
+def main():
+    c = Counter(10)
+    c.increment()
+    print(c.get())
 
 # EXPECTED OUTPUT:
 # 11
@@ -393,6 +405,13 @@ def get_multifile_generation_prompt(
 
     return f"""You are generating a MULTI-FILE Sharpy project for compiler testing (dogfooding).
 
+## CRITICAL: Program Entry Point Requirement
+
+The `main.spy` file MUST have a `main()` function as its entry point:
+- All executable statements (print, variable assignments, function calls) must be inside `main()`
+- Library modules (non-main.spy files) do NOT need a `main()` function
+- Only declarations (classes, functions, type aliases, static fields) can be at module level
+
 ## CRITICAL: Module System Rules (Phase 0.1.10)
 
 ### Import Syntax
@@ -406,6 +425,7 @@ def get_multifile_generation_prompt(
 - Module name = filename without `.spy` extension
 - No `__init__.py` needed (not Python!)
 - Modules in same directory can import each other
+- The entry point file (`main.spy`) MUST have a `main()` function
 
 ### Allowed Features (same as single-file, phases 0.1.0-0.1.10)
 - Variables, functions, classes, structs, enums, interfaces
@@ -451,11 +471,12 @@ def __init__(self, v: int):
 # Main entry point - imports from module_name
 from module_name import helper_function, UtilityClass
 
-result: int = helper_function(5)
-print(result)
+def main():
+    result: int = helper_function(5)
+    print(result)
 
-obj = UtilityClass(10)
-print(obj.value)
+    obj = UtilityClass(10)
+    print(obj.value)
 
 # EXPECTED OUTPUT:
 # 10
@@ -533,9 +554,16 @@ def get_regeneration_prompt(
 3. REMOVE or REPLACE the forbidden features
 4. Keep the same general logic/intent but use only allowed features
 
+## CRITICAL: Program Entry Point Requirement
+
+Every executable Sharpy program MUST have a `main()` function:
+- All executable statements (print, assignments, function calls) must be inside `main()`
+- Only declarations (classes, functions, constants) can be at module level
+
 ## CRITICAL: Allowed Features (Phases 0.1.0-0.1.10 ONLY)
 
 ### ✅ ALLOWED:
+- Entry point: `def main():` is REQUIRED for executable code
 - Variables: `x: int = 42`
 - Types: `int`, `str`, `bool`, `float`, nullable `int?`
 - Operators: `+`, `-`, `*`, `/`, `//`, `%`, `**`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `and`, `or`, `not`
@@ -553,6 +581,7 @@ def get_regeneration_prompt(
 - Built-ins: `print(value)` - SINGLE ARGUMENT ONLY, `range()` in for loops
 
 ### ❌ FORBIDDEN (DO NOT USE):
+- NO bare executable statements at module level - wrap in `def main():`
 - NO f-strings: `f"hello {{x}}"`
 - NO multi-argument print: `print(a, b)` - use multiple print() calls instead
 - NO string concatenation: `"a" + "b"`
@@ -595,8 +624,20 @@ def get_spec_validation_prompt(code: str, spec_context: str) -> str:
 
     return f"""You are a STRICT Sharpy language specification validator for phases 0.1.0-0.1.10.
 
+## Program Entry Point Requirement
+
+Every executable Sharpy program MUST have a `main()` function:
+- All executable statements (print, assignments without type annotation, function calls) must be inside `main()`
+- Only declarations are allowed at module level: classes, functions, constants, static fields (with type annotation)
+- Example of valid module-level: `counter: int = 0` (static field with type annotation)
+- Example of INVALID module-level: `x = 5` (no type annotation, or bare statement)
+
 ## ALLOWED Features (Phases 0.1.0-0.1.10):
 
+### Program Structure
+- Entry point: `def main():` is REQUIRED for executable code
+- Module-level declarations: classes, functions, constants, static fields (with type annotation)
+
 ### Variables & Types (0.1.3)
 - Variable declaration: `x: int = 42` or `x = 42` (inference)
 - Primitive types: `int`, `str`, `bool`, `float`
@@ -674,6 +715,7 @@ def get_spec_validation_prompt(code: str, spec_context: str) -> str:
 
 ## FORBIDDEN Features (NOT in phases 0.1.0-0.1.10):
 
+❌ Bare executable statements at module level (must be in `main()`) - REJECT
 ❌ f-strings: `f"text {{var}}"` - REJECT
 ❌ Multi-argument print: `print(a, b, c)` - REJECT (use multiple print calls)
 ❌ Lists/dicts/sets literals: `[]`, `{{}}`, `set()` - REJECT (v0.1.11)

docs/language_specification/variable_declaration.md

@@ -1,6 +1,8 @@
 # Variable Declaration and Assignment
 
-Variables in Sharpy must be declared and assigned in a single statement. There are three syntactic forms:
+Variables in Sharpy must be declared and assigned in a single statement. Variable declarations with type inference (Forms 2 and 3 below) are only allowed inside functions; module-level declarations require explicit type annotations.
+
+There are three syntactic forms:
 
 | Form | Syntax | Type Determination |
 |------|--------|-------------------|
@@ -10,63 +12,80 @@ Variables in Sharpy must be declared and assigned in a single statement. There a
 
 **Form 1: Explicit Type Annotation**
 
-The type is explicitly specified:
+The type is explicitly specified. This form can be used both at module level (static fields) and inside functions:
 
 ```python
-count: int = 0
-name: str = "Alice"
-items: list[int] = [1, 2, 3]
-user: User? = None
+# Module level (static fields) - explicit type REQUIRED
+counter: int = 0
+config: str = "default"
+
+def main():
+    # Inside functions - explicit type allowed
+    count: int = 0
+    name: str = "Alice"
+    items: list[int] = [1, 2, 3]
+    user: User? = None
 ```
 
 **Form 2: Type Inference (Implicit)**
 
-The type is inferred from the initializer expression:
+The type is inferred from the initializer expression. This form is **only allowed inside functions**, not at module level:
 
 ```python
-count = 0              # Inferred as int
-name = "Alice"         # Inferred as str
-items = [1, 2, 3]      # Inferred as list[int]
-pi = 3.14159           # Inferred as float
+def main():
+    count = 0              # Inferred as int
+    name = "Alice"         # Inferred as str
+    items = [1, 2, 3]      # Inferred as list[int]
+    pi = 3.14159           # Inferred as float
+
+# ❌ NOT allowed at module level:
+# count = 0              # ERROR: module-level requires type annotation
 ```
 
 **Form 3: Type Inference (Explicit with `auto`)**
 
-The `auto` keyword explicitly requests type inference. This is functionally equivalent to Form 2 but makes the inference explicit:
+The `auto` keyword explicitly requests type inference. This is functionally equivalent to Form 2 but makes the inference explicit. Like Form 2, this is **only allowed inside functions**:
 
 ```python
-count: auto = 0        # Inferred as int
-name: auto = "Alice"   # Inferred as str
-items: auto = [1, 2, 3]  # Inferred as list[int]
+def main():
+    count: auto = 0        # Inferred as int
+    name: auto = "Alice"   # Inferred as str
+    items: auto = [1, 2, 3]  # Inferred as list[int]
 ```
 
 **When to Use `auto`:**
 
 The `auto` keyword is primarily useful for variable shadowing, where you want to redeclare a variable with a different type:
 
 ```python
-x: int = 5
-x = 10                 # Assignment to existing int variable
-x: str = "hello"       # Shadowing: new variable of type str
-x: auto = [1, 2, 3]    # Shadowing: new variable, type inferred as list[int]
+def main():
+    x: int = 5
+    x = 10                 # Assignment to existing int variable
+    x: str = "hello"       # Shadowing: new variable of type str
+    x: auto = [1, 2, 3]    # Shadowing: new variable, type inferred as list[int]
 ```
 
 ## No Declaration Without Assignment
 
 Unlike some languages, Sharpy does not allow variable declarations without initialization:
 
 ```python
-# ❌ Invalid - no declaration without assignment
-x: int                 # ERROR: variable declaration requires initializer
-name: str              # ERROR: variable declaration requires initializer
-
-# ✅ Valid - always provide initializer
-x: int = 0
-name: str = ""
-items: list[int] = []
-user: User? = None
+def main():
+    # ❌ Invalid - no declaration without assignment
+    x: int                 # ERROR: variable declaration requires initializer
+    name: str              # ERROR: variable declaration requires initializer
+
+    # ✅ Valid - always provide initializer
+    x: int = 0
+    name: str = ""
+    items: list[int] = []
+    user: User? = None
 ```
 
 **Exception: Class Instance Fields**
 
 Class and struct fields can be declared without initialization if they are assigned in `__init__`.
+
+## Module-Level vs Function-Level Variables
+
+See [Program Entry Point](program_entry_point.md) for details on module-level declarations vs executable statements inside `main()`.

snippets/class.spy

@@ -1,3 +1,6 @@
+# Parser test file - contains syntax not yet fully supported
+# This file is for AST/parser testing, not execution
+
 class Foo:
     x: int
     y: str

snippets/example.spy

@@ -1,3 +1,6 @@
+# Parser test file - contains syntax not yet fully supported (try/except, string concat, etc.)
+# This file is for AST/parser testing, not execution
+
 class Example:
     x: int = 42
     blah: list[list[float]] = []

snippets/functions.spy

@@ -1,3 +1,6 @@
+# Function definitions (library module - no main() needed if imported)
+# To run standalone, uncomment the main() function below
+
 def foobar():
     pass
 
@@ -13,3 +16,10 @@ def fibonacci(n: int) -> int:
         return 1
     else:
         return fibonacci(n - 1) + fibonacci(n - 2)
+
+
+def main():
+    # Example usage
+    foobar()
+    print(add(3, 5))
+    print(fibonacci(10))

snippets/objects.spy

@@ -1,3 +1,6 @@
+# Parser test file - contains syntax not yet fully supported (f-strings)
+# This file is for AST/parser testing, not execution
+
 class Foo:
     _value: int