herb 0.10.4 → 0.11.0

data/sig/herb/engine/runtime/html_safe_assertions.rbs

@@ -0,0 +1,99 @@
+# Generated from lib/herb/engine/runtime/html_safe_assertions.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Runtime
+      module HTMLSafeAssertions
+        MODES: untyped
+
+        MAX_VALUE_LENGTH: ::Integer
+
+        EVENT_HANDLER_NAMES: untyped
+
+        EVENT_HANDLER_PATTERN: ::Regexp
+
+        class Violation
+          attr_reader name: Symbol
+
+          attr_reader message: String
+
+          attr_reader snippet: String
+
+          # : (Symbol, String, String) -> void
+          def initialize: (Symbol, String, String) -> void
+
+          # : () -> String
+          def inspect: () -> String
+        end
+
+        class Check
+          attr_reader name: Symbol
+
+          attr_reader requires: Symbol
+
+          attr_reader pattern: Regexp
+
+          attr_reader message: String
+
+          # : (Symbol, Symbol, Regexp, String) -> void
+          def initialize: (Symbol, Symbol, Regexp, String) -> void
+
+          # : (String) -> Violation?
+          def violation_for: (String) -> Violation?
+
+          private
+
+          # : (MatchData) -> String
+          def message_for: (MatchData) -> String
+        end
+
+        CHECKS: untyped
+
+        CHECK_NAMES: untyped
+
+        class UnsafeHTMLError < StandardError
+          attr_reader value: untyped
+
+          attr_reader violations: Array[Violation]
+
+          attr_reader file: String?
+
+          attr_reader line: Integer?
+
+          attr_reader column: Integer?
+
+          attr_reader source: String?
+
+          # : (value: untyped, violations: Array[Violation], ?file: String?, ?line: Integer?, ?column: Integer?, ?source: String?) -> void
+          def initialize: (value: untyped, violations: Array[Violation], ?file: String?, ?line: Integer?, ?column: Integer?, ?source: String?) -> void
+
+          private
+
+          # : () -> String
+          def build_message: () -> String
+
+          # : () -> String
+          def location_suffix: () -> String
+
+          # : (String) -> String
+          def indent: (String) -> String
+
+          # : (String) -> String
+          def truncate: (String) -> String
+        end
+
+        def self.on_violation: () -> (^(UnsafeHTMLError) -> void)?
+
+        def self.on_violation=: ((^(UnsafeHTMLError) -> void)?) -> (^(UnsafeHTMLError) -> void)?
+
+        attr_accessor on_violation: (^(UnsafeHTMLError) -> void)?
+
+        # : (untyped, ?file: String?, ?line: Integer?, ?column: Integer?, ?source: String?, ?mode: Symbol, ?ignore: Array[Symbol]) -> untyped
+        def self.check: (untyped, ?file: String?, ?line: Integer?, ?column: Integer?, ?source: String?, ?mode: Symbol, ?ignore: Array[Symbol]) -> untyped
+
+        # : (untyped, ?ignore: Array[Symbol]) -> Array[Violation]
+        def self.violations_for: (untyped, ?ignore: Array[Symbol]) -> Array[Violation]
+      end
+    end
+  end
+end

data/sig/herb/engine/runtime/journal/summary.rbs

