unyt-org · benStre · Nov 5, 2025 · Oct 16, 2025 · Oct 21, 2025 · Oct 21, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,35 +1,44 @@
-# Contributing to **DATEX Core**
+# Contributing to **DATEX Core**
 
 This document describes the workflow, branch strategy, coding standards, and
-quality gates for contributing to
-the [`datex-core`](https://github.com/unyt-org/datex-core) Rust crate.
+quality gates for contributing to the
+[`datex-core`](https://github.com/unyt-org/datex-core) Rust crate.
 
 ---
 
 ## Workflow & Branch Strategy
 
 | Purpose                        | Naming Pattern                    | Example                 |
 | ------------------------------ | --------------------------------- | ----------------------- |
-| **Permanent default branch**   | `main`                            | —                       |
+| **Permanent default branch**   | `main`                            | -                       |
 | **Milestone / release branch** | `release/<MAJOR>.<MINOR>.<PATCH>` | `release/0.0.4`         |
 | **Feature branch**             | `feature/<slug>`                  | `feature/tcp-interface` |
 | **Bug-fix branch**             | `fix/<slug>`                      | `fix/handshake-timeout` |
 | **Maintenance / chore branch** | `chore/<slug>`                    | `chore/update-deps`     |
+| **Hotfix branch**              | `hotfix/<slug>`                   | `hotfix/crash-on-start` |
 
-1. **`main` is protected** – direct pushes are disabled.
+> Use **lowercase letters** and **hyphens** (`-`) in branch names. Avoid spaces,
+> underscores (`_`), or other special characters.
+
+1. The default branch **`main` is protected** – direct pushes are disabled.
 2. **All work happens via Pull Requests (PRs).**
 3. **Target branch for every PR is the currently-active release branch** (e.g.
    `release/0.0.4`).
-4. After review & CI success, the feature branch is **squash-merged** into the
-   release branch.
+4. After review & CI success, the feature branch is **merged** into the release
+   branch.
 5. Release branches are merged back to `main` only by a maintainer at version
    cut-time.
 
+> **Do not branch from or target `main`** for new work. All development must
+> branch from the **latest release branch** (e.g., `release/0.0.4`). The `main`
+> branch reflects only published, production-ready code and is not used for
+> active development.
+
 ---
 
 ## Coding Style
 
-- **Edition:** Rust 2024.
+- **Edition:** Rust 2024.
 
 - **Formatting:**
 
@@ -45,19 +54,19 @@ the [`datex-core`](https://github.com/unyt-org/datex-core) Rust crate.
   cargo clippy --features debug
   ```
 
-  _We plan to treat all Clippy warnings as errors in the future._ Suppress a
+  _We plan to treat more Clippy warnings as errors in the future._ Suppress a
   lint only with a line-level `#[allow(lint_name)]` and an explanatory comment.
 
 - **Idioms & Practices:**
 
   - Prefer explicit `use` paths; group imports by crate.
   - Enable useful nightly lints in `#![deny(clippy::pedantic, clippy::nursery)]`
     where feasible.
-  - No `unsafe` unless unavoidable - must include a safety comment explaining
+  - No `unsafe` unless unavoidable – must include a safety comment explaining
     invariants.
   - Public items require rustdoc comments (`///`) with examples where possible.
-  - Follow **snake\_case** for variables/functions, **CamelCase** for
-    types/traits, **SCREAMING\_SNAKE\_CASE** for constants.
+  - Follow **snake_case** for variables/functions, **CamelCase** for
+    types/traits, **SCREAMING_SNAKE_CASE** for constants.
 
 ---
 
@@ -103,22 +112,24 @@ the [`datex-core`](https://github.com/unyt-org/datex-core) Rust crate.
 - Place Criterion benchmarks in `benches/`.
 - Benchmarks must compile and run (CI executes them with `--bench` but does not
   time-gate results).
-- Performance regressions > 10 % should be called out in the PR description.
+- Performance regressions > 10 % should be called out in the PR description.
 
 ---
 
 ## Continuous Integration Gates
 
 A pull request is **merge-ready** only when:
 
-1. All unit tests pass: `cargo test --all`.
-2. All integration tests pass: `cargo test --all --tests`.
+1. All unit tests pass: `cargo test --all --features debug`.
+2. All integration tests pass: `cargo test --all --tests --features debug`.
 3. All benchmarks build: `cargo bench --no-run`.
-4. Clippy passes with no errors
-5. Rustfmt check passes
+4. Clippy passes with no errors.
+5. Rustfmt check passes.
 6. Checks complete on all supported toolchains (currently stable, beta).
 
-CI will automatically block a PR that fails any step.
+> **Note:** CI pipelines are automatically triggered for all PRs targeting
+> release branches. PRs to `main` will be rejected unless explicitly opened by a
+> maintainer.
 
 ---
 
@@ -136,21 +147,55 @@ Before requesting review, ensure you have:
 
 ---
 
+## How to Make Changes & Open a PR
+
+1. **Always base your work on the latest release branch**, _not_ on `main`. The
+   `main` branch only tracks finalized releases - new development happens in the
+   currently active `release/x.y.z` branch.
+
+2. **Creating your branch:**
+
+   ```bash
+   git fetch origin
+   git checkout origin/release/<MAJOR>.<MINOR>.<PATCH> -b feature/<slug>
+   ```
+
+3. **When your feature or fix is ready:**
+
+   - Open a Pull Request (PR) targeting the same **release branch** you based
+     your work on.
+   - Select the [**"DATEX"**](https://github.com/orgs/unyt-org/projects/12)
+     project for the PR in GitHub.
+   - The **maintainers** will assign it to the appropriate **release
+     milestone**.
+
+4. If your PR cannot be merged cleanly (e.g., due to version conflicts), it may
+   be retargeted to a later release branch by maintainers.
+
+5. Once approved, your change will be **merged** into the active release branch;
+   the release branch will later be merged back into `main` during version cut.
+
+---
+
 ## Commit & PR Hygiene
 
 - Use **Conventional Commits** style (e.g. `feat: add TCP interface`,
   `fix: handle timeout`).
 - Keep commit history clean; squash or amend while the PR is open.
-- Reference issues in the PR body (e.g. `Closes #42`).
+- Reference issues in the PR body (e.g. `fix #42`).
 
 ---
 
 ## Communication
 
-- Small changes (< 30 LoC) may be approved by one maintainer; larger or
+- Small changes (< 30 LoC) may be approved by one maintainer; larger or
   architectural changes require two approvals.
-- Discuss API-breaking changes in a GitHub Issue before coding.
-- Feel free to draft a PR early (`[WIP]`) to get feedback on direction.
+- Discuss API-breaking changes in a GitHub
+  [Issue](https://github.com/unyt-org/datex-core/issues) or
+  [Discussion](https://github.com/unyt-org/datex-core/discussions) before
+  coding.
+- Feel free to draft a PR early (`[WIP]`) and mark as draft to get feedback on
+  direction.
 
 ---
 

diff --git a/Cargo.toml b/Cargo.toml
@@ -87,6 +87,7 @@ futures-core = "0.3.31"
 internment = "0.8.6"
 serde-big-array = "0.5.1"
 indoc = "2.0.6"
+pretty = "0.12.5"
 
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]

diff --git a/src/ast/grammar/assignment_operation.rs b/src/ast/grammar/assignment_operation.rs
@@ -0,0 +1,19 @@
+
+use crate::ast::DatexParserTrait;
+use crate::ast::grammar::utils::whitespace;
+use crate::ast::lexer::Token;
+use crate::ast::structs::operator::AssignmentOperator;
+use chumsky::prelude::*;
+
+pub fn assignment_operation<'a>()
+-> impl DatexParserTrait<'a, AssignmentOperator> {
+    select! {
+        Token::Assign      => AssignmentOperator::Assign,
+        Token::AddAssign   => AssignmentOperator::AddAssign,
+        Token::SubAssign   => AssignmentOperator::SubtractAssign,
+        Token::MulAssign   => AssignmentOperator::MultiplyAssign,
+        Token::DivAssign   => AssignmentOperator::DivideAssign,
+        Token::ModAssign   => AssignmentOperator::ModuloAssign,
+    }
+    .padded_by(whitespace())
+}
diff --git a/src/ast/atom.rs → src/ast/grammar/atom.rs b/src/ast/atom.rs → src/ast/grammar/atom.rs
@@ -1,9 +1,9 @@
 use crate::ast::DatexParserTrait;
-use crate::ast::decimal::decimal;
-use crate::ast::endpoint::endpoint;
-use crate::ast::integer::integer;
-use crate::ast::literal::literal;
-use crate::ast::text::text;
+use crate::ast::grammar::decimal::decimal;
+use crate::ast::grammar::endpoint::endpoint;
+use crate::ast::grammar::integer::integer;
+use crate::ast::grammar::literal::literal;
+use crate::ast::grammar::text::text;
 use chumsky::prelude::*;
 
 pub fn atom<'a>(

diff --git a/src/ast/grammar/binary_operation.rs b/src/ast/grammar/binary_operation.rs
@@ -0,0 +1,117 @@
+use crate::ast::DatexParserTrait;
+use crate::ast::grammar::utils::operation;
+use crate::ast::lexer::Token;
+use crate::ast::spanned::Spanned;
+use crate::ast::structs::expression::BinaryOperation;
+use crate::ast::structs::operator::BinaryOperator;
+use crate::ast::structs::operator::binary::ArithmeticOperator;
+use crate::ast::structs::operator::binary::BitwiseOperator;
+use crate::ast::structs::operator::binary::LogicalOperator;
+use crate::ast::{DatexExpression, DatexExpressionData};
+use chumsky::prelude::*;
+
+/// Generic helper for left-associative infix chains
+fn infix_left_chain<'a>(
+    lower: impl DatexParserTrait<'a>,
+    ops: Vec<(Token, BinaryOperator)>,
+) -> impl DatexParserTrait<'a> {
+    let base = lower.clone();
+
+    // Build a choice of operators
+    let choices = choice(
+        ops.into_iter()
+            .map(|(tok, op)| operation(tok).to(op))
+            .collect::<Vec<_>>(),
+    );
+
+    base.clone()
+        .foldl(
+            choices.then(base.clone()).repeated(),
+            move |lhs, (op, rhs)| binary_op(op)(Box::new(lhs), Box::new(rhs)),
+        )
+        .boxed()
+}
+
+fn binary_op(
+    op: BinaryOperator,
+) -> impl Fn(Box<DatexExpression>, Box<DatexExpression>) -> DatexExpression + Clone
+{
+    move |lhs, rhs| {
+        let start = lhs.span.start.min(rhs.span.start);
+        let end = lhs.span.end.max(rhs.span.end);
+        let combined_span = start..end;
+        DatexExpressionData::BinaryOperation(BinaryOperation {
+            operator: op,
+            left: lhs,
+            right: rhs,
+            r#type: None,
+        })
+        .with_span(SimpleSpan::from(combined_span))
+    }
+}
+fn product<'a>(atom: impl DatexParserTrait<'a>) -> impl DatexParserTrait<'a> {
+    infix_left_chain(
+        atom,
+        vec![
+            (Token::Star, ArithmeticOperator::Multiply.into()),
+            (Token::Slash, ArithmeticOperator::Divide.into()),
+        ],
+    )
+}
+fn power<'a>(product: impl DatexParserTrait<'a>) -> impl DatexParserTrait<'a> {
+    infix_left_chain(
+        product,
+        vec![(Token::Caret, ArithmeticOperator::Power.into())],
+    )
+}
+
+fn sum<'a>(prod: impl DatexParserTrait<'a>) -> impl DatexParserTrait<'a> {
+    infix_left_chain(
+        prod,
+        vec![
+            (Token::Plus, ArithmeticOperator::Add.into()),
+            (Token::Minus, ArithmeticOperator::Subtract.into()),
+        ],
+    )
+}
+
+fn bitwise_and<'a>(
+    sum: impl DatexParserTrait<'a>,
+) -> impl DatexParserTrait<'a> {
+    infix_left_chain(sum, vec![(Token::Ampersand, BitwiseOperator::And.into())])
+}
+
+fn bitwise_or<'a>(
+    bitwise_and: impl DatexParserTrait<'a>,
+) -> impl DatexParserTrait<'a> {
+    infix_left_chain(
+        bitwise_and,
+        vec![(Token::Pipe, BitwiseOperator::Or.into())],
+    )
+}
+
+fn logical_and<'a>(
+    bitwise_or: impl DatexParserTrait<'a>,
+) -> impl DatexParserTrait<'a> {
+    infix_left_chain(
+        bitwise_or,
+        vec![(Token::DoubleAnd, LogicalOperator::And.into())],
+    )
+}
+
+fn logical_or<'a>(
+    logical_and: impl DatexParserTrait<'a>,
+) -> impl DatexParserTrait<'a> {
+    infix_left_chain(
+        logical_and,
+        vec![(Token::DoublePipe, LogicalOperator::Or.into())],
+    )
+}
+
+pub fn binary_operation<'a>(
+    atom: impl DatexParserTrait<'a>,
+) -> impl DatexParserTrait<'a> {
+    logical_or(logical_and(bitwise_or(bitwise_and(sum(product(power(
+        atom,
+    )))))))
+}
diff --git a/src/ast/binding.rs → src/ast/grammar/binding.rs b/src/ast/binding.rs → src/ast/grammar/binding.rs
@@ -1,17 +1,20 @@
-use crate::ast::assignment_operation::{
-    AssignmentOperator, assignment_operation,
-};
 use crate::ast::error::error::ParseError;
 use crate::ast::error::pattern::Pattern;
