meshtastic 0.0.179 → 0.0.181

data/lib/meshtastic/telemetry.rb

@@ -4,13 +4,13 @@ require 'meshtastic/telemetry_pb'
 
 module Meshtastic
   class Telemetry
-    def self.build(opts = {})
+    public_class_method def self.build(opts = {})
       telemetry = new
       telemetry.time = opts[:time].to_i if opts[:time]
       telemetry
     end
 
-    def self.request(opts = {})
+    public_class_method def self.request(opts = {})
       data = Meshtastic::Data.new(
         portnum: :TELEMETRY_APP,
         payload: build(opts).to_proto,
@@ -19,14 +19,23 @@ module Meshtastic
       Meshtastic.deliver_data(opts.merge(data: data, port_num: Meshtastic::PortNum::TELEMETRY_APP, want_response: true))
     end
 
-    def self.authors
+    public_class_method def self.authors
       "AUTHOR(S):\n        0day Inc. <support@0dayinc.com>\n      "
     end
 
-    def self.help
-      puts "USAGE:
-        #{self}.request(serial_obj: serial_obj, to: '!aabbccdd')
+    public_class_method def self.help
+      puts "        USAGE:
+        # Run the build class method for this module.
+        #{self}.build(
+          time: 'optional - value for time passed into build'
+        )
+
+        # Run the request class method for this module.
+        #{self}.request
+
+        # Run the authors class method for this module.
         #{self}.authors
+
       "
     end
   end

data/lib/meshtastic/traceroute.rb

@@ -4,13 +4,13 @@ require 'meshtastic/mesh_pb'
 
 module Meshtastic
   module Traceroute
-    def self.encode(opts = {})
+    public_class_method def self.encode(opts = {})
       discovery = Meshtastic::RouteDiscovery.new
       Array(opts[:route]).each { |hop| discovery.route << hop }
       discovery
     end
 
-    def self.send(opts = {})
+    public_class_method def self.send(opts = {})
       data = Meshtastic::Data.new(
         portnum: :TRACEROUTE_APP,
         payload: encode(opts).to_proto,
@@ -19,14 +19,23 @@ module Meshtastic
       Meshtastic.deliver_data(opts.merge(data: data, port_num: Meshtastic::PortNum::TRACEROUTE_APP, want_response: true))
     end
 
-    def self.authors
+    public_class_method def self.authors
       "AUTHOR(S):\n        0day Inc. <support@0dayinc.com>\n      "
     end
 
-    def self.help
-      puts "USAGE:
-        #{self}.send(serial_obj: serial_obj, to: '!aabbccdd')
+    public_class_method def self.help
+      puts "        USAGE:
+        # Run the encode class method for this module.
+        #{self}.encode(
+          route: 'optional - value for route passed into encode'
+        )
+
+        # Run the send class method for this module.
+        #{self}.send
+
+        # Run the authors class method for this module.
         #{self}.authors
+
       "
     end
   end

data/lib/meshtastic/util.rb

@@ -62,8 +62,10 @@ module Meshtastic
     # Display Usage for this Module
 
     public_class_method def self.help
-      puts "USAGE:
+      puts "        USAGE:
+        # Run the authors class method for this module.
         #{self}.authors
+
       "
     end
   end

data/lib/meshtastic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Meshtastic
-  VERSION = '0.0.179'
+  VERSION = '0.0.181'
 end

data/lib/meshtastic/xmodem.rb

@@ -4,7 +4,7 @@ require 'meshtastic/xmodem_pb'
 
 module Meshtastic
   module Xmodem
-    def self.encode(opts = {})
+    public_class_method def self.encode(opts = {})
       packet = Meshtastic::XModem.new
       packet.control = opts.fetch(:control, :SOH)
       packet.seq = opts[:seq].to_i if opts[:seq]
@@ -12,14 +12,21 @@ module Meshtastic
       packet
     end
 
-    def self.authors
+    public_class_method def self.authors
       "AUTHOR(S):\n        0day Inc. <support@0dayinc.com>\n      "
     end
 
