zon-rb 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32686cf609ab53ad187e1ea5eab78453f396642b7a092c60d1104b843f7dd47c
-  data.tar.gz: e022ce6c1cb840580a105acc23ace93bf42ebca5001af78d31d2bda183e18319
+  metadata.gz: 818004dd00ec5169c64a80953c55e2b49f9b92a7691aef46251463e671c8a033
+  data.tar.gz: 2519a754dd2e2cc19ee40c8dbfa7c2ae0370e5bd33fc6e69f7dcc0bebd56eb00
 SHA512:
-  metadata.gz: 13629fb58006c1ca81cecce5d3bf893f96835e3d927458de00745b0f0c3ccfea40a640d75bfb783c76433be2bcc5b83488c1576325237134f561d286f224e5c5
-  data.tar.gz: c0968e432df9bb625d9d6d49ad6104b6a0a9d9730180d7ef62a1efcb800e6405996184e39918a63ca45e6abae11b0834854ec365be8f90efc9949349bc7062d0
+  metadata.gz: e03c8137c996cb03adc77ddebc0afbb95a6cb078f635052eb88dfb2b782365e7ca335aa5436560619b20e246d7693ba96860625943b780deb15c1a2386ef9472
+  data.tar.gz: 497d4a8b6b830abe6b533fdbb22407524616f5b44727d7c73d8a0f9e49105a7db6d2941396c3a904e4dcfc029c0f5157eb4dfe1db63b22248032d56052403344

data/CHANGELOG.md

@@ -1,4 +1,6 @@
-## [Unreleased]
+## [0.2.0] - 2025-09-27
+
+- Added basic Zig package manifest support.
 
 ## [0.1.0] - 2025-09-27
 

data/README.md

@@ -1,25 +1,31 @@
 # Zig Object Notation (ZON) for Ruby
 
