proscenium 0.26.0-aarch64-linux-gnu → 0.27.0-aarch64-linux-gnu

data/lib/proscenium/{cli → contexts}/rules.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Proscenium
-  module CLI
+  module Contexts
     # The author contract for a participating gem's package.json (#154): what `gem check` and
     # `install` refuse. Each rule yields a problem as [error code, format arguments]; the caller
     # decides whether a problem is fatal and how to word the escape.

data/lib/proscenium/contexts/stale.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../app_package'
+require_relative '../bundled_gems'
+require_relative 'map'
+require_relative 'projection'
+require_relative 'plan'
+require_relative 'messages'
+
+module Proscenium
+  module Contexts
+    # Whether an adopted app's committed gem dependency contexts are what its bundle calls for
+    # (#154). A stale context resolves a gem's imports against the wrong dependency graph, so the
+    # engine refuses to build until `proscenium install` brings them up to date. Built from
+    # committed files and Bundler only. The engine and the CLI both load it, so it loads nothing
+    # the CLI may not, and nothing of cli/ (both directions are pinned by
+    # test/cli/load_isolation_test.rb).
+    module Stale
+      COMMAND = 'Run `bundle exec proscenium install` and commit .proscenium/packages.'
+      # Why a committed context is not the one install would write, by its `drift`. The engine,
+      # `install --frozen` and `inspect` all classify a context with `drift`, so they name one
+      # cause.
+      REASONS = {
+        missing: "its dependency context hasn't been written yet",
+        invalid: 'its dependency context is not valid JSON',
+        projection: 'its dependency context was written by a different version of Proscenium',
+        edited: 'its dependency context was edited by hand',
+        changed: 'its NPM dependencies changed since its dependency context was written'
+      }.freeze
+      ORPHAN = '%<gem>s: its dependency context is left over, as the gem is no longer in the ' \
+               'bundle or no longer opted in'
+
+      module_function
+
+      # One line for each way the committed contexts differ from the bundle; empty when current, or
+      # before the app adopts. A context is stale when a participating gem has none, when its gem
+      # left Gemfile.lock or stopped participating, when its projection hash is not the gem's
+      # current one, or when that hash is not the one its own fields produce (a hand edit). A
+      # locked gem that is not installed (a group BUNDLE_WITHOUT excludes) keeps its context as
+      # committed.
+      def problems(root, specs = BundledGems.installed_specs, locked = BundledGems.locked_names)
+        registrar = Map.registrar(root)
+        return [] unless registrar
+
+        # Only the registration in use: a Bun app does not read a pnpm-workspace.yaml left over.
+        unparsable = unparsable_workspace(root) if registrar == 'pnpm-workspace.yaml'
+        return [unparsable] if unparsable
+
+        participating = BundledGems.participating(specs, overrides: BundledGems.overrides(root))
+        contexts = Plan.new(root, participating)
+        committed = Plan.committed(root)
+        found = contexts.problems.map { |code, args| Messages.message(code, **args) }
+        contexts.contexts.each_value do |context|
+          problem = compare(context, committed[context.gem])
+          found << "#{context.gem}: #{problem}" if problem
+        end
+        excluded = (locked || []) - specs.map(&:name)
+        orphans = committed.keys - participating.keys - excluded
+        found + orphans.map { format(ORPHAN, gem: it) } +
+          split_peers(root, contexts.contexts.keys & committed.keys)
+      rescue BundledGems::ConfigError => e
+        [e.message]
+      end
+
+      # An app counts as adopted when a pnpm-workspace.yaml it cannot parse names the contexts, so
+      # the engine never silently switches them off; it refuses until the file parses. Not
+      # package.json: Bun reads JSON that Ruby refuses, such as a trailing comma.
+      def unparsable_workspace(root)
+        path = File.join(root, 'pnpm-workspace.yaml')
+        return unless File.exist?(path)
+
+        Map.yaml_packages(Map.utf8(File.read(path)).delete_prefix(Map::BOM))
+        nil
+      rescue Psych::SyntaxError => e
+        "pnpm-workspace.yaml: it is not valid YAML (#{e.problem} at line #{e.line})"
+      end
+
+      # A peer meant to be shared that the gem and the app reach as two copies, as an app-only
+      # `pnpm update react` can leave it: install checks this too, and the engine repeats it for
+      # each generation.
+      def split_peers(root, gems)
+        gem, package = peer_split(root, gems)
+        gem ? [Messages.message('PSM-E-PEER-SPLIT', gem:, package:)] : []
+      end
+
+      # The first `[gem, package]` where a peer a context declares, that the app also depends on,
+      # resolves from the context and from the app to two different real directories; nil when
+      # every one is a single copy. A context that is missing or not valid JSON has no peers to
+      # check: `problems` and `install --frozen` report it themselves.
+      def peer_split(root, gems)
+        app = app_dependencies(root)
+        gems.each do |gem|
+          dir = File.join(root, Map::CONTEXTS, gem)
+          (peers(dir).keys & app).each do |name|
+            from_gem = real_dependency_dir(root, dir, name)
+            from_app = real_dependency_dir(root, root, name)
+            return [gem, name] unless from_gem.nil? || from_app.nil? || from_gem == from_app
+          end
+        end
+        nil
+      end
+
+      def peers(dir)
+        context = Map.read_json(File.join(dir, 'package.json'))
+        peers = context['peerDependencies'] if context.is_a?(Hash)
+        peers.is_a?(Hash) ? peers : {}
+      rescue Errno::ENOENT, JSON::ParserError
+        {}
+      end
+
+      def app_dependencies(root)
+        package = Map.read_json(File.join(root, 'package.json'))
+        return [] unless package.is_a?(Hash)
+
+        AppPackage::DEPENDENCY_FIELDS.flat_map { package[it].is_a?(Hash) ? package[it].keys : [] }
+      rescue Errno::ENOENT, JSON::ParserError
+        []
+      end
+
+      # The real directory `name` resolves to from `dir`, walking up node_modules as Node does,
+      # but no higher than the app at `root`.
+      def real_dependency_dir(root, dir, name)
+        current = dir
+        loop do
+          candidate = File.join(current, 'node_modules', name)
+          return File.realpath(candidate) if File.exist?(candidate)
+          return nil if current == root || current == File.dirname(current)
+
+          current = File.dirname(current)
+        end
+      end
+
+      # Why the engine refuses the committed context at `path`, or nil when it builds with it.
+      def compare(context, path) = REASONS[drift(context, path)]
+
+      # How the committed context at `path` differs from `context`, as a key of REASONS, or nil
+      # when it holds the same JSON. It is projected again from the fields it holds, not taken on
+      # trust: a hand edit that kept the reported hash would build against a graph no install
+      # produced.
+      def drift(context, path)
+        return :missing unless path && File.exist?(path)
+
+        committed = Map.read_json(path)
+        return :invalid unless committed.is_a?(Hash) && committed['proscenium'].is_a?(Hash)
+        return :projection if committed['proscenium']['projection'] != Projection::PROJECTION
+
+        # Parsed, so reformatting is not an edit; whole, so its name and the other generated fields
+        # count as well as its hash.
+        return :edited if Projection.project(context.gem, committed) != committed
+
+        :changed unless committed == JSON.parse(context.json)
+      rescue JSON::ParserError
+        :invalid
+      end
+
+      # The build error for the app at `root`, or nil when its contexts are current. Read once per
+      # mapping generation, as Map.config is.
+      def message(root, generation = 0)
+        @message ||= {}
+        key = [root, generation]
+        return @message[key] if @message.key?(key)
+
+        found = problems(root)
+        @message[key] = if found.any?
+                          "Gem dependency contexts are out of date:\n" \
+                            "#{found.map { "  - #{it}" }.join("\n")}\n#{COMMAND}"
+                        end
+      end
+
+      def reset! = @message = {}
+    end
+  end
+end

