jq 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85a8def8b4728ce33cb6bf3322969e08d95abd40dec1efd317a7a0de764f333a
+  data.tar.gz: 96a55036c41973603dba2bbcea2970ebd6312fa2334c1afb79feba3327015228
+SHA512:
+  metadata.gz: 301b55c4c77ec72aca48de6cf73d8ef421710b0cea7c6aa041191c0d39cbbe1763530920bdcf98c333d80c07ce4677c5fad78f3841ec8448e7ce2db3571a9148
+  data.tar.gz: 6d3c8b437eff186dc30e24f6add659312c37c4f0c4f73c602f172d93655c2eb02362ed128d21dd59f6b47bbb2f14805c1214b20ef71348eae92d4710aebd7b6d

data/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        ruby: ['3.3', '3.4']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install autotools (macOS)
+        if: runner.os == 'macOS'
+        run: brew install autoconf automake libtool
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake

data/.github/workflows/release-gem.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    runs-on: ubuntu-latest
+    environment: Release
+
+    needs: [ci]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Publish to RubyGems
+        uses: rubygems/release-gem@v1
+        with:
+          await-release: true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: pkg/*.gem
+          generate_release_notes: true

data/.gitignore

@@ -0,0 +1,49 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+spec/examples.txt
+
+# Compiled extensions
+*.bundle
+*.so
+*.o
+*.a
+*.log
+
+# Compiled extension outputs
+/lib/jq/jq_ext.bundle
+/lib/jq/jq_ext.so
+/lib/jq/jq_ext.dll
+
+# Build artifacts
+/ext/jq/*.o
+/ext/jq/*.so
+/ext/jq/*.bundle
+/ext/jq/Makefile
+/ext/jq/mkmf.log
+/ext/jq/tmp/
+
+# miniportile
+/ext/jq/ports/
+/ext/jq/tmp/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Editor files
+*.swp
+*.swo
+*~
+.vscode/
+.idea/
+
+# Gem files
+*.gem

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.3.9

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-26
+
+### Added
+
+- Initial release of jq-ruby gem
+- `JQ.filter` method for applying jq filters to JSON
+  - Support for `raw_output` option (jq -r)
+  - Support for `compact_output` option (jq -c)
+  - Support for `sort_keys` option (jq -S)
+  - Support for `multiple_outputs` option to return all results
+- `JQ.validate_filter!` method for validating jq filter expressions
+- Exception hierarchy:
+  - `JQ::Error` - Base exception class
+  - `JQ::CompileError` - Invalid jq filter
+  - `JQ::RuntimeError` - Runtime execution error
+  - `JQ::ParseError` - Invalid JSON input
+- Bundled jq 1.8.1 compiled from source via mini_portile2
+  - Self-contained installation with no system dependencies
+  - SHA256 verification of jq source tarball
+  - Static compilation for reliability
+- Comprehensive test suite with >95% coverage
+  - Core functionality tests
+  - Filter validation tests
+  - Error handling tests
+  - Security tests
+  - Memory leak detection tests
+- Complete documentation
+  - README with usage examples
+  - SECURITY.md with security considerations
+  - RBS type signatures
+- Ruby 3.3+ required
+- Thread safety documentation (jq is NOT thread-safe)
+
+### Security
+
+- Proper jv memory lifecycle management prevents buffer overflows
+- All inputs validated for type before processing
+- JSON parsed by jq's built-in parser (no eval/injection risk)
+- Filter expressions cannot execute system commands (safe by design)
+- Tested with large inputs, deeply nested structures, and malicious filters
+
+[1.0.0]: https://github.com/persona-id/jq-ruby/releases/tag/v1.0.0

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,40 @@
+PATH
+  remote: .
+  specs:
+    jq (1.0.0)
+      mini_portile2 (~> 2.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.6.2)
+    mini_portile2 (2.8.9)
+    rake (13.3.1)
+    rake-compiler (1.3.1)
+      rake
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  jq!
+  rake (~> 13.0)
+  rake-compiler (~> 1.2)
+  rspec (~> 3.13)
+
+BUNDLED WITH
+   2.7.2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Persona Identity Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,214 @@
+# jq-ruby
+
+A minimal, security-focused Ruby gem that wraps the jq C library for JSON transformation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jq'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install jq
+```
+
+**Note:** This gem bundles jq 1.8.1 and builds it from source automatically during installation. No system dependencies are required.
+
+## Usage
+
+### Basic Filtering
+
+```ruby
+require 'jq'
+
+# Basic filter
+result = JQ.filter('{"name":"Alice","age":30}', '.name')
+# => "\"Alice\""
+
+# Identity filter (compact output is the default)
+result = JQ.filter('{"a":1}', '.')
+# => "{\"a\":1}"
+
+# Nested access
+result = JQ.filter('{"user":{"name":"Bob"}}', '.user.name')
+# => "\"Bob\""
+
+# Array operations
+result = JQ.filter('[1,2,3]', '.[1]')
+# => "2"
+```
+
+### Options
+
+#### Raw Output
+
+Get raw strings without JSON encoding (equivalent to `jq -r`):
+
+```ruby
+result = JQ.filter('{"name":"Alice"}', '.name', raw_output: true)
+# => "Alice" (not "\"Alice\"")
+```
+
+#### Compact Output
+
+**Compact output is the default.** JSON is returned on a single line without extra whitespace:
+
+```ruby
+result = JQ.filter('{"a":1,"b":2}', '.')
+# => "{\"a\":1,\"b\":2}" (default)
+
+# To get pretty-printed output, set compact_output: false
+result = JQ.filter('{"a":1,"b":2}', '.', compact_output: false)
+# => "{\n  \"a\": 1,\n  \"b\": 2\n}"
+```
+
+#### Sort Keys
+
+Sort object keys for deterministic output (equivalent to `jq -S`):
+
+```ruby
+result = JQ.filter('{"z":1,"a":2}', '.', sort_keys: true)
+# => "{\"a\":2,\"z\":1}"
+```
+
+#### Multiple Outputs
+
+Return an array of all results instead of just the first:
+
+```ruby
+result = JQ.filter('[1,2,3]', '.[]', multiple_outputs: true)
+# => ["1", "2", "3"]
+
+# Combining with raw_output
+result = JQ.filter('["a","b","c"]', '.[]', multiple_outputs: true, raw_output: true)
+# => ["a", "b", "c"]
+```
+
+### Complex Transformations
+
+```ruby
+# Map operation
+json = '[{"name":"Alice","age":30},{"name":"Bob","age":25}]'
+result = JQ.filter(json, '[.[] | .name]')
+# => "[\"Alice\",\"Bob\"]"
+
+# Select operation
+result = JQ.filter(json, '[.[] | select(.age > 26)]')
+# => "[{\"name\":\"Alice\",\"age\":30}]"
+
+# Multiple transformations
+result = JQ.filter('{"a":1,"b":2,"c":3}', 'to_entries | map(.value) | add')
+# => "6"
+```
+
+### Filter Validation
+
+Validate a filter before using it:
+
+```ruby
+JQ.validate_filter!('.name')
+# => true
+
+JQ.validate_filter!('...invalid')
+# raises JQ::CompileError
+```
+
+### Error Handling
+
+The gem defines four exception classes:
+
+```ruby
+begin
+  JQ.filter('invalid json', '.')
+rescue JQ::ParseError => e
+  puts "Invalid JSON: #{e.message}"
+end
+
+begin
+  JQ.filter('{}', '...invalid filter')
+rescue JQ::CompileError => e
+  puts "Invalid filter: #{e.message}"
+end
+
+begin
+  JQ.filter('{}', '.nonexistent.deeply.nested')
+rescue JQ::RuntimeError => e
+  puts "Runtime error: #{e.message}"
+end
+```
+
+Exception hierarchy:
+
+- `JQ::Error` - Base class for all jq-related errors
+  - `JQ::ParseError` - Invalid JSON input
+  - `JQ::CompileError` - Invalid jq filter
+  - `JQ::RuntimeError` - Runtime execution error
+
+## Thread Safety
+
+**Status: Likely safe with jq 1.7+, but not officially guaranteed**
+
+This gem creates an isolated `jq_state` for each call, and jq 1.7+ fixed a critical thread-safety bug (PR #2546). Multi-threaded use is **probably safe** in MRI Ruby where the GVL serializes execution, but jq hasn't made formal thread-safety guarantees.
+
+**Recommendations:**
+- ✅ Use with jq 1.7+ (check: `jq --version`)
+- ✅ MRI Ruby (standard Ruby) - likely safe due to GVL
+- ⚠️ JRuby/TruffleRuby - use with caution (true parallel threads)
+- 🛡️ Safest for heavy parallel workloads: separate processes
+
+See [SECURITY.md](SECURITY.md) for detailed thread safety information.
+
+## Memory Considerations
+
+- The gem uses proper jv lifecycle management to prevent memory leaks
+- Very large JSON documents (>100MB) may cause high memory usage
+- Deeply nested structures may hit stack limits
+- Complex filters may be slow - there is no timeout mechanism in v1.0
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for detailed security information.
+
+Key points:
+
+- JSON input is parsed by jq's parser (no eval/injection risk)
+- Filter expressions cannot execute system commands (safe by design)
+- All inputs are validated for type before processing
+- The extension uses proper memory management to prevent buffer overflows
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+bundle exec rake compile
+bundle exec rake spec
+```
+
+To check for memory leaks:
+
+```bash
+bundle exec rake compile CFLAGS="-fsanitize=address -g"
+bundle exec rspec spec/memory_spec.rb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/persona-id/jq-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+jq itself is licensed under the MIT License. See https://github.com/jqlang/jq for details.

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rake/extensiontask"
+
+RSpec::Core::RakeTask.new(:spec)
+
+Rake::ExtensionTask.new("jq_ext") do |ext|
+  ext.ext_dir = "ext/jq"
+  ext.lib_dir = "lib/jq"
+end
+
+task spec: :compile
+task default: :spec

data/SECURITY.md

@@ -0,0 +1,121 @@
+# Security
+
+## Thread Safety
+
+**Status: Likely safe with jq 1.7+, but not officially guaranteed**
+
+The jq C library was not originally designed for multi-threading. However, as of jq 1.7 (PR #2546), a critical segfault bug in multi-threaded environments was fixed.
+
+**Current Safety Profile:**
+- ✅ Each `JQ.filter` call creates its own isolated `jq_state` (no shared state between calls)
+- ✅ jq 1.7+ fixed the thread-local storage segfault (included in your jq 1.8.1)
+- ✅ Ruby's GVL (MRI) prevents true parallel execution, providing additional serialization
+- ⚠️ jq developers have not made formal thread-safety guarantees beyond fixing the segfault
+- ⚠️ Other global state issues may exist but are unconfirmed
+
+**Practical Recommendation:**
+- **Probably safe** to call `JQ.filter` from multiple Ruby threads in MRI Ruby with jq 1.7+
+- **Use caution** with JRuby or TruffleRuby where threads can run truly in parallel
+- **Safest approach** for heavy parallel processing: use separate processes (e.g., `parallel` gem)
+
+**Version Requirements:**
+- jq 1.7+ strongly recommended for any multi-threaded use
+- Check your jq version: `jq --version`
+
+## Input Validation
+
+- **JSON input** is parsed by jq's built-in parser. There is no eval or code injection risk.
+- **Filter expressions** are compiled by jq's compiler. They cannot execute system commands or access the filesystem (safe by design).
+- All inputs are validated for type before processing in the Ruby C extension.
+
+## Memory Safety
+
+The extension uses proper jv lifecycle management to prevent memory leaks and buffer overflows:
+
+- Every `jv` value is tracked and freed appropriately
+- Error paths ensure cleanup before raising Ruby exceptions
+- The jq library's "consume" pattern is followed correctly
+
+### Testing for Memory Issues
+
+Run tests with AddressSanitizer to detect memory errors:
+
+```bash
+bundle exec rake compile CFLAGS="-fsanitize=address -g"
+bundle exec rspec
+```
+
+Or use valgrind:
+
+```bash
+valgrind --leak-check=full bundle exec rspec
+```
+
+Run the memory test suite:
+
+```bash
+bundle exec rspec spec/memory_spec.rb
+```
+
+## Known Limitations
+
+- **Very large JSON documents** (>100MB) may cause high memory usage. The entire document is parsed into memory before processing.
+- **Deeply nested structures** may hit stack limits (typically ~1000 levels depending on system).
+- **Complex filters** may be slow. There is no timeout mechanism in v1.0 - long-running filters will block.
+- **No sandboxing** - While jq filters cannot execute arbitrary code, complex filters can consume significant CPU and memory.
+
+## Security Best Practices
+
+1. **Validate input size** - If processing untrusted JSON, check the size before passing to `JQ.filter`:
+
+   ```ruby
+   MAX_JSON_SIZE = 10 * 1024 * 1024 # 10MB
+   raise "JSON too large" if json_string.bytesize > MAX_JSON_SIZE
+   ```
+
+2. **Validate filter** - If using user-provided filters, validate them first:
+
+   ```ruby
+   begin
+     JQ.validate_filter!(user_filter)
+   rescue JQ::CompileError => e
+     # Handle invalid filter
+   end
+   ```
+
+3. **Set timeouts** - Use Ruby's `Timeout` module for long-running operations (note: this may not interrupt C code immediately):
+
+   ```ruby
+   require 'timeout'
+
+   begin
+     Timeout.timeout(5) do
+       JQ.filter(json, filter)
+     end
+   rescue Timeout::Error
+     # Handle timeout
+   end
+   ```
+
+4. **Limit nesting depth** - Pre-validate JSON nesting if processing untrusted input:
+
+   ```ruby
+   def check_nesting_depth(json_string, max_depth = 100)
+     depth = 0
+     max_seen = 0
+     json_string.each_char do |c|
+       depth += 1 if c == '{' || c == '['
+       depth -= 1 if c == '}' || c == ']'
+       max_seen = [max_seen, depth].max
+       raise "Nesting too deep" if max_seen > max_depth
+     end
+   end
+   ```
+
+## Reporting Security Issues
+
+If you discover a security vulnerability, please email security@persona.com with details. Do not open a public issue.
+
+## Acknowledgments
+
+This gem wraps the jq library (https://github.com/jqlang/jq), which is maintained by the jq authors and community.

data/ext/jq/extconf.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+ENV["RC_ARCHS"] = "" if RUBY_PLATFORM.include?("darwin")
+
+require 'mkmf'
+require 'mini_portile2'
+
+class JQRecipe < MiniPortile
+  JQ_VERSION = '1.8.1'
+  JQ_SHA256 = '2be64e7129cecb11d5906290eba10af694fb9e3e7f9fc208a311dc33ca837eb0'
+
+  def initialize
+    super('jq', JQ_VERSION)
+    self.files << {
+      url: "https://github.com/jqlang/jq/releases/download/jq-#{JQ_VERSION}/jq-#{JQ_VERSION}.tar.gz",
+      sha256: JQ_SHA256
+    }    
+    self.configure_options += [
+      # "--enable-shared",
+      "--enable-static",
+      "--enable-all-static",
+      "--disable-maintainer-mode",
+      "--with-oniguruma=builtin",  # Use bundled oniguruma
+      "CFLAGS=-fPIC -DJQ_VERSION=\\\"#{JQRecipe::JQ_VERSION}\\\"",
+    ]
+  end
+
+  def configure
+    return if configured?
+
+    execute('autoreconf', 'autoreconf -i')
+    super
+  end
+end
+
+
+recipe = JQRecipe.new
+recipe.cook
+recipe.activate
+recipe.mkmf_config(pkg: 'oniguruma', static: 'onig')
+recipe.mkmf_config(pkg: 'libjq', static: 'jq')
+
+# Verify we can link against libjq with a test program
+checking_for "ability to link against libjq" do
+  # Create a test program that uses core jq functions
+  src = <<~SRC
+    #include <jv.h>
+    #include <jq.h>
+
+    int main(void) {
+      // Test that we can link against jq_init, jq_compile, jv_parse, etc.
+      jq_state *jq = jq_init();
+      if (!jq) return 1;
+
+      // Test basic jv operations (thread-safe in jq 1.7+)
+      jv input = jv_parse("{}");
+      int valid = jv_is_valid(input);
+      jv_free(input);
+
+      jq_teardown(&jq);
+      return valid ? 0 : 1;
+    }
+  SRC
+
+  # Try to link the test program (don't need to run it)
+  try_link(src) or abort "Failed to link against libjq"
+end
+
+# Add compiler flags
+$CFLAGS << " -Wall -Wextra -Wno-unused-parameter -fPIC"
+
+# Enable debug symbols if requested
+if ENV['DEBUG']
+  $CFLAGS << " -g -O0"
+else
+  $CFLAGS << " -O2"
+end
+
+create_makefile('jq/jq_ext')