+[![Gem Version](https://badge.fury.io/rb/zon-rb.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/zon-rb)
+
 The [Zig](https://ziglang.org/) Object Notation (ZON) is a file format primarily used within the Zig ecosystem. For example, ZON is used for the Zig package [manifest](https://github.com/ziglang/zig/blob/b7ab62540963d80f68d0e9ee7ce18520fb173487/doc/build.zig.zon.md).
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add zon-rb
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install zon-rb
 ```
 
 ## Usage
 
+To use this Gem you have to require it:
+
+```ruby
+require "zon"
+```
+
 To parse ZON data into a Ruby object, one can use the `Zon::parse` method. The method expects either a `String` or `IO` (`File`) object as its argument.
 
 ```irb
@@ -94,6 +100,32 @@ irb(main):010> Zon::serialize(255, {:ibase => 2})
 => "0b11111111"
 ```
 
+### Zig Manifest
+
+`Zon::Zig::Manifest` provides you with an abstraction for your `build.zig.zon`. It will also validate your Zig package [manifest](https://github.com/ziglang/zig/blob/b7ab62540963d80f68d0e9ee7ce18520fb173487/doc/build.zig.zon.md) and raise an exception if one of the required fields is missing.
+
+```ruby
+o = Zon::parse(File.open("../PassKeeZ/build.zig.zon"))
+manifest = Zon::Zig::Manifest.new o
+
+# Use:
+# manifest.name
+# manifest.version
+# ...
+```
+
+### Zig Package Hash
+
+Given a path `pdir` that points to the root of a Zig package, one can calculate the packages hash using the `Zon::Hasher`:
+
+```ruby
+hasher = Zon::Zig::Hasher.new pdir
+hasher.hash
+# Hash with the format nnnn-vvvv-XXXX..XXXX
+# e.g.: uuid-0.4.0-oOieIR2AAAChAUVBY4ABjYI1XN0EbVALmiN0JIlggC3i
+result = hasher.result
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/zon/hasher.rb

@@ -0,0 +1,176 @@
+require "digest"
+require "find"
+require "base64"
+
+module Zon
+  module Zig
+    ##
+    # Produces a package hash of the format: $name-$semver-$hashplus
+    #
+    # Along with 200 bits of a SHA-256, a package hash includes:
+    # - package name
+    # - package version
+    # - id component of the package fingerprint
+    # - total unpacked size on disk
+    #
+    # The following steps are taken to calculate the hash:
+    # 1. Read the list of included paths from the manifest, i.e. files that are part of the package.
+    # 2. Resolve the paths:
+    #     - for directories: include all files that are within the directory or a child dir.
+    #     - for files: include the file
+    #     - for symlinks: TODO
+    # 3. Sort the paths by:
+    #     1. Lexographical order
+    #     2. by length
+    # 4. For every included file:
+    #     - Calculate a SHA-256 over: RELATIVE_PATH_FROM_PKG_ROOT || 0x0000 || DATA
+    #     - Record the file size in bytes
+    #     - TODO: the 0x0000 will probably change in the future
+    # 5. Calculate a SHA-256 sum over all calculated file hashes
+    #     - respecting the previously mentioned sorting rules.
+    # 6. Sum up the sizes of all files into a u32 (sizes that don't fit into a 32-bit unsingned integer will be saturated with the value 2**32 - 1)
+    # 7. Produce the package hash
+    class Hasher
+      attr_reader :paths, :total_size, :digest
+
+      SUPPORTED_ZIG_VERSIONS = ["0.14.0", "0.14.1", "0.15.1", "0.15.2"]
+
+      def initialize(package_path, manifest_name: "build.zig.zon")
+        # Make sure we have a valid path to work with
+        @package_path = package_path
+        raise ArgumentError, "not a directory '#{@package_path}'" if not Dir.exist? @package_path
+
+        manifest_path = File.join(@package_path, manifest_name)
+        raise ArgumentError, "no manifest '#{manifest_name}' in '#{@package_path}'" if not File.exist? manifest_path
+
+        @manifest = Zon.parse(File.open(manifest_path))
+        raise ArgumentError, "no 'paths' field in ZON manifest '#{manifest_path}'" if not @manifest.key? :paths
+        raise ArgumentError, "no 'name' field in ZON manifest '#{manifest_path}'" if not @manifest.key? :name
+        raise ArgumentError, "no 'version' field in ZON manifest '#{manifest_path}'" if not @manifest.key? :version
+        raise ArgumentError, "no 'fingerprint' field in ZON manifest '#{manifest_path}'" if not @manifest.key? :fingerprint
+        
+        @paths = []
+        @results = {}
+        @total_size = 0
+        @digest = nil
+
+        @manifest[:paths].each do |path|
+          full_path = File.join(@package_path, path)
+
+          if File.directory? full_path
+            f = Find.find(full_path)
+            f.each do |p|
+              next if File.directory? p
+              
+              pstr = p.delete_prefix(@package_path)[1..]
+              @paths.append(pstr) if not @paths.include? pstr
+            end
+          elsif File.file? full_path or File.symlink? full_path
+            pstr = full_path.delete_prefix(@package_path)[1..]
+            @paths.append(pstr) if not @paths.include? pstr
+          end
+        end
+
+        @paths = @paths.sort_by { |str| [str, -str.length] }
+      end
+
+      def name
+        String(@manifest[:name])
+      end
+
+      def version
+        @manifest[:version]
+      end
+
+      def hash
+        @total_size = 0
+        @digest = nil
+        
+        # Hash all files individually  
+        @paths.each do |str|
+          @results[str] = Zon::Zig::Hasher::hash_file(@package_path, str)
+        end 
+
+        sha2 = Digest::SHA2.new
+
+        @paths.each do |str|
+          res = @results[str]
+
+          @total_size += res[:size]
+          sha2.update [res[:digest]].pack('H*')
+        end
+
+        @digest = sha2.hexdigest
+      end
+      
+      ##
+      # Get the ID part of the fingerprint
+      def get_id
+        @manifest[:fingerprint] & 0xffffffff
+      end
+      
+      ##
+      # Get the calculated, total size of the unpacked package.
+      def get_saturated_size
+        max_uint32 = 2**32 - 1
+
+        if @total_size > max_uint32
+          max_uint32
+        else
+          @total_size
+        end
+      end
+
+      def result
+        Zon::Zig::Hasher::make_hash(@digest, name, version, get_id, get_saturated_size)
+      end
+      
+      ##
+      # Produces $name-$semver-$hashplus
+      #
+      # - name is the name field from a build.zig.zon manifest. It is expected
+      # to be at most 32 bytes long and a valid Zig identifier.
+      # - semver is the version field from a build.zig.zon manifest. It is expected
+      # to be at most 32 bytes long.
+      # - hashplus is a base64 (urlsafe and nopad) encoded, 33-byte string:
+      #     - Pacakge ID (4) || Decompressed Size (4) || Digest0, Digest1, ..., Digest24
+      def self.make_hash(digest, name, semver, id, size)
+        raise ArgumentError, "name '#{name}' is expected to be at most 32 bytes long but it is #{name.bytesize} bytes" if name.bytesize > 32
+        raise ArgumentError, "semver '#{semver}' is expected to be at most 32 bytes long but it is #{semver.bytesize} bytes" if semver.bytesize > 32
+
+        hash_plus = [id].pack("V")
+        hash_plus += [size].pack("V")
+        hash_plus += [digest].pack('H*')[0..24]
+
+        "#{name}-#{semver}-#{Base64.urlsafe_encode64(hash_plus, padding: false)}"
+      end
+
+      def self.hash_file(package_path, path)
+        sha2 = Digest::SHA2.new    
+        sha2.update path
+
+        full_path = File.join(package_path, path)
+
+        if File.file? full_path
+          f = File.open full_path
+          data = f.read
+          file_size = data.bytesize
+          
+          # Hard-coded false executable bit: https://github.com/ziglang/zig/issues/17463
+          sha2.update "\x00\x00"
+          sha2.update data
+        elsif File.symlink? full_path
+          link_name = File.readlink full_path
+          sha2.update link_name
+        end
+
+        # TODO: symlink
+
+        {
+          digest: sha2.hexdigest,
+          size: file_size,
+        }
+      end
+    end
+  end
+end

data/lib/zon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zon
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/zon/zig.rb

@@ -0,0 +1,80 @@
+module Zon
+
+  ##
+  # Everything related specifically to the Zig programming language.
+  module Zig
+    
+    ##
+    # An abstraction of the Zig package manifest.
+    #
+    # Every Zig package should have a +build.zig.zon+ in
+    # its package root, the manifest. Like a manifest in
+    # Ruby, it is used to describe the package and specify
+    # required dependencies.
+    class Manifest
+      def initialize(zon)
+        raise "Missing '.name'" if not zon[:name]
+        raise "Missing '.version'" if not zon[:version]
+        raise "Missing '.fingerprint'" if not zon[:fingerprint]
+        raise "Missing '.paths'" if not zon[:paths]
+
+        if zon[:dependencies]
+          zon[:dependencies].each do |key, value|
+            if value[:url]
+              raise "Missing '.hash' for dependency '#{key}'" if not value[:hash]
+            elsif not value[:path]
+              raise "Expected either '.url' or '.path' for dependency '#{key}'" if not value[:hash]
+            end 
+          end
+        end
+
+        @zon = zon
+      end
+      
+      ##
+      # Get the '.name' field of the manifest.
+      def name
+        @zon[:name]
+      end
+
+      ##
+      # Get the '.version' field of the manifest.
+      def version
+        @zon[:version]
+      end
+
+      ##
+      # Get the '.fingerprint' field of the manifest.
+      def fingerprint
+        @zon[:fingerprint]
+      end
+
+      ##
+      # Get the '.dependencies' field of the manifest.
+      #
+      # This will return nil if the '.dependencies' field does not exist.
+      def dependencies
+        @zon[:dependencies]
+      end
+
+      ##
+      # Get the '.paths' field of the manifest.
+      #
+      # This will return nil if the '.paths' field does not exist.
+      def paths
+        @zon[:paths]
+      end
+
+      ##
+      # Get the '.minimum_zig_version' field of the manifest.
+      #
+      # This will return nil if the '.minimum_zig_version' field does not exist.
+      def minimum_zig_version
+        @zon[:minimum_zig_version]
+      end
+
+    end
+
+  end
+
+end

data/lib/zon.rb

@@ -4,6 +4,8 @@ require_relative "zon/version"
 require_relative "zon/lexer"
 require_relative "zon/parser"
 require_relative "zon/serializer"
+require_relative "zon/zig"
+require_relative "zon/hasher"
 
 ##
 # Zig Object Notation (ZON) de-/serializer.

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: zon-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - David P. Sugar
 bindir: exe
 cert_chain: []
-date: 2025-09-27 00:00:00.000000000 Z
+date: 2025-10-19 00:00:00.000000000 Z
 dependencies: []
-description: This gem allows you to translate ZON data into Ruby objects and vice
-  versa.
+description: This gem allows you to translate Zig Object Notation (ZON) data into
+  Ruby objects and vice versa.
 email:
 - david@thesugar.de
 executables: []
@@ -24,10 +24,12 @@ files:
 - README.md
 - Rakefile
 - lib/zon.rb
+- lib/zon/hasher.rb
 - lib/zon/lexer.rb
 - lib/zon/parser.rb
 - lib/zon/serializer.rb
 - lib/zon/version.rb
+- lib/zon/zig.rb
 - lib/zon/zon_grammar.treetop
 - sig/zon.rbs
 homepage: https://github.com/r4gus/zon-rb