proscenium 0.26.1 → 0.27.0

data/lib/proscenium/context_map.rb

@@ -1,181 +0,0 @@
-# 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/dependency_context.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-require 'digest'
-require 'json'
-
-module Proscenium
-  # A participating gem's dependency context (#154): its package.json through the
-  # `dependency-context-v1` projection, which keeps installation metadata only and is committed at
-  # `.proscenium/packages/<gem>/package.json`.
-  #
-  # The one owner of the projection and its hash, shared by the CLI and the engine, so it must not
-  # load ActiveSupport or anything else the CLI may not.
-  module DependencyContext
-    PROJECTION = 'dependency-context-v1'
-
-    # The manifest fields a context keeps, in the order it writes them. Everything else (scripts,
-    # devDependencies, version, entry points, workspaces) is left in the gem's own package.json.
-    FIELDS = %w[dependencies peerDependencies peerDependenciesMeta optionalDependencies engines os
-                cpu libc].freeze
-
-    module_function
-
-    def name_for(gem) = "@rubygems/#{gem}"
-
-    def description_for(gem)
-      "Generated by Proscenium from the #{gem} gem. Do not edit; " \
-        'run bundle exec proscenium install.'
-    end
-
-    # The context for `gem` from its parsed `manifest`. An empty field is left out, as an absent
-    # one is: the two install the same, so they hash the same.
-    def project(gem, manifest)
-      fields = FIELDS.each_with_object({}) do |key, kept|
-        value = manifest[key]
-        kept[key] = value unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
-      end
-
-      { 'name' => name_for(gem), 'private' => true, 'description' => description_for(gem),
-        **fields,
-        'proscenium' => { 'projection' => PROJECTION, 'projectionSha256' => digest(gem, fields) } }
-    end
-
-    # The bytes committed for a context: fixed key order, two-space indent, a trailing newline, and
-    # nothing that varies by host or time.
-    def to_json(context) = "#{JSON.pretty_generate(context)}\n"
-
-    # The projection hash. It hashes a fixed-field encoding of the projected fields, not JSON, so
-    # it does not move with the json gem's output, key order, whitespace or escaping, and an edit
-    # to anything the projection drops leaves it alone.
-    def digest(gem, fields)
-      Digest::SHA256.hexdigest("#{PROJECTION}\n#{encode(name_for(gem))}#{encode(fields)}")
-    end
-
-    # A self-delimiting encoding: a type tag, a length where there is one, then the value. Hash
-    # keys are sorted by their bytes, so key order in the manifest does not matter; array order
-    # does, as it does to npm.
-    def encode(value)
-      case value
-      when String then "s#{value.bytesize}:#{value.b}"
-      when true then 't'
-      when false then 'f'
-      when nil then 'n'
-      when Integer then "i#{value};"
-      when Float then "d#{value};"
-      when Array then "a#{value.size}:#{value.map { encode(it) }.join}"
-      when Hash
-        pairs = value.sort_by { |key, _| key.to_s.b }
-        "h#{value.size}:#{pairs.map { |key, val| encode(key.to_s) + encode(val) }.join}"
-      else
-        raise ArgumentError, "cannot encode #{value.class} in a dependency context"
-      end
-    end
-  end
-end

