likec4 1.59.4 → 1.60.0

package/skills/likec4-dsl/references/examples.md

@@ -0,0 +1,370 @@
+# Examples
+
+Compact, real-world patterns. Each example demonstrates multiple features.
+
+## Extend Element & Metadata Merge
+
+```likec4
+// base.c4
+model {
+  cloud = system "Cloud" {
+    api = service "API" {
+      metadata { owner "team-a"; port "8080" }
+    }
+  }
+}
+
+// ops.c4 — extend adds nested elements, merges metadata (duplicate keys become arrays)
+model {
+  extend cloud.api {
+    #monitored
+    metadata { port "9090"; region "us-east-1" }
+    // Result: port becomes ["8080", "9090"]
+
+    health = component "Health Check" { technology "HTTP" }
+  }
+}
+```
+
+## Extend Relationship
+
+```likec4
+specification {
+  relationship async { color amber; line dotted }
+}
+model {
+  frontend -> api "requests"
+  frontend -[async]-> api "streams"   // different relation (kind distinguishes)
+
+  // Extend adds metadata/tags to existing relation (must match source, target, title, kind)
+  extend frontend -> api "requests" {
+    metadata { latency_p95 "150ms" }
+  }
+}
+```
+
+## View Extends (Inheritance)
+
+```likec4
+views {
+  view overview {
+    include *
+    style * { color muted }
+  }
+  view detail extends overview {
+    title "More detail"
+    include cloud.backend.*          // adds to parent's includes
+    style cloud.backend.* { color primary }
+  }
+  view deep extends detail {         // cascade inheritance
+    include cloud.backend.api.*
+  }
+}
+```
+
+## Scoped View
+
+```likec4
+views {
+  // "of" scopes the view — `*` means the scoped element + direct children
+  view backend of cloud.backend {
+    include *
+    include -> cloud.backend ->      // incoming/outgoing relations
+
+    style cloud.backend { color primary }
+    style cloud.backend.* { color secondary }
+  }
+}
+```
+
+## Groups in Views
+
+```likec4
+views {
+  view grouped {
+    group "Internal" {
+      color primary
+      opacity 20%
+      include cloud.*
+    }
+    group "External" {
+      color amber
+      include customer, partner
+    }
+    // Unnamed group
+    group {
+      include monitoring.*
+    }
+  }
+}
+```
+
+## Global Style & Predicate Groups
+
+```likec4
+global {
+  styleGroup theme {
+    style element.tag = #deprecated { color muted; opacity 20% }
+    style element.tag = #critical { color red }
+  }
+  predicateGroup core_services {
+    include cloud.* where kind is service
+    exclude * where tag is #deprecated
+  }
+}
+views {
+  global style theme             // apply to all views in block
+
+  view services {
+    global predicate core_services
+    include * -> cloud.*         // add relations to included elements
+  }
+}
+```
+
+## Dynamic View — Parallel, Notes, NavigateTo
+
+```likec4
+dynamic view checkout {
+  title "Checkout Flow"
+
+  customer -> frontend "places order" {
+    notes '''
+      **Entry point**: customer submits cart
+    '''
+  }
+  frontend
+    -> api "POST /checkout"
+    -> validator "validate cart"     // chained syntax
+
+  parallel {
+    api -> payments "charge card"
+    api -> inventory "reserve items"
+    api -> notifications "send confirmation"
+  }
+
+  payments <- api "payment result" {
+    navigateTo payment-detail        // link to another view
+  }
+
+  include cloud with { opacity 10%; color gray }
+  style customer { color green }
+  autoLayout TopBottom
+}
+```
+
+## Dynamic View — Flow Control (alt / try / loop)
+
+```likec4
+dynamic view resilient-checkout {
+  variant sequence
+
+  customer -> app "checkout"
+  alt {
+    when "authorized" {
+      loop "until confirmed" {
+        try {
+          app -> payments "charge card"
+        } catch "declined" {
+          app -> customer "ask for another card"
+        } finally {
+          app -> audit "record attempt"
+        }
+      }
+    }
+    else "not authorized" {
+      app -> customer "show login"
+    }
+  }
+}
+```
+
+- Each block takes an optional title. Blocks nest to any depth — the only exception is `parallel`/`par`, which cannot nest.
+- `when`/`if`/`else` are valid only directly inside `alt`; other blocks (`loop`/`opt`/`parallel`/`try`) must sit inside a branch, not directly under `alt`.
+- try/catch/finally order is fixed: `try` → `catch?` → `finally?`.
+
+## Deployment — Multi-Environment, InstanceOf
+
+```likec4
+specification {
+  deploymentNode environment { style { color gray } }
+  deploymentNode region
+  deploymentNode vm
+}
+deployment {
+  environment prod "Production" {
+    technology "OpenTofu"
+
+    region eu {
+      vm server1 {
+        app = instanceOf cloud.api       // named instance
+        instanceOf cloud.ui              // anonymous instance
+      }
+      vm server2 {
+        db = instanceOf cloud.db {
+          title "Primary DB"
+          technology "PostgreSQL 16"
+        }
+      }
+    }
+    region us {
+      vm server3 {
+        db = instanceOf cloud.db "Replica DB"
+      }
+      // Deployment-specific relation (replication)
+      server3.db -> eu.server2.db "replicates" {
+        metadata { lag "100ms"; mode "async" }
+      }
+    }
+  }
+}
+views {
+  deployment view prod_deploy {
+    title "Production"
+    include prod.**
+    style eu._ { color primary }
+    style us._ { color secondary }
+  }
+}
+```
+
+## Rank — Layout Control
+
+```likec4
+views {
+  view ranked {
+    include A, B, C, D, E, F
+
+    rank same { A, B }       // same vertical level
+    rank source { C, D }     // force to top
+    rank max { F }           // force to bottom
+  }
+}
+```
+
+## Where Predicates — Filtering
+
+```likec4
+views {
+  view filtered {
+    // By tag
+    include cloud.* where tag is #production
+
+    // By kind + negated tag
+    include cloud.* where kind is service and tag is not #deprecated
+
+    // By metadata
+    include cloud.* where metadata.region is "eu"
+
+    // Relationship filtering, including own vs endpoint metadata
+    include cloud.* -> amazon.* where source.tag is #critical
+    exclude * -> * where metadata.protocol is "http"
+    exclude * -> * where target.metadata.zone is "restricted"
+
+    // Wildcard with expansion
+    include cloud._                  // direct children only
+    include cloud.**                 // all descendants
+  }
+}
+```
+
+## Relationship Kinds & Styling
+
+```likec4
+specification {
+  relationship async { color amber; line dotted; head diamond; tail vee }
+  relationship sync  { color primary; line solid }
+}
+model {
+  api -[async]-> queue "publishes" {
+    technology "Kafka"
+    metadata { format "CloudEvents" }
+  }
+  api .sync cache "reads"             // alternative syntax: .KIND (no arrow)
+
+  // Inline style override
+  api -> db "writes" {
+    style { color red; line dashed; head odiamond }
+  }
+}
+```
+
+## Complete Mini-Project
+
+```likec4
+specification {
+  element actor   { style { shape person } }
+  element system  { style { shape rectangle } }
+  element service { style { shape component } }
+  element webapp  { style { shape browser } }
+  element db      { style { shape storage } }
+
+  tag deprecated
+  tag critical
+
+  relationship async { color amber; line dotted }
+  deploymentNode env
+  deploymentNode vm
+}
+
+model {
+  customer = actor "Customer"
+
+  cloud = system "Cloud" {
+    ui = webapp "Frontend" { icon tech:react }
+    api = service "API" {
+      #critical
+      technology "Node.js"
+      icon tech:nodejs
+    }
+    db = db "Database" {
+      icon tech:postgresql
+      description '''
+        Primary PostgreSQL database.
+        Handles all transactional data.
+      '''
+    }
+    api -> db "reads/writes"
+    ui -> api "calls" { technology "HTTPS" }
+  }
+
+  customer -> cloud.ui "browses" {
+    navigateTo user-flow
+    metadata { protocol "HTTPS" }
+  }
+}
+
+deployment {
+  env prod {
+    vm web { instanceOf cloud.ui; instanceOf cloud.api }
+    vm data { instanceOf cloud.db }
+    web -> data "internal network"
+  }
+}
+
+views {
+  view index {
+    include *
+    style cloud { color primary }
+    style customer { color green }
+  }
+
+  view backend of cloud {
+    include *
+    autoLayout LeftRight
+  }
+
+  dynamic view user-flow {
+    customer -> cloud.ui "opens app"
+    cloud.ui -> cloud.api "fetches data"
+    cloud.api -> cloud.db "queries"
+    cloud.api -> cloud.ui "returns"
+
+    style cloud { opacity 20% }
+  }
+
+  deployment view prod-deploy {
+    include prod.**
+  }
+}
+```

