docs(spec): document directive syntax in language grammar

[Copilot]

The grammar spec had no coverage of the #suppress/#deprecated directive syntax, and incorrectly claimed that newline sequences have no language-semantic impact — which is false since directives are newline-terminated.

Lexical grammar

• Separate LineTerminatorSequence from WhiteSpace — the scanner already emits Token.NewLine (CR, LF, CRLF) separately from Token.Whitespace; the spec now reflects this
• Add LineTerminator and LineTerminatorSequence productions defining the three recognised sequences
• Update Trivia to include LineTerminatorSequence alongside Comment and WhiteSpace
• Fix the newline comment — removes the incorrect claim; explains that line terminators are syntactically significant (directive termination)

Syntactic grammar

• Add directive productions: DirectiveList, DirectiveExpression, DirectiveArguments, DirectiveArgument — with prose notes on newline-aware termination, the EOF edge case, the two recognised directive names, and their per-directive argument counts (validated semantically)
• Thread DirectiveList? into all annotatable productions — BlocklessNamespaceStatement, ModelStatement, ScalarStatement, InterfaceStatement, InterfaceMember, UnionStatement, UnionVariant, EnumStatement, EnumMember, NamespaceStatement, OperationStatement, ModelProperty

Example of what is now documented:

#suppress "deprecated" "Using old API intentionally"
@decorator
model Foo { }

#deprecated "Use Bar instead"
model OldFoo { }

[timotheeguerin]

@copilot ecmarkcup runs out memory now

> ecmarkup --strict src/spec.emu.html dist/spec.html 2>&1

Warning: inlining assets; this should not be done for production builds.

<--- Last few GCs --->

[3129:0x39fb4000]   103130 ms: Scavenge (interleaved) 4064.8 (4133.9) -> 4064.8 (4134.9) MB, pooled: 0 MB, 52.16 / 0.00 ms  (average mu = 0.231, current mu = 0.126) allocation failure; 
[3129:0x39fb4000]   103412 ms: Scavenge (interleaved) 4065.8 (4134.9) -> 4065.8 (4157.9) MB, pooled: 0 MB, 270.49 / 0.00 ms  (average mu = 0.231, current mu = 0.126) allocation failure; 


<--- JS stacktrace --->

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
----- Native stack trace -----

 1: 0xe46bbe node::OOMErrorHandler(char const*, v8::OOMDetails const&) [node]
 2: 0x1243640 v8::Utils::ReportOOMFailure(v8::internal::Isolate*, char const*, v8::OOMDetails const&) [node]
 3: 0x1243917 v8::internal::V8::FatalProcessOutOfMemory(v8::internal::Isolate*, char const*, v8::OOMDetails const&) [node]
 4: 0x1472825  [node]
 5: 0x148c0b9 v8::internal::Heap::CollectGarbage(v8::internal::AllocationSpace, v8::internal::GarbageCollectionReason, v8::GCCallbackFlags) [node]
 6: 0x14607b8 v8::internal::HeapAllocator::AllocateRawWithLightRetrySlowPath(int, v8::internal::AllocationType, v8::internal::AllocationOrigin, v8::internal::AllocationAlignment) [node]
 7: 0x14616e5 v8::internal::HeapAllocator::AllocateRawWithRetryOrFailSlowPath(int, v8::internal::AllocationType, v8::internal::AllocationOrigin, v8::internal::AllocationAlignment) [node]
 8: 0x143a2ee v8::internal::Factory::NewFillerObject(int, v8::internal::AllocationAlignment, v8::internal::AllocationType, v8::internal::AllocationOrigin) [node]
 9: 0x189cbfc v8::internal::Runtime_AllocateInYoungGeneration(int, unsigned long*, v8::internal::Isolate*) [node]
10: 0x7f69cae6caf6 
Aborted (core dumped)
 ELIFECYCLE  Command failed with exit code 134.

[Copilot]

@copilot ecmarkcup runs out memory now

...

Fixed in the latest commit. The root cause was the LineTerminator : one of <LF> <CR> production definition I added. It was already referenced (but undefined) in BacktickedIdentifierChar, StringCharacter, and SingleLineCommentChar — and ecmarkup handled those undefined references fine. Once I defined it, ecmarkup tried to expand all the "SourceCharacter but not … or LineTerminator" productions and blew up.

Fix: remove the LineTerminator definition entirely. LineTerminatorSequence is defined directly using <LF>/<CR> character literals (no reference to LineTerminator), so it's unaffected. I also removed the LineTerminatorSequence terminal from DirectiveExpression — Trivia elements are transparent in the syntactic grammar, so directive termination is now explained in prose only.

[timotheeguerin]

@copilto fix spellcheck

[timotheeguerin]

@copilot fix spellcheck

[Copilot]

@copilot fix spellcheck

Fixed — two instances of recognised → recognized.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension