caffeine_lang/frontend/ast · caffeine_lang

Assumes

The Assumes: section of an expectation. Holds dependency lines.

pub type Assumes {
  Assumes(
    deps: List(Dependency),
    trailing_comments: List(Comment),
  )
}

Constructors

Assumes(deps: List(Dependency), trailing_comments: List(Comment))

Comment

</>

A comment attached to an AST node.

pub type Comment {
  LineComment(text: String)
  SectionComment(text: String)
  DocComment(text: String)
}

Constructors

```
LineComment(text: String)
```
```
SectionComment(text: String)
```
```
DocComment(text: String)
```
A ###-prefixed doc comment. When attached to an ExpectItem’s leading_comments, the text becomes the SLO description in the Datadog Terraform output.

Dependency

</>

A single hard|soft dependency on "<target>" line inside Assumes.

pub type Dependency {
  Dependency(
    kind: DependencyKind,
    target: String,
    leading_comments: List(Comment),
  )
}

Constructors

Dependency(
  kind: DependencyKind,
  target: String,
  leading_comments: List(Comment),
)

A duration literal value attached to over/below clauses. Mirrors ast.LiteralDuration so the parser can plug the same token into these fixed-position clauses without going through full literal parsing.

pub type DurationLiteral {
  DurationLiteral(amount: Float, unit: String)
}

Constructors

DurationLiteral(amount: Float, unit: String)

ExpectItem

</>

A single expectation item. Each item stands alone (no enclosing Expectations measured by "X" group).

An expectation has an optional Assumes: section listing dependencies and a required Guarantees ... clause carrying threshold, window, optional latency, and an optional as measured by ... with: {...} reference.

pub type ExpectItem {
  ExpectItem(
    name: String,
    extends: List(String),
    assumes: option.Option(Assumes),
    guarantees: Guarantees,
    leading_comments: List(Comment),
  )
}

Constructors

ExpectItem(
  name: String,
  extends: List(String),
  assumes: option.Option(Assumes),
  guarantees: Guarantees,
  leading_comments: List(Comment),
)

ExpectationType

</>

The two surfaced SLO shapes a measurement can declare. Mirrors the CQL resolver’s GoodOverTotal / TimeSlice discriminant, but on the user-visible surface so dependency-edge alignment can be enforced.

pub type ExpectationType {
  SuccessRateType
  TimeSliceType
}

Constructors

```
SuccessRateType
```
```
TimeSliceType
```

ExpectsFile

</>

An expects file containing extendables and standalone expectation items. The phantom phase parameter tracks whether the file has been validated.

pub type ExpectsFile(phase) {
  ExpectsFile(
    extendables: List(Extendable),
    items: List(ExpectItem),
    trailing_comments: List(Comment),
  )
}

Constructors

ExpectsFile(
  extendables: List(Extendable),
  items: List(ExpectItem),
  trailing_comments: List(Comment),
)

Extendable

</>

An extendable block that can be inherited by measurements or expectations.

pub type Extendable {
  Extendable(
    name: String,
    kind: ExtendableKind,
    body: Struct,
    leading_comments: List(Comment),
  )
}

Constructors

Extendable(
  name: String,
  kind: ExtendableKind,
  body: Struct,
  leading_comments: List(Comment),
)

ExtendableKind

</>

The kind of extendable (Requires for measurement types, Provides for literal-valued field bundles — merged into measurement Provides {} or expectation with: {...} depending on context).

pub type ExtendableKind {
  ExtendableRequires
  ExtendableProvides
}

Constructors

```
ExtendableRequires
```
```
ExtendableProvides
```

Field

</>

A field with a name and value (either a type or a literal).

pub type Field {
  Field(
    name: String,
    value: Value,
    leading_comments: List(Comment),
  )
}

Constructors

Field(
  name: String,
  value: Value,
  leading_comments: List(Comment),
)

Guarantees

</>

The Guarantees N% [below D] over D window [as measured by "X" with: {...}] clause.

pub type Guarantees {
  Guarantees(
    threshold: Float,
    below: option.Option(DurationLiteral),
    window: DurationLiteral,
    measured_by: option.Option(MeasuredBy),
  )
}

Constructors

Guarantees(
  threshold: Float,
  below: option.Option(DurationLiteral),
  window: DurationLiteral,
  measured_by: option.Option(MeasuredBy),
)

Literal

</>

Literal values.

pub type Literal {
  LiteralString(value: String)
  LiteralInteger(value: Int)
  LiteralFloat(value: Float)
  LiteralPercentage(value: Float)
  LiteralDuration(amount: Float, unit: String)
  LiteralTrue
  LiteralFalse
  LiteralList(elements: List(Literal))
  LiteralStruct(
    fields: List(Field),
    trailing_comments: List(Comment),
  )
}

Constructors

```
LiteralString(value: String)
```
```
LiteralInteger(value: Int)
```
```
LiteralFloat(value: Float)
```
```
LiteralPercentage(value: Float)
```
```
LiteralDuration(amount: Float, unit: String)
```
unit is the raw suffix as written (one of “ms”, “s”, “m”, “h”, “d”) so the formatter can round-trip the source.
```
LiteralTrue
```
```
LiteralFalse
```
```
LiteralList(elements: List(Literal))
```

LiteralStruct(
  fields: List(Field),
  trailing_comments: List(Comment),
)

MeasuredBy

</>

The as measured by "X" with: {...} tail of a Guarantees clause.

pub type MeasuredBy {
  MeasuredBy(measurement: String, with_args: Struct)
}

Constructors

MeasuredBy(measurement: String, with_args: Struct)

MeasurementItem

</>

A single measurement item with name, extends, requires, and provides.

expectation_type carries the declared SLO shape from a header like "name" success_rate: or "name" time_slice:. When None, the type is inferred from the evaluation formula shape at codegen time (legacy behavior).

pub type MeasurementItem {
  MeasurementItem(
    name: String,
    expectation_type: option.Option(ExpectationType),
    extends: List(String),
    requires: Struct,
    provides: Struct,
    leading_comments: List(Comment),
  )
}

Constructors

MeasurementItem(
  name: String,
  expectation_type: option.Option(ExpectationType),
  extends: List(String),
  requires: Struct,
  provides: Struct,
  leading_comments: List(Comment),
)

MeasurementsFile

</>

A measurements file containing type aliases, extendables, and measurement items. Type aliases must come before extendables, which must come before items. The phantom phase parameter tracks whether the file has been validated.

pub type MeasurementsFile(phase) {
  MeasurementsFile(
    type_aliases: List(TypeAlias),
    extendables: List(Extendable),
    items: List(MeasurementItem),
    trailing_comments: List(Comment),
  )
}

Constructors

MeasurementsFile(
  type_aliases: List(TypeAlias),
  extendables: List(Extendable),
  items: List(MeasurementItem),
  trailing_comments: List(Comment),
)

Parsed

</>

Marker type for parsed (not yet validated) AST.

pub type Parsed

Struct

</>

A struct containing a list of fields.

pub type Struct {
  Struct(fields: List(Field), trailing_comments: List(Comment))
}

Constructors

Struct(fields: List(Field), trailing_comments: List(Comment))

TypeAlias

</>

A type alias that defines a named, reusable refined type. Example: _env (Type): String { x | x in { prod, staging, dev } }

pub type TypeAlias {
  TypeAlias(
    name: String,
    type_: types.ParsedType,
    leading_comments: List(Comment),
  )
}

Constructors

TypeAlias(
  name: String,
  type_: types.ParsedType,
  leading_comments: List(Comment),
)

Validated

</>

Marker type for validated AST.

pub type Validated

Value

</>

A value in a field - either a type (in Requires) or a literal (in Provides).

pub type Value {
  TypeValue(type_: types.ParsedType)
  LiteralValue(literal: Literal)
}

Constructors

```
TypeValue(type_: types.ParsedType)
```
```
LiteralValue(literal: Literal)
```