@@ -0,0 +1,172 @@
+# Generated from lib/herb/engine/runtime/journal/summary.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Runtime
+      class Journal
+        # What a journal says once its records are folded together.
+        #
+        # Read raw, a journal shows the same finding two hundred times. Folding on position turns
+        # that into one finding per place, which is both what an editor can show and the only form
+        # in which the history says something the requests do not.
+        #
+        # Everything here carries the number of times it was seen, because what this holds is
+        # evidence and not proof. A rewrite proposed from it is only as good as the renders that
+        # happened to run, so a reader gets counts and phrases them itself. Nothing here says
+        # "always".
+        class Summary
+          class Finding < Data
+            attr_reader line(): untyped
+
+            attr_reader column(): untyped
+
+            attr_reader end_line(): untyped
+
+            attr_reader end_column(): untyped
+
+            attr_reader code(): untyped
+
+            attr_reader origin(): untyped
+
+            attr_reader kind(): untyped
+
+            attr_reader severity(): untyped
+
+            attr_reader message(): untyped
+
+            attr_reader value(): untyped
+
+            attr_reader peak_message(): untyped
+
+            attr_reader description(): untyped
+
+            attr_reader observations(): untyped
+
+            attr_reader values(): untyped
+
+            attr_reader range(): untyped
+
+            attr_reader observed(): untyped
+
+            attr_reader observed_trimmed(): untyped
+
+            attr_reader recent(): untyped
+
+            attr_reader first_seen(): untyped
+
+            attr_reader last_seen(): untyped
+
+            attr_reader paths(): untyped
+
+            attr_reader runs(): untyped
+
+            def self.new: (untyped line, untyped column, untyped end_line, untyped end_column, untyped code, untyped origin, untyped kind, untyped severity, untyped message, untyped value, untyped peak_message, untyped description, untyped observations, untyped values, untyped range, untyped observed, untyped observed_trimmed, untyped recent, untyped first_seen, untyped last_seen, untyped paths, untyped runs) -> instance
+                        | (line: untyped, column: untyped, end_line: untyped, end_column: untyped, code: untyped, origin: untyped, kind: untyped, severity: untyped, message: untyped, value: untyped, peak_message: untyped, description: untyped, observations: untyped, values: untyped, range: untyped, observed: untyped, observed_trimmed: untyped, recent: untyped, first_seen: untyped, last_seen: untyped, paths: untyped, runs: untyped) -> instance
+
+            def self.members: () -> [ :line, :column, :end_line, :end_column, :code, :origin, :kind, :severity, :message, :value, :peak_message, :description, :observations, :values, :range, :observed, :observed_trimmed, :recent, :first_seen, :last_seen, :paths, :runs ]
+
+            def members: () -> [ :line, :column, :end_line, :end_column, :code, :origin, :kind, :severity, :message, :value, :peak_message, :description, :observations, :values, :range, :observed, :observed_trimmed, :recent, :first_seen, :last_seen, :paths, :runs ]
+          end
+
+          class Call < Data
+            attr_reader line(): untyped
+
+            attr_reader column(): untyped
+
+            attr_reader via(): untyped
+
+            attr_reader targets(): untyped
+
+            attr_reader per_parent(): untyped
+
+            attr_reader parents(): untyped
+
+            attr_reader renders(): untyped
+
+            attr_reader observations(): untyped
+
+            attr_reader first_seen(): untyped
+
+            attr_reader last_seen(): untyped
+
+            attr_reader paths(): untyped
+
+            def self.new: (untyped line, untyped column, untyped via, untyped targets, untyped per_parent, untyped parents, untyped renders, untyped observations, untyped first_seen, untyped last_seen, untyped paths) -> instance
+                        | (line: untyped, column: untyped, via: untyped, targets: untyped, per_parent: untyped, parents: untyped, renders: untyped, observations: untyped, first_seen: untyped, last_seen: untyped, paths: untyped) -> instance
+
+            def self.members: () -> [ :line, :column, :via, :targets, :per_parent, :parents, :renders, :observations, :first_seen, :last_seen, :paths ]
+
+            def members: () -> [ :line, :column, :via, :targets, :per_parent, :parents, :renders, :observations, :first_seen, :last_seen, :paths ]
+          end
+
+          class Call
+            # : () -> Integer
+            def peak: () -> Integer
+
+            # : () -> String?
+            def only_target: () -> String?
+          end
+
+          MAX_RECENT: Integer
+
+          attr_reader template: String
+
+          attr_reader digest: String
+
+          attr_reader findings: Array[Finding]
+
+          attr_reader calls: Array[Call]
+
+          attr_reader dropped: Integer
+
+          attr_reader first_seen: String?
+
+          # : (String, String, Array[Hash[String, untyped]]) -> Summary
+          def self.build: (String, String, Array[Hash[String, untyped]]) -> Summary
+
+          # : (Array[Hash[String, untyped]]) -> Array[Finding]
+          def self.fold_findings: (Array[Hash[String, untyped]]) -> Array[Finding]
+
+          # : (Array[Hash[String, untyped]]) -> Array[Call]
+          def self.fold_calls: (Array[Hash[String, untyped]]) -> Array[Call]
+
+          # : (Array[Hash[String, untyped]]) -> Finding
+          def self.finding_for: (Array[Hash[String, untyped]]) -> Finding
+
+          # : (Array[Hash[String, untyped]]) -> Call
+          def self.call_for: (Array[Hash[String, untyped]]) -> Call
+
+          # : (Array[Hash[String, untyped]]) -> Hash[String, untyped]
+          def self.newest: (Array[Hash[String, untyped]]) -> Hash[String, untyped]
+
+          # : (Array[Hash[String, untyped]]) -> Hash[String, untyped]
+          def self.worst: (Array[Hash[String, untyped]]) -> Hash[String, untyped]
+
+          # : (Array[Hash[String, untyped]]) -> Array[Hash[Symbol, untyped]]
+          def self.recent: (Array[Hash[String, untyped]]) -> Array[Hash[Symbol, untyped]]
+
+          # : (Hash[String, untyped]) -> Array[untyped]
+          def self.values_in: (Hash[String, untyped]) -> Array[untyped]
+
+          # : (Array[Hash[String, untyped]?]) -> Hash[untyped, Integer]
+          def self.merge_counts: (Array[Hash[String, untyped]?]) -> Hash[untyped, Integer]
+
+          # : (Array[String]) -> Hash[Symbol, untyped]?
+          def self.range: (Array[String]) -> Hash[Symbol, untyped]?
+
+          # : (untyped) -> Float?
+          def self.leading_number: (untyped) -> Float?
+
+          # : (template: String, digest: String, findings: Array[Finding], calls: Array[Call], dropped: Integer, first_seen: String?) -> void
+          def initialize: (template: String, digest: String, findings: Array[Finding], calls: Array[Call], dropped: Integer, first_seen: String?) -> void
+
+          # : () -> bool
+          def truncated?: () -> bool
+
+          # : () -> bool
+          def empty?: () -> bool
+        end
+      end
+    end
+  end
+end

