chore: GitHub Actions CI, xtask dev ci, rustfmt parity

.cargo/config.toml

@@ -1,5 +1,7 @@
 [alias]
 xtask = "run -p xtask --"
+ci = "xtask dev ci"
+fmt-check = "xtask dev fmt-check"
 qa = "xtask dev qa"
 lint = "xtask dev lint"
 test-all = "xtask dev test"

.github/workflows/ci.yml

@@ -0,0 +1,96 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  CARGO_INCREMENTAL: 0
+
+# `tool/*` Git submodules are Cargo path dependencies. Checkout fetches them so the
+# workspace can compile; crate-specific fmt/clippy/test policy belongs in each
+# submodule repository’s own CI, not duplicated here beyond what Aura already
+# exercises through `cargo test` / `cargo clippy` on this repo.
+
+jobs:
+  fmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo xtask dev fmt-check
+
+  workspace:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            run_lint: true
+          - os: windows-latest
+            run_lint: false
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - if: matrix.run_lint
+        run: cargo xtask dev lint
+      - run: cargo xtask dev test
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo xtask docs check
+
+  llvm:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install LLVM prebuilt dependencies (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libxml2 zlib1g libzstd1 wget ca-certificates
+          # LLVM.org x86_64 Linux tarballs target Ubuntu 18.04 and link libtinfo.so.5. Ubuntu 24.04+
+          # images dropped ncurses5 packages; install Jammy's libtinfo5 .deb (same ABI family as tinfo6).
+          wget -q "http://security.ubuntu.com/ubuntu/pool/universe/n/ncurses/libtinfo5_6.3-2ubuntu0.1_amd64.deb"
+          sudo apt-get install -y ./libtinfo5_6.3-2ubuntu0.1_amd64.deb
+      - uses: Swatinem/rust-cache@v2
+      # Cache only the downloaded tarball. Caching the extracted `toolchains/llvm`
+      # tree can restore broken `toolchains/llvm/18` symlinks across runners.
+      - uses: actions/cache@v4
+        with:
+          path: toolchains/cache
+          key: llvm-18.1.8-${{ runner.os }}-${{ hashFiles('xtask/src/main.rs') }}
+      - run: cargo xtask llvm setup
+      - name: Prefer bundled LLVM shared libraries at runtime (Linux)
+        if: runner.os == 'Linux'
+        run: echo "LD_LIBRARY_PATH=${{ github.workspace }}/toolchains/llvm/18/lib:$LD_LIBRARY_PATH" >> "$GITHUB_ENV"
+      - run: cargo xtask llvm clippy
+      - run: cargo xtask llvm test

AGENTS.md

@@ -23,6 +23,8 @@ Agents should treat `docs/` as a maintained second-brain surface, not as optiona
   - `examples`
   - `tool`
 
+Repositories under `tool/` are often **Git submodules** with their **own CI** in those repos. Aura’s GitHub workflow checks out submodules only so Cargo `path` dependencies resolve; it does not replace per-repo automation there.
+
 Key entry files:
 
 - `crates/aura-frontend/src/token.rs` — token model
@@ -59,6 +61,8 @@ cargo xtask dev build
 cargo xtask dev test
 cargo xtask dev lint
 cargo xtask dev fmt
+cargo xtask dev fmt-check
+cargo xtask dev ci
 cargo xtask dev qa
 cargo xtask docs sync
 cargo xtask docs check
@@ -67,6 +71,8 @@ cargo xtask docs check
 Preferred command runner aliases (defined in `.cargo/config.toml`):
 
 ```bash
+cargo ci
+cargo fmt-check
 cargo qa
 cargo lint
 cargo test-all
@@ -77,6 +83,12 @@ cargo docs-sync
 cargo docs-check
 ```
 
+### CI parity before ending a session
+
+Before wrapping up non-trivial work (especially codegen, xtask, `docs/` generated inventories, or LLVM paths), run **`cargo xtask dev ci`** (or **`cargo ci`**) so local results match [GitHub Actions](https://github.com/nahharris/aura/actions/workflows/ci.yml): rustfmt check and `docs check` (Linux runners), workspace clippy once plus tests on Linux and Windows, then LLVM doctor, clippy, and tests (Linux and Windows).
+
+Doc-only or inventory edits still use `cargo xtask docs sync` when you change what should be generated; `dev ci` includes `docs check` so a single command catches stale generated notes before you stop.
+
 ## Xtask Usage
 
 Use `cargo xtask` for project automation and environment-sensitive routines.
@@ -90,6 +102,7 @@ Common commands:
 ```bash
 cargo xtask llvm setup
 cargo xtask llvm doctor
+cargo xtask llvm ci
 cargo xtask llvm check
 cargo xtask llvm build
 cargo xtask llvm test

README.md

@@ -2,7 +2,7 @@
 
 [![Status: Pre-Alpha](https://img.shields.io/badge/status-pre--alpha-blue)](#project-status)
 [![Rust Workspace](https://img.shields.io/badge/rust-workspace-orange?logo=rust)](#for-developers)
-[![CI](https://img.shields.io/badge/ci-not%20configured-lightgrey)](#for-developers)
+[![CI](https://github.com/nahharris/aura/actions/workflows/ci.yml/badge.svg)](https://github.com/nahharris/aura/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-TBD-lightgrey)](#project-status)
 
 > [!NOTE]

crates/aura-cli/src/main.rs

@@ -784,7 +784,7 @@ fn render_ir_pretty(module: &CheckedModule) -> String {
 
     out.push_str("## Value Types\n");
     let mut values: Vec<_> = module.value_types.iter().collect();
-    values.sort_by(|(a, _), (b, _)| a.cmp(b));
+    values.sort_by_key(|(name, _)| name.as_str());
     for (name, ty) in values {
         out.push_str(&format!("- {name}: ty#{}\n", ty.0));
     }
@@ -1009,16 +1009,21 @@ fn find_static_decl_name_span(source: &str, name: &str) -> Option<Span> {
 }
 
 fn span_from_line(source: &str, line_number: usize, column: usize, len: usize) -> Span {
-    let mut start = 0usize;
-    let mut line = 1usize;
-    for part in source.split_inclusive('\n') {
-        if line == line_number {
-            break;
+    let mut offset = 0usize;
+    for (idx, part) in source.split_inclusive('\n').enumerate() {
+        let current_line = idx + 1;
+        if current_line == line_number {
+            let start = offset + column.saturating_sub(1);
+            return Span {
+                start,
+                end: start + len.max(1),
+                line: line_number,
+                column,
+            };
         }
-        start += part.len();
-        line += 1;
+        offset += part.len();
     }
-    let start = start + column.saturating_sub(1);
+    let start = offset + column.saturating_sub(1);
     Span {
         start,
         end: start + len.max(1),