### Install Project Dependencies

Source: https://github.com/webdriverio/cddl/blob/main/CONTRIBUTING.md

Install all necessary project dependencies using pnpm.

```sh
pnpm install
```

--------------------------------

### Install CDDL Package

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/README.md

Install the CDDL package using npm.

```sh
npm install cddl
```

--------------------------------

### Install cddl2py CLI

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2py/README.md

Install the command-line interface for cddl2py using npm.

```sh
npm install cddl2py
```

--------------------------------

### Install cddl2java Package

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2java/README.md

Install the package using npm. This is a prerequisite for using the CLI or programmatic interface.

```sh
npm install cddl2java
```

--------------------------------

### Clone and Navigate Project Repository

Source: https://github.com/webdriverio/cddl/blob/main/CONTRIBUTING.md

Clone the cddl repository and navigate into the project directory to begin setup.

```sh
git clone git@github.com:webdriverio/cddl.git
cd cddl
```

--------------------------------

### Install cddl2py Programmatic API

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2py/README.md

Install the necessary packages for using the programmatic API of cddl2py.

```sh
npm install cddl cddl2py
```

--------------------------------

### Run All Validations

Source: https://github.com/webdriverio/cddl/blob/main/CONTRIBUTING.md

Execute all project validations to ensure the setup is correct and all checks are passing.

```sh
pnpm checks:all
```

--------------------------------

### Named Array Example and AST

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/arrays.md

A basic example of a named array in CDDL and its corresponding AST representation.

```cddl
basic-header = [
    field1: int,
    field2: text
]
```

```json
{
  "Type": "array",
  "Name": "basic-header",
  "Values": [
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "field1",
      "Type": ["int"],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "field2",
      "Type": ["text"],
      "Comments": []
    }
  ],
  "Comments": []
}
```

--------------------------------

### Install CDDL Packages

Source: https://github.com/webdriverio/cddl/blob/main/README.md

Install the CDDL parser/validator or the CDDL to TypeScript generator using npm.

```sh
# Parser & validator
$ npm install cddl
```

```sh
# Generate typescript definition
$ npm install cddl2ts
```

--------------------------------

### CDDL Simple Array Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Example of a 'Point3D' array containing three float values for x, y, and z coordinates.

```cddl
; An array of an integer, a string, and a float
Point3D = [ x: float, y: float, z: float ]
```

--------------------------------

### CDDL to AST Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/ast-structure.md

Demonstrates the transformation of a basic CDDL definition into its corresponding Abstract Syntax Tree (AST) representation.

```cddl
person = {
  name: tstr,
  age: uint,
  addresses: [* address],
}

address = {
  street: tstr,
  city: tstr,
}
```

```json
[
  {
    "Type": "group",
    "Name": "person",
    "IsChoiceAddition": false,
    "Properties": [
      {
        "HasCut": true,
        "Occurrence": { "n": 1, "m": 1 },
        "Name": "name",
        "Type": ["tstr"],
        "Comments": []
      },
      {
        "HasCut": true,
        "Occurrence": { "n": 1, "m": 1 },
        "Name": "age",
        "Type": ["uint"],
        "Comments": []
      },
      {
        "HasCut": true,
        "Occurrence": { "n": 1, "m": 1 },
        "Name": "addresses",
        "Type": [{
          "Type": "array",
          "Values": [{
            "HasCut": false,
            "Occurrence": { "n": 0, "m": Infinity },
            "Name": "",
            "Type": [{
              "Type": "group",
              "Value": "address",
              "Unwrapped": false
            }],
            "Comments": []
          }]
        }],
        "Comments": []
      }
    ],
    "Comments": []
  },
  {
    "Type": "group",
    "Name": "address",
    "IsChoiceAddition": false,
    "Properties": [
      {
        "HasCut": true,
        "Occurrence": { "n": 1, "m": 1 },
        "Name": "street",
        "Type": ["tstr"],
        "Comments": []
      },
      {
        "HasCut": true,
        "Occurrence": { "n": 1, "m": 1 },
        "Name": "city",
        "Type": ["tstr"],
        "Comments": []
      }
    ],
    "Comments": []
  }
]
```

--------------------------------

### CDDL Array with Group Choice Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Example of an 'Item' array where each element can be either an integer or a string.

```cddl
; An item is either an integer OR a string
Item = [ (int // tstr) ]
```

--------------------------------

### Unwrapped Array Example and AST

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/arrays.md

An example of an unwrapped array in CDDL and its AST representation, showing how elements are included directly.

```cddl
basic-header = [
    field1: int,
    field2: text
]

advanced-header = [
    ~basic-header,
    field3: bytes,
    field4: ~time
]
```

```json
{
  "Type": "array",
  "Name": "advanced-header",
  "Values": [
    {
      "HasCut": false,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "",
      "Type": [
        {
          "Type": "group",
          "Value": "basic-header",
          "Unwrapped": true
        }
      ],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "field3",
      "Type": ["bytes"],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "field4",
      "Type": [
        {
          "Type": "group",
          "Value": "time",
          "Unwrapped": true
        }
      ],
      "Comments": []
    }
  ],
  "Comments": []
}
```