data/lib/proscenium/contexts.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Proscenium
+  # The model of gem dependency contexts (#154), which the engine and the `proscenium` CLI share.
+  # Its files load nothing of either: not ActiveSupport, and nothing under cli/. The CLI requires
+  # each file it needs; the engine reaches them through these autoloads.
+  module Contexts
+    autoload :Map, "#{__dir__}/contexts/map"
+    autoload :MappingGeneration, "#{__dir__}/contexts/mapping_generation"
+    autoload :Messages, "#{__dir__}/contexts/messages"
+    autoload :Plan, "#{__dir__}/contexts/plan"
+    autoload :Projection, "#{__dir__}/contexts/projection"
+    autoload :Rules, "#{__dir__}/contexts/rules"
+    autoload :Stale, "#{__dir__}/contexts/stale"
+  end
+end

data/lib/proscenium/css_module/path.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Proscenium
+  # @api public: an extension point for component gems (README, "Extending Proscenium").
   module CssModule::Path
     # Returns the path to the CSS module file for this class, where the file is located alongside
     # the class file, and has the same name as the class file, but with a `.module.css` extension.

data/lib/proscenium/css_module/transformer.rb

@@ -55,6 +55,8 @@ module Proscenium
     # @yieldparam transformed_name [String]
     # @yieldparam side_load_path [String, nil]
     # @return [Array<String>] the transformed CSS module names.
