Initial release

.emmyrc.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://raw.githubusercontent.com/EmmyLuaLs/emmylua-analyzer-rust/refs/heads/main/crates/emmylua_code_analysis/resources/schema.json",
+  "runtime": {
+    "version": "LuaJIT"
+  },
+  "workspace": {
+    "userThirdParty": [
+      "/Users/demiller/git/lua-addons"
+    ],
+    "library": [
+    ],
+    "useGitIgnore": false,
+    "ignoreDir": [
+      ".claude",
+      ".git",
+      ".idea",
+      ".venv",
+      "build",
+      "dist",
+      "node_modules"
+    ]
+  },
+  "diagnostics": {
+    "disable": [
+      "unnecessary-assert"
+    ]
+  }
+}

.github/workflows/build.yml

@@ -0,0 +1,122 @@
+name: Lua Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    name: Check
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Lua
+        uses: leafo/gh-actions-lua@v11
+        with:
+          luaVersion: '5.4'
+
+      - name: Setup LuaRocks
+        uses: leafo/gh-actions-luarocks@v5
+        with:
+          luarocksVersion: "3.12.2"
+
+      - name: Install luacheck
+        run: luarocks install luacheck
+
+      - name: Install stylua
+        uses: JohnnyMorganz/stylua-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          version: v2.1.0
+          args: false # Will be run as part of `make check`
+
+      - name: Check
+        run: make check
+
+  test:
+    needs: check
+    runs-on: ubuntu-latest
+    continue-on-error: false
+    strategy:
+      fail-fast: true
+      matrix:
+        lua-version: ['5.1', '5.2', '5.3', '5.4', 'luajit-2.0', 'luajit-2.1']
+
+    name: Lua ${{ matrix.lua-version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Lua
+        uses: leafo/gh-actions-lua@v11
+        with:
+          luaVersion: ${{ matrix.lua-version }}
+
+      - name: Setup tests
+        run: |
+          # Set the correct binary name based on the Lua version
+          if [[ "${{ matrix.lua-version }}" == luajit* ]]; then
+            LUA_BINARY=luajit
+          else
+            LUA_BINARY=lua
+          fi
+
+          echo "LUA_BINARY=$LUA_BINARY" >> "$GITHUB_ENV"
+          ${LUA_BINARY} -v
+
+      - name: Run tests
+        run: |
+          make test-all
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    name: Build Combined Module
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Lua
+        uses: leafo/gh-actions-lua@v11
+        with:
+          luaVersion: '5.4'
+
+      - name: Setup LuaRocks
+        uses: leafo/gh-actions-luarocks@v5
+        with:
+          luarocksVersion: "3.12.2"
+
+      - name: Install amalg
+        run: luarocks install amalg
+
+      - name: Build combined module
+        run: make build
+
+      - name: Verify build
+        run: |
+          # Check default build
+          if [ -f "build/bitn.lua" ]; then
+            echo "✅ build/bitn.lua exists ($(wc -c < "build/bitn.lua") bytes)"
+            # Quick sanity check - make sure it contains expected content
+            if grep -q "bitn" build/bitn.lua; then
+              echo "✅ Build contains expected content"
+            else
+              echo "❌ Build seems corrupted"
+              exit 1
+            fi
+          else
+            echo "❌ build/bitn.lua missing"
+            exit 1
+          fi
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: bitn.lua
+          path: build/bitn.lua
+          retention-days: 30

.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Lua
+        uses: leafo/gh-actions-lua@v11
+        with:
+          luaVersion: '5.4'
+
+      - name: Setup LuaRocks
+        uses: leafo/gh-actions-luarocks@v5
+        with:
+          luarocksVersion: "3.12.2"
+
+      - name: Install amalg
+        run: luarocks install amalg
+
+      - name: Build combined module
+        run: |
+          # The make build command will automatically inject the version from the git tag
+          make build
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-beta') || contains(github.ref_name, '-alpha') }}
+          name: Release ${{ github.ref_name }}
+          tag_name: ${{ github.ref }}
+          generate_release_notes: true
+          files: |
+            build/bitn.lua

.gitignore

@@ -0,0 +1,43 @@
+# Compiled Lua sources
+luac.out
+
+# luarocks build files
+*.src.rock
+*.zip
+*.tar.gz
+
+# Object files
+*.o
+*.os
+*.ko
+*.obj
+*.elf
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Libraries
+*.lib
+*.a
+*.la
+*.lo
+*.def
+*.exp
+
+# Shared objects (inc. Windows DLLs)
+*.dll
+*.so
+*.so.*
+*.dylib
+
+# Executables
+*.exe
+*.out
+*.app
+*.i*86
+*.x86_64
+*.hex
+
+# Build artifacts
+build/

.luacheckrc

@@ -0,0 +1,12 @@
+std = "min"
+globals = {
+ unpack = {}
+}
+ignore = {
+  "212/_.*",
+  "211/_.*",
+  "213/_.*",
+}
+compat = true
+unused_args = false
+max_line_length = false

CLAUDE.md

@@ -0,0 +1,110 @@
+# lua-bitn Development Guide
+
+## Project Structure
+
+```
+lua-bitn/
+├── src/bitn/
+│   ├── init.lua      # Module aggregator, exports bit16/bit32/bit64
+│   ├── bit16.lua     # 16-bit bitwise operations
+│   ├── bit32.lua     # 32-bit bitwise operations
+│   └── bit64.lua     # 64-bit bitwise operations (uses {high, low} pairs)
+├── tests/
+│   ├── test_bit16.lua    # 16-bit test vectors
+│   ├── test_bit32.lua    # 32-bit test vectors
+│   └── test_bit64.lua    # 64-bit test vectors
+├── .github/workflows/
+│   ├── build.yml     # CI: lint, test matrix, build
+│   └── release.yml   # Release automation
+├── run_tests.sh      # Main test runner
+├── run_tests_matrix.sh   # Multi-version test runner
+└── Makefile          # Build automation
+```
+
+## Key Commands
+
+```bash
+# Run tests
+make test
+
+# Run specific module tests
+make test-bit32
+
+# Run across Lua versions
+make test-matrix
+
+# Format code
+make format
+
+# Lint code
+make lint
+
+# Build single-file distribution
+make build
+```
+
+## Architecture
+
+### Module Design
+
+Each bit module (bit16, bit32, bit64) provides the same API:
+- Bitwise: band, bor, bxor, bnot
+- Shifts: lshift, rshift, arshift
+- Rotates: rol, ror
+- Arithmetic: add, mask
+- Byte conversions: uN_to_be_bytes, uN_to_le_bytes, be_bytes_to_uN, le_bytes_to_uN
+
+### 64-bit Representation
+
+64-bit values use `{high, low}` pairs for Lua 5.1 compatibility:
+```lua
+-- 0x123456789ABCDEF0 represented as:
+local value = {0x12345678, 0x9ABCDEF0}
+```
+
+### Pure Lua Implementation
+
+All operations are implemented using basic Lua arithmetic to ensure
+compatibility across all Lua versions without native bit library dependencies.
+
+## Testing
+
+Tests use Lua table-based vectors for easy maintenance:
+
+```lua
+local test_vectors = {
+  { name = "band(0xFF, 0x0F)", fn = bit32.band, inputs = {0xFF, 0x0F}, expected = 0x0F },
+  -- ...
+}
+```
+
+Run with: `./run_tests.sh` or `make test`
+
+## Building
+
+The build process uses `amalg` to create a single-file distribution:
+
+```bash
+make build
+# Output: build/bitn.lua
+```
+
+Version is automatically injected from git tags during release.
+
+## CI/CD
+
+- **build.yml**: Runs on push/PR to main
+  - Format check with stylua
+  - Lint with luacheck
+  - Test matrix (Lua 5.1-5.4, LuaJIT 2.0/2.1)
+  - Build single-file distribution
+
+- **release.yml**: Runs on version tags (v*)
+  - Builds and publishes release with bitn.lua artifact
+
+## Code Style
+
+- 2-space indentation
+- 120 column width
+- Double quotes preferred
+- LuaDoc annotations for all public functions