--------------------------------

### CDDL Simple Value Type Choice Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Example of a variable that can be an integer or a text string.

```cddl
; MyValue can be an integer OR a text string
MyValue = int / tstr
```

--------------------------------

### Range Property Reference Examples

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/ranges.md

Illustrates how minimum and maximum values in a range can be direct numeric values or references to named values.

```json
"Min": 0,
"Max": 255
```

```json
"Min": 0,
"Max": "max-byte"
```

--------------------------------

### Install cddl2ts Package

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2ts/README.md

Install the package using npm. This command is used to add the cddl2ts package to your project dependencies.

```sh
npm install cddl2ts
```

--------------------------------

### CDDL AST Group Assignment Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/ast-structure.md

Illustrates the structure of an AST node representing a group assignment in CDDL.

```json
{
  "Type": "group",
  "Name": "person",
  "IsChoiceAddition": false,
  "Properties": [
    // Properties...
  ],
  "Comments": []
}
```

--------------------------------

### CDDL: Size Operator with Range Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/operators.md

Defines a byte string with a size constrained to a range between 1 and 63.

```cddl
label = bstr .size (1..63)
```

--------------------------------

### CDDL Literals Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Demonstrates the use of various literal values in CDDL, including exact string matches, integers, big integers, booleans, and null.

```cddl
LiteralTest = {
  ; Exact string match
  type: "widget",

  ; Exact integer match
  version: 1,

  ; Big Integers
  big_id: 9007199254740995,

  ; Null and Booleans
  is_active: true,
  deleted_at: null
}
```

--------------------------------

### CDDL: Size Operator Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/operators.md

Defines a byte string with a fixed size of 4, typically used for IPv4 addresses.

```cddl
ip4 = bstr .size 4
```

--------------------------------

### CDDL Comment Syntax Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/comments.md

Illustrates the basic syntax for comments in CDDL files, using a semicolon to denote comments that extend to the end of the line.

```cddl
; This is a comment
person = {
    name: tstr,  ; This is another comment
    age: uint
}
```

--------------------------------

### CDDL Tag Reference Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/references.md

Illustrates a CDDL definition for 'my_uri' using a tag reference. The AST representation specifies the 'NumericPart' and 'TypePart' of the tag.

```cddl
my_uri = #6.32(tstr) / tstr
```

```json
{
  "Type": "tag",
  "Value": {
    "NumericPart": 6.32,
    "TypePart": "tstr"
  },
  "Unwrapped": false
}
```

--------------------------------

### CDDL: Regular Expression Operator Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/operators.md

Defines a text string that must match a specific email address pattern.

```cddl
nai = tstr .regexp "[A-Za-z0-9]+@[A-Za-z0-9]+(\.[A-Za-z0-9]+)+"
```

--------------------------------

### Run pnpm compile command

Source: https://github.com/webdriverio/cddl/blob/main/AGENTS.md

Execute the compile command within the cloud agent environment. No preliminary 'pnpm install' is required due to pre-installed workspace dependencies.

```bash
pnpm compile
```

--------------------------------

### CDDL Range Reference Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/references.md

Shows a CDDL definition for a 'port' using a numeric range. The AST representation includes 'Min', 'Max', and 'Inclusive' properties for the range.

```cddl
port = 0..65535
```

```json
{
  "Type": "range",
  "Value": {
    "Min": 0,
    "Max": 65535,
    "Inclusive": true
  },
  "Unwrapped": false
}
```

--------------------------------

### CDDL Choices with Groups and Maps

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Example demonstrating how to use type choices to match either an explicit Map definition ('ArrayMap') or a Group definition wrapped in Map syntax ('{ DateGroup }').

```cddl
ArrayMap = { type: "array", values: [...] }
DateGroup = ( type: "date", value: tstr )

; Matches either map structure
MixedValue = (
  ArrayMap /      ; Map defined elsewhere
  { DateGroup }   ; Group wrapped in Map
)
```

--------------------------------

### CDDL Group Choice Between Sets of Fields

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Example of an 'Address' type that can be either a street address or a PO box, each with specific fields.

```cddl
; A defined group that is either a "street address" OR a "po box"
Address = (
    street: tstr,
    city: tstr
) // (
    po-box: int,
    city: tstr
)
```

--------------------------------

### CDDL Reference with Operator Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/references.md

Demonstrates a CDDL definition where an 'ip4' type is referenced with an '.and' operator. The AST shows nested 'Type' and 'Operator' structures.

```cddl
ip4 = bstr .size 4
foo = ip4 .and nai
```

```json
{
  "Type": {
    "Type": "group",
    "Value": "ip4",
    "Unwrapped": false
  },
  "Operator": {
    "Type": "and",
    "Value": {
      "Type": "group",
      "Value": "nai",
      "Unwrapped": false
    }
  }
}
```