+    #
+    # @api public: an extension point for component gems (README, "Extending Proscenium").
     def class_names(*names, require_prefix: true)
       self.class.filter_names(names).map do |name|
         transformed, path = transform_class_name(name, require_prefix: require_prefix)
@@ -63,6 +65,19 @@ module Proscenium
       end
     end
 
+    # Transforms one class `name` to its CSS module name against the CSS module at `path`, whatever
+    # its prefix, and side loads that module. `original_name` is the name as the caller wrote it,
+    # for the error raised when there is no path.
+    #
+    #   transformer.class_name!(:title, 'cssm:title') # => "title_<digest>"
+    #
+    # @param name [String, Symbol]
+    # @param original_name [String]
+    # @param path [Pathname, String] the CSS module; by default, the transformer's own.
+    # @raise [Proscenium::CssModule::TransformError] when there is no path.
+    # @return [String] the transformed CSS module name.
+    #
+    # @api public: apps call it directly (README, "Extending Proscenium").
     def class_name!(name, original_name, path: @source_path)
       unless path
         raise Proscenium::CssModule::TransformError.new(original_name, 'CSS module path not given')

data/lib/proscenium/css_module.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# @api public: an extension point for component gems (README, "Extending Proscenium").
 module Proscenium::CssModule
   extend ActiveSupport::Autoload
 
@@ -17,14 +18,14 @@ module Proscenium::CssModule
 
   module ClassMethods
     def css_module(*names, path: nil)
-      path ||= respond_to?(:css_module_path) ? css_module_path : path
+      path ||= css_module_path if respond_to?(:css_module_path)
 
       cssm = Transformer.new(path)
       cssm.class_names(*names, require_prefix: false).join(' ')
     end
 
     def class_names(*names, path: nil)
-      path ||= respond_to?(:css_module_path) ? css_module_path : path
+      path ||= css_module_path if respond_to?(:css_module_path)
       names = Transformer.filter_names(names)
 
       cssm = Transformer.new(path)

data/lib/proscenium/helper.rb

@@ -45,9 +45,14 @@ module Proscenium
       @proscenium_sideload_assets_options ||= {}
     end
 
+    # A tag helper's source with no leading slash, looked up in the manifest's own key space:
+    # `/app/...` for an app file, `@rubygems/...` for a gem's. An entry holds its outputs, the
+    # entry's own first. With no entry, the URL the middleware serves it at, as Resolver builds it.
     def compute_asset_path(path, options = {})
       if %i[javascript stylesheet].include?(options[:type])
