Implement Ruby SDK via C FFI bindings with automatic binary downloads

[Copilot]

Adds Ruby SDK wrapping the C library through FFI, providing native-performance JSON Structure schema and instance validation for Ruby applications. The Ruby SDK treats the C library as a foreign dependency, automatically downloading pre-built binaries from GitHub releases.

Changes

• C library: Added JS_BUILD_SHARED CMake option to build shared library (.so/.dylib/.dll) for FFI consumption
• Binary distribution: Automatic download of platform-specific pre-built binaries from GitHub releases (Linux/macOS/Windows x86_64/arm64)
• Binary installer: New BinaryInstaller module that handles platform detection and binary downloads
• FFI bindings: Low-level bindings to C API with proper struct definitions and memory management
• Ruby wrappers: Idiomatic SchemaValidator and InstanceValidator classes with both result-based and exception-based APIs
• Tests: 32 RSpec tests covering validation, error handling, and edge cases
• CI: GitHub Actions workflow testing Ruby 2.7-3.3 on Ubuntu and macOS
• Fixed: Root .gitignore to allow Ruby lib/ directories while preserving Python exclusions

Installation

The gem automatically downloads the appropriate pre-built C library binary for your platform during installation. No compilation required - users don't need CMake or a C compiler.

Usage

require 'json_structure'

# Schema validation
result = JsonStructure::SchemaValidator.validate('{"type": "string"}')
puts "Valid!" if result.valid?

# Instance validation with exceptions
begin
  JsonStructure::InstanceValidator.validate!('"hello"', '{"type": "integer"}')
rescue JsonStructure::InstanceValidationError => e
  e.errors.each { |err| puts "#{err.path}: #{err.message}" }
end

Implementation Notes

• Foreign SDK pattern: Ruby SDK downloads pre-built binaries from GitHub releases, treating the C SDK as an external dependency
• Platform detection: Automatically detects OS (Linux/macOS/Windows) and architecture (x86_64/arm64) to download the correct binary
• Development fallback: When developing in this repository, gracefully falls back to local C library builds if binaries aren't available
• C inline convenience functions (js_validate_schema, js_validate_instance) are not exported in shared libraries; wrapper methods implemented in Ruby FFI module
• Validator warnings (missing $id, name fields) have severity=1 vs errors with severity=0; tests distinguish appropriately
• Gem structure follows Ruby conventions with Bundler, RSpec, and standard layout

Original prompt

create a PR for issue 10

Summary of Conversation History

Recent Agent Commands and Tool Results

1. User Command: "create a PR for issue 11."

   • Context Provided: Instructions for creating a composer.json file for a package, including minimal required fields and validation steps.
   • Expected Outcome: A pull request (PR) should be created to address issue 11 by adding the composer.json file.

2. User Command: "create a PR for issue 10."

   • Expected Outcome: A pull request (PR) should be created to address issue 10.

Results from Recent Tool Calls

• No specific tool results were returned for the commands to create PRs for issues 10 and 11, as the commands were primarily instructions for the agent to execute.

Active Work When Token Budget Exceeded

• The agent was actively working on creating pull requests for issues 10 and 11, specifically focusing on adding necessary files and configurations for PHP package management (Packagist) and ensuring compliance with the required standards.

Connection to Overall User Goals

• The user is focused on enhancing the SDK repository by ensuring proper package management for PHP through the creation of a composer.json file. This aligns with the broader goal of improving the SDK's usability and accessibility across different programming languages, ensuring that all necessary components are in place for effective package distribution and management.

Conclusion

The conversation has revolved around enhancing the SDK repository, particularly for PHP, by creating necessary configuration files and addressing open issues. The recent commands indicate a push towards finalizing these enhancements through pull requests.
TITLE: Creating a PR for PHP SDK Packagist Integration

Created from VS Code via the GitHub Pull Request extension.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[clemensv]

@copilot the ruby wrapper should build on the binaries created by the C SDK as if they were a foreign SDK, i.e. get libraries from github as if they were not in this same repo

[Copilot]

@copilot the ruby wrapper should build on the binaries created by the C SDK as if they were a foreign SDK, i.e. get libraries from github as if they were not in this same repo

Done! The Ruby wrapper now treats the C SDK as a foreign SDK and downloads pre-built binaries from GitHub releases instead of building locally.

Key changes (commit d1080a3):

1. New BinaryInstaller - Downloads platform-specific binaries (Linux/macOS/Windows x86_64/arm64) from GitHub releases
2. Updated FFI loader - Prioritizes downloaded binaries in ext/ directory
3. Refactored Rakefile:
   • download_binary - Downloads from GitHub (production use)
   • build_c_lib_local - Local build (development only, when C source is available)
   • test - Tries download first, falls back to local build in dev environment
4. Updated CI - Clarified local builds are for testing; production uses pre-built binaries
5. Updated docs - Explains binary distribution and development workflow

The gem now works like a typical FFI gem that consumes external C libraries, with automatic binary download on install. For development in this repo, it gracefully falls back to local builds.