--------------------------------

### CDDL: Default Value Operator Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/operators.md

Defines an optional text string field with a default value of 'foobar'.

```cddl
optional = tstr .default "foobar"
```

--------------------------------

### Generated TypedDict Python Code

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2py/README.md

Example of Python code generated from a CDDL schema using the default TypedDict output.

```python
from __future__ import annotations

from typing_extensions import NotRequired, TypedDict

class Person(TypedDict):
    name: str
    age: int
    nickname: NotRequired[str]
```

--------------------------------

### Run pnpm test:typechecks command

Source: https://github.com/webdriverio/cddl/blob/main/AGENTS.md

Execute the type checking tests within the cloud agent environment. No preliminary 'pnpm install' is required due to pre-installed workspace dependencies.

```bash
pnpm run test:typechecks
```

--------------------------------

### CDDL Cut Marker Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/properties.md

Illustrates the use of a cut marker (/) in CDDL syntax, which signifies that a property should be matched exactly once. The AST representation shows `HasCut: true`.

```cddl
person = {
    name: tstr,
    / age: uint,
}
```

```json
{
  "HasCut": true,
  "Occurrence": { "n": 1, "m": 1 },
  "Name": "age",
  "Type": ["uint"],
  "Comments": []
}
```

--------------------------------

### CDDL Mixing Choices in Maps

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Example of a 'Response' type that can be one of two distinct map structures: one for success ('ok') and one for errors.

```cddl
Response = {
    "status" => "ok",
    "data" => tstr
} / {
    "status" => "error",
    "code" => int,
    "message" => tstr
}
```

--------------------------------

### Parse CDDL File and Get AST

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/README.md

Instantiate the parser with a CDDL file path and then parse the file to obtain the AST. The resulting AST can be used for generating other formats.

```typescript
import Parser from '../src/parser.js'

// Create a new parser instance with the path to a CDDL file
const parser = new Parser('./example.cddl')

// Parse the file and get the AST
const ast = parser.parse()

// Now you can work with the AST to generate other formats
console.log(JSON.stringify(ast, null, 2))
```

--------------------------------

### CDDL Type Choice Inside an Array

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Example of an array where elements can be of different types, specifically an integer or a float for the first element.

```cddl
; An array where the first element is either an int OR a float
MyArray = [ int / float, tstr ]
```

--------------------------------

### CDDL Group with Default Operators

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/operators.md

This example demonstrates applying default operators to various properties within a group. It includes string, enumerated literal, range, and boolean types, each with a default value.

```cddl
someGroup = {
  optional: tstr .default "foobar" ?,
  orientation: ("portrait" / "landscape") .default "portrait" ?,
  scale: (0.1..2) .default 1 ?,
  shrinkToFit: bool .default true ?
}
```

--------------------------------

### CDDL Literal Value Reference Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/references.md

Shows a CDDL definition for a 'status' with multiple literal string values. The AST representation lists each literal under 'PropertyType'.

```cddl
status = "active" / "inactive" / "suspended"
```

```json
{
  "Type": "variable",
  "Name": "status",
  "IsChoiceAddition": false,
  "PropertyType": [
    {
      "Type": "literal",
      "Value": "active",
      "Unwrapped": false
    },
    {
      "Type": "literal",
      "Value": "inactive",
      "Unwrapped": false
    },
    {
      "Type": "literal",
      "Value": "suspended",
      "Unwrapped": false
    }
  ],
  "Comments": []
}
```

--------------------------------

### CDDL Array with Element Choices

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/arrays.md

Defines an array where elements can be of different types, specified using the '/' (choice) operator. This example allows elements to be either integers or floats.

```cddl
points = [* (int / float)]
```

```json
{
  "Type": "array",
  "Name": "points",
  "Values": [
    {
      "HasCut": false,
      "Occurrence": { "n": 0, "m": Infinity },
      "Name": "",
      "Type": [
        "int",
        "float"
      ],
      "Comments": []
    }
  ],
  "Comments": []
}
```

--------------------------------

### Generated Pydantic Python Code

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2py/README.md

Example of Python code generated from a CDDL schema using the --pydantic flag for Pydantic BaseModel output.

```python
from __future__ import annotations

from typing import Optional
from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int
    nickname: Optional[str] = None
```

--------------------------------

### CDDL Unwrapped Group Reference Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/references.md

Demonstrates a CDDL definition where a 'basic-header' group is included in 'advanced-header' with unwrapping. The AST shows 'Unwrapped: true' for the 'basic-header' reference.

```cddl
basic-header = [
    field1: int,
    field2: text
]

advanced-header = [
    ~basic-header,
    field3: bytes
]
```

```json
{
  "Type": "group",
  "Value": "basic-header",
  "Unwrapped": true
}
```

--------------------------------

### CDDL Array Element Reference Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/references.md