-    def self.help
-      puts "USAGE:
-        #{self}.encode(control: :SOH, seq: 1, buffer: data)
+    public_class_method def self.help
+      puts "        USAGE:
+        # Run the encode class method for this module.
+        #{self}.encode(
+          seq: 'optional - value for seq passed into encode',
+          buffer: 'optional - value for buffer passed into encode'
+        )
+
+        # Run the authors class method for this module.
         #{self}.authors
+
       "
     end
   end

data/lib/meshtastic.rb

@@ -67,11 +67,28 @@ module Meshtastic
 
   # Display a List of Every Meshtastic Module
 
+  public_class_method def self.authors
+    "AUTHOR(S):\n      0day Inc. <support@0dayinc.com>\n    "
+  end
+
   public_class_method def self.help
-    constants.sort
+    puts "        USAGE:
+        # Run the deliver_data class method for this module.
+        #{self}.deliver_data(
+          data: 'optional - value for data passed into deliver_data',
+          serial_obj: 'optional - value for serial_obj passed into deliver_data',
+          bluetooth_obj: 'optional - value for bluetooth_obj passed into deliver_data',
+          tcp_obj: 'optional - value for tcp_obj passed into deliver_data',
+          mqtt_obj: 'optional - value for mqtt_obj passed into deliver_data'
+        )
+
+        # Run the authors class method for this module.
+        #{self}.authors
+
+    "
   end
 
-  def self.deliver_data(opts = {})
+  public_class_method def self.deliver_data(opts = {})
     raise ArgumentError, 'data is required' unless opts[:data].is_a?(Meshtastic::Data)
 
     if opts[:serial_obj]
@@ -80,8 +97,10 @@ module Meshtastic
       Bluetooth.send_data(opts)
     elsif opts[:tcp_obj]
       TCP.send_data(opts)
+    elsif opts[:mqtt_obj]
+      MQTT.send_data(opts)
     else
-      raise ArgumentError, 'serial_obj, bluetooth_obj, or tcp_obj is required'
+      raise ArgumentError, 'serial_obj, bluetooth_obj, tcp_obj, or mqtt_obj is required'
     end
   end
 end