-        return Proscenium::Manifest[path] || "/#{path}"
+        gem = path.start_with?('@rubygems/')
+        return Proscenium::Manifest[gem ? path : "/#{path}"]&.first ||
+               (gem ? "/node_modules/#{path}" : "/#{path}")
       end
 
       super

data/lib/proscenium/importer.rb

@@ -32,7 +32,9 @@ module Proscenium
       #   or a URL, which has no file on disk. Should be the actual asset file, eg. app.css,
       #   some/component.js.
       # @return [String|nil] the digest of the imported file path if a css module (*.module.css).
-      def import(filepath = nil, sideloaded: false, **)
+      #
+      # @api public: an extension point for component gems (README, "Extending Proscenium").
+      def import(filepath, sideloaded: false, **)
         self.imported ||= {}
 
         if filepath.end_with?('.module.css')
@@ -90,6 +92,8 @@ module Proscenium
       #
       # @param filepath [Pathname] Absolute file system path of the Ruby file to sideload.
       # @param options [Hash] Options to pass to `import`.
+      #
+      # @api public: an extension point for component gems (README, "Extending Proscenium").
       def sideload(filepath, **options)
         return if !Proscenium.config.side_load || (options[:js] == false && options[:css] == false)
 
@@ -129,6 +133,10 @@ module Proscenium
         end
       end
 
+      # Yields each imported stylesheet, with its options. `delete: true` also removes each one from
+      # the imports, so it is written only once.
+      #
+      # @api public: apps call it to write their own tags (README, "Extending Proscenium").
       def each_stylesheet(delete: false)
         return if imported.blank?
 
@@ -142,6 +150,10 @@ module Proscenium
         delete ? imported.delete_if(&blk) : imported.each(&blk)
       end
 
+      # Yields each imported script, with its options. `delete: true` also removes each one from the
+      # imports, so it is written only once.
+      #
+      # @api public: apps call it to write their own tags (README, "Extending Proscenium").
       def each_javascript(delete: false)
         return if imported.blank?
 

data/lib/proscenium/middleware/base.rb

@@ -3,8 +3,6 @@
 module Proscenium
   class Middleware
     class Base
-      include ActiveSupport::Benchmarkable
-
       def self.attempt(request)
         new(request).renderable!&.attempt
       end
@@ -70,8 +68,6 @@ module Proscenium
         when '.js', '.mjs', '.ts', '.tsx', '.jsx' then 'application/javascript'
         when '.css' then 'text/css'
         when '.map' then 'application/json'
-        else
-          ::Rack::Mime.mime_type(::File.extname(path_to_build), nil) || 'application/javascript'
         end
       end
 

data/lib/proscenium/middleware.rb

@@ -4,8 +4,6 @@ module Proscenium
   class Middleware
     extend ActiveSupport::Autoload
 
-    class BuildError < Error; end
-
     autoload :Base
     autoload :Esbuild
     autoload :RubyGems

data/lib/proscenium/railtie.rb

@@ -36,16 +36,16 @@ module Proscenium
 
       Proscenium::Manifest.load!
 
-      project = Proscenium::ContextMap.project_root
-      if (notice = Proscenium::ContextMap.adoption_notice(project))
+      project = Proscenium::Contexts::Map.project_root
+      if (notice = Proscenium::Contexts::Map.adoption_notice(project))
         Rails.logger.info "[Proscenium] #{notice}"
       end
       # Production finds stale contexts at assets:precompile, which refuses to compile. Elsewhere
       # the first mapping generation starts here, so a change after boot, such as running
       # `proscenium install`, starts the next one. No Go call: Puma may fork after boot.
       unless Rails.env.production?