Illustrates a CDDL definition for a 'people' array, where each element is a reference to the 'person' group. The AST shows 'Type: array' with 'person' as a value.

```cddl
people = [* person]
```

```json
{
  "Type": "array",
  "Name": "people",
  "Values": [
    {
      "HasCut": false,
      "Occurrence": { "n": 0, "m": Infinity },
      "Name": "",
      "Type": [
        {
          "Type": "group",
          "Value": "person",
          "Unwrapped": false
        }
      ],
      "Comments": []
    }
  ],
  "Comments": []
}
```

--------------------------------

### AST Representation: Property-Level Operator (Default)

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/operators.md

Shows the AST structure for a property-level operator, using a default value for an 'orientation' property as an example. The 'Operator' field is part of the property definition.

```json
{
  "HasCut": true,
  "Name": "orientation",
  "Type": [...],
  "Operator": {
    "Type": "default",
    "Value": {...}
  }
}
```

--------------------------------

### CDDL Logical Operator: AND

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/operators.md

The .and operator combines two constraints, requiring a value to satisfy both. This example shows combining an IP address type with a Network Access Identifier type.

```cddl
foo = ip4 .and nai
```

--------------------------------

### CDDL AST Node Types: Group, Array, Variable

Source: https://context7.com/webdriverio/cddl/llms.txt

Examples demonstrating the structure of `Group`, `Array`, and `Variable` AST nodes. These nodes represent different CDDL constructs and share common fields like `Name`, `Comments`, and `IsChoiceAddition`.

```typescript
import type { Group, Array as CDDLArray, Variable, Assignment } from 'cddl'

// Group node (curly-brace struct)
const groupNode: Group = {
    Type: 'group',
    Name: 'address',
    IsChoiceAddition: false,
    Properties: [
        { HasCut: true, Occurrence: { n: 1, m: 1 }, Name: 'street', Type: ['tstr'], Comments: [] },
        { HasCut: true, Occurrence: { n: 1, m: 1 }, Name: 'city',   Type: ['tstr'], Comments: [] },
    ],
    Comments: [],
}

// Array node (square-bracket ordered list)
const arrayNode: CDDLArray = {
    Type: 'array',
    Name: 'unlimited-people',
    Values: [
        {
            HasCut: false,
            Occurrence: { n: 0, m: Infinity },
            Name: '',
            Type: [{ Type: 'group', Value: 'person', Unwrapped: false }],
            Comments: [],
        },
    ],
    Comments: [],
}

// Variable node (type alias / choice)
const variableNode: Variable = {
    Type: 'variable',
    Name: 'attire',
    IsChoiceAddition: false,
    PropertyType: [
        { Type: 'literal', Value: 'bow tie',        Unwrapped: false },
        { Type: 'literal', Value: 'necktie',         Unwrapped: false },
        { Type: 'literal', Value: 'Internet attire', Unwrapped: false },
    ],
    Comments: [],
}
```

--------------------------------

### Show CLI Help

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2py/README.md

Display the help message for the cddl2py command-line interface.

```sh
npx cddl2py --help
```

--------------------------------

### CDDL Type Choice Inside a Map Property

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Example of a map property where the value can be an integer or null.

```cddl
; The "score" property can be an integer OR null
MyMap = {
    "score" => int / null
}
```

--------------------------------

### Run cddl2java CLI

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2java/README.md

Use the CLI to convert a CDDL file to Java classes. Specify the input CDDL file path and the output directory.

```sh
npx cddl2java ./path/to/interface.cddl ./outputDir
```

--------------------------------

### CDDL Group Choice Usage in Maps

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Example of a 'UserProfile' map that must contain either a 'username' or an 'email' field, alongside a mandatory 'id'.

```cddl
; A user profile must have either a "username" OR an "email" (but not necessarily both, depending on other rules)
UserProfile = {
    id: int,
    (
        username: tstr
    ) // (
        email: tstr
    )
}
```

--------------------------------

### Generate TypedDict Output via CLI

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2py/README.md

Use the npx command to run cddl2py and redirect the generated TypedDict Python code to a file.

```sh
npx cddl2py ./path/to/schema.cddl > ./types.py
```

--------------------------------

### Generate Pydantic Models via CLI

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2py/README.md

Use the npx command with the --pydantic flag to generate Pydantic BaseModel Python code and redirect it to a file.

```sh
npx cddl2py --pydantic ./path/to/schema.cddl > ./models.py
```

--------------------------------

### Define Port Range Type in CDDL

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/ranges.md

Use ranges to define the start and end of a port number. This is useful for specifying valid port number boundaries.

```cddl
port-range = {
  start: 0..65535,
  end: 0..65535
}
```

--------------------------------

### AST Representation of Port Range

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/ranges.md

The Abstract Syntax Tree (AST) representation shows how a CDDL range definition is structured, including min, max, and inclusivity.

