likec4 1.59.4 → 1.61.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"
+  }
+
+  api <- payments "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 that have relationships with the accumulated result
+    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,180 @@
+# 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.