data/sig/herb/engine/runtime/journal.rbs

@@ -0,0 +1,126 @@
+# Generated from lib/herb/engine/runtime/journal.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Runtime
+      # What a template did, kept after the request that did it is gone.
+      #
+      #     journal = Herb::Engine::Runtime::Journal.new(root: "tmp/herb")
+      #     journal.write(session.report, request: { method: "GET", path: "/posts" })
+      #     journal.summary("app/views/posts/_card.html.erb", digest)
+      #
+      # A report describes one request and dies with it, which is enough for the browser and no use
+      # to an editor. An editor has a file open and wants to know what happened in it, without
+      # knowing which request that was or whether the request has been made yet. So this is keyed by
+      # what the editor already has, a path and the text at that path:
+      #
+      #     tmp/herb/journal/app/views/posts/_card.html.erb.9f2a1c4e.jsonl
+      #
+      # The digest in the name is the whole staleness mechanism. An editor hashes its buffer, builds
+      # that path and opens it. A file edited since produces a different name, which does not exist,
+      # so a position recorded against text that no longer exists is never shown and nothing has to
+      # work out how far an edit moved things.
+      #
+      # Written the way `Dev::ServerEntry` writes its own registry: a known directory, one file per
+      # key, and pruning done by whoever happens to pass by rather than a separate sweep.
+      #
+      # What accumulates is the point. One request says a partial ran three queries. A journal says
+      # it ran between three and forty seven across two hundred renders, which is the shape of an
+      # N+1 and is not visible from any one request.
+      class Journal
+        RECORD_VERSION: Integer
+
+        DEFAULT_ROOT: String
+
+        DIRECTORY: String
+
+        EXTENSION: String
+
+        MAX_RECORDS: Integer
+
+        MAX_RECORD_BYTES: Integer
+
+        MIN_RECORD_BYTES: Integer
+
+        KEPT_DIGESTS: Integer
+
+        attr_reader root: Pathname
+
+        attr_reader max_records: Integer
+
+        attr_reader kept_digests: Integer
+
+        # : (?root: (String | Pathname), ?max_records: Integer, ?kept_digests: Integer) -> void
+        def initialize: (?root: String | Pathname, ?max_records: Integer, ?kept_digests: Integer) -> void
+
+        # : () -> Pathname
+        def directory: () -> Pathname
+
+        # : (String, String) -> Pathname?
+        def path_for: (String, String) -> Pathname?
+
+        # : (Herb::Engine::Runtime::Report, ?request: Hash[Symbol, untyped]?) -> String?
+        def write: (Herb::Engine::Runtime::Report, ?request: Hash[Symbol, untyped]?) -> String?
+
+        # : (String, String?) -> Herb::Engine::Runtime::Journal::Summary?
+        def summary: (String, String?) -> Herb::Engine::Runtime::Journal::Summary?
+
+        # : (String) -> Array[String]
+        def digests: (String) -> Array[String]
+
+        private
+
+        # : (Herb::Engine::Runtime::Report, Hash[Array[untyped], Array[String]], String, String, String?) -> void
+        def collect_findings: (Herb::Engine::Runtime::Report, Hash[Array[untyped], Array[String]], String, String, String?) -> void
+
+        # : (Herb::Engine::Runtime::Report, Hash[Array[untyped], Array[String]], String, String, String?) -> void
+        def collect_calls: (Herb::Engine::Runtime::Report, Hash[Array[untyped], Array[String]], String, String, String?) -> void
+
+        # : (Hash[String, Hash[Symbol, untyped]], Hash[Symbol, untyped]) -> Array[untyped]?
+        def call_site: (Hash[String, Hash[Symbol, untyped]], Hash[Symbol, untyped]) -> Array[untyped]?
+
+        # : (Herb::Diagnostic, String, String, String?) -> String?
+        def finding_line: (Herb::Diagnostic, String, String, String?) -> String?
+
+        # : (String, String, String) -> String
+        def header_for: (String, String, String) -> String
+
+        # : (Hash[Symbol, untyped]) -> String
+        def encode: (Hash[Symbol, untyped]) -> String
+
+        # : (Pathname) -> Array[Hash[String, untyped]]
+        def records_in: (Pathname) -> Array[Hash[String, untyped]]
+
+        # : (Pathname, header: String?, lines: Array[String]) -> void
+        def append: (Pathname, header: String?, lines: Array[String]) -> void
+
+        # : (File) -> bool
+        def over_cap?: (File) -> bool
+
+        # : (File, String?) -> void
+        def compact: (File, String?) -> void
+
+        # : (String) -> bool
+        def truncated?: (String) -> bool
+
+        # : (String) -> Integer
+        def truncated_count: (String) -> Integer
+
+        # : (Pathname) -> void
+        def collect_siblings: (Pathname) -> void
+
+        # : (Pathname) -> String
+        def base_of: (Pathname) -> String
+
+        # : (String?) -> String?
+        def safe_relative_path: (String?) -> String?
+
+        # : () -> String
+        def mint_run_id: () -> String
+
+        # : () -> String
+        def timestamp: () -> String
+      end
+    end
+  end
+end