data/spec/conventions_spec.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# Global source-level conventions for every Ruby module under lib/meshtastic
+# (same rules as /opt/pwn/spec/conventions_spec.rb).
+#
+# RULES
+#   0. Every method on a Meshtastic namespace *module* MUST be referenced via
+#      `self.<method_name>` with public_class_method / private_class_method.
+#      Bare `def foo` at module scope fails. So does `module_function`.
+#      Nested `class` instance methods and class_eval / `class <<` are exempt.
+#   1. Module methods MUST be declared with an explicit visibility decorator
+#      immediately preceding `def self.<name>` on the same line.
+#   2. Methods that accept arguments MUST take exactly `(opts = {})`.
+#   3. Methods declared `(opts = {})` MUST consume opts in the body.
+#   4. Every leaf module file MUST define `def self.help`.
+#   5. Every leaf module file MUST define `def self.authors`.
+#   6. Every public class method except `help` MUST appear in that module's
+#      `help` method — including `authors`. Directly above each method, `help`
+#      MUST print a brief purpose line. Methods that take `(opts = {})` MUST
+#      document each `opts[:key]` they read as `required` or `optional` plus an
+#      operator-usable description — same shape as PWN::WWW::Google.help.
+
+module MeshtasticConventions
+  ROOT = File.expand_path('..', __dir__)
+  LIB  = File.join(ROOT, 'lib', 'meshtastic')
+
+  GLOBAL_ALLOWLIST = [
+    'lib/meshtastic/version.rb' # VERSION constant only
+  ].freeze
+
+  NAMESPACE_INDEX_FILES = [].freeze
+
+  RB_FILES = (
+    Dir[File.join(LIB, '**', '*.rb')] + [File.join(ROOT, 'lib', 'meshtastic.rb')]
+  ).reject do |f|
+    rel = f.sub("#{ROOT}/", '')
+    GLOBAL_ALLOWLIST.include?(rel) || rel.end_with?('_pb.rb')
+  end.sort.freeze
+
+  MODULE_FILES = RB_FILES.select { |f| File.read(f).match?(/^\s*module\s+\w/) }.freeze
+
+  SELF_DEF_RE = /^([ \t]*)((?:public_class_method|private_class_method)\s+)?def self\.([a-z_][\w?!]*)(?:\(([^)]*)\))?/
+
+  BARE_DEF_RE = /^[ \t]*def ([a-z_][\w?!]*)(?:\(([^)]*)\))?/
+
+  MODULE_FUNCTION_RE = /^\s*module_function\b/
+
+  CLASS_LIKE_OPEN_RE = /
+    \Aclass\b
+    | \.class_eval\b
+    | \.module_eval\b
+    | \Aclass_eval\b
+    | \Amodule_eval\b
+    | \Aclass\s*<<
+    | \bClass\.new\b
+    | \bStruct\.new\b
+    | \bModule\.new\b
+    | \bData\.define\b
+  /x
+
+  MODULE_OPEN_RE = /\Amodule\s+[A-Z]/
+
+  module_function
+
+  def line_indent(line)
+    line[/^[ \t]*/].to_s.length
+  end
+
+  def scan_methods(path)
+    src   = File.read(path)
+    lines = src.lines
+    out   = []
+    lines.each_with_index do |line, idx|
+      m = line.match(SELF_DEF_RE)
+      next unless m
+
+      out << {
+        file: path,
+        line: idx + 1,
+        decorator: m[2]&.strip,
+        name: m[3],
+        arglist: m[4],
+        body_excerpt: lines[(idx + 1)..(idx + 60)]&.join.to_s,
+        method_body: method_body_excerpt(lines, idx)
+      }
+    end
+    out
+  end
+
+  def method_body_excerpt(lines, idx)
+    indent = lines[idx][/^[ \t]*/]
+    buf = []
+    ((idx + 1)...lines.length).each do |i|
+      break if lines[i].match?(/^#{Regexp.escape(indent)}end\b/)
+
+      buf << lines[i]
+      break if buf.length >= 120
+    end
+    buf.join
+  end
+
+  def scan_bare_defs(path)
+    stack = []
+    out   = []
+    File.readlines(path).each_with_index do |line, idx|
+      stripped = line.strip
+      next if stripped.empty? || stripped.start_with?('#')
+
+      indent = line_indent(line)
+
+      if stripped == 'end' || stripped.match?(/\Aend\b/)
+        stack.pop while stack.any? && stack.last[:indent] >= indent
+        next
+      end
+
+      if stripped.match?(MODULE_OPEN_RE) && !stripped.match?(/\bend\b/)
+        stack.pop while stack.any? && stack.last[:indent] >= indent
+        stack << { type: :module, indent: indent }
+        next
+      end
+
+      if stripped.match?(CLASS_LIKE_OPEN_RE) && !stripped.match?(/\bend\b/)
+        stack.pop while stack.any? && stack.last[:indent] >= indent
+        stack << { type: :class, indent: indent }
+        next
+      end
+
+      next if line.match?(SELF_DEF_RE)
+
+      m = line.match(BARE_DEF_RE)
+      next unless m
+
+      container = stack.rfind { |frame| frame[:indent] < indent }
+      next if container.nil?
+      next if container[:type] == :class
+
+      out << {
+        file: path,
+        line: idx + 1,
+        name: m[1],
+        arglist: m[2]
+      }
+    end
+    out
+  end
+
+  def scan_module_function(path)
+    out = []
+    File.readlines(path).each_with_index do |line, idx|
+      next if line.match?(/^\s*#/)
+      next unless line.match?(MODULE_FUNCTION_RE)
+
+      out << { file: path, line: idx + 1 }
+    end
+    out
+  end
+
+  ALL_METHODS = MODULE_FILES.flat_map { |f| scan_methods(f) }.freeze
+  ALL_BARE_DEFS = MODULE_FILES.flat_map { |f| scan_bare_defs(f) }.freeze
+  ALL_MODULE_FUNCTIONS = MODULE_FILES.flat_map { |f| scan_module_function(f) }.freeze
+
+  HELP_SKIP = %w[help].freeze
+
+  def help_text(path)
+    lines = File.readlines(path)
+    idx = lines.find_index { |l| l.match?(/def self\.help\b/) }
+    return '' unless idx
+
+    indent = lines[idx][/^[ \t]*/]
+    buf = []
+    ((idx + 1)...lines.length).each do |i|
+      break if lines[i].match?(/^#{Regexp.escape(indent)}end\b/)
+
+      buf << lines[i]
+    end
+    buf.join
+  end
+
+  def opts_keys(body)
+    body.to_s.scan(/opts\[\s*:([A-Za-z_]\w*)\s*\]/).flatten.uniq
+  end
+
+  def thin_option_desc?(key, desc)
+    rest = desc.to_s.strip.sub(/\A(?:required|optional)\s*-\s*/i, '')
+    return true if rest.empty?
+
+    norm = rest.downcase.gsub(/[^a-z0-9]+/, ' ').strip
+    key_norm = key.to_s.downcase.tr('_', ' ')
+    return true if norm == key_norm
+
+    words = rest.split
+    words.length < 2 && rest.length < 18
+  end
+
+  def purpose_above?(help, name)
+    lines = help.to_s.lines
+    idx = lines.find_index { |l| l.match?(/\#\{self\}(?:::[A-Z]\w*)*\.#{Regexp.escape(name)}(?!\w)/) }
+    return false unless idx
+
+    prev = nil
+    (idx - 1).downto(0) do |i|
+      next if lines[i].strip.empty?
+
+      prev = lines[i]
+      break
+    end
+    return false unless prev
+
+    text = prev.strip.sub(/\A#\s*/, '')
+    return false if text.match?(/\AUSAGE:/i)
+    return false if text.match?(/\.\w+\s*\(/) || text.match?(/\#\{self\}/)
+    return false if text.match?(/\A\w+\s*=\s*(?:PWN|Meshtastic)::/)
+    return false if text.downcase.gsub(/[^a-z0-9]+/, ' ').strip == name.downcase.tr('_', ' ')
+
+    words = text.split
+    words.length >= 3 || text.length >= 20
+  end
+
+  def rel(path)
+    path.sub("#{ROOT}/", '')
+  end
+end
+
+describe 'Meshtastic module conventions' do
+  c = MeshtasticConventions
+
+  it '0) every Meshtastic module method is referenced via `self.<method_name>` (no bare module-level `def`, no module_function)' do
+    bare = c::ALL_BARE_DEFS
+    mfun = c::ALL_MODULE_FUNCTIONS
+    parts = []
+    unless bare.empty?
+      parts << 'bare module-level `def <name>` (use `public_class_method def self.<name>` / `private_class_method def self.<name>`):'
+      parts.concat(bare.map { |m| "  #{c.rel(m[:file])}:#{m[:line]}  def #{m[:name]}" })
+    end
+    unless mfun.empty?
+      parts << '`module_function` is forbidden (declare each method with def self.<name>):'
+      parts.concat(mfun.map { |m| "  #{c.rel(m[:file])}:#{m[:line]}  module_function" })
+    end
+    msg = parts.join("\n")
+    expect(bare + mfun).to be_empty, msg
+  end
+
+  it '1) every `def self.<name>` is decorated with public_class_method or private_class_method' do
+    bare = c::ALL_METHODS.select { |m| m[:decorator].nil? }
+    msg  = bare.map { |m| "  #{c.rel(m[:file])}:#{m[:line]}  def self.#{m[:name]}" }.join("\n")
+    expect(bare).to be_empty, "bare `def self.*` (add public_class_method / private_class_method):\n#{msg}"
+  end
+
+  it '2) every argument-accepting module method takes exactly `(opts = {})`' do
+    bad = c::ALL_METHODS.reject do |m|
+      a = m[:arglist]
+      a.nil? || a.strip.empty? || a.strip == 'opts = {}'
+    end
+    msg = bad.map { |m| "  #{c.rel(m[:file])}:#{m[:line]}  def self.#{m[:name]}(#{m[:arglist]})" }.join("\n")
+    expect(bad).to be_empty, "non-conforming arglists (use `(opts = {})`):\n#{msg}"
+  end
+
+  it '3) methods declared `(opts = {})` actually consume opts in the body' do
+    unused = c::ALL_METHODS.select do |m|
+      m[:arglist]&.strip == 'opts = {}' &&
+        !m[:body_excerpt].match?(/\bopts\s*\[|\bopts\.(?:dig|fetch|key\?|keys|values|merge|each|delete|map|\[)/)
+    end
+    msg = unused.map { |m| "  #{c.rel(m[:file])}:#{m[:line]}  def self.#{m[:name]}(opts = {})  # opts never read" }.join("\n")
+    expect(unused).to be_empty, "declared `(opts = {})` but never read opts (unpack at top of method):\n#{msg}"
+  end
+
+  it '4) every module file defines `def self.help`' do
+    missing = c::MODULE_FILES.reject do |f|
+      c::NAMESPACE_INDEX_FILES.include?(c.rel(f)) || File.read(f).match?(/def self\.help\b/)
+    end
+    msg = missing.map { |f| "  #{c.rel(f)}" }.join("\n")
+    expect(missing).to be_empty, "modules missing `def self.help`:\n#{msg}"
+  end
+
+  it '5) every module file defines `def self.authors`' do
+    missing = c::MODULE_FILES.reject do |f|
+      c::NAMESPACE_INDEX_FILES.include?(c.rel(f)) || File.read(f).match?(/def self\.authors\b/)
+    end
+    msg = missing.map { |f| "  #{c.rel(f)}" }.join("\n")
+    expect(missing).to be_empty, "modules missing `def self.authors`:\n#{msg}"
+  end
+
+  it '6) every public class method is documented in help with required/optional options (Google.help shape)' do
+    misses = []
+    c::MODULE_FILES.each do |path|
+      next if c::NAMESPACE_INDEX_FILES.include?(c.rel(path))
+
+      help = c.help_text(path)
+      misses << "#{c.rel(path)}  missing method authors in help" unless help.match?(/\.authors(?!\w)/)
+      pubs = c::ALL_METHODS.select do |m|
+        m[:file] == path &&
+          m[:decorator] == 'public_class_method' &&
+          !c::HELP_SKIP.include?(m[:name])
+      end
+      pubs.each do |meth|
+        name = meth[:name]
+        unless help.match?(/\.#{Regexp.escape(name)}(?!\w)/)
+          misses << "#{c.rel(path)}  missing method #{name} in help"
+          next
+        end
+        misses << "#{c.rel(path)}  #{name}: missing purpose line above the method in help" unless c.purpose_above?(help, name)
+        next unless meth[:arglist]&.strip == 'opts = {}'
+
+        c.opts_keys(meth[:method_body]).each do |key|
+          descs = help.scan(/#{Regexp.escape(key)}:\s*['"]((?:required|optional)\s*-\s*[^'"]+)/i).flatten
+          if descs.empty?
+            misses << "#{c.rel(path)}  #{name} option #{key}: missing required/optional description"
+            next
+          end
+          next unless descs.any? { |d| c.thin_option_desc?(key, d) }
+
+          misses << "#{c.rel(path)}  #{name} option #{key}: description too thin (say what to pass, not just the key name)"
+        end
+      end
+    end
+    extra = misses.length > 80 ? "\n... #{misses.length} total" : ''
+    expect(misses).to be_empty, "#{misses.first(80).join("\n")}#{extra}"
+  end
+end