data/lib/proscenium/mapping_generation.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'bundled_gems'
-require_relative 'context_map'
-require_relative 'stale_contexts'
-
-module Proscenium
-  # Which mapping generation a build uses (#154). A generation is the context map and the
-  # staleness verdict, read once and kept, so every build sees one consistent view. In production
-  # a generation lasts the process: restart after a deploy. In development and test, `refresh`
-  # looks at most once a second for a change to the files the map is built from, and starts a new
-  # generation when one changed, such as `proscenium install` finishing.
-  #
-  # Gemfile.lock is watched, but a gem added or upgraded still needs a restart: Bundler loads the
-  # bundle once per process.
-  module MappingGeneration
-    # The lockfiles too: with contexts adopted, resolved paths carry each package's version.
-    WATCHED = ['Gemfile.lock', 'package.json', 'pnpm-workspace.yaml', '.npmrc',
-               'bunfig.toml', 'pnpm-lock.yaml', 'bun.lock', ContextMap::INSTALLING].freeze
-    EVERY = 1.0
-    LOCK = Mutex.new
-
-    module_function
-
-    # The current generation number, starting a new one first if a watched file changed and the
-    # last look was at least `every` seconds ago. Returns [number, whether it just changed].
-    def refresh(root, every: EVERY)
-      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      LOCK.synchronize do
-        @looked ||= {}
-        @number ||= 0
-        at, before = @looked[root]
-        return [@number, false] if at && now - at < every
-
-        after = signature(root)
-        @looked[root] = [now, after]
-        return [@number, false] if before.nil? || before == after
-
-        ContextMap.reset!
-        StaleContexts.reset!
-        [@number += 1, true]
-      end
-    end
-
-    # The modification time of every file the map is built from, by path, nil for a missing one.
-    def signature(root)
-      files = WATCHED.map { File.join(root, it) } +
-              Dir.glob(File.join(root, ContextMap::CONTEXTS, '*', 'package.json')) +
-              manifests(root)
-      files.sort.to_h { [it, File.exist?(it) ? File.mtime(it).to_f : nil] }
-    end
-
-    # Each participating gem's package.json: editing a path gem's manifest makes its context stale.
-    def manifests(root)
-      BundledGems.participating(BundledGems.installed_specs, overrides: BundledGems.overrides(root))
-                 .values.filter_map { BundledGems.manifest_root(it) }
-                 .map { File.join(it, 'package.json') }
-    rescue BundledGems::ConfigError
-      []
-    end
-
-    def reset! = LOCK.synchronize { @looked = {} }
-  end
-end

data/lib/proscenium/stale_contexts.rb

@@ -1,118 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require_relative 'bundled_gems'
-require_relative 'context_map'
-require_relative 'dependency_context'
-require_relative 'cli/contexts'
-require_relative 'cli/error'
-require_relative 'cli/verify'
-
-module Proscenium
-  # 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; it loads nothing the `proscenium` CLI may not.
-  module StaleContexts
-    COMMAND = 'Run `bundle exec proscenium install` and commit .proscenium/packages.'
-    EDITED = 'its dependency context was edited by hand'
-    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 = ContextMap.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 = CLI::Contexts.new(root, participating)
-      committed = CLI::Contexts.committed(root)
-      found = contexts.problems.map { |code, args| CLI::Error.new(code, **args).message }
-      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)
-
-      ContextMap.yaml_packages(ContextMap.utf8(File.read(path)).delete_prefix(ContextMap::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)
-      pnpm = ContextMap.registers?(root, 'pnpm-workspace.yaml')
-      CLI::Verify.new(root, Struct.new(:name).new(pnpm ? 'pnpm' : 'bun'), gems).check_peers
-      []
-    rescue CLI::Error => e
-      [e.message]
-    end
-
-    # The committed context 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 compare(context, path)
-      return "its dependency context hasn't been written yet" unless path && File.exist?(path)
-
-      committed = ContextMap.read_json(path)
-      unless committed.is_a?(Hash) && committed['proscenium'].is_a?(Hash)
-        return 'its dependency context is not valid JSON'
-      end
-      if committed['proscenium']['projection'] != DependencyContext::PROJECTION
-        return 'its dependency context was written by a different version of Proscenium'
-      end
-
-      # Parsed, so reformatting is not an edit; whole, so its name and the other generated fields
-      # count as well as its hash.
-      edited = DependencyContext.project(context.gem, committed) != committed
-      return EDITED if edited
-      return if committed == JSON.parse(context.json)
-
-      'its NPM dependencies changed since its dependency context was written'
-    rescue JSON::ParserError
-      'its dependency context is not valid JSON'
-    end
-
-    # The build error for the app at `root`, or nil when its contexts are current. Read once per
-    # mapping generation, as ContextMap.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