Update AGR language extension syntax highlighting (#2087)

## Summary

Updates the VS Code AGR language extension to support all current
grammar features with proper syntax coloring.

### Syntax highlighting additions

- **Block comments** (`/* ... */`) — previously only line comments were
supported
- **`export` keyword** — for exported rule definitions
- **`[spacing=...]` annotations** — `required`, `optional`, `auto`,
`none` with distinct scopes
- **Value type annotations** — `: TypeName | TypeName` after rule names
- **Source-less entity imports** — `import { Ordinal, CalendarDate };`
(no `from` clause)
- **Value expression operators** — `===`, `!==`, `??`, `?.`, `||`, `&&`,
ternary `? :`, `typeof`, arithmetic, member access
- **Template literals** — `\`text \${expr} text\`` with recursive
expression highlighting inside `\${}`
- **Spread operator** — `...` in value positions
- **Capture quantifiers** — `?`, `*`, `+` on captures and rule
references
- **Grouped expressions** — `(expr)` and function call arguments in
value context

### Bug fixes

- **Single-quote handling** — Apostrophes in expression context (e.g.
`what('s | is)`) are now treated as literal characters, not string
delimiters. Previously this broke all highlighting from that point
onward.
- **Action object values** — Replaced embedded `source.js` grammar with
native AGR value syntax for correct highlighting of AGR-specific
constructs.

### Other changes

- **language-configuration.json** — Added `blockComment` support for `/*
*/` toggle
- **grammarRuleParser.ts** — Added comprehensive BNF for value
expressions to the parser documentation comment
- **sample.agr** — Updated with examples demonstrating all new features

### Files changed

- `extensions/agr-language/syntaxes/agr.tmLanguage.json`
- `extensions/agr-language/language-configuration.json`
- `extensions/agr-language/sample.agr`
- `packages/actionGrammar/src/grammarRuleParser.ts`

Author: curtisman

ts/extensions/agr-language/language-configuration.json

@@ -1,6 +1,7 @@
 {
   "comments": {
-    "lineComment": "//"
+    "lineComment": "//",
+    "blockComment": ["/*", "*/"]
   },
   "brackets": [
     ["{", "}"],

ts/extensions/agr-language/sample.agr

@@ -4,15 +4,30 @@
 // Sample Action Grammar file demonstrating syntax highlighting
 // This file shows all the major syntax elements
 
-// Import syntax
+/* Block comment:
+   The grammar supports both line comments (//) and block comments.
+*/
+
+// ─── Import syntax ────────────────────────────────────────────────────────────
+
+// Named imports from .agr files
 import { Cardinal, TrackName, ArtistName } from "./base.agr";
+
+// Wildcard import from .agr files
 import * from "./shared.agr";
+
+// Imports from .ts schema files
 import { GreetAction, PlayAction, PauseAction } from "./schema.ts";
 
-// Simple rule definition
+// Source-less entity imports (no "from" clause — built-in entities)
+import { Ordinal, CalendarDate };
+
+// ─── Simple rule definition ───────────────────────────────────────────────────
+
 <Start> = <Greeting> | <Command>;
 
-// Rule with captures and value type annotation
+// ─── Rule with value type annotation ──────────────────────────────────────────
+
 <Greeting> : GreetAction =
     hello $(name:PersonName) -> {
         actionName: "greet",
@@ -22,7 +37,8 @@ import { GreetAction, PlayAction, PauseAction } from "./schema.ts";
     }
   | hi there -> { actionName: "greet" };
 
-// Rule with optional elements (union value type)
+// ─── Union value type annotation ──────────────────────────────────────────────
+
 <Command> : PlayAction | PauseAction =
     play (the)? $(track:TrackName)
     by $(artist:ArtistName) -> {
@@ -34,7 +50,25 @@ import { GreetAction, PlayAction, PauseAction } from "./schema.ts";
     }
   | pause (the)? music? -> { actionName: "pause" };
 
-// Rule with multiple patterns
+// ─── Exported rule ────────────────────────────────────────────────────────────
+
+export <PublicRule> = hello | goodbye;
+
+// ─── Spacing annotations ─────────────────────────────────────────────────────
+
+<Hashtag> [spacing=none] = \# $(tag:word) -> { actionName: "hashtag", parameters: { tag } };
+
+<SearchPhrase> [spacing=required] = search for $(query:string) -> {
+    actionName: "search",
+    parameters: { query }
+};
+
+<CJKMixed> [spacing=auto] = $(text:string) -> text;
+
+<Adjacent> [spacing=optional] = $(a:word) $(b:word) -> { a, b };
+
+// ─── Multiple patterns with bare results ─────────────────────────────────────
+
 <Volume> =
     (turn | set) (the)? volume to $(level:number) -> {
         actionName: "setVolume",
@@ -43,7 +77,7 @@ import { GreetAction, PlayAction, PauseAction } from "./schema.ts";
   | volume up -> { actionName: "volumeUp" }
   | volume down -> { actionName: "volumeDown" };
 
-// Bare -> results (non-object): string literal, number, or variable reference
+// Bare -> results: string literal, number, or variable reference
 <PromptSpec> = (
     ('ask me' | 'confirm' | 'please confirm') -> "true" |
     ("don't ask" | 'without asking' | 'skip') -> "false"
@@ -55,7 +89,8 @@ import { GreetAction, PlayAction, PauseAction } from "./schema.ts";
     'all' -> "all"
 );
 
-// Numeric patterns
+// ─── Numeric patterns ────────────────────────────────────────────────────────
+
 <Cardinal> =
     $(x:number)
   | one -> 1
@@ -64,15 +99,26 @@ import { GreetAction, PlayAction, PauseAction } from "./schema.ts";
   | four -> 4
   | five -> 5;
 
-// String type references
+// ─── Entity type captures ────────────────────────────────────────────────────
+
+<ScheduleEvent> =
+    schedule $(desc:string) on $(date:CalendarDate) -> {
+        actionName: "schedule",
+        parameters: { description: desc, date }
+    };
+
+<PlayNth> =
+    play (the)? $(n:Ordinal) (track | song)? -> {
+        actionName: "playFromQueue",
+        parameters: { trackNumber: n }
+    };
+
+// ─── Capture with rule references ─────────────────────────────────────────────
+
 <TrackName> = $(x:string);
 <ArtistName> = $(x:string);
 <PersonName> = $(x:string);
 
-// Complex nested rule
-<PlayCommand> =
-    <PlayTrack> | <PlayAlbum> | <PlayArtist>;
-
 <PlayTrack> =
     play track $(n:<Cardinal>) -> {
         actionName: "playTrackNumber",
@@ -96,7 +142,83 @@ import { GreetAction, PlayAction, PauseAction } from "./schema.ts";
 
 <AlbumName> = $(x:string);
 
-// Operators demonstration
+// ─── Spread operator in values ────────────────────────────────────────────────
+
+<MergeAction> =
+    merge $(src:string) into $(dest:string) -> {
+        actionName: "merge",
+        parameters: { ...src, destination: dest }
+    };
+
+// ─── Escape sequences in string expressions ──────────────────────────────────
+
+<Status> = (what('s | is) | show) (playing | status)?
+    -> { actionName: "status" };
+
+<EscapeDemo> = hello\ world -> "hello world";
+
+// ─── Operators and grouping ──────────────────────────────────────────────────
+
 <Operators> =
     one? two* three+ four  // optional, zero-or-more, one-or-more
-  | (first | second | third)  // alternation with grouping;
+  | (first | second | third)  // alternation with grouping
+  | (item)+ // one-or-more group
+  | (prefix)* suffix; // zero-or-more group
+
+// ─── Optional capture quantifiers ────────────────────────────────────────────
+
+<ItemList> =
+    add $(item:word)+ to $(list:string) -> {
+        actionName: "addItems",
+        parameters: { items: [item], listName: list }
+    };
+
+// ─── Value expressions (enableExpressions mode) ──────────────────────────────
+
+// Ternary operator
+<Toggle> =
+    toggle $(flag:word) -> flag === "on" ? true : false;
+
+// Logical and nullish coalescing operators
+<Fallback> =
+    set $(key:word) to $(val:string) -> {
+        actionName: "set",
+        parameters: {
+            key,
+            value: val ?? "default",
+            enabled: val !== "" && val !== "off"
+        }
+    };
+
+// Arithmetic and comparison in values
+<Repeat> =
+    repeat $(n:number) times -> {
+        actionName: "repeat",
+        parameters: {
+            count: n,
+            doubled: n * 2,
+            isMany: n > 5 || n === 0
+        }
+    };
+
+// Member access and optional chaining
+<Lookup> =
+    lookup $(obj:word) -> obj.value?.name;
+
+// Template literals
+<Greet> =
+    greet $(name:string) -> `Hello, ${name}!`;
+
+// Unary operators
+<Negate> =
+    negate $(x:number) -> -x;
+
+<Check> =
+    check $(val:word) -> !val ? "empty" : typeof val;
+
+// Method calls and computed access
+<Transform> =
+    transform $(data:word) -> data.items[0]?.toString();
+
+/* End of sample — this block comment demonstrates
+   that multi-line block comments are highlighted. */