proscenium 0.26.1-x86_64-linux-gnu → 0.27.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 815da55e5651bb005e8c4e32491d98b5d8775b231b055fa682a17a58bb75d071
-  data.tar.gz: 93016be331926ffd92cb21492804fdd30acbbdaf33f09599322083c83d7ed6c2
+  metadata.gz: 1d6c5afd9078a48be6ebca7a839a34e30a64ae1c5d82e38ae9ab660f2b35a4e4
+  data.tar.gz: 9441d7864ad57c4db79a9d1966b88c2bb90fc8f8cc9c92fe3b7a25824bdd9efe
 SHA512:
-  metadata.gz: 68a1f37e2172224aa20470644e7a16c3a7a3f4537cdfeebe47366064b1d098718d94a90badb62372437bdad567a95565840b0e992c2f136ad93a5f04378a126a
-  data.tar.gz: 0bcf2175d9b0b88af24ea9e226cb13ffa900de6784235978e2448373b3a20d799c1536a4b54ce76be5e4bd805740b04215811b3ef65735b700f61f6b44247a59
+  metadata.gz: 3ca42f3ef2f473f07c45804e87b2b0b4299ad3984a8a37dddc0e477800265ab99fa3340eabfee1b14b36b60b0ee77c07504aa81e48e96f1690d48625be86bf0c
+  data.tar.gz: 877dcd79fc4693e3b06498a878f4d368fe66b1cba84f9ad9d21d7e68edb7df4fb88cdc1960274c1e860409963af914a747d898a7520d77912cabac74e6b62c3a

data/README.md

