glslkit 0.1.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 13d9773aaab7e412f3a84693c9c5906310180722565fb870b64000b9bf8ea74a
+  data.tar.gz: 6dc9b85466232122da5d012bfe251564eee853c33b369c1cf2e73590bed9fd64
+SHA512:
+  metadata.gz: fea6181044d5c985678d050bdeb582b002c63d435b54c569e489b0fbf7aeef4c36bfbbff72ef6742bb64974e56b2fc5a3fe1c6d493f8f7ec2b855e70e40b8552
+  data.tar.gz: 6a6d411e5e9f541f65742aac540c279e68b637b846a9c43f4f14cedd6a4d6c415e04a7a19332f7ba1cba93c8a06bfb1d93039fdb57a6ba8eaff54f30d22f1929

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## [Unreleased]
+
+初回リリース (v0.1)。
+
+### 追加
+
+- `Glslkit::Preprocessor` — `#include`解決、`#pragma once`、`#version`/`#extension`の
+  集約と衝突検出、`#line`ディレクティブ挿入、循環include検出
+- `Glslkit::Resolvers::FileSystem` / `Glslkit::Resolvers::Hash`
+- `Glslkit::Reflection` — attribute / uniform / uniform_block / output の抽出
+- `Glslkit::Types` — GLSL型 → WebGL2 setter の対応表
+- `Glslkit::Manifest` — `spec/schema/reflection-v1.json` (Draft 2020-12) に
+  準拠したマニフェスト生成。ステージ間のuniform/uniform_block統合
+- `Glslkit::Minifier` — コメント・空白のみの除去 (識別子リネームなし)
+- `Glslkit::SourceMap` / `Glslkit::Source`
+- `Glslkit::Validator` — E001〜E007 / W001〜W004 の検証ルール(ステージ間の
+  out/in不一致、cross-stage uniform型不一致、attribute/output location衝突、
+  ステージ内の重複宣言、`gl_`予約プレフィックス)。例外を投げず診断の配列を返す
+- `Glslkit::Diagnostic` / `Glslkit::Program` — Validator/Manifest.build/
+  ライブリロードが共有する値オブジェクト
+- `Glslkit::Bundle` — 前処理→Program化→検証→Manifest組み立てをまとめた
+  中間表現。core/rails/wasmのどれにも属さず、`glslkit-webgl`の埋め込み生成
+  (`rake glslkit:embed`)と`glslkit-rails`のライブリロードエンドポイントの
+  両方から使われる。ポーリング用のソースdigestも計算する
+- `Glslkit::Digest` — stdlib `digest` への依存をこのファイルだけに閉じ込める
+- `require "glslkit/runtime"` — マニフェストの読み込みとSourceMapの復元だけに
+  必要な狭い入口。`glslkit-webgl`(ruby.wasm)側はこちらを使い、
+  前処理・解析・digest計算のコードを読み込まない
+- `Glslkit::Manifest` の `generator` フィールド — マニフェストが
+  `rake glslkit:embed`/`glslkit-rails`のどちらで生成されたかを来歴として残す

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kyubey1228
+
+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,104 @@
+# glslkit
+
+GLSLソースを前処理・解析し、ビルド時に得たリフレクション情報（uniform / attribute
+/ output / uniform block）をJSONとして残すためのRuby gem。実行時依存はゼロ
+（stdlibの `json` `strscan` `set` `digest` のみ）で、将来 [ruby.wasm](https://github.com/ruby/ruby.wasm)
+上のWebGLバインディングにそのまま組み込めることを狙っている。
+
+Rails (Propshaft) との統合は別gem [`glslkit-rails`](../rails) が提供する。
+
+## インストール
+
+```ruby
+gem "glslkit"
+```
+
+## 使い方
+
+```ruby
+require "glslkit"
+
+resolver = Glslkit::Resolvers::FileSystem.new(load_paths: ["app/shaders"])
+source   = Glslkit::Preprocessor.new(resolver: resolver).process("pbr.frag")
+
+source.code        # => 平坦化済みGLSL (String)。#include解決済み、#lineディレクティブ付き
+source.reflection  # => Glslkit::Reflection (attributes / uniforms / uniform_blocks / outputs)
+source.source_map  # => Glslkit::SourceMap (#lineのファイルインデックス → パス)
+source.digest      # => SHA256 hex (String)
+```
+
+### `#include` の解決
+
+```glsl
+#include "common/math.glsl"   // 相対探索 → load_pathsの順に探索
+#include <glslkit/pbr.glsl>   // load_pathsのみを探索(相対探索はしない)
+```
+
+- 循環includeは `Glslkit::CircularIncludeError`
+- `#pragma once` は2回目以降の展開をスキップ(デフォルトは毎回展開)
+- `#version` は複数ファイルに散在していても1行目に1回だけ出力し、値が食い違えば
+  `Glslkit::VersionConflictError`
+- `#if` / `#ifdef` / `#else` / `#endif` は評価せずそのまま出力する(内部の
+  `#include` は展開される。これはv0.1の既知の制限)
+
+wasm側でファイルシステムの無い環境向けに `Glslkit::Resolvers::Hash` も同梱している:
+
+```ruby
+resolver = Glslkit::Resolvers::Hash.new(
+  "pbr.frag" => "...",
+  "common/math.glsl" => "..."
+)
+```
+
+### リフレクション抽出
+
+```ruby
+source.reflection.attributes     # => [#<Attribute name="a_position" type="vec3" location=0 array_size=1>, ...]
+source.reflection.uniforms       # => [#<Uniform name="u_mvp" type="mat4" setter="uniformMatrix4fv" matrix=true sampler=false ...>, ...]
+source.reflection.uniform_blocks # => [#<UniformBlock name="Camera" layout="std140" binding=0>, ...]
+source.reflection.outputs        # => [#<Output name="fragColor" type="vec4" location=0>, ...]
+```
+
+型からWebGL2のsetterへの対応表は `Glslkit::Types` が唯一の正:
+
+```ruby
+Glslkit::Types.setter_for("mat4")  # => "uniformMatrix4fv"
+Glslkit::Types.matrix?("mat4")     # => true
+Glslkit::Types.sampler?("sampler2D") # => true
+```
+
+### マニフェスト生成
+
+vertex/fragmentの `Source` ペアから、`spec/schema/reflection-v1.json`
+(Draft 2020-12 JSON Schema) に準拠したマニフェストを組み立てる:
+
+```ruby
+manifest = Glslkit::Manifest.new(generated_at: Time.now.utc.iso8601)
+manifest.add_program("pbr",
+  vertex:   {path: "pbr.vert", source: vertex_source,   url: "/assets/pbr-a1b2.vert"},
+  fragment: {path: "pbr.frag", source: fragment_source, url: "/assets/pbr-c3d4.frag"})
+
+manifest.to_json
+```
+
+同名uniform/uniform_blockはステージ間で1エントリに統合され、型
+(またはlayout/binding)が食い違えば `Glslkit::StageMismatchError` になる。
+
+### Minify
+
+コメント・空白の除去のみを行う(識別子リネームはしない)。改行は一切削除しない
+ため、`#line` ディレクティブの行番号や `Reflection` の抽出結果を壊さない:
+
+```ruby
+Glslkit::Minifier.minify(source.code)
+```
+
+## エラークラス
+
+`Glslkit::IncludeNotFound`, `Glslkit::PathTraversalError`,
+`Glslkit::CircularIncludeError`, `Glslkit::VersionConflictError`,
+`Glslkit::StageMismatchError`, `Glslkit::UnknownTypeError`
+
+## ライセンス
+
+[MIT](LICENSE.txt)

data/glslkit.gemspec

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "lib/glslkit/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "glslkit"
+  spec.version = Glslkit::VERSION
+  spec.authors = ["kyubey1228"]
+  spec.email = ["kyuuka1228@gmail.com"]
+
+  spec.summary = "GLSL preprocessing and reflection toolkit"
+  spec.description = "Flattens #include directives in GLSL shaders and extracts " \
+    "uniform/attribute/output reflection data as JSON, with zero runtime " \
+    "dependencies so it can run under ruby.wasm."
+  spec.homepage = "https://github.com/kyubey1228/glslkit"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/main/core"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/core/CHANGELOG.md"
+
+  spec.files = Dir.glob("lib/**/*.rb") + ["glslkit.gemspec", "README.md", "CHANGELOG.md", "LICENSE.txt"]
+  spec.require_paths = ["lib"]
+end

data/lib/glslkit/bundle.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "preprocessor"
+require_relative "program"
+require_relative "validator"
+require_relative "manifest"
+require_relative "digest"
+
+module Glslkit
+  # 1プログラム分(vertex+fragment)を「前処理→Program化→検証→Manifest組み立て」
+  # まで通す中間表現(M11b、SPEC-livereload.md §3.2)。core/rails/wasmのどれにも
+  # 属さない — `Glslkit::WebGL::Embed` はこれを `.rb` に整形するだけの薄い
+  # ラッパーになり、Rails側のライブリロードは同じ結果をJSONに整形して返す
+  # (シリアライズ形式だけが違う、というのがこのクラスを切り出した理由)。
+  #
+  # `.build` は例外を投げない。前処理(#include解決)が失敗した場合も、
+  # Validatorがエラーを返した場合も、結果は常に Result として返る。
+  # 例外にして呼び出し側に伝える/伝えないの判断は呼び出し側の役目
+  # (Embedは前者、Railsのライブリロードエンドポイントは後者になる想定)。
+  module Bundle
+    # Preprocessor#process とその内部で使うResolverが実際に投げうる例外を
+    # 尽くす。ここに列挙されていない例外(想定外のバグ等)は握り潰さず
+    # そのまま伝播させる。
+    PREPROCESS_ERRORS = [
+      IncludeNotFound,
+      CircularIncludeError,
+      VersionConflictError,
+      PathTraversalError
+    ].freeze
+
+    # kind: nil(成功) | :preprocess(#include解決の失敗) | :validation(Validatorのエラー)。
+    # kind == :validation でも vertex/fragment は入る(前処理自体は成功している)。
+    # manifest は kind.nil? のときだけ入る。
+    class Result
+      attr_reader :name, :kind, :source_digest, :vertex, :fragment, :manifest, :diagnostics, :error
+
+      def initialize(name:, source_digest:, kind: nil, vertex: nil, fragment: nil, manifest: nil, diagnostics: [], error: nil)
+        @name = name
+        @kind = kind
+        @source_digest = source_digest
+        @vertex = vertex
+        @fragment = fragment
+        @manifest = manifest
+        @diagnostics = diagnostics
+        @error = error
+      end
+
+      def ok?
+        kind.nil?
+      end
+    end
+
+    module_function
+
+    # resolver: #include解決に使うResolver(呼び出し側が用意する。FileSystem/Hash等)。
+    # vertex/fragment: resolverへ渡すエントリポイントのリクエスト文字列(相対パス)。
+    # urls: Manifestのstage.urlに載せる値。省略時はvertex/fragmentのパス自身を使う
+    #   (Embedの用途。実URLが要るRails側は明示的に渡す)。
+    # known_files: ポーリング用digest(§3.2 決定1)を、前処理が失敗した回にも
+    #   計算するための「前回成功時のfiles」。呼び出し側が持ち回る
+    #   (Bundle自身はステートレスに保つ)。
+    def build(resolver:, name:, vertex:, fragment:, line_directives: true, disabled_checks: [],
+      urls: {vertex: vertex, fragment: fragment}, known_files: [], now: Time.now)
+      preprocessor = Preprocessor.new(resolver: resolver, line_directives: line_directives)
+
+      begin
+        vertex_source = preprocessor.process(vertex)
+        fragment_source = preprocessor.process(fragment)
+      rescue *PREPROCESS_ERRORS => e
+        digest = source_digest(resolver, fallback_files(known_files, [vertex, fragment]))
+        return Result.new(name: name, kind: :preprocess, source_digest: digest, error: e)
+      end
+
+      program = Program.new(name: name, sources: {vertex: vertex_source, fragment: fragment_source})
+      validation = Validator.new(disabled: disabled_checks).validate(program)
+      digest = source_digest(resolver, (vertex_source.source_map.files + fragment_source.source_map.files).uniq)
+
+      unless validation.ok?
+        return Result.new(
+          name: name, kind: :validation, source_digest: digest,
+          vertex: vertex_source, fragment: fragment_source, diagnostics: validation.diagnostics
+        )
+      end
+
+      manifest = Manifest.build(programs: [program], urls: {name => urls}, now: now)
+      Result.new(
+        name: name, source_digest: digest, vertex: vertex_source, fragment: fragment_source,
+        manifest: manifest, diagnostics: validation.diagnostics
+      )
+    end
+
+    def fallback_files(known_files, entry_points)
+      (known_files.empty? ? entry_points : known_files + entry_points).uniq
+    end
+
+    # 依存する全ソースファイルの生バイト列(前処理後のコードではない)を
+    # パスでソートして "path\0content" で連結し、SHA256を取る(決定1)。
+    def source_digest(resolver, files)
+      entries = files.sort.filter_map do |path|
+        content = read_raw(resolver, path)
+        "#{path}\0#{content}" unless content.nil?
+      end
+      Digest.hexdigest(entries.join)
+    end
+
+    # digest計算専用の再読み込み。known_filesに含まれる「前回成功時のファイル」が
+    # その後削除されている等で読めなくなっていても、digest計算そのものは
+    # 落とさない(ポーリングを壊さないことを優先する。digestは変化を検知できれば
+    # 十分で、読めなかった1ファイルの厳密な反映までは求めない)。
+    def read_raw(resolver, path)
+      _, content = resolver.read(path, from: nil)
+      content
+    rescue
+      nil
+    end
+  end
+end

data/lib/glslkit/diagnostic.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Glslkit
+  # 検証結果1件分(§8.2)。file/lineの解決はValidatorの役目であり、
+  # DiagnosticやReflection自身は関与しない。
+  Diagnostic = Struct.new(:severity, :code, :message, :program, :stage, :name, :file, :line, keyword_init: true) do
+    def error?
+      severity == :error
+    end
+
+    def warning?
+      severity == :warning
+    end
+
+    def to_s
+      "[#{code}] #{location}: #{message}"
+    end
+
+    private
+
+    def location
+      return "#{file}:#{line}" if file
+
+      stage ? "#{program}(#{stage})" : program.to_s
+    end
+  end
+end

data/lib/glslkit/digest.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Glslkit
+  # stdlibの `digest` を要求するのはこのファイルだけにする(M8g)。
+  # `glslkit/runtime`(wasm向けの狭い入口)はこのファイルをrequireしないため、
+  # マニフェストの読み込み・SourceMapの復元だけならdigestはロードされない。
+  module Digest
+    module_function
+
+    # 定数探索はこのモジュール自身より先にこのレキシカルスコープを見るため、
+    # 曖昧さを避けて常にトップレベルの `::Digest` を明示する。
+    def hexdigest(string)
+      ::Digest::SHA256.hexdigest(string)
+    end
+  end
+end

data/lib/glslkit/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Glslkit
+  class UnknownTypeError < StandardError; end
+  class IncludeNotFound < StandardError; end
+  class PathTraversalError < StandardError; end
+  class CircularIncludeError < StandardError; end
+  class VersionConflictError < StandardError; end
+  class StageMismatchError < StandardError; end
+  # M11a: glslkit-railsのassets:precompileフックが、Validatorのエラーで
+  # ビルドを止めるときに投げる(SPEC.md §8.6)。coreはこれを自分では投げない
+  # (Rails側からしか使われないが、例外クラス自体は名前空間の都合でcoreに置く)。
+  class ValidationFailed < StandardError; end
+end

data/lib/glslkit/manifest.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "errors"
+require_relative "types"
+require_relative "version"
+
+module Glslkit
+  # プログラムごとのvertex+fragment Sourceペアから reflection-v1.json の
+  # マニフェスト(spec/schema/reflection-v1.json)を組み立てる。各stageの
+  # `url`は呼び出し側から渡される不透明な文字列(例: Propshaftの
+  # フィンガープリント付きアセットパス)である — glslkit自身のdigestとは
+  # 無関係で、digestから導出することはなく、渡された値をそのまま格納する
+  # だけである。
+  class Manifest
+    class UnsupportedVersionError < StandardError; end
+
+    # JSON文字列(またはJSON.parse済みのHash)からManifestを復元する(M8g)。
+    # `glslkit/runtime`(digestをロードしない狭い入口)から使われる想定のため、
+    # ここではdigestに一切触れない。検証は行わない — 壊れた入力は
+    # KeyError/JSON::ParserError等をそのまま投げる。
+    def self.parse(json_string_or_hash)
+      hash = json_string_or_hash.is_a?(String) ? JSON.parse(json_string_or_hash) : json_string_or_hash
+      version = hash.fetch("schema_version")
+      raise UnsupportedVersionError, "unsupported schema_version: #{version.inspect}" unless version == 1
+
+      new(generated_at: hash.fetch("generated_at"), programs: hash.fetch("programs"), generator: hash["generator"])
+    end
+
+    # Glslkit::Program (§8.3) の配列からマニフェストのHashを直接組み立てる。
+    # Validatorと入力を共有できるようにする入口で、内部的には
+    # add_program に委譲するだけ(既存のマージロジックには手を入れない)。
+    #
+    # vertex/fragmentが両方揃っていないProgramは(共有partial等の可能性が
+    # あるため)黙ってスキップする — SPEC.md §2.4/§3の「プログラムは
+    # 両ステージ必須」という決定と、ManifestBuilder(rails側)が既に
+    # 行っているのと同じ扱い。
+    #
+    # 検証(Validator)は必ずこれより先に呼ぶこと(§8.6)。ここは今まで通り
+    # StageMismatchErrorを投げる経路のままなので、検証を経ていない入力を
+    # 渡すと診断を得る前に例外で落ちる。
+    def self.build(programs:, urls: {}, now: Time.now)
+      # digest(§8.9)と同じ扱い: `.iso8601` はstdlibの"time"の拡張なので、
+      # 実際に使う`.build`経路でだけ遅延require する。`glslkit/runtime`
+      # (`.parse`/`.to_h`のみ)はこのメソッドを経由しないため影響しない。
+      require "time"
+      manifest = new(generated_at: now.utc.iso8601, generator: "glslkit/#{Glslkit::VERSION}")
+      programs.each do |program|
+        next unless program.sources.key?(:vertex) && program.sources.key?(:fragment)
+
+        manifest.add_program(
+          program.name,
+          vertex: stage_input(program, :vertex, urls),
+          fragment: stage_input(program, :fragment, urls)
+        )
+      end
+      manifest.to_h
+    end
+
+    def self.stage_input(program, stage, urls)
+      ext = (stage == :vertex) ? "vert" : "frag"
+      {path: "#{program.name}.#{ext}", source: program.sources.fetch(stage), url: urls.dig(program.name, stage)}
+    end
+    private_class_method :stage_input
+
+    def initialize(generated_at:, programs: {}, generator: nil)
+      @generated_at = generated_at
+      @programs = programs
+      @generator = generator
+    end
+
+    def add_program(name, vertex:, fragment:)
+      @programs[name.to_s] = build_program(vertex: vertex, fragment: fragment)
+      self
+    end
+
+    # `generator`(M10e)は「このManifestを実際に組み立てたのは何か」を表す
+    # 来歴情報。`build`が呼ばれたときにだけそのバージョンで確定させ、`to_h`が
+    # 呼ばれるたびに現在実行中のバージョンで上書きしたりはしない —
+    # `parse`で読み込んだ古いバージョンの生成物の来歴を破壊しないため。
+    # 未設定(手書きのManifestや、generatorを持たない古い生成物)なら
+    # キー自体を出さない。`reflection-v1.json`でoptional(型はstring)なので
+    # nullを出すとスキーマ違反になる。
+    def to_h
+      {
+        "schema_version" => 1,
+        "generated_at" => @generated_at,
+        "generator" => @generator,
+        "programs" => @programs
+      }.compact
+    end
+
+    def to_json(*args)
+      JSON.generate(to_h, *args)
+    end
+
+    private
+
+    def build_program(vertex:, fragment:)
+      vertex_reflection = vertex.fetch(:source).reflection
+      fragment_reflection = fragment.fetch(:source).reflection
+
+      {
+        "digest" => program_digest(vertex.fetch(:source).digest, fragment.fetch(:source).digest),
+        "stages" => {
+          "vertex" => stage_hash(vertex),
+          "fragment" => stage_hash(fragment)
+        },
+        "attributes" => vertex_reflection.attributes.map { |a| attribute_hash(a) },
+        "uniforms" => merge_uniforms(vertex_reflection.uniforms, fragment_reflection.uniforms),
+        "uniform_blocks" => merge_uniform_blocks(vertex_reflection.uniform_blocks, fragment_reflection.uniform_blocks),
+        "outputs" => fragment_reflection.outputs.map { |o| output_hash(o) }
+      }
+    end
+
+    # digestをrequireするのは実際にdigestを計算する経路(build/add_program)
+    # だけにするため、ここで遅延require する(M8g)。`glslkit/runtime` 経由で
+    # `parse`/`to_h` だけを使う限りこのメソッドは呼ばれず、digestはロードされない。
+    def program_digest(vertex_digest, fragment_digest)
+      require_relative "digest"
+      Digest.hexdigest("#{vertex_digest}:#{fragment_digest}")
+    end
+
+    def stage_hash(stage)
+      {"path" => stage.fetch(:path), "digest" => stage.fetch(:source).digest, "url" => stage.fetch(:url)}
+    end
+
+    def attribute_hash(attribute)
+      {"name" => attribute.name, "type" => attribute.type, "location" => attribute.location,
+       "array_size" => attribute.array_size}
+    end
+
+    def output_hash(output)
+      {"name" => output.name, "type" => output.type, "location" => output.location}
+    end
+
+    def merge_uniforms(vertex_uniforms, fragment_uniforms)
+      group_by_name(vertex: vertex_uniforms, fragment: fragment_uniforms).map do |name, by_stage|
+        first_stage, first_entry = by_stage.first
+        by_stage.each do |stage, entry|
+          next if entry.type == first_entry.type
+
+          raise StageMismatchError,
+            "uniform #{name.inspect} is #{first_entry.type.inspect} in #{first_stage} " \
+              "but #{entry.type.inspect} in #{stage}"
+        end
+
+        components = Types.components_for(first_entry.type)
+        {
+          "name" => name,
+          "type" => first_entry.type,
+          "array_size" => first_entry.array_size,
+          "setter" => first_entry.setter,
+          "matrix" => first_entry.matrix,
+          "sampler" => first_entry.sampler,
+          "components" => components,
+          "element_count" => components * first_entry.array_size,
+          "stages" => by_stage.keys.map(&:to_s)
+        }
+      end
+    end
+
+    def merge_uniform_blocks(vertex_blocks, fragment_blocks)
+      group_by_name(vertex: vertex_blocks, fragment: fragment_blocks).map do |name, by_stage|
+        first_stage, first_entry = by_stage.first
+        by_stage.each do |stage, entry|
+          next if entry.layout == first_entry.layout && entry.binding == first_entry.binding
+
+          raise StageMismatchError, "uniform block #{name.inspect} differs between #{first_stage} and #{stage}"
+        end
+
+        {
+          "name" => name,
+          "layout" => first_entry.layout,
+          "binding" => first_entry.binding,
+          "stages" => by_stage.keys.map(&:to_s)
+        }
+      end
+    end
+
+    # #nameを持つエントリの {vertex: [...], fragment: [...]} を受け取り、
+    # 初出順(vertexのエントリが先、fragmentのみの名前はその後)を保った
+    # name => {stage => entry} の順序付きHashを返す。
+    #
+    # 同一ステージのentries内に同名が2件以上あった場合、後のものが前のものを
+    # 静かに上書きする(`[stage] = entry`)。これは**入力がValidator(§8.3の
+    # E006)で検証済みで、同一ステージ内の重複が存在しないこと**を前提として
+    # 許容している。Validatorを経ていない入力でこのメソッドを単体利用すると、
+    # 重複が黙って握り潰されるので注意。
+    def group_by_name(stage_entries)
+      grouped = {}
+      stage_entries.each do |stage, entries|
+        entries.each { |entry| (grouped[entry.name] ||= {})[stage] = entry }
+      end
+      grouped
+    end
+  end
+end

data/lib/glslkit/minifier.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Glslkit
+  # コメントと不要な空白のみを除去する — 識別子のリネームも行数のマージも
+  # しない。プリプロセッサディレクティブ(#version, #line, #ifdefなど)は
+  # それぞれ独立した1物理行でなければならないため、改行は一切削除しない:
+  # 入力の各行は必ず出力のちょうど1行に対応するので、コード中に既にある
+  # #lineディレクティブの行番号は正しいまま保たれ、Reflectionの抽出結果も
+  # 変化しない。
+  module Minifier
+    COMMENT_PATTERN = %r{//[^\n]*|/\*.*?\*/}m
+
+    module_function
+
+    def minify(code)
+      strip_comments(code).each_line.map { |line| minify_line(line) }.join
+    end
+
+    def strip_comments(code)
+      code.gsub(COMMENT_PATTERN) do |match|
+        newlines = match.count("\n")
+        # 改行を含まないコメントでも、区切りは残しておく必要がある。
+        # 例えば `vec3/* x */foo` が `vec3foo` になってしまわないように。
+        newlines.positive? ? ("\n" * newlines) : " "
+      end
+    end
+
+    def minify_line(line)
+      ending = line.end_with?("\n") ? "\n" : ""
+      "#{line.chomp.strip.gsub(/[ \t]+/, " ")}#{ending}"
+    end
+  end
+end