```json
{
  "Type": "group",
  "Name": "port-range",
  "IsChoiceAddition": false,
  "Properties": [
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "start",
      "Type": [
        {
          "Type": "range",
          "Value": {
            "Min": 0,
            "Max": 65535,
            "Inclusive": true
          },
          "Unwrapped": false
        }
      ],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "end",
      "Type": [
        {
          "Type": "range",
          "Value": {
            "Min": 0,
            "Max": 65535,
            "Inclusive": true
          },
          "Unwrapped": false
        }
      ],
      "Comments": []
    }
  ],
  "Comments": []
}
```

--------------------------------

### Parse CDDL Ranges to AST

Source: https://context7.com/webdriverio/cddl/llms.txt

Parses a CDDL schema and identifies range definitions within the Abstract Syntax Tree (AST). Ensure the `cddl` package is installed.

```cddl
; schema.cddl
byte      = 0..255
js-int    = -9007199254740991..9007199254740991
exclusive = 0...256
named-max = 0..max-byte
```

```ts
import { parse, isVariable, isPropertyReference } from 'cddl'

const ast = parse('./schema.cddl')

for (const node of ast) {
    if (!isVariable(node)) continue
    const types = Array.isArray(node.PropertyType) ? node.PropertyType : [node.PropertyType]
    for (const t of types) {
        if (isPropertyReference(t) && (t as any).Type === 'range') {
            const { Min, Max, Inclusive } = (t as any).Value
            console.log(`${node.Name}: ${Min} ${Inclusive ? '..' : '...'} ${Max}`)
            // byte:   0 .. 255
            // js-int: -9007199254740991 .. 9007199254740991
            // exclusive: 0 ... 256
        }
    }
}
```

--------------------------------

### CDDL Property Choice

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/groups.md

Illustrates defining a choice between properties within a CDDL group using the `/` operator. This is represented as an array of properties in the AST.

```cddl
delivery = {
  street: tstr,
  (city: city // po-box: uint)
}
```

--------------------------------

### Property with Leading Comment and AST

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/properties.md

Demonstrates a property 'employer' with a preceding comment in CDDL. The AST includes the comment content and indicates it's a leading comment.

```cddl
person = {
    ; a good employer
    employer: tstr
}
```

```json
{
  "HasCut": true,
  "Occurrence": { "n": 1, "m": 1 },
  "Name": "employer",
  "Type": ["tstr"],
  "Comments": [
    {
      "Type": "comment",
      "Content": "a good employer",
      "Leading": false
    }
  ]
}
```

--------------------------------

### CDDL Group Composition with Reference

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/references.md

Shows how a 'person' group is composed into an 'employee' group using a reference. The AST for 'employee' includes a property representing the 'person' group reference.

```cddl
person = {
    name: tstr,
    age: uint
}

employee = {
    person,
    employeeId: uint,
    department: tstr
}
```

```json
{
  "Type": "group",
  "Name": "employee",
  "IsChoiceAddition": false,
  "Properties": [
    {
      "HasCut": false,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "",
      "Type": [
        {
          "Type": "group",
          "Value": "person",
          "Unwrapped": false
        }
      ],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "employeeId",
      "Type": ["uint"],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "department",
      "Type": ["tstr"],
      "Comments": []
    }
  ],
  "Comments": []
}
```

--------------------------------

### AST Representation of Person Type

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/basic-types.md

Shows the Abstract Syntax Tree (AST) representation for the 'person' CDDL type. This illustrates how CDDL constructs are translated into a structured format, detailing properties, types, and occurrences.

```json
{
  "Type": "group",
  "Name": "person",
  "IsChoiceAddition": false,
  "Properties": [
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "name",
      "Type": ["tstr"],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "age",
      "Type": ["uint"],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "is-active",
      "Type": ["bool"],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "tags",
      "Type": [{
        "Type": "array",
        "Values": [{
          "HasCut": false,
          "Occurrence": { "n": 0, "m": Infinity },
          "Name": "",
          "Type": ["tstr"],
          "Comments": []
        }]
      }],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "status",
      "Type": [
        {
          "Type": "literal",
          "Value": "active",
          "Unwrapped": false
        },
        {
          "Type": "literal",
          "Value": "inactive",
          "Unwrapped": false
        },
        {
          "Type": "literal",
          "Value": "suspended",
          "Unwrapped": false
        }
      ],
      "Comments": []
    }
  ],
  "Comments": []
}
```

--------------------------------

### CDDL Groups as Maps Syntax

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/cddl-cheatsheet.md

Shows how to wrap a Group definition in curly braces to treat it as a standalone Map.

```cddl
; A reusable Group of fields
DateFields = ( year: int, month: int, day: int )

; 1. Mix it into a Map
Appointment = {
  description: tstr,
  DateFields
}

; 2. Standalone Map
DateObject = { DateFields }
```

--------------------------------

### CDDL Named Group Reference Example

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/references.md

Illustrates a CDDL definition for a 'person' object referencing an 'address' group. The AST representation shows 'Type' as 'group' and 'Value' as 'address'.