@@ -56,6 +56,7 @@
 - [Resolution](#resolution)
 - [Aliases](#aliases)
 - [Pre-compilation](#pre-compilation)
+- [Extending Proscenium](#extending-proscenium)
 - [Puma `preload_app!` and Cluster Mode](#puma-preload_app-and-cluster-mode)
 - [Thanks](#thanks)
 - [Development](#development)
@@ -103,7 +104,8 @@ fine; if not, `gem update --system`. Bundler 2.5.6 or newer resolves the platfor
 needing anything else from you.
 
 Installing on a platform not listed here gets you the platform-less gem, which carries no compiled
-library, and Proscenium will say so by name when it loads rather than failing somewhere inside FFI.
+library, and Proscenium will say so by name on its first build or resolve, rather than failing
+somewhere inside FFI.
 If your platform should be supported, please [open an
 issue](https://github.com/joelmoss/proscenium/issues).
 
@@ -742,6 +744,8 @@ p {
 
 A mixin must be defined at the root of a file. A `@define-mixin` inside a rule or an at-rule block such as `@media`, or inside another mixin, does not define anything: it is passed through as written, with a warning.
 
+A mixin from another file whose definition is malformed is refused: its `@mixin` is left as written, with a "malformed CSS" warning, and the stylesheet's other mixins still expand. A definition is malformed when it holds a bad token, such as a string broken by a newline, or when the file ends before closing it, inside an open comment, `url(` or escape (as when it is saved mid-edit). Malformed CSS in the stylesheet itself is returned as written, for esbuild to report.
+
 One stylesheet may expand at most 100,000 mixins, inserting at most 4 MiB (4,194,304 bytes) of mixin definitions, with mixins nested at most 100 deep, so a chain of mixins that each include another more than once cannot grow without bound. Past any limit, each remaining `@mixin` is left as written, with one warning.
 
 Each stylesheet reports at most 100 warnings, plus one saying how many more were not reported and, past a limit, the mixin limit warning. A precompile sends at most 100 errors and 100 warnings in all, then one more message for each saying how many more there were, so in a build that noisy the limit warning can be one of those counted.
@@ -909,10 +913,12 @@ treated as test, and so is served and precompiled unminified.
 
 ## Resolution
 
-Proscenium will serve files ending with any of these extension: `js,mjs,ts,css,jsx,tsx` from the following directories, and their sub-directories of your Rails application's root: `/app`, `/lib`, `/config`, `/node_modules`, `/vendor`.
+Proscenium will build and serve files ending with any of these extension: `js,mjs,ts,css,jsx,tsx` from the following directories, and their sub-directories of your Rails application's root: `/app`, `/lib`, `/config`, `/node_modules`.
 
 So a file at `/app/views/users/index.js` will be served from `https://localhost:3000/app/views/users/index.js`.
 
+`.js` and `.css` files under `/vendor` are served as they are, without building, and with `Cache-Control: public, max-age=3155695200, immutable`. A browser never asks for one again, so put a version in the path of each vendored file (`/vendor/foo/1.2.3/foo.js`), and change the path when the file changes. This suits a package you load at run time rather than bundle, such as one marked `external`.
+
 You can continue to access any file in the `/public` directory as you normally would. Proscenium will not process files in the `/public` directory.
 
 If requesting a file that exists in a root directory and the public directory, the file in the public directory will be served. For example, if you have a file at `/lib/foo.js` and `/public/lib/foo.js`, and you request `/lib/foo.js`, the file in the public directory (`/public/lib/foo.js`) will be served.
@@ -959,11 +965,52 @@ Rails.configuration.proscenium.precompile = Set[
 
 This will bundle, code split, tree shake, and compile all your JS, TS, JSX, TSX and CSS files and place them in the `public/assets` directory, ready to be served in production.
 
+## Extending Proscenium
+
+Gems that bring side loading and CSS modules to other component libraries, such as
+[proscenium-phlex](https://github.com/joelmoss/proscenium-phlex) and
+[proscenium-view_component](https://github.com/joelmoss/proscenium-view_component), build on a
+small public API. Each method below is tagged `@api public` and has its own tests, so it changes
+only with a note in the release.
+
+| API | What it does |
+| --- | --- |
+| `Proscenium::SideLoad.sideload_inheritance_chain(obj, options)` | Side loads the assets of `obj`'s class and each superclass, as described below. |
+| `Proscenium::SideLoad.merge_options(base, override, receiver)` | Merges side load options as Proscenium does for views: a new Hash, keys symbolized at every depth, any `css`/`js` Proc evaluated against `receiver`. |
+| `Proscenium::Importer.import(path, sideloaded: false, **options)` | Imports one asset for the current request, once, merging repeat options (later ones win). A truthy `sideloaded` sends a `sideload.proscenium` notification. |
+| `Proscenium::Importer.each_stylesheet(delete: false)`, `each_javascript(delete: false)` | Yield each imported stylesheet or script with its options, for an app that writes its own tags. `delete: true` also removes each one from the imports, so it is written only once. |
+| `Proscenium::Importer.sideload(path, **options)` | Imports the script and stylesheet beside the Ruby file at `path`, an absolute `Pathname` (anything else raises `ArgumentError`). Does nothing when side loading is off, or `js:` and `css:` are both `false`. `lazy: true` imports a script but writes no tag for it, for a component that loads it itself. |
+| `Proscenium::CssModule` | Included into a component, against its `css_module_path`: `css_module` transforms every name, `class_names` only `@`-prefixed ones and paths (a name with a `/`, such as `/lib/users@name`), and the private `cssm` is the component's `Transformer`. |
+| `Proscenium::CssModule::Path` | Extended by a component class: `css_module_path` is the `.module.css` beside its source file, else the nearest ancestor's. |
+| `Proscenium::CssModule::Transformer#class_names(*names, require_prefix: true)` | Transforms names; given a block, yields each transformed name and the path of the CSS module it side loads, if any. |
+| `Proscenium::CssModule::Transformer#class_name!(name, original_name, path: source_path)` | Transforms one name, whatever its prefix, against the CSS module at `path`, and side loads that module. Raises `TransformError`, naming `original_name`, when there is no path. |
+| `Proscenium::SourcePath` | Included into a class: `source_path` is the file the class is defined in. |
+| `Proscenium::Resolver.resolve(path)` | Where an asset is served, for an absolute file or URL path, or a bare specifier such as an NPM package (a `./` or `../` path raises `ArgumentError`): its URL, or, when a loaded manifest has it, the entry's outputs as an Array, its own first. `as_array: true` returns `[manifest outputs, URL, file]`. |
+| `Proscenium::Utils.merge_bang_attributes!(names, attributes, allowed)` | Turns an allowed `:name!` argument into `name: true`, unless `name` was given as a keyword. |
+
+Side loading and CSS module lookup walk a component's class hierarchy through these methods,
+which the component's classes provide:
+
+- `source_path` on each class: the Ruby file whose sibling `.js`/`.ts`/`.jsx`/`.tsx`, `.css` and
+  `.module.css` files are side loaded.
+- `abstract_class` on each class, optional: when true, the walk stops there, and neither that
+  class nor any above it is side loaded or searched for a CSS module.
+- `sideload(options)` on each class, optional: called after that class's own assets, to side load
+  anything else.
+- `sideload_assets_options` on the instance: its own side load options, merged over the ones
+  given.
+- `css_module_path` on each class, from `CssModule::Path`: the class's CSS module, used by
+  `CssModule` and walked the same way, ending at an abstract class.
+
+The walk side loads each class's script, starting with the component's own, then the first CSS
+module found, then each class's stylesheet starting with the topmost, so a component's styles
+come after the ones it inherits.
+
 ## Puma `preload_app!` and Cluster Mode
 
 Proscenium's builder is backed by a Go shared library, and Go's runtime has a known, unfixed limitation ([golang/go#15538](https://github.com/golang/go/issues/15538)): if the Go runtime has already been initialized in a process before that process calls `fork()`, the forked child's Go runtime is left in a broken state (only the forking thread survives `fork()`; the Go scheduler and GC's other threads simply vanish) and any subsequent call into Go code in that child can hang or fail.
 
-This matters if you run Puma in cluster mode with `preload_app!` (the app, including gems, is booted once in the master process, then workers are created via `fork()` with no `exec()` afterward). Proscenium itself never triggers this - simply requiring the gem does not initialize the Go runtime, and nothing in Proscenium's own boot sequence calls into it. The Go runtime only initializes lazily, the first time something actually calls a builder method (`build_to_string`, `resolve`, or `compile`).
+This matters if you run Puma in cluster mode with `preload_app!` (the app, including gems, is booted once in the master process, then workers are created via `fork()` with no `exec()` afterward). Proscenium itself never triggers this - requiring the gem does not initialize the Go runtime, and neither does naming `Proscenium::Builder` or one of its error classes (so a `rescue_from Proscenium::Builder::BuildError` in a controller is safe), and nothing in Proscenium's own boot sequence calls into it. The library is opened, and the Go runtime initialized, the first time something actually calls a builder method (`build_to_string`, `resolve`, or `compile`).
 
 **Do not call any `Proscenium::Builder` method (directly, or indirectly via the resolver/side-loading) from a Rails initializer or any other code that runs during application boot**, if you use `preload_app!` with `workers`. Doing so initializes the Go runtime in the master process before the fork, and every worker will inherit a broken one. There is no fix available from Go's side - this is a fundamental fork() limitation, not a bug Proscenium can work around. Asset builds and resolves triggered by actual HTTP requests (the normal case) are unaffected, since those always happen after the fork, independently in each worker.
 

data/lib/proscenium/app_package.rb

@@ -3,10 +3,14 @@
 require 'json'
 
 module Proscenium
-  # What the app's own package.json says that the context map needs (#154). Like ContextMap, which
-  # it reads JSON through, it loads nothing the `proscenium` CLI may not.
+  # What the app's own package.json says that the context map needs (#154). Like Contexts::Map,
+  # which it reads JSON through, it loads nothing the `proscenium` CLI may not.
   module AppPackage
     LOCAL_SPECS = %w[link: file: workspace: portal:].freeze
+    # The fields an app's own dependencies are under. Peers too: pnpm installs the app's own peers
+    # at the root.
+    DEPENDENCY_FIELDS = %w[dependencies devDependencies optionalDependencies
+                           peerDependencies].freeze
 
     module_function
 
@@ -18,7 +22,7 @@ module Proscenium
       package = read(root) or return []
 
       members = bun?(root, package) ? workspace_members(root, package['workspaces']) : []
-      %w[dependencies devDependencies optionalDependencies peerDependencies].flat_map do |field|
+      DEPENDENCY_FIELDS.flat_map do |field|
         deps = package[field]
         next [] unless deps.is_a?(Hash)
 
@@ -81,7 +85,7 @@ module Proscenium
     # The app's package.json as an object, or nil when it is missing or not one.
     def read(root)
       path = File.join(root, 'package.json')
-      package = File.exist?(path) && ContextMap.read_json(path)
+      package = File.exist?(path) && Contexts::Map.read_json(path)
       package if package.is_a?(Hash)
     rescue JSON::ParserError
       nil

data/lib/proscenium/builder/request.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module Proscenium
+  class Builder
+    module Request
+      extend FFI::Library
+
+      raise UnsupportedPlatform, LIBRARY_PATH unless LIBRARY_PATH.exist?
+
+      ffi_lib LIBRARY_PATH.to_s
+
+      # Windows unmaps the library at interpreter exit, and the Go runtime does not survive it.
+      #
+      # ffi's library_free calls dl_close on every platform but macOS, which is FreeLibrary here,
+      # and Ruby runs every T_DATA free during VM teardown. Go's c-shared runtime cannot be
+      # unloaded: its threads are still running when the mapping goes. On Linux this never bites,
+      # because the Go linker marks the library nodelete and dlclose is a no-op; Windows has no
+      # equivalent. Measured on windows-latest: three of five plain `require` runs exited 139,
+      # while five of five exited 0 when the script ended in `exit!`, which skips the teardown.
+      #
+      # Pinning the module means the reference count never reaches zero, so FreeLibrary returns
+      # without unmapping anything. Nothing here needs the handle, only the pin.
+      if Gem.win_platform?
+        module Kernel32
+          extend FFI::Library
+
+          ffi_lib 'kernel32'
+          attach_function :GetModuleHandleExW, %i[uint32 buffer_in pointer], :int
+        end
+
+        # GET_MODULE_HANDLE_EX_FLAG_PIN. Backslashes, because GetModuleHandle documents that a full
+        # path must use them, and LIBRARY_PATH is built from __dir__, which uses "/". Checked,
+        # because a pin that quietly failed would bring back an exit crash that only happens some
+        # of the time, with nothing to say why.
+        name = "#{LIBRARY_PATH.to_s.tr('/', '\\')}\0".encode(Encoding::UTF_16LE)
+        if Kernel32.GetModuleHandleExW(0x1, name, FFI::MemoryPointer.new(:pointer)).zero?
+          warn "Proscenium could not pin #{LIBRARY_PATH} (Windows error " \
+               "#{FFI::LastError.winapi_error}), so Ruby may crash when it exits."
+        end
+      end
+
+      enum :environment, [:development, 1, :test, :production]
+
+      # `blocking: true` releases the GVL for the duration of the call, so a build/resolve
+      # doesn't stall unrelated Ruby threads (eg. other requests in a multi-threaded server).
+      # Safe to do because the Go side shares nothing between calls: each call parses its own
+      # config, and the caches that outlive a call (i18n, svg, npm replacements) carry their own
+      # locks. See the note in main.go. There is no serialising mutex any more; a new piece of
+      # global state on the Go side needs its own.
+
+      attach_function :build_to_string, [
+        :string, # Path or entry point.
+        :pointer # Config as JSON.
+      ], Result.by_value, blocking: true
+
+      attach_function :resolve, [
+        :string, # path or entry point
+        :pointer # Config as JSON.
+      ], ResolveResult.by_value, blocking: true
+
+      attach_function :compile, [
+        :pointer # Config as JSON.
+      ], CompileResult.by_value, blocking: true
+
+      attach_function :reset_config, [], :void, blocking: true
+
+      attach_function :free_cstr, [:pointer], :void
+    end
+  end
+end

data/lib/proscenium/builder.rb

@@ -55,70 +55,11 @@ module Proscenium
       end
     end
 
-    module Request
-      extend FFI::Library
-
-      raise UnsupportedPlatform, LIBRARY_PATH unless LIBRARY_PATH.exist?
-
-      ffi_lib LIBRARY_PATH.to_s
-
-      # Windows unmaps the library at interpreter exit, and the Go runtime does not survive it.
-      #
-      # ffi's library_free calls dl_close on every platform but macOS, which is FreeLibrary here,
-      # and Ruby runs every T_DATA free during VM teardown. Go's c-shared runtime cannot be
-      # unloaded: its threads are still running when the mapping goes. On Linux this never bites,
-      # because the Go linker marks the library nodelete and dlclose is a no-op; Windows has no
-      # equivalent. Measured on windows-latest: three of five plain `require` runs exited 139,
-      # while five of five exited 0 when the script ended in `exit!`, which skips the teardown.
-      #
-      # Pinning the module means the reference count never reaches zero, so FreeLibrary returns
-      # without unmapping anything. Nothing here needs the handle, only the pin.
-      if Gem.win_platform?
-        module Kernel32
-          extend FFI::Library
-
-          ffi_lib 'kernel32'
-          attach_function :GetModuleHandleExW, %i[uint32 buffer_in pointer], :int
-        end
-
-        # GET_MODULE_HANDLE_EX_FLAG_PIN. Backslashes, because GetModuleHandle documents that a full
-        # path must use them, and LIBRARY_PATH is built from __dir__, which uses "/". Checked,
-        # because a pin that quietly failed would bring back an exit crash that only happens some
-        # of the time, with nothing to say why.
-        name = "#{LIBRARY_PATH.to_s.tr('/', '\\')}\0".encode(Encoding::UTF_16LE)
-        if Kernel32.GetModuleHandleExW(0x1, name, FFI::MemoryPointer.new(:pointer)).zero?
-          warn "Proscenium could not pin #{LIBRARY_PATH} (Windows error " \
-               "#{FFI::LastError.winapi_error}), so Ruby may crash when it exits."
-        end
-      end
-
-      enum :environment, [:development, 1, :test, :production]
-
-      # `blocking: true` releases the GVL for the duration of the call, so a build/resolve
-      # doesn't stall unrelated Ruby threads (eg. other requests in a multi-threaded server).
-      # Safe to do because the Go side shares nothing between calls: each call parses its own
-      # config, and the caches that outlive a call (i18n, svg, npm replacements) carry their own
-      # locks. See the note in main.go. There is no serialising mutex any more; a new piece of
-      # global state on the Go side needs its own.
-
-      attach_function :build_to_string, [
-        :string, # Path or entry point.
-        :pointer # Config as JSON.
-      ], Result.by_value, blocking: true
-
-      attach_function :resolve, [
-        :string, # path or entry point
-        :pointer # Config as JSON.
-      ], ResolveResult.by_value, blocking: true
-
-      attach_function :compile, [
-        :pointer # Config as JSON.
-      ], CompileResult.by_value, blocking: true
-
-      attach_function :reset_config, [], :void, blocking: true
-
-      attach_function :free_cstr, [:pointer], :void
-    end
+    # The FFI binding to the Go library. Autoloaded, so the library is opened (and the Go runtime
+    # started) by the first call into it, never by naming Builder or one of its error classes: a
+    # `rescue_from Proscenium::Builder::BuildError` in a controller loaded during a Puma
+    # `preload_app!` boot must not start Go before the fork (golang/go#15538).
+    autoload :Request, File.expand_path('builder/request', __dir__)
 
     class BuildError < Error
       attr_reader :error, :path
@@ -199,12 +140,12 @@ module Proscenium
     # finished, or the committed gem dependency contexts are stale. With
     # PROSCENIUM_STALE_CONTEXT=warn, for an incident, stale contexts are logged once instead.
     def self.refusal(root = Rails.root)
-      project = ContextMap.project_root
-      return ContextMap::INSTALLING_MESSAGE if ContextMap.installing?(project)
+      project = Contexts::Map.project_root
+      return Contexts::Map::INSTALLING_MESSAGE if Contexts::Map.installing?(project)
 
       outside = outside_rails_root(project, root) and return outside
 
-      stale = StaleContexts.message(project, generation) or return
+      stale = Contexts::Stale.message(project, generation) or return
       return stale unless ENV['PROSCENIUM_STALE_CONTEXT'] == 'warn'
 
       @warned ||= Set.new
@@ -217,7 +158,7 @@ module Proscenium
     # has no URL the engine serves, so such a layout is refused plainly, not left to fail
     # mid-page. Only compares paths unless they differ.
     def self.outside_rails_root(project, root = Rails.root)
-      return if within?(project, root) || !ContextMap.adopted?(project)
+      return if within?(project, root) || !Contexts::Map.adopted?(project)
 
       "Gem dependency contexts are under #{project}, outside the Rails app at #{root}, " \
         'which Proscenium cannot serve yet. Keep the Gemfile in the Rails root to use them.'
@@ -270,7 +211,6 @@ module Proscenium
       config_hash = {
         RootPath: (@root || Rails.root).to_s,
         OutputDir: "public#{Proscenium.config.output_dir}",
-        GemPath: gem_root,
         Environment: ENVIRONMENTS.fetch(Rails.env.to_sym, 2),
         EnvVars: env_vars,
         CodeSplitting: Proscenium.config.code_splitting,
@@ -280,7 +220,7 @@ module Proscenium
         External: Proscenium.config.external,
         Precompile: Proscenium.config.precompile,
         Debug: Proscenium.config.debug,
-        **ContextMap.config(ContextMap.project_root, generation)
+        **Contexts::Map.config(Contexts::Map.project_root, generation)
       }.merge(@overrides)
 
       self.class.request_config_pointer(config_hash)
@@ -395,9 +335,5 @@ module Proscenium
       ENV['NODE_ENV'] = ENV.fetch('RAILS_ENV', nil)
       ENV.slice(*Proscenium::DEFAULT_ENV_VARS, *names)
     end
-
-    def gem_root
-      Pathname.new(__dir__).join('..', '..').to_s
-    end
   end
 end

data/lib/proscenium/cli/bun_linker.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
-require_relative '../context_map'
+require_relative '../contexts/map'
 require_relative 'manager'
 
 module Proscenium
@@ -65,7 +65,7 @@ module Proscenium
 
       def workspaces?(root)
         path = File.join(root, 'package.json')
-        File.exist?(path) && ContextMap.read_json(path).key?('workspaces')
+        File.exist?(path) && Contexts::Map.read_json(path).key?('workspaces')
       rescue JSON::ParserError
         false
       end

data/lib/proscenium/cli/collisions.rb

@@ -2,7 +2,8 @@
 
 require 'json'
 require 'yaml'
-require_relative 'registration'
+require_relative '../app_package'
+require_relative '../contexts/map'
 
 module Proscenium
   module CLI
@@ -12,14 +13,11 @@ module Proscenium
     module Collisions
       module_function
 
-      DEPENDENCY_FIELDS = %w[dependencies devDependencies optionalDependencies
-                             peerDependencies].freeze
-
       # One line for each package of the app's own taking a context's name.
       def find(root, manager, gems)
         names = gems.to_h { ["@rubygems/#{it}", it] }
         app = read_json(File.join(root, 'package.json')) || {}
-        pinned = DEPENDENCY_FIELDS.flat_map do |field|
+        pinned = AppPackage::DEPENDENCY_FIELDS.flat_map do |field|
           (app[field] || {}).filter_map do |name, spec|
             next if !names.key?(name) || context_workspace?(spec, name) ||
                     context_link?(root, spec, names[name])
@@ -46,7 +44,7 @@ module Proscenium
       def context_link?(root, spec, gem)
         return false unless spec.to_s.start_with?('link:')
 
-        context = File.join(File.expand_path(root), ContextMap::CONTEXTS, gem)
+        context = File.join(File.expand_path(root), Contexts::Map::CONTEXTS, gem)
         File.expand_path(spec.to_s.delete_prefix('link:'), root) == context
       end
 
@@ -55,7 +53,7 @@ module Proscenium
       # Bun read `./packages/*` and `packages/*` alike.
       def workspace_packages(root, manager, app)
         excluded, included = workspace_patterns(root, manager, app)
-                             .grep(String).reject { ContextMap.registration?(it) }
+                             .grep(String).reject { Contexts::Map.registration?(it) }
                              .map { it.sub(%r{\A(!?)\./}, '\\1') }
                              .partition { it.start_with?('!') }
         files = included.flat_map { Dir.glob(File.join(it, 'package.json'), base: root) }.uniq
@@ -77,14 +75,14 @@ module Proscenium
           Array(workspaces.is_a?(Hash) ? workspaces['packages'] : workspaces)
         else
           path = File.join(root, 'pnpm-workspace.yaml')
-          File.exist?(path) ? Array(ContextMap.yaml_packages(File.read(path))) : []
+          File.exist?(path) ? Array(Contexts::Map.yaml_packages(File.read(path))) : []
         end
       rescue Psych::SyntaxError
         [] # the manager reports it
       end
 
       def read_json(path)
-        json = File.exist?(path) && ContextMap.read_json(path)
+        json = File.exist?(path) && Contexts::Map.read_json(path)
         json.is_a?(Hash) ? json : nil
       rescue JSON::ParserError
         nil