-        generation, = Proscenium::MappingGeneration.refresh(project)
-        if (stale = Proscenium::StaleContexts.message(project, generation))
+        generation, = Proscenium::Contexts::MappingGeneration.refresh(project)
+        if (stale = Proscenium::Contexts::Stale.message(project, generation))
           Rails.logger.warn "[Proscenium] #{stale}"
         end
       end

data/lib/proscenium/resolver.rb

@@ -10,6 +10,8 @@ module Proscenium
     # @param as_array [Boolean] whether or not to return the manifest path, non-manifest path, and
     #   absolute file system path as an array. Only returns the resolved path if false (default).
     # @return [String, Array<String>]
+    #
+    # @api public: an extension point for component gems (README, "Extending Proscenium").
     def self.resolve(path, as_array: false)
       # Normalised before anything reads it, the guard and the cache key included. The bun test
       # harness hands this Bun's own spelling of a module path, which on Windows is `D:\...`;
@@ -55,7 +57,7 @@ module Proscenium
     def self.generation
       return 0 if Rails.env.production?
 
-      number, changed = MappingGeneration.refresh(ContextMap.project_root)
+      number, changed = Contexts::MappingGeneration.refresh(Contexts::Map.project_root)
       reset if changed
       number
     end

data/lib/proscenium/side_load.rb

@@ -38,7 +38,7 @@ module Proscenium
           opts = opts.merge(data: opts[:data] || {})
           opts = opts.merge(preload_links_header: false) if fragments
 
-          out << helpers.stylesheet_link_tag(path.delete_prefix('/'), extname: false, **opts)
+          out << helpers.stylesheet_link_tag(path, extname: false, **opts)
         end
 
         if fragments
@@ -64,7 +64,7 @@ module Proscenium
           opts = opts[:js].is_a?(Hash) ? opts[:js] : {}
           opts = opts.merge(preload_links_header: false) if fragments
 
-          out << helpers.javascript_include_tag(path.delete_prefix('/'), extname: false, **opts)
+          out << helpers.javascript_include_tag(path, extname: false, **opts)
         end
 
         if fragments
@@ -95,6 +95,8 @@ module Proscenium
       #
       # If the class responds to `.sideload`, it will be called after the regular side loading. You
       # can use this to customise what is side loaded.
+      #
+      # @api public: an extension point for component gems (README, "Extending Proscenium").
       def sideload_inheritance_chain(obj, options)
         return unless Proscenium.config.side_load
 
@@ -168,6 +170,8 @@ module Proscenium
       # attribute, so writing to it would leak one request's options into every later one. Values
       # other than hashes are passed through as they are, not copied: `dup` on an ActiveRecord
       # model returns a new record with no id.
+      #
+      # @api public: an extension point for component gems (README, "Extending Proscenium").
       def merge_options(base, override, receiver)
         options = base.nil? ? {} : base
         options = { js: options, css: options } unless options.is_a?(Hash)

data/lib/proscenium/source_path.rb

@@ -2,6 +2,8 @@
 
 # Include this into any class to expose a `source_path` class and instance method, which will return
 # the absolute file system path to the current object.
+#
+# @api public: an extension point for component gems (README, "Extending Proscenium").
 module Proscenium::SourcePath
   def self.included(base)
     base.extend ClassMethods

data/lib/proscenium/utils.rb

@@ -79,7 +79,7 @@ module Proscenium
     # Example:
     #
     #   def tab(name, *args, href:, **attributes)
-    #     Hue::Utils.merge_bang_attributes!(args, attributes, [:current])
+    #     UiGem::Utils.merge_bang_attributes!(args, attributes, [:current])
     #   end
     #
     # Allowing you to use either of the following API's:
@@ -87,6 +87,7 @@ module Proscenium
     #   tab 'Tab 1', required: true
     #   tab 'Tab 1', :required!
     #
+    # @api public: an extension point for component gems (README, "Extending Proscenium").
     def merge_bang_attributes!(names, kw_attributes, allowed)
       allowed.each do |name|
         sym_name = name.to_sym

