spinel_kit 0.1.0

data/lib/spinel_kit/log.rb

@@ -0,0 +1,87 @@
+# SpinelKit::Log -- minimal levelled logger for spinel-AOT'd apps.
+#
+# WHY THIS EXISTS. CRuby's stdlib `Logger` is metaprogrammed (the severity
+# dispatch loop, the formatter API, the device-rotation logic) and the
+# spinelgems catalog rejects it (unresolved calls). Most app code that wants
+# logging really wants three things: a level guard, a formatted line, and a
+# destination. Ported verbatim from Tep::Logger; toy gains it for free.
+#
+# Surface
+# -------
+#   logger = SpinelKit::Log.new
+#   logger.set_level("info")        # one of: debug / info / warn / error
+#   logger.info("server up on " + port.to_s)
+#   logger.error("db connect failed")
+#
+#   # File output: appends to the path. Leave unset for stderr.
+#   logger.to_file("/var/log/app.log")
+#
+# Each line is `[<unix_seconds>] [<level>] <message>`. The integer-seconds
+# timestamp is what spinel exposes from `Time.now`; wider strftime support
+# would need a C-shim (defer until callers ask for it).
+#
+# SPINEL NAMING DISCIPLINE: the method/param names below are the donor's
+# proven-green spellings; the class-side `level_value` keeps the comparison
+# a pure function so spinel pins its arg type to :str cleanly via a consumer
+# type-seed. See docs/spinel-discipline.md.
+module SpinelKit
+  class Log
+    attr_accessor :min_level, :file_path
+
+    def initialize
+      @min_level = "info"
+      @file_path = ""
+    end
+
+    def set_level(name); @min_level = name; end
+    def to_file(path);   @file_path = path; end
+    def to_stderr;       @file_path = ""; end
+
+    def debug(msg); log("debug", msg); end
+    def info(msg);  log("info",  msg); end
+    def warn(msg);  log("warn",  msg); end
+    def error(msg); log("error", msg); end
+
+    def log(level, msg)
+      if !should_log?(level)
+        return
+      end
+      line = format_line(level, msg)
+      if @file_path.length > 0
+        File.open(@file_path, "a") do |f|
+          f.puts(line)
+        end
+      else
+        $stderr.puts(line)
+      end
+    end
+
+    def should_log?(level)
+      Log.level_value(level) >= Log.level_value(@min_level)
+    end
+
+    # Class-side helper so the comparison stays a pure function and spinel
+    # pins its arg type to :str cleanly via a consumer-side type-seed.
+    def self.level_value(name)
+      if name == "debug"
+        return 0
+      end
+      if name == "info"
+        return 1
+      end
+      if name == "warn"
+        return 2
+      end
+      if name == "error"
+        return 3
+      end
+      # Unknown level -- treat as info so misspelled labels don't vanish
+      # silently.
+      1
+    end
+
+    def format_line(level, msg)
+      "[" + Time.now.to_i.to_s + "] [" + level + "] " + msg
+    end
+  end
+end

data/lib/spinel_kit/version.rb

@@ -0,0 +1,6 @@
+# SpinelKit version. Kept in its own file so the gemspec can read it
+# without loading the rest of the library (the json/git/log modules pull
+# in no deps, but this matches the toy/tep convention exactly).
+module SpinelKit
+  VERSION = "0.1.0"
+end

data/lib/spinel_kit.rb

@@ -0,0 +1,39 @@
+# SpinelKit -- the Spinel stdlib-surface gem.
+#
+# A pure-Ruby, Spinel-safe toolkit holding the generic "stdlib substitute"
+# shims that every Spinel-compiled project would otherwise hand-roll. Spinel
+# (the Ruby->native AOT compiler) cannot lower large chunks of CRuby stdlib
+# -- the `json` gem's C-ext fast path and metaprogrammed pure-Ruby fallback,
+# stdlib `Logger`, C-ext git bindings -- and the spinelgems compatibility
+# catalog confirms there is no verified gem to reuse for any of them. So this
+# gem consolidates the shims toy and tep each grew independently:
+#
+#   SpinelKit::Json          -- JSON encoders (json.rb) + flat-key decoders
+#                               (json_decoder.rb).
+#   SpinelKit::Json::Builder -- incremental ordered-object builder.
+#   SpinelKit::Git           -- git provenance from .git/HEAD (was Toy::Git).
+#   SpinelKit::Log           -- minimal levelled logger (was Tep::Logger).
+#
+# MINIMAL-SURFACE REQUIRING. This umbrella requires everything for
+# convenience (and for CRuby use). But because Spinel compiles every loaded
+# method with no tree-shaking, a Spinel-compiled consumer should require ONLY
+# the file(s) it uses, to avoid compiling -- and degrading -- code it never
+# calls:
+#
+#   require "spinel_kit/json"          # encoders
+#   require "spinel_kit/json_decoder"  # decoders (require alongside json if you decode)
+#   require "spinel_kit/json_builder"  # builder
+#   require "spinel_kit/git"
+#   require "spinel_kit/log"
+#
+# No native extension (spinel-ext.json is []), no runtime dependencies. See
+# docs/adoption.md and docs/spinel-discipline.md.
+require_relative "spinel_kit/version"
+require_relative "spinel_kit/json"
+require_relative "spinel_kit/json_decoder"
+require_relative "spinel_kit/json_builder"
+require_relative "spinel_kit/git"
+require_relative "spinel_kit/log"
+
+module SpinelKit
+end

data/sig/spinel_kit/git.rbs

@@ -0,0 +1,8 @@
+module SpinelKit
+  class Git
+    def initialize: (String sha, String branch) -> void
+    def sha: () -> String
+    def branch: () -> String
+    def self.read: () -> SpinelKit::Git
+  end
+end

