proscenium 0.25.3 → 0.26.1

data/lib/proscenium/cli/gem_check.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'rubygems/package'
+require 'zlib'
+require_relative 'gem_archive'
+require_relative 'rules'
+require_relative '../bundled_gems'
+require_relative '../context_map'
+
+module Proscenium
+  module CLI
+    # `proscenium gem check [path]`: the gem author's check, which needs no bundle. Checks a gem
+    # source directory, or a built `.gem`, against the author contract: opted in, the manifest and
+    # frontend files in `spec.files`, and the manifest rules. A built `.gem` is only read; a source
+    # directory's gemspec is Ruby, which loading it runs, so check an untrusted gem as a `.gem`.
+    class GemCheck
+      FRONTEND = /\.(?:js|jsx|mjs|ts|tsx|css)\z/
+      # Not shipped on purpose: tests, dependencies, and tool configuration at the root, such as
+      # eslint.config.js.
+      UNSHIPPED = Regexp.union(%r{(?:\A|/)(?:node_modules|test|spec)/}, /\.(?:test|spec)\.[a-z]+\z/,
+                               %r{\A[^/]+\.config\.[a-z]+\z})
+
+      def initialize(path, reporter)
+        @path = File.expand_path(path || Dir.pwd)
+        @reporter = reporter
+      end
+
+      def call
+        spec, files, manifest_text, cause = @path.end_with?('.gem') ? read_archive : read_source
+        problems = check(spec, files, manifest_text, cause)
+        problems.each { |code, args| @reporter.error(Error.new(code, **args), phase: 'gem-check') }
+        if problems.empty?
+          message = "#{spec.name} #{spec.version} passes every check: Proscenium can install " \
+                    'its NPM dependencies.'
+          @reporter.info(@reporter.paint(message, :bold, :green),
+                         event: 'gem-check', gem: spec.name)
+          return 0
+        end
+
+        Error::EXIT.fetch(:input)
+      end
+
+      private
+
+      # `cause` is why the manifest could not be read safely, if it could not (C29).
+      def check(spec, files, manifest_text, cause = nil)
+        gem = spec.name
+        unless spec.metadata['proscenium.dependencies'] == 'true'
+          return [['PSM-E-NOT-OPTED-IN', { gem: }]]
+        end
+
+        root = frontend_root(spec)
+        return [['PSM-E-FRONTEND-ROOT', { gem:, root: }]] unless root
+
+        manifest_path = root.empty? ? 'package.json' : File.join(root, 'package.json')
+        return [['PSM-E-MANIFEST', { gem:, path: manifest_path, cause: }]] if cause
+        unless manifest_text
+          return [['PSM-E-MANIFEST',
+                   { gem:, path: manifest_path, cause: 'it is missing' }]]
+        end
+
+        manifest = parse(manifest_text)
+        if manifest.is_a?(String)
+          return [['PSM-E-MANIFEST',
+                   { gem:, path: manifest_path, cause: manifest }]]
+        end
+
+        gyp = root.empty? ? 'binding.gyp' : File.join(root, 'binding.gyp')
+        problems = Rules.check(gem, manifest, root: source_root(root), path: manifest_path,
+                                              binding_gyp: files.include?(gyp))
+        # A field of the wrong type stops here: the checks below read it as an object.
+        return problems if problems.any? { it.first == 'PSM-E-MANIFEST' }
+
+        unless files.include?(manifest_path)
+          problems << ['PSM-E-GEM-FILES',
+                       { gem:, files: manifest_path }]
+        end
+        missing = unlisted_frontend(files, root)
+        problems << ['PSM-E-GEM-FILES', { gem:, files: summarize(missing) }] if missing.any?
+        problems + cross_gem(spec, manifest)
+      end
+
+      def frontend_root(spec) = BundledGems.frontend_root(spec)
+
+      # A reference to another gem's context needs that gem as a runtime dependency.
+      def cross_gem(spec, manifest)
+        runtime = spec.runtime_dependencies.map(&:name)
+        Rules::DEPENDENCY_FIELDS.flat_map { (manifest[it] || {}).keys }
+                                .grep(%r{\A@rubygems/})
+                                .map { it.delete_prefix('@rubygems/') }
+                                .reject { runtime.include?(it) }
+                                .map { ['PSM-E-CROSS-GEM', { gem: spec.name, other: it }] }
+      end
+
+      def parse(text)
+        manifest = ContextMap.parse_json(text)
+        manifest.is_a?(Hash) ? manifest : 'it is not a JSON object'
+      rescue JSON::ParserError => e
+        "it is not valid JSON (#{e.message.lines.first.strip})"
+      end
+
+      def read_source
+        gemspecs = Dir.glob('*.gemspec', base: @path)
+        raise Error.new('PSM-E-GEMSPEC', path: @path, found: gemspecs.size) unless gemspecs.one?
+
+        # Loaded by absolute path: Specification.load caches by the path it is given, so a relative
+        # one would return another directory's gem. Inside the directory, because gemspecs often
+        # list their files relative to it.
+        spec = Dir.chdir(@path) { Gem::Specification.load(File.join(@path, gemspecs.first)) }
+        raise Error.new('PSM-E-GEMSPEC', path: @path, found: 0) unless spec
+
+        root = frontend_root(spec) || ''
+        manifest = File.join(@path, root, 'package.json')
+        @source = @path
+        return [spec, spec.files, nil, nil] unless File.exist?(manifest)
+
+        cause = Rules.manifest_file_problem(manifest, @path)
+        [spec, spec.files, cause ? nil : File.read(manifest), cause]
+      end
+
+      # A built gem, read from its archive (GemArchive).
+      def read_archive
+        spec, manifest, cause = GemArchive.read(@path)
+        [spec, spec.files, manifest, cause]
+      end
+
+      def source_root(root) = @source && File.join(@source, root)
+
+      # Frontend files on disk under the frontend root but missing from `spec.files`, in the gem's
+      # root or a top-level directory it ships something from: a directory it ships nothing from,
+      # such as a demo app beside the gem's code, is left out on purpose. A built gem has nothing on
+      # disk to compare.
+      def unlisted_frontend(files, root)
+        return [] unless @source
+
+        shipped = files.filter_map { it.split('/', 2).first if it.include?('/') }
+        Dir.glob('**/*', base: File.join(@source, root)).grep(FRONTEND)
+           .map { root.empty? ? it : File.join(root, it) }
+           .reject { files.include?(it) || UNSHIPPED.match?(it) }
+           .select { !it.include?('/') || shipped.include?(it.split('/', 2).first) }
+      end
+
+      def summarize(paths)
+        shown = paths.first(3).join(', ')
+        paths.size > 3 ? "#{shown} and #{paths.size - 3} more" : shown
+      end
+    end
+  end
+end