+use crate::ast::grammar::assignment_operation::assignment_operation;
+use crate::ast::grammar::r#type::{r#type, type_declaration};
+use crate::ast::grammar::utils::whitespace;
 use crate::ast::lexer::Token;
-use crate::ast::r#type::{r#type, type_declaration};
-use crate::ast::utils::whitespace;
-use crate::ast::{DatexExpression, DatexExpressionData, DatexParserTrait, ParserRecoverExt};
+use crate::ast::spanned::Spanned;
+use crate::ast::structs::expression::VariableDeclaration;
+use crate::ast::structs::expression::{
+    DerefAssignment, VariableAssignment, VariableKind,
+};
+use crate::ast::structs::operator::assignment::AssignmentOperator;
+use crate::ast::structs::r#type::TypeExpression;
+use crate::ast::{
+    DatexExpression, DatexExpressionData, DatexParserTrait, ParserRecoverExt,
+};
 use chumsky::prelude::*;
-use datex_core::ast::tree::VariableDeclaration;
-use crate::ast::tree::{TypeExpression, VariableAssignment, VariableKind};
-
-pub type VariableId = usize;
 
 fn create_variable_declaration(
     name: String,
@@ -43,7 +46,8 @@ pub fn variable_assignment<'a>(
                 operator,
                 name: var_name.to_string(),
                 expression: Box::new(expr),
-            }).with_span(e.span())
+            })
+            .with_span(e.span())
         })
         .labelled(Pattern::Declaration)
         .as_context()
@@ -65,13 +69,15 @@ pub fn deref_assignment<'a>(
             |(
                 ((deref_count, deref_expression), operator),
                 assigned_expression,
-            ), e| {
-                DatexExpressionData::DerefAssignment {
+            ),
+             e| {
+                DatexExpressionData::DerefAssignment(DerefAssignment {
                     operator,
                     deref_count,
                     deref_expression: Box::new(deref_expression),
                     assigned_expression: Box::new(assigned_expression),
-                }.with_span(e.span())
+                })
+                .with_span(e.span())
             },
         )
         // FIXME #369 assignment instead of declaration
@@ -113,7 +119,8 @@ pub fn variable_declaration<'a>(
                 expr,
                 annotation,
                 kind,
-            ).with_span(e.span()))
+            )
+            .with_span(e.span()))
         })
         .recover_invalid()
         .labelled(Pattern::Declaration)