Introduce _compat module and add benchmarking infrastructure

CLAUDE.md

@@ -6,9 +6,13 @@
 lua-bitn/
 ├── src/bitn/
 │   ├── init.lua      # Module aggregator, exports bit16/bit32/bit64
+│   ├── _compat.lua   # Internal compatibility layer, feature detection
 │   ├── bit16.lua     # 16-bit bitwise operations
 │   ├── bit32.lua     # 32-bit bitwise operations
-│   └── bit64.lua     # 64-bit bitwise operations (uses {high, low} pairs)
+│   ├── bit64.lua     # 64-bit bitwise operations (uses {high, low} pairs)
+│   └── utils/
+│       ├── init.lua      # Utils module aggregator
+│       └── benchmark.lua # Benchmarking utilities
 ├── tests/
 │   ├── test_bit16.lua    # 16-bit test vectors
 │   ├── test_bit32.lua    # 32-bit test vectors
@@ -18,6 +22,7 @@ lua-bitn/
 │   └── release.yml   # Release automation
 ├── run_tests.sh      # Main test runner
 ├── run_tests_matrix.sh   # Multi-version test runner
+├── run_benchmarks.sh # Benchmark runner
 └── Makefile          # Build automation
 ```
 
@@ -33,6 +38,12 @@ make test-bit32
 # Run across Lua versions
 make test-matrix
 
+# Run benchmarks
+make bench
+
+# Run specific module benchmark
+make bench-bit32
+
 # Format code
 make format
 
@@ -62,10 +73,16 @@ Each bit module (bit16, bit32, bit64) provides the same API:
 local value = {0x12345678, 0x9ABCDEF0}
 ```
 
-### Pure Lua Implementation
+### Compatibility Layer (_compat)
+
+The `_compat` module provides automatic feature detection and optimized primitives:
+- **Lua 5.3+**: Uses native bitwise operators (`&`, `|`, `~`, `<<`, `>>`)
+- **Lua 5.2**: Uses built-in `bit32` library
+- **LuaJIT**: Uses `bit` library with signed-to-unsigned conversion
+- **Lua 5.1**: Falls back to pure Lua arithmetic implementation
 
-All operations are implemented using basic Lua arithmetic to ensure
-compatibility across all Lua versions without native bit library dependencies.
+This ensures optimal performance on modern Lua while maintaining compatibility
+with older versions.
 
 ## Testing
 
