mmobeus-luadata 0.1.7__tar.gz

mmobeus_luadata-0.1.7/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [mmobeus]

mmobeus_luadata-0.1.7/.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+updates:
+  # Go modules
+  - package-ecosystem: 'gomod'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+      day: 'monday'
+      time: '09:00'
+    open-pull-requests-limit: 5
+    labels:
+      - 'dependencies'
+      - 'go'
+    commit-message:
+      prefix: 'chore'
+      include: 'scope'
+
+  # GitHub Actions
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+      day: 'monday'
+      time: '09:00'
+    open-pull-requests-limit: 5
+    labels:
+      - 'dependencies'
+      - 'ci/cd'
+    commit-message:
+      prefix: 'ci'
+      include: 'scope'

mmobeus_luadata-0.1.7/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  rust:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+      - name: Clippy
+        run: cargo clippy --workspace -- -D warnings
+
+      - name: Test core library
+        run: cargo test -p luadata
+
+      - name: Check Python module
+        run: cargo check -p luadata_python
+
+      - name: Check WASM module
+        run: cargo check -p luadata-wasm
+
+      - name: Build CLI
+        run: cargo build -p luadata_cli --release
+
+      - name: Validate testdata
+        run: |
+          ./target/release/luadata validate testdata/valid/simple.lua
+          ./target/release/luadata validate testdata/valid/array.lua
+          ./target/release/luadata validate testdata/valid/nested.lua
+          ./target/release/luadata validate testdata/valid/comments.lua
+
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: actions/setup-go@v6.3.0
+        with:
+          go-version-file: go/go.mod
+
+      - name: Build Rust cdylib
+        run: |
+          cargo build -p luadata_clib --release
+          mkdir -p bin/clib
+          cp target/release/libluadata_clib.so bin/clib/libluadata.so
+
+      - name: Test Go wrapper
+        run: |
+          LUADATA_LIB_PATH=${{ github.workspace }}/bin/clib/libluadata.so \
+            go test -C go -v ./...

mmobeus_luadata-0.1.7/.github/workflows/pages.yml

@@ -0,0 +1,42 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: actions/setup-go@v6.3.0
+        with:
+          go-version-file: web/docs/gen/go.mod
+
+      - name: Install wasm-pack
+        run: cargo install wasm-pack
+
+      - name: Build site
+        run: make build-site SITE_VERSION=${{ github.ref_name }}
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: bin/web
+
+      - id: deployment
+        uses: actions/deploy-pages@v4

mmobeus_luadata-0.1.7/.github/workflows/release.yml