package/skills/likec4-dsl/references/identifier-validity.md

@@ -0,0 +1,90 @@
+# Identifier Validity (LikeC4 DSL)
+
+## Valid identifier form
+
+```
+identifier = /^[a-zA-Z_][a-zA-Z0-9_-]*$/
+```
+
+- **Starts with** letter or underscore
+- **Contains** letters, digits, hyphens, or underscores only
+- **No dots**, no spaces, no special characters
+
+## Valid examples
+
+| Valid | Why |
+|---|---|
+| `payment-api` | hyphens allowed |
+| `paymentAPI` | camelCase allowed |
+| `payment_service` | underscores allowed |
+| `service1` | digits allowed (not at start) |
+| `_internal` | underscore at start allowed |
+| `PaymentService` | PascalCase allowed |
+
+## Invalid examples
+
+| Invalid | Why | Correct form |
+|---|---|---|
+| `payment.api` | **dots are FQN separators**, not identifier chars | `payment-api` or `paymentApi` |
+| `payment api` | spaces not allowed | `payment-api` |
+| `1payment` | cannot start with digit | `payment1` |
+| `payment-` | cannot end with hyphen | `payment` |
+| `payment@api` | special chars not allowed | `payment-api` |
+
+## Critical: dots vs. hyphens
+
+**Dots are reserved for fully qualified names (FQN):**
+
+```likec4
+model {
+  cloud.backend.payment-api   // FQN: cloud (parent) -> backend (child) -> payment-api (child identifier)
+  //    ^     ^                   Dots separate hierarchy levels
+  //                 |---- hyphen used in identifier name itself
+}
+```
+
+**Correct identifier:** `payment-api` (with hyphen)  
+**Incorrect identifier:** `payment.api` (dots are FQN syntax, not part of the name)
+
+## Use in different contexts
+
+| Context | Rule | Example |
+|---|---|---|
+| **Element name** | Must be valid identifier | `service name = api "payment api"` ✓ |
+| **Tag name** | Must be valid identifier | `tag critical` ✓, `tag #critical` ✗ |
+| **Relationship kind** | Must be valid identifier | `-[async]->` ✓, `-[async-queue]->` ✓ |
+| **Kind name** | Must be valid identifier | `element service`, `deploymentNode vm` ✓ |
+| **Metadata key** | Must be valid identifier | `metadata { api_version "1.0" }` ✓ |
+| **Color name** | Must be valid identifier (or hex) | `color primary`, `color custom-blue` ✓ |
+
+## When referencing by FQN
+
+Once defined, elements are referenced using their fully qualified names (FQNs), which *do* use dots:
+
+```likec4
+model {
+  // Definition (identifier = payment-api, no dots)
+  cloud = system {
+    backend = container {
+      payment-api = service "Payment API"
+    }
+  }
+}
+
+deployment {
+  vm1 {
+    // Reference (FQN = cloud.backend.payment-api, dots for hierarchy)
+    instanceOf cloud.backend.payment-api
+  }
+}
+```
+
+## Summary
+
+| Check | Valid | Invalid |
+|---|---|---|
+| Identifier rule | `[a-zA-Z_][a-zA-Z0-9_-]*` | Contains dots, spaces, or special chars |
+| Hyphens allowed? | **Yes** in identifiers | Not dots |
+| Dots allowed? | **Only in FQNs** (for scope separation) | Never in a single identifier name |
+| `payment-api` | ✓ identifier | — |
+| `payment.api` | ✗ identifier, but valid as FQN if `payment` and `api` are nested parents/children | — |