```cddl
person = {
    address: address
}

address = {
    street: tstr,
    city: tstr
}
```

```json
{
  "Type": "group",
  "Value": "address",
  "Unwrapped": false
}
```

--------------------------------

### Parse CDDL file to AST with `parse()`

Source: https://context7.com/webdriverio/cddl/llms.txt

Use the `parse()` function to read a `.cddl` file and convert it into an Abstract Syntax Tree (AST). The AST represents top-level definitions like Groups, Arrays, or Variables.

```typescript
import { parse } from 'cddl'

// schema.cddl:
// person = {
//   name: tstr,
//   age: uint,
//   ?nickname: tstr,
//   status: "active" / "inactive",
// }
const ast = parse('./schema.cddl')

console.log(JSON.stringify(ast, null, 2))
// [
//   {
//     "Type": "group",
//     "Name": "person",
//     "IsChoiceAddition": false,
//     "Properties": [
//       { "HasCut": true, "Occurrence": { "n": 1, "m": 1 }, "Name": "name",     "Type": ["tstr"],   "Comments": [] },
//       { "HasCut": true, "Occurrence": { "n": 1, "m": 1 }, "Name": "age",      "Type": ["uint"],   "Comments": [] },
//       { "HasCut": true, "Occurrence": { "n": 0, "m": null },"Name": "nickname","Type": ["tstr"],   "Comments": [] },
//       { "HasCut": true, "Occurrence": { "n": 1, "m": 1 }, "Name": "status",
//         "Type": [
//           { "Type": "literal", "Value": "active",   "Unwrapped": false },
//           { "Type": "literal", "Value": "inactive", "Unwrapped": false }
//         ],
//         "Comments": [] }
//     ],
//     "Comments": []
//   }
// ]
```

--------------------------------

### Transform CDDL to TypeScript via CLI

Source: https://github.com/webdriverio/cddl/blob/main/README.md

Use the `cddl2ts` CLI to convert a CDDL file into a TypeScript definition file.

```sh
npx cddl2ts ./path/to/interface.cddl &> ./path/to/interface.ts
```

--------------------------------

### Validate CDDL File with CLI

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/README.md

Use the `cddl` CLI to validate the format of a CDDL file.

```sh
npx cddl validate ./path/to/interface.cddl
✅ Valid CDDL file!
```

--------------------------------

### CDDL Range Syntax

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/ranges.md

Shows the CDDL syntax for defining inclusive ranges with '..' and exclusive ranges with '...'.

```cddl
byte = 0..255
byte1 = 0...first-non-byte
```

--------------------------------

### Programmatic CDDL to Java Transformation

Source: https://context7.com/webdriverio/cddl/llms.txt

Use the `transform` function from the `cddl2java` package to parse a CDDL file and generate a directory tree of Java source files. This is particularly useful for the WebDriver BiDi specification, converting groups with a `method` property into command-dispatch methods and other groups into data classes.

```typescript
import { transform } from 'cddl2java'

// Generates ./out/
//   Session/SessionModule.java        – BiDi command methods
//   Session/CapabilityRequest.java    – parameter class with constructor + getters + asMap()
//   Session/NewResult.java            – result class
//   EmptyResult.java
//   ContextValue.java
//   AccessibilityValue.java
await transform('./webdriver/local.cddl', './out')
```

--------------------------------

### CDDL Operators in AST Representation

Source: https://context7.com/webdriverio/cddl/llms.txt

CDDL control operators are captured in the AST as 'Operator' objects with 'Type' and 'Value' fields. This example shows the AST representation for various operators applied to different types.

```cddl
; schema.cddl
ip4          = bstr .size 4
label        = bstr .size (1..63)
nai          = tstr .regexp "[A-Za-z0-9]+@[A-Za-z0-9]+(\.[A-Za-z0-9]+)+"
speed        = number .ge 0
display-step = number .default 1
```

```typescript
import { parse } from 'cddl'

const ast = parse('./schema.cddl')

// ip4  →  { Type: 'bstr', Operator: { Type: 'size', Value: { Type: 'literal', Value: 4, Unwrapped: false } } }
// label → { Type: 'bstr', Operator: { Type: 'size', Value: { Type: 'range', Value: { Min: 1, Max: 63, Inclusive: true }, Unwrapped: false } } }
// nai  →  { Type: 'tstr', Operator: { Type: 'regexp', Value: { Type: 'literal', Value: '[A-Za-z0-9]+@...', Unwrapped: false } } }
// speed → { Type: { Type: 'group', Value: 'number', Unwrapped: false }, Operator: { Type: 'ge', Value: { Type: 'literal', Value: 0, Unwrapped: false } } }
console.log(JSON.stringify(ast[0], null, 2))
```

--------------------------------

### CDDL Definition of Person Type

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/basic-types.md

Defines a 'person' type with various basic data types including string, integer, boolean, an array of strings, and a choice of string literals. This serves as a foundational example for CDDL type definitions.