data/sig/spinel_kit/json.rbs

@@ -0,0 +1,15 @@
+# Advisory RBS for SpinelKit::Json encoders (lib/spinel_kit/json.rb).
+# Decoders are in json_decoder.rbs; the builder in json_builder.rbs.
+module SpinelKit
+  class Json
+    def self.escape: (String s) -> String
+    def self.hex2: (Integer n) -> String
+    def self.quote: (String s) -> String
+    def self.encode_pair_str: (String k, String v) -> String
+    def self.encode_pair_int: (String k, Integer v) -> String
+    def self.from_str_hash: (Hash[String, String] h) -> String
+    def self.from_int_hash: (Hash[String, Integer] h) -> String
+    def self.from_str_array: (Array[String] a) -> String
+    def self.from_int_array: (Array[Integer] a) -> String
+  end
+end

data/sig/spinel_kit/json_builder.rbs

@@ -0,0 +1,19 @@
+module SpinelKit
+  class Json
+    class Builder
+      def initialize: () -> void
+      def add_str: (String key, String value) -> String
+      def add_num: (String key, untyped value) -> String
+      def add_bool: (String key, bool value) -> String
+      def add_raw: (String key, String raw) -> String
+      def add_obj: (String key, SpinelKit::Json::Builder child) -> String
+      def dump: () -> String
+      def comma: () -> void
+
+      # self-contained escapers (byte-identical to SpinelKit::Json.*)
+      def self.quote: (String s) -> String
+      def self.escape: (String s) -> String
+      def self.hex2: (Integer n) -> String
+    end
+  end
+end

data/sig/spinel_kit/json_decoder.rbs

@@ -0,0 +1,21 @@
+# Advisory RBS for SpinelKit::Json decoders (lib/spinel_kit/json_decoder.rb).
+module SpinelKit
+  class Json
+    def self.get_str: (String s, String key) -> String
+    def self.get_int: (String s, String key) -> Integer
+    def self.get_float: (String s, String key) -> Float
+    def self.get_int_array: (String s, String key) -> Array[Integer]
+    def self.has_key?: (String s, String key) -> bool
+
+    # internal walkers
+    def self.skip_ws: (String s, Integer pos) -> Integer
+    def self.skip_str: (String s, Integer pos) -> Integer
+    def self.skip_value: (String s, Integer pos) -> Integer
+    def self.skip_container: (String s, Integer pos) -> Integer
+    def self.parse_str_value: (String s, Integer pos) -> String
+    def self.hex_nibble: (String c) -> Integer
+    def self.byte_to_chr: (Integer n) -> String
+    def self.parse_int_value: (String s, Integer pos) -> Integer
+    def self.find_value_start: (String s, String target_key) -> Integer
+  end
+end

data/sig/spinel_kit/log.rbs

@@ -0,0 +1,19 @@
+module SpinelKit
+  class Log
+    attr_accessor min_level: String
+    attr_accessor file_path: String
+
+    def initialize: () -> void
+    def set_level: (String name) -> String
+    def to_file: (String path) -> String
+    def to_stderr: () -> String
+    def debug: (String msg) -> void
+    def info: (String msg) -> void
+    def warn: (String msg) -> void
+    def error: (String msg) -> void
+    def log: (String level, String msg) -> void
+    def should_log?: (String level) -> bool
+    def self.level_value: (String name) -> Integer
+    def format_line: (String level, String msg) -> String
+  end
+end

data/sig/spinel_kit/version.rbs

@@ -0,0 +1,3 @@
+module SpinelKit
+  VERSION: String
+end

data/spinel-ext.json

@@ -0,0 +1 @@
+[]

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: spinel_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ori Pekelman
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  SpinelKit consolidates the pure-Ruby "stdlib substitute" shims that every
+  Spinel-compiled project would otherwise hand-roll. Spinel (the Ruby->native
+  AOT compiler) cannot lower the json gem's C-ext fast path / metaprogrammed
+  fallback, stdlib Logger, or C-ext git bindings -- and the spinelgems
+  compatibility catalog confirms no verified gem exists to reuse. So this gem
+  ships a JSON encoder+decoder+builder, .git/HEAD provenance, and a minimal
+  levelled logger. Pure Ruby, no native extension, no runtime dependencies --
+  it vendors cleanly via bundler-spinel. Pre-alpha.
+email:
+- ori@pekelman.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/adoption.md
+- docs/gem-audit-first.md
+- docs/spinel-discipline.md
+- docs/spinelgems-issues.md
+- lib/spinel_kit.rb
+- lib/spinel_kit/git.rb
+- lib/spinel_kit/json.rb
+- lib/spinel_kit/json_builder.rb
+- lib/spinel_kit/json_decoder.rb
+- lib/spinel_kit/log.rb
+- lib/spinel_kit/version.rb
+- sig/spinel_kit/git.rbs
+- sig/spinel_kit/json.rbs
+- sig/spinel_kit/json_builder.rbs
+- sig/spinel_kit/json_decoder.rbs
+- sig/spinel_kit/log.rbs
+- sig/spinel_kit/version.rbs
+- spinel-ext.json
+homepage: https://github.com/OriPekelman/spinelkit
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/OriPekelman/spinelkit
+  bug_tracker_uri: https://github.com/OriPekelman/spinelkit/issues
+  documentation_uri: https://github.com/OriPekelman/spinelkit#readme
+  changelog_uri: https://github.com/OriPekelman/spinelkit/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'The Spinel stdlib-surface gem: pure-Ruby JSON/Git/Log shims for AOT-compiled
+  apps'
+test_files: []