package/skills/likec4-dsl/references/include-predicates-wildcards.md

@@ -0,0 +1,179 @@
+# Include Predicates and Wildcards in Views
+
+## Wildcard semantics
+
+LikeC4 view predicates use the wildcard `*` and the selector suffixes `parent.*`, `parent._` and `parent.**`.
+`_` and `**` exist **only** as suffixes on an element reference: bare `include **` and `exclude _` are parse errors.
+
+### `*` — immediate children and direct contains-relationships
+
+```likec4
+views {
+  view container-overview {
+    include *
+  }
+}
+```
+
+- Includes **direct children** of the scoped element (one level down).
+- Includes **direct relationships** defined at the same scope.
+- Does **not** include grandchildren or descendant chains.
+
+### `parent._` — expand (children that have relationships)
+
+```likec4
+views {
+  view connected-children {
+    include customer
+    include cloud._
+  }
+}
+```
+
+- Includes `cloud` and only those direct children of `cloud` that have relationships with visible elements; other children are omitted.
+- Same as `include cloud` + `include -> cloud.* ->`.
+- `_` is **not** a "match anything" wildcard. To exclude every visible element with a tag, use `exclude * where tag is #deprecated`.
+
+### `parent.**` — recursive descent (descendants)
+
+```likec4
+views {
+  view full-tree {
+    include cloud.**
+  }
+}
+```
+
+- Includes **all descendants** recursively (grandchildren, great-grandchildren, etc.).
+- **Not** the same as `include cloud.*` (which is immediate children only).
+- Use when you want nested hierarchies visible in a single view.
+
+## Scoped view base semantics
+
+In a **scoped view** (`view name of parent { ... }`), the `include` base set has special meaning:
+
+```likec4
+views {
+  view backend-overview of cloud.backend {
+    include *                  // Base set: cloud.backend + its immediate children
+    include -> cloud.backend   // Add: inbound relationships to the scope
+    include -> *               // Add: outbound relationships from children
+  }
+}
+```
+
+**Key facts:**
+- `include *` in a scoped view = the scoped parent + **direct children only**
+- Grandchildren inside `*` context are **not** included (you'd need `include cloud.backend.**` or explicit FQN inclusion)
+- Relationship predicates like `->` and `<->` can further expand what neighbors appear
+
+## Common filter patterns
+
+### Show a container and its components
+
+```likec4
+views {
+  view container-details of cloud.backend.api {
+    include *              // api (parent) + all components
+    include -> api         // Add external callers
+  }
+}
+```
+
+### Show descendants recursively
+
+```likec4
+views {
+  view system-tree of cloud {
+    include cloud.**       // All descendants of cloud (full tree)
+  }
+}
+```
+
+### Filter by kind
+
+```likec4
+views {
+  view services-only {
+    include * where kind is service
+    include cloud.** where kind is service  // All services at any depth inside cloud
+  }
+}
+```
+
+### Filter by tag
+
+```likec4
+views {
+  view critical-view {
+    include * where tag is #critical
+    exclude * where tag is #deprecated  // Removes deprecated elements at any depth
+  }
+}
+```
+
+## Relationship predicate expansion
+
+In scoped views, you can expand what neighboring elements appear via relationship predicates:
+
+```likec4
+views {
+  view backend-with-neighbors of cloud.backend {
+    include *                // Base: backend scope + direct children
+    include -> cloud.backend // Add: inbound edges from outside scope
+  }
+}
+```
+
+This **does not change the base set of elements**; it only **includes relationships** that end in the visible elements. Neighbors of the scope that have incoming edges *do* appear because they are needed to render those edges visually.
+
+## Wildcard `**` vs. explicit include
+
+### Using `**` (recursive)
+
+```likec4
+views {
+  view all-elements {
+    include cloud.**
+  }
+}
+```
+
+- Automatically includes all descendants.
+- Used when hierarchy depth is unknown or variable.
+
+### Using `*` + explicit FQNs
+
+```likec4
+views {
+  view two-levels {
+    include *              // Level 1
+    include cloud.*        // Level 2 under cloud
+  }
+}
+```
+
+- More explicit; requires knowing the hierarchy.
+- Useful when you want fine-grained control.
+
+## Common mistakes
+
+| Wrong | Right | Why |
+|---|---|---|
+| Bare `include **` or `exclude _` | `include cloud.**`, `exclude * where tag is #deprecated` | `**` and `_` are suffixes on an element reference, not standalone wildcards |
+| `include cloud.**` expecting only immediate children | `include cloud.*` | `**` is recursive; use `*` for one level |
+| Forgetting to add relationship filters in scoped view | `include *` + `include -> parent` | Relationships may not auto-render without explicit inclusion |
+| Assuming `include *` includes grandchildren | Use `include cloud.**` instead | `*` is immediate children only |
+
+## Summary table
+
+| Form | Matches | Scope context |
+|---|---|---|
+| `*` | Direct children + sibling relationships | One level down |
+| `parent._` | `parent` + direct children that have relationships with visible elements | One level down |
+| `parent.**` | All descendants recursively | Any depth |
+| `include -> element` | Inbound relationships to element | Shows external sources |
+| `include element ->` | Outbound relationships from element | Shows targets |
+| `include a <-> b` | Relationships between `a` and `b` in either direction | Shows symmetric dependencies |
+
+**In scoped views:** `include *` establishes a base set of the scope parent + immediate children. Relationship predicates like `->` and `<->` can bring in neighboring elements needed to render those relationships.