proscenium 0.26.0-x86_64-linux-gnu

data/lib/proscenium/cli/verify.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../context_map'
+require_relative 'manager'
+
+module Proscenium
+  module CLI
+    # What install checks after the manager has run (#154): no gem context came from a registry,
+    # the manager installed every context (Bun exits 0 when a workspace is missing, so this is
+    # Proscenium's to check), and a peer meant to be shared is one copy.
+    class Verify
+      # A `packages:` key in pnpm-lock.yaml, and a `packages` entry in bun.lock, for a
+      # `@rubygems/*` package that is not a link to its context. A pnpm key starting with `@` is
+      # always quoted, and a Git one holds colons: `'@rubygems/hue@git+ssh://git@github.com/...':`.
+      PNPM_REGISTRY = %r{^\s{2}'(@rubygems/[^@'\s]+)@(?!link:|workspace:)[^']*':\s*$}
+      BUN_REGISTRY = %r{"(@rubygems/[^"]+)":\s*\["@rubygems/[^@"]+@(?!workspace:)}
+
+      def initialize(root, manager, gems)
+        @root = root
+        @manager = manager
+        @gems = gems
+      end
+
+      def call
+        lock = File.read(File.join(@root, Manager::LOCKFILES.key(@manager.name)))
+        check_registry(lock)
+        check_workspaces(lock)
+        check_peers
+      end
+
+      # A `@rubygems/*` package resolved from a registry, rather than linked to its context.
+      # bun.lock is JSON with trailing commas, so both locks are scanned as text.
+      def check_registry(lock)
+        found = lock.scan(@manager.name == 'pnpm' ? PNPM_REGISTRY : BUN_REGISTRY).flatten
+        return if found.empty?
+
+        raise Error.new('PSM-E-REGISTRY-TARBALL', packages: found.uniq.join(', '))
+      end
+
+      def check_workspaces(lock)
+        missing = @gems.reject do |gem|
+          path = ".proscenium/packages/#{gem}"
+          if @manager.name == 'pnpm'
+            # An importer with no dependencies is written on one line: `  <path>: {}`.
+            lock.match?(/^  #{Regexp.escape(path)}:(?: \{\})?$/)
+          else
+            lock.include?("\"#{path}\"")
+          end
+        end
+        return if missing.empty?
+
+        raise Error.new('PSM-E-WORKSPACE-MISSING', gems: missing.join(', '), manager: @manager.name)
+      end
+
+      # Each peer a context declares that the app also depends on must resolve, from the context
+      # and from the app, to one real directory. A context that is missing or not valid JSON has
+      # no peers to check; StaleContexts and `install --frozen` report it themselves.
+      def check_peers
+        app = app_dependencies
+        @gems.each do |gem|
+          dir = File.join(@root, '.proscenium', 'packages', gem)
+          (peers(dir).keys & app).each do |name|
+            from_gem = resolve(dir, name)
+            from_app = resolve(@root, name)
+            next if from_gem.nil? || from_app.nil? || from_gem == from_app
+
+            raise Error.new('PSM-E-PEER-SPLIT', gem:, package: name, manager: @manager.name)
+          end
+        end
+      end
+
+      def peers(dir)
+        context = ContextMap.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
+        package = ContextMap.read_json(File.join(@root, 'package.json'))
+        return [] unless package.is_a?(Hash)
+
+        # Peers too: pnpm installs the app's own peers at the root.
+        %w[dependencies devDependencies optionalDependencies peerDependencies].flat_map do |field|
+          package[field].is_a?(Hash) ? package[field].keys : []
+        end
+      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.
+      def resolve(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
+    end
+  end
+end

data/lib/proscenium/cli.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'cli/error'
+require_relative 'cli/reporter'
+require_relative 'cli/gem_check'
+require_relative 'cli/install'
+require_relative 'cli/inspect'
+
+autoload :OptionParser, 'optparse'
+
+module Proscenium
+  # The `proscenium` command (#154): installs participating gems' JavaScript dependencies through
+  # the app's own package manager. It runs under `bundle exec` and reads the bundle in process.
+  #
+  # Load isolation is a contract, tested in test/cli/load_isolation_test.rb: nothing under
+  # lib/proscenium/cli/ may require `proscenium` itself, ActiveSupport, Rails, FFI or the engine
+  # library. Only Proscenium's plain-Ruby modules the engine shares with it (bundled_gems,
+  # dependency_context, context_map, stale_contexts) and these files.
+  module CLI
+    USAGE = <<~TEXT
+      Usage: bundle exec proscenium <command> [options]
+             bundle exec psm <command> [options]
+
+      Installs the NPM dependencies of the gems in your bundle that opt in.
+
+      Commands:
+        install            Install your gems' NPM dependencies
+        install --frozen   Check everything is up to date, without changing anything you commit
+        inspect [gem]      Show which gems install NPM dependencies, and any problems
+        doctor [gem]       The same as inspect
+        gem check [path]   For gem authors: check a gem's package.json and gemspec
+
+      install options:
+        --frozen                        Change nothing you commit; fail if anything is out of date
+        --production                    Leave out development dependencies, and keep the committed
+                                        dependency context of a gem in an excluded Bundler group
+        --offline                       Install from the package manager's cache only
+        --manager pnpm|bun              Which package manager, for an app with no package.json yet
+        --js-arg ARG                    Pass ARG to the package manager (repeatable)
+        --experimental-manager-version  Allow a package manager version Proscenium doesn't support
+
+      Options:
+        --json             Print newline-delimited JSON events instead of text
+        --quiet            Print less
+        --version          Print the Proscenium version
+        --help             Print this help
+    TEXT
+
+    module_function
+
+    # Runs the command in `argv` and returns its exit status.
+    def start(argv, out: $stdout, err: $stderr)
+      args = argv.dup
+      reporter = Reporter.new(out:, err:, json: !args.delete('--json').nil?,
+                              quiet: !args.delete('--quiet').nil?)
+      run(args, reporter)
+    rescue Error => e
+      reporter.error(e)
+      e.exit_status
+    rescue Interrupt
+      Error::EXIT.fetch(:interrupted)
+    rescue StandardError => e
+      internal = Error.new('PSM-E-INTERNAL', detail: "#{e.class}: #{e.message}")
+      reporter.error(internal)
+      internal.exit_status
+    end
+
+    def run(args, reporter)
+      # Anywhere, so `install --help` and `gem check --help` print it too.
+      if args.intersect?(%w[--help -h])
+        reporter.result(USAGE, event: 'help')
+        return 0
+      end
+
+      case args.first
+      when '--version', '-v'
+        reporter.result(Proscenium::VERSION, event: 'version', version: Proscenium::VERSION)
+      when nil
+        reporter.result(USAGE, event: 'help')
+      when 'install'
+        return Install.new(project_root, reporter, **install_options(args.drop(1))).call
+      when 'inspect', 'doctor'
+        return Inspect.new(project_root, reporter, gem: args[1]).call
+      when 'gem'
+        unless args[1] == 'check'
+          raise Error.new('PSM-E-USAGE', detail: 'Did you mean `proscenium gem check`?')
+        end
+
+        return GemCheck.new(args[2], reporter).call
+      else
+        raise Error.new('PSM-E-USAGE', detail: "Unknown command: #{args.join(' ')}")
+      end
+
+      0
+    end
+
+    # The active bundle's root: subdirectories and BUNDLE_GEMFILE both resolve to the app the
+    # bundle belongs to, so contexts are never written into another app.
+    def project_root = Bundler.root.to_s
+
+    def install_options(args)
+      options = { js_args: [] }
+      rest = OptionParser.new do |parser|
+        parser.on('--frozen') { options[:frozen] = true }
+        parser.on('--production') { options[:production] = true }
+        parser.on('--offline') { options[:offline] = true }
+        parser.on('--manager NAME') { options[:manager] = it }
+        parser.on('--experimental-manager-version') { options[:experimental] = true }
+        parser.on('--js-arg ARG') { options[:js_args] << it }
+      end.parse(args)
+      raise Error.new('PSM-E-USAGE', detail: "Unexpected argument: #{rest.join(' ')}") if rest.any?
+      if options[:js_args].any? && (options[:frozen] || options[:offline])
+        raise Error.new('PSM-E-USAGE', detail: '--js-arg cannot be used with --frozen or --offline')
+      end
+
+      options
+    rescue OptionParser::ParseError => e
+      raise Error.new('PSM-E-USAGE', detail: e.message)
+    end
+  end
+end

data/lib/proscenium/context_map.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'bundler'
+require 'json'
+require_relative 'app_package'
+require_relative 'bundled_gems'
+require_relative 'yaml_tree'
+
+module Proscenium
+  # What the engine passes Go about gem dependency contexts (#154): which gems resolve their bare
+  # imports from `.proscenium/packages/<gem>/`, and which of the app's own packages keep their link
+  # paths. Built from committed files and Bundler only. Like BundledGems, it loads nothing the
+  # `proscenium` CLI may not.
+  module ContextMap
+    CONTEXTS = File.join('.proscenium', 'packages')
+    REGISTRATION = '.proscenium/packages/*'
+
+    module_function
+
+    # Where the `proscenium` CLI keeps contexts, its lock and its marker: the bundle's root, which
+    # need not be Rails.root.
+    def project_root = Bundler.root.to_s
+
+    # The config keys Go reads, for the app at `root`. Read once per mapping generation: a value
+    # read during an older one is kept under that one's key, never handed to the next.
+    def config(root, generation = 0)
+      @config ||= {}
+      @config[[root, generation]] ||= { DependencyContexts: contexts(root),
+                                        AppLocalPackages: AppPackage.local_packages(root) }.freeze
+    end
+
+    def reset! = @config = {}
+
+    # Each registering file, with the lockfile and the name of the manager that reads it.
+    REGISTRARS = { 'pnpm-workspace.yaml' => %w[pnpm-lock.yaml pnpm],
+                   'package.json' => %w[bun.lock bun] }.freeze
+
+    # Whether the app at `root` adopted gem dependency contexts: pnpm's workspace file registers
+    # them, or package.json does in a Bun app. Each counts only where its manager installs: when
+    # packageManager names no other manager, and with that manager's lockfile or no other
+    # manager's, as an app missing its lockfile is an incomplete checkout, which must not silently
+    # switch the contexts off.
+    def adopted?(root) = !registrar(root).nil?
+
+    # The file whose registration makes the app at `root` adopted, or nil.
+    def registrar(root)
+      named = AppPackage.package_manager(root)
+      REGISTRARS.find do |file, (own, manager)|
+        # bun.lockb is Bun's too, until bun.lock replaces it.
+        others = [*UNSUPPORTED.keys, *REGISTRARS.values.map(&:first)] - [own] +
+                 (manager == 'bun' ? [] : ['bun.lockb'])
+        registers?(root, file) && [nil, manager].include?(named) &&
+          (File.exist?(File.join(root, own)) || others.none? { File.exist?(File.join(root, it)) })
+      end&.first
+    end
+
+    # Whether `file` lists the contexts: pnpm-workspace.yaml's `packages`, or package.json's
+    # `workspaces` (an array, or an object's `packages`). Parsed, so a commented-out line does not
+    # count. For the engine a file that does not parse counts if it names them, so a parse failure
+    # never silently switches off the context map and the stale check; `strict` (the CLI, which
+    # must register a file its manager can read) counts only a file that parses.
+    def registers?(root, file)
+      path = File.join(root, file)
+      File.exist?(path) && registered_in?(file, File.read(path))
+    end
+
+    def registered_in?(file, text, strict: false)
+      text = utf8(text).delete_prefix(BOM)
+      list = file.end_with?('.yaml') ? yaml_packages(text) : json_workspaces(text)
+      list.is_a?(Array) && list.any? { registration?(it) } && !excludes?(list)
+    rescue Psych::SyntaxError, JSON::ParserError
+      return false if strict
+
+      file.end_with?('.yaml') ? text.include?(REGISTRATION) : AppPackage.workspaces?(text)
+    end
+
+    # Whether the list has a `!` pattern that takes a context out: pnpm and Bun apply one whatever
+    # its order, so the contexts would never be installed. Generous: `*` crosses `/`, and any
+    # segment of the pattern may be a gem's directory.
+    def excludes?(list)
+      Array(list).grep(/\A!/).any? do |entry|
+        pattern = entry[1..].delete_prefix('./').chomp('/')
+        # A segment with a wildcard, class or brace, such as `[ah]ue`, may match any gem.
+        wide = pattern.split('/').map { it.match?(/[*?\[{]/) ? '*' : it }.join('/')
+        ['gem', *pattern.split('/')].product([pattern, wide]).any? do |name, glob|
+          File.fnmatch?(glob, "#{CONTEXTS}/#{name}", GLOB)
+        end
+      end
+    end
+
+    GLOB = File::FNM_EXTGLOB | File::FNM_DOTMATCH
+
+    def json_workspaces(text)
+      parsed = JSON.parse(text)
+      list = parsed['workspaces'] if parsed.is_a?(Hash)
+      list.is_a?(Hash) ? list['packages'] : list
+    end
+
+    # pnpm-workspace.yaml's `packages`: each entry's scalar text, or nil for one that is not a
+    # scalar; nil when the document is not a mapping or the key is missing or not a list. Read from
+    # the parse tree and never built into Ruby objects, so no alias can make it slow and no tag or
+    # date can raise. Raises Psych::SyntaxError.
+    def yaml_packages(text)
+      list, anchors = YamlTree.value(text, 'packages')
+      return unless list.is_a?(Psych::Nodes::Sequence)
+
+      list.children.map do |entry|
+        entry = YamlTree.node(entry, anchors)
+        entry.value if entry.is_a?(Psych::Nodes::Scalar)
+      end
+    end
+
+    # pnpm and Bun read `./<pattern>` and `<pattern>/` as the pattern.
+    def registration?(entry)
+      entry.is_a?(String) && entry.delete_prefix('./').chomp('/') == REGISTRATION
+    end
+
+    BOM = "\uFEFF"
+
+    # A JSON file as Node, pnpm and Bun read it, a leading byte order mark included.
+    def read_json(path) = parse_json(File.read(path))
+    def parse_json(text) = JSON.parse(utf8(text).delete_prefix(BOM))
+
+    # Text as UTF-8, whatever encoding the caller's locale gave it.
+    def utf8(text) = text.dup.force_encoding(Encoding::UTF_8)
+
+    # Gem name => absolute context directory for each participating gem, when the app at `root`
+    # adopted dependency contexts; empty before. A gem whose context is missing is mapped all the
+    # same: its imports then fail by name rather than fall back to the app's packages.
+    def contexts(root, specs = BundledGems.installed_specs)
+      return {} unless adopted?(root)
+
+      BundledGems.participating(specs, overrides: BundledGems.overrides(root)).keys.to_h do |gem|
+        [gem, File.join(root, CONTEXTS, gem)]
+      end
+    rescue BundledGems::ConfigError
+      {} # StaleContexts reports it, so every build is refused with the reason
+    end
+
+    INSTALLING = File.join('.proscenium', 'installing')
+    LOCK = File.join('.proscenium', 'lock')
+    INSTALLING_MESSAGE = '`bundle exec proscenium install` is running, or stopped before it ' \
+                         'finished. Wait for it, or run it again.'
+
+    # Whether an install is under way in the app at `root`, or stopped before it finished: its
+    # marker is there, or another process holds the project lock. The engine refuses to build or
+    # resolve meanwhile (C34). The probe takes a shared lock, so it never stops an install
+    # starting; the CLI retries a lock it finds taken for a moment. About 16 µs.
+    def installing?(root)
+      return true if File.exist?(File.join(root, INSTALLING))
+
+      lock = File.join(root, LOCK)
+      File.exist?(lock) && File.open(lock, File::RDONLY) { !it.flock(File::LOCK_SH | File::LOCK_NB) }
+    end
+
+    # Each file that says the app uses an unsupported manager, as Manager.select reads them.
+    UNSUPPORTED = { 'yarn.lock' => 'Yarn', '.yarnrc.yml' => 'Yarn', 'package-lock.json' => 'npm',
+                    'npm-shrinkwrap.json' => 'npm' }.freeze
+
+    # The one notice a process logs at boot when gems opt in but the app has not adopted dependency
+    # contexts, or nil. Those gems' imports keep resolving as they always have, so upgrading
+    # Proscenium never breaks an app that has not run `proscenium install` (C52).
+    def adoption_notice(root, specs = BundledGems.installed_specs)
+      return if adopted?(root)
+
+      gems = BundledGems.participating(specs, overrides: BundledGems.overrides(root)).keys
+      return if gems.empty?
+
+      opted = "#{gems.join(', ')} opt in to installing their NPM dependencies " \
+              'through Proscenium'
+      manager = UNSUPPORTED.find { |file, _| File.exist?(File.join(root, file)) }&.last
+      if manager
+        "#{opted}, but #{manager} is not supported, so the app keeps managing them."
+      else
+        "#{opted}. Run `bundle exec proscenium install` to install them."
+      end
+    rescue BundledGems::ConfigError => e
+      e.message
+    end
+  end
+end

data/lib/proscenium/css_module/path.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module 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.
+    #
+    # If the CSS module file does not exist, it's ancestry is checked, returning the first that
+    # exists. Then finally `nil` is returned if never found.
+    #
+    # @return [Pathname]
+    def css_module_path
+      return @css_module_path if instance_variable_defined?(:@css_module_path)
+
+      path = source_path.sub_ext('.module.css')
+      @css_module_path = path.exist? ? path : nil
+
+      unless @css_module_path
+        klass = superclass
+
+        while klass.respond_to?(:css_module_path) &&
+              (klass.respond_to?(:abstract_class) ? !klass.abstract_class : true)
+          break if (@css_module_path = klass.css_module_path)
+
+          klass = klass.superclass
+        end
+      end
+
+      @css_module_path
+    end
+  end
+end

data/lib/proscenium/css_module/transformer.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Proscenium
+  class CssModule::Transformer
+    FILE_EXT = '.module.css'
+
+    def self.class_names(path, *names)
+      new(path).class_names(*names)
+    end
+
+    # Flattens `names`, and drops nil, false and blank String or Symbol names. Anything else is
+    # kept, so that `#class_names` can reject it.
+    def self.filter_names(names)
+      names.flatten.reject do |name|
+        !name || ((name.is_a?(String) || name.is_a?(Symbol)) && name.to_s.blank?)
+      end
+    end
+
+    def initialize(source_path)
+      return unless (@source_path = source_path)
+
+      @source_path = Pathname.new(@source_path) unless @source_path.is_a?(Pathname)
+      @source_path = @source_path.sub_ext(FILE_EXT) unless @source_path.to_s.end_with?(FILE_EXT)
+    end
+
+    # Transform each of the given class `names` to their respective CSS module name, which consist
+    # of the name, and suffixed with the digest of the resolved source path.
+    #
+    # Any name beginning with '@' will be transformed to a CSS module name. If `require_prefix` is
+    # false, then all names will be transformed to a CSS module name regardless of whether or not
+    # they begin with '@'.
+    #
+    #   class_names :@my_module_name, :my_class_name
+    #
+    # Note that the generated digest is based on the resolved (URL) path, not the original path.
+    #
+    # You can also provide a path specifier and class name. The path will be the URL path to a
+    # stylesheet. The class name will be the name of the class to transform.
+    #
+    #   class_names "/lib/button@default"
+    #   class_names "mypackage/button@large"
+    #   class_names "@scoped/package/button@small"
+    #
+    # Nested arrays of names are flattened, and nil, false and blank names are dropped (see
+    # `.filter_names`). Any other name that is not a String or Symbol raises TransformError.
+    #
+    # When a block is given, it is yielded once per name with
+    # `(transformed_name, side_load_path)`. `side_load_path` is the exact string passed to
+    # `Importer.import` for that name, or `nil` for names that did not trigger a side-load (plain
+    # class names with `require_prefix: true`). The return value is unchanged — callers that don't
+    # need the path can keep ignoring the block.
+    #
+    # @param names [String,Symbol,nil,false,Array<String,Symbol,nil,false>]
+    # @param require_prefix: [Boolean] whether or not to require the `@` prefix.
+    # @yieldparam transformed_name [String]
+    # @yieldparam side_load_path [String, nil]
+    # @return [Array<String>] the transformed CSS module names.
+    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)
+        yield(transformed, path) if block_given?
+        transformed
+      end
+    end
+
+    def class_name!(name, original_name, path: @source_path)
+      unless path
+        raise Proscenium::CssModule::TransformError.new(original_name, 'CSS module path not given')
+      end
+
+      digest = Importer.import(path.to_s)
+
+      transformed_name = name.to_s
+      if transformed_name.start_with?('_')
+        "_#{transformed_name[1..]}_#{digest}"
+      else
+        "#{transformed_name}_#{digest}"
+      end
+    end
+
+    private
+
+    # Returns `[transformed_name, side_load_path]` for a single class-name reference.
+    # `side_load_path` is the exact string that `class_name!` passed to `Importer.import`, or
+    # `nil` if the name did not trigger a side-load. Extracted so `#class_names` can yield paths
+    # to consumers (e.g. proscenium-phlex's `resolved_css_module_paths` replay registry) without
+    # re-parsing names.
+    def transform_class_name(name, require_prefix:)
+      original_name = name.dup
+      name = name.to_s if name.is_a?(Symbol)
+      unless name.is_a?(String)
+        raise Proscenium::CssModule::TransformError.new(original_name.inspect,
+                                                        'class name must be a String or Symbol')
+      end
+
+      if name.include?('/')
+        if name.start_with?('@')
+          # Scoped bare specifier (eg. "@scoped/package/lib/button@default").
+          _, path, name = name.split('@')
+          path = "@#{path}"
+        else
+          # Local path (eg. /some/path/to/button@default") or bare specifier (eg.
+          # "mypackage/lib/button@default").
+          path, name = name.split('@')
+        end
+
+        module_path = "#{path}#{FILE_EXT}"
+        [class_name!(name, original_name, path: module_path), module_path]
+      elsif name.start_with?('@')
+        [class_name!(name[1..], original_name), @source_path&.to_s]
+      elsif require_prefix
+        [name, nil]
+      else
+        [class_name!(name, original_name), @source_path&.to_s]
+      end
+    end
+  end
+end

data/lib/proscenium/css_module.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Proscenium::CssModule
+  extend ActiveSupport::Autoload
+
+  autoload :Path
+  autoload :Transformer
+
+  class TransformError < Proscenium::Error
+    def initialize(name, additional_msg = nil)
+      msg = "Failed to transform CSS module `#{name}`"
+      msg << ' - ' << additional_msg if additional_msg
+
+      super(msg)
+    end
+  end
+
+  module ClassMethods
+    def css_module(*names, path: nil)
+      path ||= respond_to?(:css_module_path) ? css_module_path : 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
+      names = Transformer.filter_names(names)
+
+      cssm = Transformer.new(path)
+      cssm.class_names(*names).join(' ') unless names.empty?
+    end
+  end
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  # Accepts one or more CSS class names, and transforms them into CSS module names.
+  #
+  # @param names [String,Symbol,nil,false,Array<String,Symbol,nil,false>]
+  # @param path [Pathname] the path to the CSS module file to use for the transformation.
+  # @return [String] the transformed CSS module names concatenated as a string.
+  def css_module(*names, path: nil)
+    transformer = path.nil? ? cssm : Transformer.new(path)
+    transformer.class_names(*names, require_prefix: false).join(' ')
+  end
+
+  # @param names [String,Symbol,nil,false,Array<String,Symbol,nil,false>]
+  # @param path [Pathname] the path to the CSS file to use for the transformation.
+  # @return [String, nil] the transformed CSS module names concatenated as a string, or nil if none.
+  def class_names(*names, path: nil)
+    names = Transformer.filter_names(names)
+    transformer = path.nil? ? cssm : Transformer.new(path)
+    transformer.class_names(*names).join(' ') unless names.empty?
+  end
+
+  private
+
+  def cssm
+    @cssm ||= Transformer.new(self.class.css_module_path)
+  end
+end