@eventcatalog/language-server 0.5.0 → 0.6.1

package/specification/06-channel.md

@@ -11,6 +11,7 @@ channel <id> {
 
   address "<address-string>"
   protocol "<protocol>"
+  deliveryGuarantee at-most-once|at-least-once|exactly-once
 
   // Channel parameters
   parameter <name> {
@@ -29,6 +30,24 @@ channel <id> {
 }
 ```
 
+## Delivery guarantee
+
+The `deliveryGuarantee` property declares the message delivery semantics of a channel. The visualiser renders a colored badge on the channel node to make the guarantee visible at a glance.
+
+```
+channel OrderEvents {
+  version 1.0.0
+  protocol "Kafka"
+  deliveryGuarantee exactly-once
+}
+```
+
+| Value           | Meaning                                                     |
+| --------------- | ----------------------------------------------------------- |
+| `at-most-once`  | Messages may be lost; never delivered more than once        |
+| `at-least-once` | Messages are never lost but may be delivered more than once |
+| `exactly-once`  | Messages are delivered exactly once with no duplicates      |
+
 ## Channel-to-Channel Routing
 
 Channels can route to other channels using the `route` statement. This models message pipelines where data flows through multiple channels (e.g., Kafka topic → Kafka topic → MQTT broker):
@@ -112,10 +131,11 @@ service OrderService {
 ```ebnf
 channel_decl     = "channel" identifier "{" common_props
                    { channel_body_item } "}" ;
-channel_body_item= address_prop | protocol_prop | parameter_decl
-                 | route_stmt | annotation ;
-address_prop     = "address" string_lit ;
-protocol_prop    = "protocol" string_lit ;
+channel_body_item= address_prop | protocol_prop | delivery_guarantee_prop
+                 | parameter_decl | route_stmt | annotation ;
+address_prop              = "address" string_lit ;
+protocol_prop             = "protocol" string_lit ;
+delivery_guarantee_prop   = "deliveryGuarantee" ( "at-most-once" | "at-least-once" | "exactly-once" ) ;
 parameter_decl   = "parameter" identifier "{" { param_prop } "}" ;
 param_prop       = "description" string_lit
                  | "default" string_lit

package/specification/16-annotations.md

@@ -68,6 +68,58 @@ service PaymentService {
 }
 ```
 
+## @api
+
+Attaches HTTP API metadata to a message (event, command, or query). Typically generated automatically when importing an OpenAPI spec, but can also be written manually. The visualiser displays the method badge, API path, and response status codes on the node.
+
+```
+// Basic usage with method and path
+command CreateOrder {
+  version 1.0.0
+  summary "Create a new order"
+  @api(method: "POST", path: "/orders")
+}
+
+// With status codes
+query GetOrders {
+  version 1.0.0
+  summary "List all orders"
+  @api(method: "GET", path: "/orders", statusCodes: "200,401")
+}
+
+// On inline message definitions
+service PaymentService {
+  version 2.0.0
+  receives command CreatePayment {
+    version 2.0.0
+    summary "Process a new payment"
+    @api(method: "POST", path: "/payments", statusCodes: "201,400,422")
+  }
+  receives query GetPayment {
+    version 2.0.0
+    @api(method: "GET", path: "/payments/{paymentId}", statusCodes: "200,404")
+  }
+}
+```
+
+### Parameters
+
+| Parameter     | Type   | Description                                              |
+| ------------- | ------ | -------------------------------------------------------- |
+| `method`      | string | HTTP method (GET, POST, PUT, PATCH, DELETE)              |
+| `path`        | string | API path (e.g. `/orders`, `/users/{id}`)                 |
+| `statusCodes` | string | Comma-separated HTTP status codes (e.g. `"200,401,500"`) |
+
+### Auto-generated from OpenAPI
+
+When importing an OpenAPI spec, `@api` annotations are automatically added to the generated `.ec` definitions:
+
+```
+import PaymentService from "./payments-openapi.yml"
+```
+
+This generates commands and queries with `@api` annotations populated from the OpenAPI paths, methods, and response codes.
+
 ## @detailsPanel
 
 Controls visibility of detail panel sections:

package/syntaxes/ec.tmLanguage.json

@@ -10,7 +10,7 @@
     },
     {
       "name": "keyword.control.ec",
-      "match": "\\b(access-mode|actor|address|and|animated|appendOnly|authoritative|avatar|cache|channel|channels|classification|color|command|commands|confidential|container|container-type|contract|data-product|dataLake|dataWarehouse|database|default|delivery|deprecated|description|diagram|domain|draft|email|enum|event|events|examples|external-system|externalSaaS|false|flow|focus-mode|from|hidden|icon|import|input|internal|label|legend|member|message|ms-teams|name|objectStore|other|output|owner|parameter|path|post-it|protocol|public|pull|push|push-pull|queries|query|read|readWrite|reads-from|receives|regulated|residency|retention|role|route|schema|search|searchIndex|sends|service|slack|style|subdomain|summary|team|technology|title|to|toolbar|true|type|url|user|version|visible|visualizer|when|write|writes-to)\\b"
+      "match": "\\b(access-mode|actor|address|and|animated|appendOnly|authoritative|avatar|cache|channel|channels|classification|color|command|commands|confidential|container|container-type|containers|contract|data-product|dataLake|dataWarehouse|database|default|delivery|deprecated|description|diagram|domain|draft|email|enum|event|events|examples|external-system|externalSaaS|false|flow|focus-mode|from|hidden|icon|import|input|internal|label|legend|member|message|ms-teams|name|objectStore|other|output|owner|parameter|path|post-it|protocol|public|pull|push|push-pull|queries|query|read|readWrite|reads-from|receives|regulated|residency|retention|role|route|schema|search|searchIndex|sends|service|services|slack|style|subdomain|summary|team|technology|title|to|toolbar|true|type|url|user|version|visible|visualizer|when|write|writes-to)\\b"
     },
     {
       "name": "string.quoted.double.ec",