```cddl
person = {
  name: tstr,
  age: uint,
  is-active: bool,
  tags: [* tstr],
  status: "active" / "inactive" / "suspended"
}
```

--------------------------------

### parse(filePath) — Parse a CDDL file into an AST

Source: https://context7.com/webdriverio/cddl/llms.txt

Reads a .cddl file from disk, runs the full lexer/parser pipeline, and returns an Assignment[] array representing every top-level definition in the file. Each element is a Group, Array, or Variable node.

```APIDOC
## `parse(filePath)` — Parse a CDDL file into an AST

Reads a `.cddl` file from disk, runs the full lexer/parser pipeline, and returns an `Assignment[]` array representing every top-level definition in the file. Each element is a `Group`, `Array`, or `Variable` node.

```ts
import { parse } from 'cddl'

// schema.cddl:
// person = {
//   name: tstr,
//   age: uint,
//   ?nickname: tstr,
//   status: "active" / "inactive",
// }
const ast = parse('./schema.cddl')

console.log(JSON.stringify(ast, null, 2))
// [
//   {
//     "Type": "group",
//     "Name": "person",
//     "IsChoiceAddition": false,
//     "Properties": [
//       { "HasCut": true, "Occurrence": { "n": 1, "m": 1 }, "Name": "name",     "Type": ["tstr"],   "Comments": [] },
//       { "HasCut": true, "Occurrence": { "n": 1, "m": 1 }, "Name": "age",      "Type": ["uint"],   "Comments": [] },
//       { "HasCut": true, "Occurrence": { "n": 0, "m": null },"Name": "nickname","Type": ["tstr"],   "Comments": [] },
//       { "HasCut": true, "Occurrence": { "n": 1, "m": 1 }, "Name": "status",
//         "Type": [
//           { "Type": "literal", "Value": "active",   "Unwrapped": false },
//           { "Type": "literal", "Value": "inactive", "Unwrapped": false }
//         ],
//         "Comments": [] }
//     ],
//     "Comments": []
//   }
// ]
```
```

--------------------------------

### Programmatic Interface for CDDL to TypeScript Transformation

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl2ts/README.md

Utilize the programmatic interface to parse a CDDL file and transform its Abstract Syntax Tree (AST) into a TypeScript definition string. This example demonstrates converting a CDDL specification with snake_case field casing.

```js
import { parse, transform } from 'cddl'

/**
 * spec.cddl:
 *
 * session.CapabilityRequest = {
 *   ?acceptInsecureCerts: bool,
 *   ?browserName: text,
 *   ?browserVersion: text,
 *   ?platformName: text,
 * };
 */
const ast = parse('./spec.cddl')
const ts = transform(ast, { fieldCase: 'snake' })
console.log(ts)
/**
 * outputs:
 *
 * interface SessionCapabilityRequest {
 *   accept_insecure_certs?: boolean,
 *   browser_name?: string,
 *   browser_version?: string,
 *   platform_name?: string,
 * }
 */
```

--------------------------------

### Parse CDDL to AST Programmatically

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/README.md

Use the `parse` function from the `cddl` package to convert a CDDL file into an Abstract Syntax Tree (AST). The output structure represents the defined data types.

```js
import { parse } from 'cddl'

const ast = parse('./spec.cddl')
console.log(ast)
/**
 * outputs:
 * [
 *   {
 *     Type: 'group',
 *     Name: 'person',
 *     Properties: [ [Object], [Object] ],
 *     IsChoiceAddition: false
 *   }
 * ]
 */
```

--------------------------------

### CDDL Variable Comments and AST

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/comments.md

Illustrates how a leading comment can be attached to a CDDL variable definition and its corresponding AST structure.

```cddl
; unit: m/s
speed = number .ge 0
```

```json
{
  "Type": "variable",
  "Name": "speed",
  "IsChoiceAddition": false,
  "PropertyType": [
    {
      "Type": {
        "Type": "group",
        "Value": "number",
        "Unwrapped": false
      },
      "Operator": {
        "Type": "ge",
        "Value": {
          "Type": "literal",
          "Value": 0,
          "Unwrapped": false
        }
      }
    }
  ],
  "Comments": [
    {
      "Type": "comment",
      "Content": "unit: m/s",
      "Leading": false
    }
  ]
}
```

--------------------------------

### CLI CDDL to Java Generation

Source: https://context7.com/webdriverio/cddl/llms.txt

Generate Java classes from CDDL files using the `cddl2java` CLI tool. The output directory is created automatically, and existing files are overwritten. The generated file tree mirrors the CDDL module namespaces.

```bash
# Generate Java classes into ./java-out/
npx cddl2java ./webdriver/local.cddl ./java-out

# The output directory is created automatically; existing files are overwritten.
# The generated file tree mirrors the CDDL module namespaces:
#   java-out/Session/SessionModule.java
#   java-out/Session/CapabilityRequest.java
#   java-out/BrowsingContext/BrowsingContextModule.java
#   ...

```