data/sig/herb/engine/runtime/middleware.rbs

@@ -0,0 +1,96 @@
+# Generated from lib/herb/engine/runtime/middleware.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Runtime
+      # Scopes one diagnostics session to one request and hands what it collected to the browser.
+      #
+      #     config.middleware.use Herb::Engine::Runtime::Middleware
+      #
+      # One request is the right scope because a page is what the dev tools show: findings from every
+      # template that took part in it, in one payload, whoever found them.
+      #
+      # Given a journal, the same session is also written to disk, where it outlives the page and an
+      # editor can read it. Whoever mounts this middleware is often not the application, so the
+      # journal can be set on the class instead of passed:
+      #
+      #     Herb::Engine::Runtime::Middleware.journal = "tmp/herb"
+      #
+      # Nothing here is allowed to be the reason a page fails. A response it cannot safely touch is
+      # returned untouched, and any error while injecting, measuring or writing is swallowed in
+      # favour of the original response.
+      class Middleware
+        # Where a session goes when whoever mounted this middleware did not say. Left unset, nothing
+        # is written.
+        #
+        # Written out instead of as an `attr_accessor` in a `class << self` block, because rbs-inline
+        # emits that as an instance accessor and the signature would be wrong.
+        # : () -> untyped
+        def self.journal: () -> untyped
+
+        # : (untyped) -> void
+        def self.journal=: (untyped) -> void
+
+        HTML_CONTENT_TYPE: Regexp
+
+        BODY_END_TAG: Regexp
+
+        HEAD_END_TAG: Regexp
+
+        ANCHORS: Hash[Symbol, Regexp]
+
+        # Where the session for this request is left, so that anything holding the env can read what
+        # the page collected.
+        #
+        #     get "/posts"
+        #
+        #     request.env[Herb::Engine::Runtime::Middleware::ENV_KEY].entries
+        ENV_KEY: String
+
+        # : (untyped, ?inject: bool, ?journal: untyped) -> void
+        def initialize: (untyped, ?inject: bool, ?journal: untyped) -> void
+
+        # : (untyped) -> untyped
+        def call: (untyped) -> untyped
+
+        private
+
+        # : (Herb::Engine::Runtime::Session) -> void
+        def measure: (Herb::Engine::Runtime::Session) -> void
+
+        # : (Herb::Engine::Runtime::Session, untyped, untyped) -> void
+        def persist: (Herb::Engine::Runtime::Session, untyped, untyped) -> void
+
+        # : (untyped, untyped) -> Hash[Symbol, untyped]
+        def request_of: (untyped, untyped) -> Hash[Symbol, untyped]
+
+        # : (untyped) -> untyped
+        def coerce: (untyped) -> untyped
+
+        # : (untyped, Herb::Engine::Runtime::Report) -> untyped
+        def inject: (untyped, Herb::Engine::Runtime::Report) -> untyped
+
+        # : (String, Herb::Engine::Runtime::Report) -> String
+        def inject_channels: (String, Herb::Engine::Runtime::Report) -> String
+
+        # : (String, Herb::Engine::Runtime::Report) -> String
+        def inject_report: (String, Herb::Engine::Runtime::Report) -> String
+
+        # : (untyped) -> bool
+        def html?: (untyped) -> bool
+
+        # : (untyped) -> String?
+        def read: (untyped) -> String?
+
+        # : (untyped, String) -> void
+        def set_content_length: (untyped, String) -> void
+
+        # : (untyped, String) -> untyped
+        def header: (untyped, String) -> untyped
+
+        # : (untyped, String) -> untyped
+        def header_name: (untyped, String) -> untyped
+      end
+    end
+  end
+end