data/lib/proscenium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Proscenium
-  VERSION = '0.26.0'
+  VERSION = '0.27.0'
 end

data/lib/proscenium.rb

@@ -2,12 +2,15 @@
 
 require 'active_support'
 require_relative 'proscenium/error'
+# Required rather than autoloaded: the model's files are also required directly (by the CLI), and
+# one that defined Contexts first would leave its autoloads unregistered.
+require_relative 'proscenium/contexts'
 
 module Proscenium
   extend ActiveSupport::Autoload
 
-  # Default paths for Rails assets. Used by the `compute_asset_path` helper to maintain Rails
-  # default conventions of where JS and CSS files are located.
+  # Rails' default asset directories. Nothing in Proscenium reads this; it is public, and its
+  # removal waits on a release note (H-3 in docs/AUDIT.md, closed as not planned in #92).
   DEFAULT_RAILS_ASSET_PATHS = {
     stylesheet: 'app/assets/stylesheets/',
     javascript: 'app/javascript/'
@@ -39,9 +42,6 @@ module Proscenium
   autoload :Importer
   autoload :Resolver
   autoload :BundledGems
-  autoload :ContextMap
-  autoload :StaleContexts
-  autoload :MappingGeneration
 
   class Deprecator
     def deprecation_warning(name, message, _caller_backtrace = nil)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: proscenium
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: aarch64-linux-gnu
 authors:
 - Joel Moss
@@ -61,13 +61,13 @@ files:
 - lib/proscenium.rb
 - lib/proscenium/app_package.rb
 - lib/proscenium/builder.rb
+- lib/proscenium/builder/request.rb
 - lib/proscenium/bundled_gems.rb
 - lib/proscenium/cli.rb
 - lib/proscenium/cli/brackets.rb
 - lib/proscenium/cli/bun_linker.rb
 - lib/proscenium/cli/capabilities.json
 - lib/proscenium/cli/collisions.rb
-- lib/proscenium/cli/contexts.rb
 - lib/proscenium/cli/diff.rb
 - lib/proscenium/cli/error.rb
 - lib/proscenium/cli/gem_archive.rb
@@ -82,14 +82,19 @@ files:
 - lib/proscenium/cli/project_lock.rb
 - lib/proscenium/cli/registration.rb
 - lib/proscenium/cli/reporter.rb
-- lib/proscenium/cli/rules.rb
 - lib/proscenium/cli/runner.rb
 - lib/proscenium/cli/verify.rb
-- lib/proscenium/context_map.rb
+- lib/proscenium/contexts.rb
+- lib/proscenium/contexts/map.rb
+- lib/proscenium/contexts/mapping_generation.rb
+- lib/proscenium/contexts/messages.rb
+- lib/proscenium/contexts/plan.rb
+- lib/proscenium/contexts/projection.rb
+- lib/proscenium/contexts/rules.rb
+- lib/proscenium/contexts/stale.rb
 - lib/proscenium/css_module.rb
 - lib/proscenium/css_module/path.rb
 - lib/proscenium/css_module/transformer.rb
-- lib/proscenium/dependency_context.rb
 - lib/proscenium/ensure_loaded.rb
 - lib/proscenium/error.rb
 - lib/proscenium/ext/proscenium
@@ -98,7 +103,6 @@ files:
 - lib/proscenium/importer.rb
 - lib/proscenium/log_subscriber.rb
 - lib/proscenium/manifest.rb
-- lib/proscenium/mapping_generation.rb
 - lib/proscenium/middleware.rb
 - lib/proscenium/middleware/base.rb
 - lib/proscenium/middleware/chunks.rb
@@ -115,7 +119,6 @@ files:
 - lib/proscenium/runtime/server.rb
 - lib/proscenium/side_load.rb
 - lib/proscenium/source_path.rb
-- lib/proscenium/stale_contexts.rb
 - lib/proscenium/templates/rescues/build_error.html.erb
 - lib/proscenium/utils.rb
 - lib/proscenium/version.rb