--------------------------------

### CDDL to TypeScript CLI

Source: https://context7.com/webdriverio/cddl/llms.txt

Generates TypeScript from the terminal by reading a CDDL file and writing to stdout. Supports `--field-case` and `--unknown-as-any` flags.

```sh
# Emit camelCase TypeScript (default)
npx cddl2ts ./webdriver/local.cddl > ./types/local.ts
```

```sh
# Emit snake_case field names
npx cddl2ts ./webdriver/local.cddl --field-case snake > ./types/local.ts
```

```sh
# Treat any/unknown as `any` (default is `unknown` when --unknown-as-any is omitted)
npx cddl2ts ./webdriver/remote.cddl --unknown-as-any > ./types/remote.ts
```

--------------------------------

### AST Representation of an Optional CDDL Property

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/properties.md

Shows the Abstract Syntax Tree (AST) for an optional CDDL property named 'optional' with a default string value. This structure helps in programmatically understanding CDDL definitions.

```json
{
  "HasCut": true,
  "Occurrence": { "n": 0, "m": Infinity },
  "Name": "optional",
  "Type": [
    {
      "Type": "tstr",
      "Operator": {
        "Type": "default",
        "Value": {
          "Type": "literal",
          "Value": "foobar",
          "Unwrapped": false
        }
      }
    }
  ],
  "Comments": []
}
```

--------------------------------

### Sign Commits with Developer Certificate of Origin

Source: https://github.com/webdriverio/cddl/blob/main/CONTRIBUTING.md

Sign your commits using the '-s' flag to agree to the Developer Certificate of Origin (DCO) version 1.1. This is a mandatory step for all contributions.

```sh
git commit -s -m "adding X to change Y"
```

--------------------------------

### CDDL Named Group Definition and AST

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/groups.md

Illustrates the definition of a named group in CDDL and its corresponding Abstract Syntax Tree (AST) representation. The AST shows the group's properties and their types.

```cddl
person = {
    name: tstr,
    age: uint
}
```

```json
{
  "Type": "group",
  "Name": "person",
  "IsChoiceAddition": false,
  "Properties": [
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "name",
      "Type": ["tstr"],
      "Comments": []
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "age",
      "Type": ["uint"],
      "Comments": []
    }
  ],
  "Comments": []
}
```

--------------------------------

### CDDL Variable Choice Additions

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/variables.md

Demonstrates extending existing CDDL variable choices using the `/=` operator, indicated by `IsChoiceAddition: true` in the AST.

```cddl
attire = "bow tie" / "necktie" / "Internet attire"
attire /= "swimwear"
```

```json
{
  "Type": "variable",
  "Name": "attire",
  "IsChoiceAddition": true,
  "PropertyType": [
    {
      "Type": "literal",
      "Value": "swimwear",
      "Unwrapped": false
    }
  ],
  "Comments": []
}
```

--------------------------------

### AST Representation of Property Choice

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/groups.md

Shows the JSON AST structure for a CDDL group with a property choice, where the choices are represented as an array within the `Properties` array.

```json
{
  "Type": "group",
  "Name": "delivery",
  "IsChoiceAddition": false,
  "Properties": [
    {
      "HasCut": true,
      "Name": "street",
      "Occurrence": { "n": 1, "m": 1 },
      "Type": ["tstr"],
      "Comments": []
    },
    [
      {
        "HasCut": false,
        "Name": "",
        "Occurrence": { "n": 1, "m": 1 },
        "Type": {
          "Type": "group",
          "Value": "city",
          "Unwrapped": false
        },
        "Comments": []
      },
      {
        "HasCut": true,
        "Name": "po-box",
        "Occurrence": { "n": 1, "m": 1 },
        "Type": ["uint"],
        "Comments": []
      }
    ]
  ],
  "Comments": []
}
```

--------------------------------

### CDDL Array Comments and AST

Source: https://github.com/webdriverio/cddl/blob/main/packages/cddl/docs/comments.md

Demonstrates how comments can be associated with elements within a CDDL array definition and their representation in the AST.

```cddl
Geography = [
    ; a city
    city: tstr,
    ; some coordinates
    gpsCoordinates: GpsCoordinates
]
```

```json
{
  "Type": "array",
  "Name": "Geography",
  "Values": [
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "city",
      "Type": ["tstr"],
      "Comments": [
        {
          "Type": "comment",
          "Content": "a city",
          "Leading": false
        }
      ]
    },
    {
      "HasCut": true,
      "Occurrence": { "n": 1, "m": 1 },
      "Name": "gpsCoordinates",
      "Type": [{
        "Type": "group",
        "Value": "GpsCoordinates",
        "Unwrapped": false
      }],
      "Comments": [
        {
          "Type": "comment",
          "Content": "some coordinates",
          "Leading": false
        }
      ]
    }
  ],
  "Comments": []
}
```