@@ -80,6 +97,29 @@ local test_vectors = {
 
 Run with: `./run_tests.sh` or `make test`
 
+## Benchmarking
+
+Each module includes a `benchmark()` function that measures performance of all
+operations. Benchmarks use the `bitn.utils.benchmark` module for consistent
+timing and output formatting.
+
+```bash
+# Run all benchmarks (uses LuaJIT by default for best performance)
+./run_benchmarks.sh or `make bench`
+
+# Run with specific Lua version
+LUA_BINARY=lua5.4 ./run_benchmarks.sh
+
+# Run specific module
+./run_benchmarks.sh bit32
+make bench-bit64
+```
+
+The benchmark utility performs:
+- 3 warmup iterations before timing
+- Configurable iteration count (default: 100, modules use 10000)
+- Reports ms/op and ops/sec metrics
+
 ## Building
 
 The build process uses `amalg` to create a single-file distribution:

Makefile

@@ -1,6 +1,9 @@
 # Luarocks path for amalg and other tools
 LUAROCKS_PATH := $(shell luarocks path --lr-path 2>/dev/null)
 
+# Lua path for local modules (src, vendor)
+LUA_PATH_LOCAL := ./?.lua;./?/init.lua;./src/?.lua;./src/?/init.lua;./vendor/?.lua;$(LUAROCKS_PATH)
+
 # Default target
 .PHONY: all
 all: format lint test build
@@ -25,11 +28,31 @@ test-matrix-%:
 test-%:
 	./run_tests.sh $*
 
+# Run benchmarks
+.PHONY: bench
+bench:
+	./run_benchmarks.sh
+
+# Run bench matrix
+.PHONY: bench-matrix
+bench-matrix:
+	./run_benchmarks_matrix.sh
+
+# Run specific bench suite for bench matrix
+.PHONY: bench-matrix-%
+bench-matrix-%:
+	./run_benchmarks_matrix.sh $*
+
+# Run specific benchmark suite
+.PHONY: bench-%
+bench-%:
+	./run_benchmarks.sh $*
+
 build/amalg.cache: src/bitn/init.lua
 	@echo "Generating amalgamation cache..."
 	@mkdir -p build
 	@if command -v amalg.lua >/dev/null 2>&1; then \
-		LUA_PATH="./?.lua;./?/init.lua;./src/?.lua;./src/?/init.lua;$(LUAROCKS_PATH)" lua -lamalg src/bitn/init.lua && mv amalg.cache build || exit 1; \
+		LUA_PATH="$(LUA_PATH_LOCAL)" lua -lamalg src/bitn/init.lua && mv amalg.cache build || exit 1; \
 		echo "Generated amalg.cache"; \
 	else \
 		echo "Error: amalg not found."; \
@@ -43,7 +66,7 @@ build/amalg.cache: src/bitn/init.lua
 build: build/amalg.cache
 	@echo "Building single-file distribution..."
 	@if command -v amalg.lua >/dev/null 2>&1; then \
-		LUA_PATH="./?.lua;./?/init.lua;./src/?.lua;./src/?/init.lua;$(LUAROCKS_PATH)" amalg.lua -o build/bitn.lua -C ./build/amalg.cache || exit 1;\
+		LUA_PATH="$(LUA_PATH_LOCAL)" amalg.lua -o build/bitn.lua -C ./build/amalg.cache || exit 1;\
 		echo "Built build/bitn.lua"; \
 		VERSION=$$(git describe --exact-match --tags 2>/dev/null || echo "dev"); \
 		if [ "$$VERSION" != "dev" ]; then \
@@ -144,20 +167,28 @@ help:
 	@echo "Lua bitN Library - Makefile targets"
 	@echo ""
 	@echo "Testing:"
-	@echo "  make test              - Run all tests"
-	@echo "  make test-<name>       - Run specific test (e.g., make test-bit32)"
-	@echo "  make test-matrix       - Run test matrix across Lua versions"
+	@echo "  make test               - Run all tests"
+	@echo "  make test-<name>        - Run specific test (e.g., make test-bit32)"
+	@echo "  make test-matrix        - Run tests across all Lua versions"
+	@echo "  make test-matrix-<name> - Run specific test across all Lua versions"
+	@echo ""
+	@echo "Benchmarking:"
+	@echo "  make bench               - Run all benchmarks"
+	@echo "  make bench-<name>        - Run specific benchmark (e.g., make bench-bit32)"
+	@echo "  make bench-matrix        - Run benchmarks across all Lua versions"
+	@echo "  make bench-matrix-<name> - Run specific benchmark across all Lua versions"
 	@echo ""
 	@echo "Building:"
-	@echo "  make build             - Build single-file distribution"
+	@echo "  make build              - Build single-file distribution"
 	@echo ""
 	@echo "Code Quality:"
-	@echo "  make format            - Format all code (Lua)"
-	@echo "  make format-check      - Check code formatting"
-	@echo "  make lint              - Lint code with luacheck"
+	@echo "  make check              - Run format-check and lint"
+	@echo "  make format             - Format code with stylua"
+	@echo "  make format-check       - Check code formatting"
+	@echo "  make lint               - Lint code with luacheck"
 	@echo ""
 	@echo "Setup:"
-	@echo "  make install-deps      - Install all development dependencies"
-	@echo "  make clean             - Remove generated files"
+	@echo "  make install-deps       - Install development dependencies"
+	@echo "  make clean              - Remove generated files"
 	@echo ""
-	@echo "  make help              - Show this help"
+	@echo "  make help               - Show this help"

README.md

@@ -1,13 +1,14 @@
 # lua-bitn
 
-A pure Lua implementation of bitwise operations for 16-bit, 32-bit, and 64-bit
-integers with **zero external dependencies**. This library provides a complete,
-portable implementation that runs on Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT.
+A portable bitwise operations library for 16-bit, 32-bit, and 64-bit integers
+with **zero external dependencies**. This library provides a complete,
+cross-platform implementation that runs on Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT.
 
 ## Features
 
-- **Zero Dependencies**: Pure Lua implementation, no C extensions or external
-  libraries required
+- **Zero Dependencies**: No C extensions or external libraries required
+- **Automatic Optimization**: Uses native bit operations when available (Lua 5.2+
+  bit32 library, Lua 5.3+ operators, LuaJIT bit library) with pure Lua fallback
 - **Portable**: Runs on any Lua interpreter (5.1+)
 - **Complete**: Full bitwise operations API for 16-bit, 32-bit, and 64-bit integers
 - **Byte Conversions**: Big-endian and little-endian byte string conversions
@@ -68,27 +69,64 @@ local xored = bit64.bxor(
 
 Example: `0x123456789ABCDEF0` is represented as `{0x12345678, 0x9ABCDEF0}`
 
-## Testing
+## Development
 
-Run the test suite:
+### Setup
 
 ```bash
-# Run all tests with default Lua interpreter
-./run_tests.sh
+# Install development dependencies (stylua, luacheck, amalg)
+make install-deps
+```
+
+### Testing
 
-# Run with specific Lua version
+```bash
+make test                # Run all tests
+make test-bit32          # Run specific module tests
+make test-matrix         # Run tests across all Lua versions
+make test-matrix-bit32   # Run specific module across all Lua versions
+
+# Or use scripts directly with custom Lua binary
 LUA_BINARY=lua5.1 ./run_tests.sh
+```
+
+### Benchmarking
+
+```bash
+make bench               # Run all benchmarks
+make bench-bit32         # Run specific module benchmark
+make bench-matrix        # Run benchmarks across all Lua versions
+make bench-matrix-bit64  # Run specific module across all Lua versions
+
+# Or use scripts directly with custom Lua binary
+LUA_BINARY=lua5.4 ./run_benchmarks.sh
+```
 
-# Run specific module
-./run_tests.sh bit32
+### Code Quality
 
-# Run test matrix across all Lua versions
-./run_tests_matrix.sh
+```bash
+make check               # Run format check and lint
+make format              # Format code with stylua
+make format-check        # Check formatting without modifying
+make lint                # Run luacheck
+```
+
+### Building
+
+```bash
+make build               # Build single-file distribution (build/bitn.lua)
+make clean               # Remove generated files
+```
+
+### Help
+
+```bash
+make help                # Show all available targets
 ```
 
 ## Current Limitations
 
-- Pure Lua performance is slower than native bit libraries
+- Pure Lua fallback (Lua 5.1 without LuaJIT) is slower than native bit libraries
 - No constant-time guarantees
 
 ## License