@@ -0,0 +1,311 @@
+name: Release
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+on:
+  push:
+    tags:
+      - "v*-rc.*"
+
+jobs:
+  build-clib:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            runner: ubuntu-latest
+            platform: linux_amd64
+            lib_name: libluadata_clib.so
+          - target: aarch64-unknown-linux-gnu
+            runner: ubuntu-24.04-arm
+            platform: linux_arm64
+            lib_name: libluadata_clib.so
+          - target: x86_64-apple-darwin
+            runner: macos-15-intel
+            platform: darwin_amd64
+            lib_name: libluadata_clib.dylib
+          - target: aarch64-apple-darwin
+            runner: macos-latest
+            platform: darwin_arm64
+            lib_name: libluadata_clib.dylib
+          - target: x86_64-pc-windows-msvc
+            runner: windows-latest
+            platform: windows_amd64
+            lib_name: luadata_clib.dll
+
+    runs-on: ${{ matrix.runner }}
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Build cdylib
+        run: cargo build -p luadata_clib --release --target ${{ matrix.target }}
+
+      - name: Upload shared library
+        uses: actions/upload-artifact@v4
+        with:
+          name: clib-${{ matrix.platform }}
+          path: target/${{ matrix.target }}/release/${{ matrix.lib_name }}
+
+  test-and-release:
+    needs: build-clib
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      release_tag: ${{ steps.release_tag.outputs.tag }}
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: actions/setup-go@v6.3.0
+        with:
+          go-version-file: go/go.mod
+
+      - name: Test Rust
+        run: cargo test -p luadata
+
+      - name: Download all shared libraries
+        uses: actions/download-artifact@v4
+        with:
+          pattern: clib-*
+          path: clib-artifacts
+
+      - name: Test Go wrapper
+        run: |
+          LUADATA_LIB_PATH=${{ github.workspace }}/clib-artifacts/clib-linux_amd64/libluadata_clib.so \
+            go test -C go -v ./...
+
+      - name: Compute release tag
+        id: release_tag
+        run: |
+          RC_TAG="${{ github.ref_name }}"
+          RELEASE_TAG="${RC_TAG%%-rc.*}"
+          echo "tag=${RELEASE_TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Prepare release branch and tag
+        run: bash scripts/prepare-release.sh "${{ steps.release_tag.outputs.tag }}" clib-artifacts
+
+      - name: Rename artifacts with platform
+        run: |
+          for dir in clib-artifacts/clib-*; do
+            platform="${dir##*clib-}"
+            for file in "$dir"/*; do
+              base="$(basename "$file")"
+              name="${base%.*}"
+              ext="${base##*.}"
+              mv "$file" "$dir/${name}-${platform}.${ext}"
+            done
+          done
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ steps.release_tag.outputs.tag }}" \
+            --title "${{ steps.release_tag.outputs.tag }}" \
+            --generate-notes \
+            clib-artifacts/clib-*/*
+
+  build-python-wheels:
+    needs: test-and-release
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            maturin_args: ""
+          - runner: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-gnu
+            maturin_args: ""
+          - runner: macos-15-intel
+            target: x86_64-apple-darwin
+            maturin_args: ""
+          - runner: macos-latest
+            target: aarch64-apple-darwin
+            maturin_args: ""
+          - runner: windows-latest
+            target: x86_64-pc-windows-msvc
+            maturin_args: ""
+
+    runs-on: ${{ matrix.runner }}
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          ref: ${{ needs.test-and-release.outputs.release_tag }}
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install maturin
+        run: pip install maturin
+
+      - name: Build wheel
+        run: |
+          cd python
+          maturin build --release --target ${{ matrix.target }} --out ../wheels/ ${{ matrix.maturin_args }}
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-wheel-${{ matrix.target }}
+          path: wheels/*.whl
+
+  build-python-sdist:
+    needs: test-and-release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          ref: ${{ needs.test-and-release.outputs.release_tag }}
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out wheels/ -m python/Cargo.toml
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-sdist
+          path: wheels/*.tar.gz
+
+  publish-python:
+    needs: [build-python-wheels, build-python-sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: pypi
+
+    steps:
+      - name: Download all wheels and sdist
+        uses: actions/download-artifact@v4
+        with:
+          pattern: python-*
+          path: dist
+          merge-multiple: true
+
+      - name: List packages
+        run: ls -la dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  publish-npm:
+    needs: test-and-release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment: npm
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          ref: ${{ needs.test-and-release.outputs.release_tag }}
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+
+      - name: Install wasm-pack
+        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Build WASM into npm package
+        run: |
+          wasm-pack build wasm --target bundler --out-dir ../npm/wasm
+          rm -f npm/wasm/package.json npm/wasm/.gitignore
+
+      - name: Publish to npm
+        working-directory: npm
+        run: npm publish --access public
+
+  publish-crates:
+    needs: test-and-release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment: crates-io
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          ref: ${{ needs.test-and-release.outputs.release_tag }}
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Authenticate with crates.io
+        id: auth
+        uses: rust-lang/crates-io-auth-action@v1
+
+      - name: Publish to crates.io
+        run: cargo publish -p luadata
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
+
+  bump-main-version:
+    needs: test-and-release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          ref: main
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Bump version files
+        run: |
+          TAG="${{ needs.test-and-release.outputs.release_tag }}"
+          VERSION="${TAG#v}"
+          sed -i "s/^version = \".*\"/version = \"${VERSION}\"/" Cargo.toml
+          sed -i "s/\"version\": \".*\"/\"version\": \"${VERSION}\"/" npm/package.json
+          cargo generate-lockfile
+          echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
+
+      - name: Create PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          BRANCH="version-bump/v${VERSION}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add Cargo.toml npm/package.json Cargo.lock
+          git commit -m "Bump version to ${VERSION} after release"
+          git push origin "$BRANCH"
+          gh pr create \
+            --base main \
+            --head "$BRANCH" \
+            --title "Bump version to ${VERSION}" \
+            --body "Automated version bump after release of v${VERSION}."

mmobeus_luadata-0.1.7/.gitignore

@@ -0,0 +1,9 @@
+# Build outputs
+bin/
+target/
+wheels/
+.venv/
+.claude
+
+# wasm-pack output inside npm package (built at release time)
+npm/wasm/

mmobeus_luadata-0.1.7/.golangci.yml

@@ -0,0 +1,6 @@
+version: "2"
+
+formatters:
+  enable:
+    - gofumpt
+    - goimports

mmobeus_luadata-0.1.7/AGENTS.md

@@ -0,0 +1,17 @@
+# Agents
+
+## Building
+
+- **Always use Make targets** (`make build`, `make build-clib`, etc.) instead of running `cargo build` or `go build` directly.
+- All build outputs go under `bin/` (`bin/cli/` for the CLI, `bin/clib/` for the shared library, `bin/web/` for WASM + static assets).
+- The Rust workspace root is `Cargo.toml`. Crates: `luadata` (core lib in `src/`), `clib/`, `cli/`, `python/`, `wasm/`.
+- The Go wrapper lives in `go/` with its own `go.mod` (`github.com/mmobeus/luadata/go`).
+- For local Go development, run `make build-clib` first, then set `LUADATA_LIB_PATH` to `bin/clib/libluadata.dylib` (or `.so`).
+- `go/lib/` is gitignored — shared libraries are embedded only at release time via CI.
+- To verify compilation only: `cargo check --workspace` for Rust, `go build ./...` (from `go/` dir) for Go.
+
+## Testing
+
+- `make test-rust` — runs Rust core library tests
+- `make test-go` — builds cdylib, then runs Go wrapper tests with it
+- `make test` — runs both

mmobeus_luadata-0.1.7/ARCHITECTURE.md

@@ -0,0 +1,180 @@
+# Architecture
+
+luadata is a Lua data parser written in Rust, with bindings for Go, Python,
+WebAssembly, and a standalone CLI. This document describes the architecture and
+the reasoning behind it.
+
+## Overview
+
+```
+Rust core library (src/)
+├── cdylib (clib/)          → C shared library (.so/.dylib/.dll)
+│   └── exports: LuaDataToJSON, LuaDataFree
+├── PyO3 module (python/)   → native Python extension
+├── wasm-bindgen (wasm/)    → WebAssembly module (~124KB)
+└── CLI binary (cli/)       → luadata tojson / validate
+
+Go wrapper (go/)
+├── Uses purego to load the Rust cdylib at runtime (no CGO)
+├── Embeds platform-specific shared libs via go:embed + build tags
+└── Exposes TextToJSON, FileToJSON, ToJSON, ReaderToJSON
+```
+
+All language bindings share the same Rust parser — there is exactly one
+implementation of the lexer, parser, and JSON converter.
+
+## Why Rust as source of truth
+
+Before the rewrite, luadata was a pure Go library. Go served the core use case
+well, but adding Python and WebAssembly support exposed limitations:
+
+- **WASM size**: Go's WASM binary was ~3.2MB (runtime overhead). The Rust WASM
+  module is ~124KB — roughly 25x smaller.
+- **Python integration**: The Go approach required building a CGO shared library
+  and loading it via ctypes, with manual JSON-envelope marshalling. Rust/PyO3
+  compiles directly to a native Python extension with native types.
+- **Single parser**: Maintaining one parser instead of porting logic across
+  languages eliminates behavioral drift between platforms.
+- **Go compatibility**: The main objection to Rust was that Go consumers would
+  need CGO. With [purego](https://github.com/ebitengine/purego), Go loads the
+  Rust shared library at runtime with `CGO_ENABLED=0` — no C toolchain required.
+
+## Repository structure
+
+```
+luadata/
+├── src/                    Rust core library
+│   ├── lib.rs              Module exports
+│   ├── lexer.rs            Hand-written character-by-character lexer
+│   ├── parser.rs           Recursive descent parser
+│   ├── converter.rs        Lua → JSON conversion
+│   ├── options.rs          ParseConfig, ArrayMode, EmptyTableMode, StringTransform
+│   └── types.rs            Key, Value, KeyValuePairs, RawValue, RawKey
+├── cli/                    CLI binary (clap)
+│   └── src/main.rs         tojson + validate subcommands
+├── clib/                   C shared library (cdylib)
+│   └── src/lib.rs          LuaDataToJSON / LuaDataFree FFI exports
+├── python/                 PyO3 Python module
+│   ├── src/lib.rs          lua_to_json / lua_to_dict
+│   ├── pyproject.toml      Package: mmobeus-luadata
+│   └── tests/              pytest suite
+├── wasm/                   wasm-bindgen module
+│   └── src/lib.rs          convertLuaDataToJson (JS name)
+├── npm/                    npm package (mmobeus-luadata)
+│   ├── package.json        Package metadata
+│   ├── index.js            ES module wrapper: init() + convert()
+│   ├── index.d.ts          TypeScript type definitions
+│   └── wasm/               (built at release time, gitignored)
+├── go/                     Pure Go wrapper (no CGO)
+│   ├── luadata.go          Public API: TextToJSON, FileToJSON, etc.
+│   ├── options.go          Functional options: WithArrayMode, etc.
+│   ├── luadata_test.go     Go test suite
+│   └── internal/ffi/       purego FFI bridge
+│       ├── ffi.go          Call(), init, library loading
+│       ├── ffi_unix.go     purego.Dlopen (darwin/linux)
+│       ├── ffi_windows.go  syscall.LoadLibrary
+│       └── embed_dev.go    Empty embed (dev); replaced on release branch
+├── web/                    Browser interface
+│   ├── index.html          Live converter UI
+│   ├── luadata.js          ES module wrapper: init() + convert()
+│   ├── app.js              UI logic
+│   └── docs/gen/           "Luadata by Example" generator
+├── testdata/               Shared test fixtures
+│   ├── valid/              .lua files that must parse
+│   └── invalid/            .lua files that must fail
+├── scripts/
+│   ├── release.sh          Tag RC on main
+│   ├── prepare-release.sh  Stage libs + generate embeds on release branch
+│   └── validate-folder.sh  Validate testdata against CLI
+├── Cargo.toml              Workspace root
+└── Makefile                Build, test, lint, release targets
+```
+
+## Release workflow
+
+Development happens on `main`. The `go/internal/ffi/lib/` directory is
+gitignored — local development uses `make build-clib` to populate it, or sets
+`LUADATA_LIB_PATH` to point at a locally-built shared library.
+
+### Cutting a release
+
+1. **Tag RC on main**: `make release` (or `make release BUMP=minor`, etc.) tags
+   the current commit as `v<version>-rc.1` and pushes the tag.
+
+2. **CI cross-compiles**: The `release.yml` workflow triggers on `v*-rc.*` tags.
+   It builds the Rust cdylib for five platforms:
+   - `darwin_amd64`, `darwin_arm64`
+   - `linux_amd64`, `linux_arm64`
+   - `windows_amd64`
+
+3. **CI tests**: Rust tests and Go tests (using the freshly-built Linux library)
+   run in the same workflow.
+
+4. **Prepare release branch**: `scripts/prepare-release.sh` copies the
+   cross-compiled shared libraries into `go/internal/ffi/lib/<platform>/`,
+   generates platform-specific `go:embed` files (replacing `embed_dev.go`), and
+   commits everything to the `release` branch with the final version tag.
+
+5. **GitHub Release**: CI creates a GitHub Release with shared library artifacts.
+
+6. **Publish to registries**: After the release succeeds, three publish jobs run
+   in parallel — all using OIDC trusted publishing (no stored secrets):
+   - **PyPI**: Builds platform-specific wheels (same five platforms as clib) plus
+     an sdist, then publishes `mmobeus-luadata` via `pypa/gh-action-pypi-publish`.
+   - **npm**: Builds the WASM module with wasm-pack, packages it with the JS/TS
+     wrapper from `npm/`, and publishes `mmobeus-luadata`.
+   - **crates.io**: Publishes the `luadata` core crate via
+     `rust-lang/crates-io-auth-action` for OIDC token exchange.
+
+### Go consumer model
+
+Go consumers install with:
+
+```
+go get github.com/mmobeus/luadata/go@v0.5.0
+```
+
+This resolves to the `release` branch commit, which contains the embedded shared
+libraries. At runtime, the Go wrapper extracts the platform-appropriate library
+to a temp file and loads it via purego. No CGO is involved at any point.
+
+On `main`, `embed_dev.go` provides an empty `EmbeddedLib` byte slice. If
+`LUADATA_LIB_PATH` is set, the FFI layer loads the library from that path
+instead — this is the local development path.
+
+## Key design decisions
+
+### purego FFI
+
+The Go wrapper uses [purego](https://github.com/ebitengine/purego) to call the
+Rust shared library. purego uses assembly trampolines to make C function calls
+from pure Go — no CGO, no C compiler, no `CGO_ENABLED=1`. This means:
+
+- `go get` works without a C toolchain
+- Cross-compilation works (libraries are pre-built per platform)
+- The Go module is a normal Go package from the consumer's perspective
+
+### internal/ffi for platform isolation
+
+Platform-specific code (library loading, embed directives) lives in
+`go/internal/ffi/` behind build tags. The public API in `go/luadata.go` is
+platform-agnostic and delegates to `ffi.Call()`.
+
+### runtime.KeepAlive for GC safety
+
+When passing Go byte slices to the Rust FFI as C pointers, `runtime.KeepAlive`
+ensures the Go garbage collector doesn't collect the backing memory while Rust
+is reading it.
+
+### Null-terminated C strings for UTF-8 correctness
+
+The FFI boundary uses null-terminated C strings (`*const c_char` on the Rust
+side). The Go wrapper converts Go strings to null-terminated byte slices before
+passing them. This avoids length-prefix mismatches and ensures Rust's `CStr`
+can safely interpret the data as UTF-8.
+
+### JSON envelope for FFI results
+
+The clib returns results as a JSON envelope: `{"result":"..."}` on success,
+`{"error":"..."}` on failure. This keeps the FFI surface minimal (two functions:
+`LuaDataToJSON` and `LuaDataFree`) while supporting structured error reporting.