data/sig/herb/engine/runtime/observations.rbs

@@ -0,0 +1,38 @@
+# Generated from lib/herb/engine/runtime/observations.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Runtime
+      # What a producer observed, made fit to be written down.
+      #
+      # An observation is any object its producer chose to record, while both places it ends up are
+      # JSON: the journal on disk and the report a page carries. Anything that is not already a
+      # primitive has to become one, and there is a size past which an observation stops being worth
+      # keeping whole.
+      #
+      #     Observations.jsonable({ queries: [statement, connection] })
+      #     #=> { "queries" => ["SELECT 1", "#<ActiveRecord::ConnectionAdapters::SQLite3Adapter>"] }
+      #
+      # The default `to_s` of an object carries its memory address, which means nothing once the
+      # process is gone and differs on every run, so what is kept is the class name alone. It says
+      # an object was there without pretending to be it.
+      module Observations
+        MAX_SAMPLED: Integer
+
+        MAX_LENGTH: Integer
+
+        # : (untyped) -> untyped
+        def self.jsonable: (untyped) -> untyped
+
+        # : (untyped, ?sampled: Integer, ?length: Integer) -> Hash[untyped, untyped]
+        def self.trim: (untyped, ?sampled: Integer, ?length: Integer) -> Hash[untyped, untyped]
+
+        # : (untyped, ?Integer) -> untyped
+        def self.truncate: (untyped, ?Integer) -> untyped
+
+        # : (Hash[untyped, untyped]) -> Hash[String, untyped]
+        private def self.jsonable_hash: (Hash[untyped, untyped]) -> Hash[String, untyped]
+      end
+    end
+  end
+end