data/lib/proscenium/cli/gitignore.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module CLI
+    # The `.gitignore` lines for Proscenium's own state (#154): everything under .proscenium/
+    # ignored but the generated contexts, which are committed.
+    module Gitignore
+      # Each level down to a context's package.json is re-included: Git never looks inside a
+      # directory an earlier rule (`.proscenium/`, `.*`) ignores, and `.proscenium/**` ignores
+      # every level below it.
+      IGNORES = ['!.proscenium/', '.proscenium/*', '!.proscenium/packages/',
+                 '!.proscenium/packages/*/', '!.proscenium/packages/*/package.json',
+                 '.proscenium/packages/*/node_modules/'].freeze
+
+      module_function
+
+      # Appends the lines Proscenium owns, and a node_modules rule if the app has none (Bun moves
+      # an old tree to node_modules/.old_modules-<hash> when its linker changes).
+      def splice(text)
+        lines = text.lines(chomp: true)
+        # Only the lines together, in order, and with no rule after them that could hide the
+        # contexts are enough; otherwise all of them again. Git applies the last matching rule.
+        size = IGNORES.size
+        at = (0..(lines.size - size)).reverse_each.find { lines[it, size] == IGNORES }
+        hidden = at.nil? || lines[(at + size)..].any? { hides_contexts?(it) }
+        wanted = hidden ? IGNORES.dup : []
+        wanted.unshift('node_modules/') unless lines.any? { it.match?(%r{\A/?node_modules/?\z}) }
+        return text if wanted.empty?
+
+        nl = text.include?("\r\n") ? "\r\n" : "\n"
+        separator = text.empty? || text.end_with?("\n") ? '' : nl
+        "#{text}#{separator}#{nl unless text.empty?}# Proscenium#{nl}#{wanted.join(nl)}#{nl}"
+      end
+
+      FLAGS = [File::FNM_DOTMATCH, File::FNM_DOTMATCH | File::FNM_PATHNAME].freeze
+      COMMITTED = %w[.proscenium .proscenium/packages].freeze
+
+      # Whether an ignore rule could match a path the contexts are committed under. Generous: `*`
+      # crosses `/` here, so at worst the lines are added once more than needed.
+      def hides_contexts?(line)
+        pattern = line.strip.delete_prefix('/').chomp('/')
+        return false if pattern.empty? || pattern.start_with?('#', '!')
+
+        # Git's `**/` also matches no directory at all. Ruby's does too with FNM_PATHNAME, inside a
+        # pattern, but not at its start, so that prefix is also dropped; without FNM_PATHNAME, a
+        # trailing `**` (and `*`) crosses `/` as Git's trailing `/**` does.
+        # Any segment of the rule may name a gem's directory, such as `.proscenium/packages/hue/**`,
+        # and one with a wildcard, class or brace, such as `[ah]ue`, may match any of them.
+        names = ['gem', *pattern.split('/')]
+        wide = pattern.split('/').map { it.match?(/[*?\[{]/) ? '*' : it }.join('/')
+        paths = COMMITTED + names.flat_map do |name|
+          ["#{COMMITTED.last}/#{name}", "#{COMMITTED.last}/#{name}/package.json"]
+        end
+        [pattern, wide].flat_map { [it, it.delete_prefix('**/')] }.uniq.any? do |glob|
+          paths.any? do |path|
+            FLAGS.any? { File.fnmatch?(glob, path, it) } ||
+              File.fnmatch?(glob, File.basename(path), File::FNM_DOTMATCH)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/proscenium/cli/inspect.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'bundler'
+require_relative '../bundled_gems'
+require_relative 'contexts'
+require_relative 'gitignore'
+require_relative 'manager'
+require_relative 'registration'
+require_relative 'verify'
+require_relative '../stale_contexts'
+
+module Proscenium
+  module CLI
+    # `proscenium inspect [gem]` (#154): read-only. What each participating gem contributes, where
+    # it is locked from, whether its committed context is current, and which gems ship a
+    # package.json without taking part. With --json, one document.
+    class Inspect
+      CREDENTIALS = %r{(://)[^/@\s]+@}
+      # A query parameter whose name says it holds a secret, which Bundler keeps in a git source.
+      SECRET_PARAMS = /([?&][^=&#\s]*(?:token|key|auth|pass|secret|sig)[^=&#\s]*=)[^&#\s]+/i
+
+      # Each context status, as a person reads it.
+      STATUS = {
+        'current' => ['up to date', :green],
+        'stale' => ['out of date: run `bundle exec proscenium install`', :yellow],
+        'edited' => ['edited by hand: run `bundle exec proscenium install` to restore it', :yellow],
+        'missing' => ['not written yet: run `bundle exec proscenium install`', :yellow],
+        'invalid' => ["can't be installed: see the problems below", :red]
+      }.freeze
+
+      def initialize(root, reporter, gem: nil)
+        @root = root
+        @reporter = reporter
+        @only = gem
+      end
+
+      def call
+        report = build
+        if @reporter.json?
+          @reporter.document(report)
+        else
+          @reporter.result(text(report), event: 'inspect')
+        end
+        report['problems'].empty? && report['buildRefused'].empty? ? 0 : Error::EXIT.fetch(:drift)
+      end
+
+      private
+
+      def build
+        overrides = BundledGems.overrides(@root)
+        specs = BundledGems.installed_specs
+        participating = BundledGems.participating(specs, overrides:)
+        if @only && !participating.key?(@only)
+          raise Error.new('PSM-E-USAGE', detail: "#{@only} doesn't install NPM " \
+                                                 'dependencies through Proscenium')
+        end
+
+        contexts = Contexts.new(@root, participating)
+        committed = Contexts.committed(@root)
+        gems = participating.keys.select { @only.nil? || it == @only }.map do |name|
+          gem_report(name, participating[name], contexts, committed)
+        end
+        manager, problems = select_manager
+        # An app that uses none of this has nothing to set up, whatever its manager.
+        if participating.any? || committed.any? || ContextMap.registrar(@root)
+          problems += project_problems(manager, contexts, committed)
+        else
+          problems = []
+        end
+        problems += contexts.problems.map { |code, args| Error.new(code, **args) }
+        { 'schema' => 1, 'manager' => manager_report(manager), 'gems' => gems,
+          'notParticipating' => BundledGems.unparticipating_with_manifest(specs, overrides:),
+          # Every reason the engine refuses to build: orphans and split peers as well.
+          'buildRefused' => StaleContexts.problems(@root, specs),
+          'problems' => problems.map { problem_report(it) } }
+      rescue BundledGems::ConfigError => e
+        raise Error.new('PSM-E-CONFIG', detail: e.message)
+      end
+
+      def gem_report(name, spec, contexts, committed)
+        context = contexts.contexts[name]
+        current = context && JSON.parse(context.json)
+        path = committed[name]
+        on_disk = path && File.exist?(path) ? File.read(path) : nil
+        {
+          'gem' => name, 'version' => spec.version.to_s, 'source' => redact(source(name)),
+          'context' => ".proscenium/packages/#{name}",
+          'status' => status(context, on_disk, path),
+          'projectionSha256' => current&.dig('proscenium', 'projectionSha256'),
+          'kept' => current ? (current.keys & DependencyContext::FIELDS) : [],
+          'gitAndUrl' => (context&.git_and_url || []).map { redact(it) },
+          'optionalPeers' => optional_peers(current)
+        }
+      end
+
+      # `stale` exactly when the engine refuses to build: the projection hash differs. Different
+      # bytes with the same hash are a hand edit, which only `install --frozen` refuses.
+      def status(context, on_disk, path)
+        return 'invalid' unless context
+        return 'missing' unless on_disk
+        return 'current' if on_disk == context.json
+
+        reason = StaleContexts.compare(context, path)
+        reason.nil? || reason == StaleContexts::EDITED ? 'edited' : 'stale'
+      end
+
+      # Where Gemfile.lock takes the gem from.
+      def source(name)
+        locked = Bundler.locked_gems&.specs&.find { it.name == name }
+        return 'not locked' unless locked
+
+        locked.source.to_s
+      end
+
+      # Optional peers that are other gems, beside the version Bundler locked: Bundler checks a
+      # gemspec dependency's version, but nothing checks an optional peer's range.
+      def optional_peers(context)
+        return [] unless context
+
+        (context['peerDependenciesMeta'] || {}).filter_map do |name, meta|
+          next unless meta.is_a?(Hash) && meta['optional'] && name.start_with?('@rubygems/')
+
+          gem = name.delete_prefix('@rubygems/')
+          locked = Bundler.locked_gems&.specs&.find { it.name == gem }
+          { 'peer' => name, 'range' => context.dig('peerDependencies', name),
+            'locked' => locked&.version&.to_s }
+        end
+      end
+
+      # The manager, and what stops install using it, as install would check it: [manager or nil,
+      # problems].
+      def select_manager
+        manager = Manager.select(@root)
+        manager.check_version!
+        manager.check_project!(frozen: Registration.registered?(@root, manager.name))
+        [manager, []]
+      rescue Error => e
+        [manager, [e]]
+      end
+
+      # What stops the app's gem dependencies working once installed: the registration, the
+      # .gitignore lines, the lockfile and the install itself. Before the first install, only that
+      # it has not happened.
+      def project_problems(manager, contexts, committed)
+        return gitignore_problems unless manager
+
+        file = manager.name == 'bun' ? 'package.json' : 'pnpm-workspace.yaml'
+        registered = Registration.registered?(@root, manager.name)
+        unregistered = Error.new('PSM-E-NOT-REGISTERED', file:, manager: manager.name)
+        return [unregistered] if !registered && committed.empty?
+
+        found = gitignore_problems
+        found << unregistered unless registered
+        lockfile = Manager::LOCKFILES.key(manager.name)
+        lock = File.join(@root, lockfile)
+        return found << Error.new('PSM-E-LOCKFILE-MISSING', lockfile:) unless File.exist?(lock)
+        unless File.directory?(File.join(@root, 'node_modules'))
+          return found << Error.new('PSM-E-NOT-INSTALLED')
+        end
+
+        found + (registered ? installed_problems(manager, contexts, File.read(lock)) : [])
+      end
+
+      def gitignore_problems
+        path = File.join(@root, '.gitignore')
+        text = File.exist?(path) ? File.read(path) : ''
+        Gitignore.splice(text) == text ? [] : [Error.new('PSM-E-GITIGNORE')]
+      end
+
+      # A gem context the lock takes from a registry, or one the manager did not install. A split
+      # peer is in buildRefused, as the engine refuses to build for it.
+      def installed_problems(manager, contexts, lock)
+        verify = Verify.new(@root, manager, contexts.contexts.keys)
+        %i[check_registry check_workspaces].filter_map do |check|
+          verify.public_send(check, lock)
+          nil
+        rescue Error => e
+          e
+        end
+      end
+
+      def problem_report(error)
+        { 'code' => error.code, 'message' => error.message,
+          'fix' => error.fix }
+      end
+
+      def manager_report(manager)
+        return nil unless manager
+
+        linker = manager.name == 'bun' ? manager.bun_linker : pnpm_linker
+        { 'name' => manager.name, 'linker' => linker }
+      end
+
+      # pnpm's `node-linker` from .npmrc, `isolated` by default.
+      def pnpm_linker
+        npmrc = File.join(@root, '.npmrc')
+        setting = File.exist?(npmrc) && File.read(npmrc)[/^\s*node-linker\s*=\s*(\S+)/, 1]
+        setting || 'isolated'
+      end
+
+      def redact(text)
+        text.to_s.gsub(CREDENTIALS, '\1<redacted>@').gsub(SECRET_PARAMS, '\1<redacted>')
+      end
+
+      def text(report)
+        lines = []
+        if (manager = report['manager'])
+          linker = manager['linker'] ? "#{manager['linker']} linker" : 'linker not set'
+          lines << "#{bold('Package manager:')} #{manager['name']} (#{linker})" << ''
+        end
+        lines.concat(gem_lines(report['gems']))
+        if report['notParticipating'].any?
+          lines << '' << bold('These gems ship a package.json but have not opted in:')
+          lines.concat(report['notParticipating'].map { "  #{it}" })
+          lines << '  To opt one in, add `"proscenium": {"gemOverrides": {"<gem>": ' \
+                   '{"participate": true}}}` to package.json.'
+        end
+        report['problems'].each do |problem|
+          lines << '' << "#{@reporter.paint('Problem:', :bold, :red)} #{problem['message']}"
+          lines << "#{bold('To fix:')} #{problem['fix']}"
+        end
+        if report['buildRefused'].any?
+          lines << '' << @reporter.paint('Rails will refuse to build assets until you fix:', :bold,
+                                         :red)
+          lines.concat(report['buildRefused'].map { "  - #{it}" })
+        end
+        if report['problems'].empty? && report['buildRefused'].empty?
+          lines << '' << @reporter.paint('No problems found.', :bold, :green)
+        end
+        lines.join("\n")
+      end
+
+      def gem_lines(gems)
+        return ['No gems install NPM dependencies through Proscenium.'] if gems.empty?
+
+        lines = [bold("Gems whose NPM dependencies Proscenium installs (#{gems.size}):")]
+        gems.each do |gem|
+          status, colour = STATUS.fetch(gem['status'])
+          lines << "  #{gem['gem']} #{gem['version']}: #{@reporter.paint(status, colour)}"
+          lines << "    from: #{gem['source']}"
+          lines << "    uses: #{gem['kept'].join(', ')}" if gem['kept'].any?
+          if gem['gitAndUrl'].any?
+            lines << "    Git and URL dependencies: #{gem['gitAndUrl'].join(', ')}"
+          end
+          gem['optionalPeers'].each do |peer|
+            locked = peer['locked'] ? "#{peer['locked']} is locked" : 'not locked'
+            lines << "    optional peer #{peer['peer']} #{peer['range']} (#{locked})"
+          end
+        end
+        lines
+      end
+
+      def bold(text) = @reporter.paint(text, :bold)
+    end
+  end
+end