ide: advertise typed-language keywords

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Advertise typed-language keywords to IDE helpers
+
+- Added `RETURNS`, `CHECK`, and `TYPE` to `claro ide` keyword metadata so editor integrations can recognize the current typed function and type-checking syntax.
+- Extended the IDE metadata validator and documented the updated completion surface.
+
 ### Validate the complete typecheck matrix
 
 - `claro validate` now runs the complete focused typecheck fixture matrix, including method-call, alias, return, and expression fixtures that were previously covered only by the standalone diagnostic validator.

README.md

@@ -23,6 +23,7 @@ Validated in this package:
 # Validation passed. Claro v1.18.26 networking reliability is ready for use.
 
 python3 tools/validate_typecheck_diagnostics.py
+python3 tools/validate_ide_metadata.py
 python3 tools/validate_version_convention.py
 python3 tools/validate_package_security.py
 python3 tools/validate_ci_workflow.py

docs/CURRENT_STATUS.md

@@ -175,7 +175,7 @@ Status: **Foundation present**
 Ready now:
 - `claro ide`
 - metadata JSON
-- completion list
+- completion list, including the current typed-language keywords `RETURNS`, `CHECK`, and `TYPE`
 - diagnostics helper
 - Forgejo/Gitea CI coverage for the current release validation gates (`claro validate`, typecheck diagnostics validation, version convention validation, package security validation, and the CI workflow coverage check); the workflow validator verifies these commands, including its own command, occur in executable `run` steps rather than comments
 

docs/ROADMAP.md

@@ -37,6 +37,7 @@ See `CURRENT_STATUS.md` for the detailed feature matrix.
 4. Add small examples for each foundation feature before adding bigger syntax. The object-field foundation now includes positive and negative validation for field expressions such as `SET player.score player.name`, `SET player.score player.score + 1`, `SET player.name player.score + 1`, explicitly typed field assignments, explicit typed assignments to undeclared fields, simple and chained aliases such as `SET alias player`, `SET backup alias`, followed by `SET backup.score ...` or `CHECK TYPE backup.score IS ...`, chained aliases in object-method calls through both modern `DO` and compatibility `CALL ... WITH` forms (including a dedicated positive modern `DO` fixture), and arithmetic/text expression mismatches; typed containers also accept a map with nested type metadata when it is added to a `LIST OF MAP`; broader alias/control-flow checking remains planned.
 5. Keep the focused typecheck validator complete: every `typecheck_*.claro` fixture, including positive fixtures, is now exercised by both the standalone diagnostic validator and `claro validate`.
 6. Continue narrowing expression diagnostics: known TEXT operands now remain visible through arithmetic, with focused numeric-subtraction, numeric-division, and numeric-multiplication positives plus text-operand addition, subtraction, multiplication, and division coverage. Text concatenation into TEXT fields is covered in both operand orders, including field-to-field concatenation. Each numeric operator gives specific guidance naming the text operand. `CHECK TYPE` also rejects misspelled expected type names before comparing values.
+- Keep IDE metadata aligned with the current beginner syntax: typed-language keywords such as `RETURNS`, `CHECK`, and `TYPE` are now included in the metadata used by editor helpers.
 - Keep declared return types honest: `claro typecheck` now reports friendly diagnostics for unknown declared return types, mismatched and empty return expressions, declarations with no `RETURN`, and incomplete conditional branches, when a simple function or object method declares `RETURNS TYPE`; complete `IF`/`ELSE` return branches, including nested complete conditionals in functions and methods, are accepted, and modern and compatibility function syntax plus compatibility method syntax are covered by focused fixtures. `CHECK TYPE` parameter metadata also informs arithmetic return-expression checking, including object methods. Full path-sensitive analysis across nested conditionals and loops remains planned.
 
 ## Complete-platform milestones

src/claro.c

@@ -721,7 +721,7 @@ static int print_ide_info(void){
  printf("  \"language\": \"Claro\",\n");
  printf("  \"version\": \"v1.18.26\",\n");
  printf("  \"file_extensions\": [\".claro\"],\n");
- printf("  \"keywords\": [\"SAY\",\"ASK\",\"SET\",\"IF\",\"ELSE\",\"ENDIF\",\"END\",\"REPEAT\",\"UNTIL\",\"TEACH\",\"LEARNED\",\"DO\",\"RETURN\",\"CLASS\",\"HAS\",\"NEW\",\"IMPORT\",\"TRY\",\"CATCH\",\"ENDTRY\",\"START TASK\",\"YIELD\",\"WAIT TASK\",\"TASK STATUS\",\"HTTP CHECK\",\"HTTP GET\",\"HTTP SAVE\",\"OPEN WINDOW\"],\n");
+ printf("  \"keywords\": [\"SAY\",\"ASK\",\"SET\",\"IF\",\"ELSE\",\"ENDIF\",\"END\",\"REPEAT\",\"UNTIL\",\"TEACH\",\"TAKES\",\"RETURNS\",\"CHECK\",\"TYPE\",\"LEARNED\",\"DO\",\"CALL\",\"WITH\",\"RETURN\",\"CLASS\",\"HAS\",\"NEW\",\"IMPORT\",\"TRY\",\"CATCH\",\"ENDTRY\",\"START TASK\",\"YIELD\",\"WAIT TASK\",\"TASK STATUS\",\"HTTP CHECK\",\"HTTP GET\",\"HTTP SAVE\",\"OPEN WINDOW\"],\n");
  printf("  \"types\": [\"NUMBER\",\"TEXT\",\"YESNO\",\"LIST\",\"LIST OF TEXT\",\"LIST OF NUMBER\",\"LIST OF YESNO\",\"MAP\",\"MAP OF TEXT\",\"MAP OF NUMBER\",\"MAP OF YESNO\",\"OBJECT\",\"ANY\"],\n");
  printf("  \"commands\": [\n");
  printf("    {\"name\": \"run\", \"usage\": \"claro run\", \"description\": \"Run main.claro or the project main script\"},\n");

tests/test_validate_ide_metadata.py

@@ -0,0 +1,34 @@
+import json
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_ide_metadata_lists_current_typed_function_keywords():
+    result = subprocess.run(
+        ["python3", "tools/validate_ide_metadata.py"],
+        cwd=ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+
+    assert result.returncode == 0, result.stdout
+    assert result.stdout.strip() == "IDE metadata validation OK"
+
+
+def test_ide_metadata_is_valid_json_with_keyword_list():
+    result = subprocess.run(
+        ["./claro", "ide"],
+        cwd=ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=True,
+    )
+    metadata = json.loads(result.stdout)
+
+    assert "RETURNS" in metadata["keywords"]
+    assert "CHECK" in metadata["keywords"]
+    assert "TYPE" in metadata["keywords"]

tools/validate_ide_metadata.py

@@ -31,6 +31,9 @@ def main():
 
     if ".claro" not in data["file_extensions"]:
         fail("IDE metadata must advertise the .claro file extension")
+    for keyword in ("RETURNS", "CHECK", "TYPE"):
+        if keyword not in data["keywords"]:
+            fail(f"IDE metadata must include the current typed-language keyword: {keyword}")
     if "LIST OF TEXT" not in data["types"]:
         fail("IDE metadata must include typed container types")
     if not any(cmd.get("name") == "typecheck" for cmd in data["commands"]):