data/sig/herb/engine/runtime/report.rbs

@@ -0,0 +1,97 @@
+# Generated from lib/herb/engine/runtime/report.rb with RBS::Inline
+
+module Herb
+  class Engine
+    module Runtime
+      class Report
+        VERSION: Integer
+
+        MAX_TAG_LENGTH: Integer
+
+        MAX_DIAGNOSTICS: Integer
+
+        ATTRIBUTE: String
+
+        attr_reader meta: Hash[Symbol, untyped]
+
+        attr_reader sources: Hash[String, String]
+
+        attr_reader digests: Hash[String, String]
+
+        attr_reader nodes: Hash[String, Hash[String, Hash[Symbol, untyped]]]
+
+        attr_reader render_tree: Array[Hash[Symbol, untyped]]
+
+        # : (?max_diagnostics: Integer) -> void
+        def initialize: (?max_diagnostics: Integer) -> void
+
+        # : (Symbol) { () -> untyped } -> untyped
+        def channel: (Symbol) { () -> untyped } -> untyped
+
+        # : () -> Array[untyped]
+        def channels: () -> Array[untyped]
+
+        # : (Herb::Diagnostic) -> Herb::Diagnostic
+        def add: (Herb::Diagnostic) -> Herb::Diagnostic
+
+        # : (untyped) -> Report
+        def concat: (untyped) -> Report
+
+        # : (Symbol, untyped) -> void
+        def note: (Symbol, untyped) -> void
+
+        # : (String, String?) -> void
+        def source: (String, String?) -> void
+
+        # : (String?) -> String?
+        def digest_for: (String?) -> String?
+
+        # : (String, String?, String?, ?called_from: Array[untyped]?, ?digest: String?) -> void
+        def render: (String, String?, String?, ?called_from: Array[untyped]?, ?digest: String?) -> void
+
+        # : (String, Symbol, untyped, origin: String) -> void
+        def annotate: (String, Symbol, untyped, origin: String) -> void
+
+        # : () -> Array[Herb::Diagnostic]
+        def diagnostics: () -> Array[Herb::Diagnostic]
+
+        # : () -> bool
+        def empty?: () -> bool
+
+        # : () -> bool
+        def noted?: () -> bool
+
+        # : () -> bool
+        def reportable?: () -> bool
+
+        # : () -> Hash[Symbol, untyped]
+        def to_h: () -> Hash[Symbol, untyped]
+
+        alias to_hash to_h
+
+        # : (?untyped) -> String
+        def to_json: (?untyped) -> String
+
+        # : () -> String
+        def to_html: () -> String
+
+        private
+
+        # : (Herb::Diagnostic) -> Hash[Symbol, untyped]
+        def serialized: (Herb::Diagnostic) -> Hash[Symbol, untyped]
+
+        # : (Herb::Diagnostic) -> String?
+        def tag_source: (Herb::Diagnostic) -> String?
+
+        # : (String, Integer) -> String?
+        def template_line: (String, Integer) -> String?
+
+        # : (String) -> String?
+        def read_template: (String) -> String?
+
+        # : () -> String
+        def escaped_json: () -> String
+      end
+    end
+  end
+end