vcdeps 0.1.0

data/lib/vcdeps/cli.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "vcdeps"
+require "vcvars"
+
+module Vcdeps
+  # Command-line interface for the `vcdeps` executable. Mirrors the vcvars CLI:
+  # `run` returns an Integer exit status (never calls exit), dispatch is a plain
+  # case, flags are hand-parsed (no optparse), and one rescue turns every known
+  # error into a clean one-liner with no backtrace.
+  class CLI
+    def self.start(argv)
+      new.run(argv)
+    end
+
+    # Returns a process exit status (Integer).
+    def run(argv)
+      argv = argv.dup
+      command = argv.shift
+
+      case command
+      when "doctor"                     then cmd_doctor(argv)
+      when "where"                      then cmd_where(argv)
+      when "install"                    then cmd_install(argv)
+      when "vendor"                     then cmd_vendor(argv)
+      when "baseline"                   then cmd_baseline(argv)
+      when "bootstrap"                  then cmd_bootstrap(argv)
+      when "version", "-v", "--version" then cmd_version
+      when nil, "help", "-h", "--help"  then print_help; 0
+      else
+        warn "vcdeps: unknown command #{command.inspect}\n\n"
+        print_help
+        1
+      end
+    rescue Vcdeps::Error, Vcvars::Error, ArgumentError => e
+      # Library messages already carry the "vcdeps: " prefix (§2.1); don't double
+      # it when we re-emit them through the CLI.
+      msg = e.message.to_s.sub(/\Avcdeps:\s*/, "")
+      warn "vcdeps: #{msg}"
+      1
+    rescue Interrupt
+      130
+    end
+
+    # --- commands ------------------------------------------------------------
+
+    def cmd_version
+      puts "vcdeps #{Vcdeps::VERSION}"
+      0
+    end
+
+    def cmd_doctor(argv)
+      require "vcdeps/doctor"
+      manifest = extract_opt(argv, "--manifest")
+      deep = !argv.include?("--quick")
+      checks = Doctor.run(manifest: manifest, deep: deep)
+
+      checks.each do |c|
+        puts "#{c.icon} #{c.label}"
+        next unless c.detail && !c.detail.to_s.empty?
+
+        c.detail.to_s.each_line { |line| puts "       #{line.chomp}" }
+      end
+
+      fails = checks.count { |c| c.status == :fail }
+      warns = checks.count { |c| c.status == :warn }
+      puts
+      if fails.zero?
+        extra = warns.positive? ? " (#{warns} warning#{'s' if warns > 1})" : ""
+        puts "Summary: no blocking problems#{extra}."
+        0
+      else
+        puts "Summary: #{fails} problem#{'s' if fails > 1} found — see remedies above."
+        1
+      end
+    end
+
+    def cmd_where(_argv)
+      tool = Vcdeps.tool
+      if tool
+        puts tool.to_s
+        puts "exe:     #{tool.exe}"
+        puts "version: #{tool.version}"
+        puts "source:  #{tool.source}"
+        0
+      else
+        Vcdeps.tool! # raises ToolNotFound with the three remedies -> rescued as a one-liner
+        0
+      end
+    end
+
+    def cmd_install(argv)
+      manifest = extract_opt(argv, "--manifest")
+      triplet  = extract_opt(argv, "--triplet")
+      force    = argv.delete("--force") ? true : false
+      manifest_dir = resolve_manifest(manifest)
+
+      inst = Vcdeps.install!(manifest: manifest_dir, triplet: triplet, force: force,
+                             out: $stderr)
+      puts inst.prefix
+      0
+    end
+
+    def cmd_vendor(argv)
+      into     = extract_opt(argv, "--into")
+      manifest = extract_opt(argv, "--manifest")
+      triplet  = extract_opt(argv, "--triplet")
+      licenses = !argv.delete("--no-licenses")
+      shim     = !argv.delete("--no-shim")
+
+      if into.nil? || into.empty?
+        warn "vcdeps vendor: --into DIR is required."
+        warn "Example: vcdeps vendor --into lib/foo/vendor"
+        return 1
+      end
+
+      inst = Vcdeps.install!(manifest: resolve_manifest(manifest), triplet: triplet,
+                             out: $stderr)
+      written = Vcdeps.vendor!(inst, into: into, licenses: licenses, shim: shim,
+                               out: $stderr)
+      if written.empty?
+        puts "(nothing to vendor — static-md or header-only build)"
+      else
+        written.each { |f| puts f }
+      end
+      0
+    end
+
+    def cmd_baseline(argv)
+      manifest = extract_opt(argv, "--manifest")
+      sha = Vcdeps.baseline!(manifest: resolve_manifest(manifest), out: $stderr)
+      puts sha
+      0
+    end
+
+    def cmd_bootstrap(_argv)
+      tool = Vcdeps.bootstrap!(out: $stderr)
+      puts "Bootstrapped: #{tool}"
+      0
+    end
+
+    # --- helpers -------------------------------------------------------------
+
+    # Manifest default: cwd; if cwd has no vcpkg.json and exactly one
+    # ext/*/vcpkg.json exists, use that one (gem-layout DX).
+    def resolve_manifest(explicit)
+      return explicit if explicit && !explicit.empty?
+      return Dir.pwd if File.exist?(File.join(Dir.pwd, "vcpkg.json"))
+
+      ext_manifests = Dir[File.join(Dir.pwd, "ext", "*", "vcpkg.json")]
+      return File.dirname(ext_manifests.first) if ext_manifests.size == 1
+
+      Dir.pwd
+    end
+
+    # Pulls "--opt value" or "--opt=value" out of argv (mutating it). Returns the
+    # value or nil; raises on a dangling flag.
+    def extract_opt(argv, name)
+      if (i = argv.index(name))
+        value = argv[i + 1]
+        if value.nil?
+          argv.slice!(i, 1)
+          raise Error, "#{name} requires a value."
+        end
+        argv.slice!(i, 2)
+        return value
+      end
+      prefix = "#{name}="
+      if (i = argv.index { |a| a.to_s.start_with?(prefix) })
+        value = argv[i][prefix.length..]
+        argv.slice!(i, 1)
+        return value
+      end
+      nil
+    end
+
+    def print_help
+      puts <<~HELP
+        vcdeps #{Vcdeps::VERSION} — vcpkg-powered native dependencies for Ruby C extensions on Windows (MSVC).
+
+        Usage:
+          vcdeps doctor    [--manifest DIR] [--quick]
+                                           Diagnose vcpkg acquisition + mkmf wiring
+          vcdeps where                     Show the resolved vcpkg (path, version, source)
+          vcdeps install   [--manifest DIR] [--triplet T] [--force]
+                                           Pre-build the manifest's ports (CI / warm cache)
+          vcdeps vendor    --into DIR [--manifest DIR] [--triplet T] [--no-licenses] [--no-shim]
+                                           install! then vendor DLLs + licenses + preload shim
+          vcdeps baseline  [--manifest DIR]
+                                           Add/refresh "builtin-baseline" in vcpkg.json
+          vcdeps bootstrap                 Create a private vcpkg under %LOCALAPPDATA%\\vcdeps
+          vcdeps version
+          vcdeps help
+
+        Examples:
+          vcdeps doctor --manifest ext/foo
+          vcdeps install --manifest ext/foo --triplet x64-windows-static-md
+          vcdeps vendor  --into lib/foo/vendor --manifest ext/foo
+          vcdeps baseline --manifest ext/foo
+
+        In extconf.rb, `require "vcdeps/mkmf"; Vcdeps.mkmf!(vendor: ...)` does the
+        install + wiring + vendoring automatically — no CLI step is needed to build.
+      HELP
+    end
+  end
+end

data/lib/vcdeps/doctor.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "vcdeps"
+require "vcvars"
+require "vcvars/doctor"
+
+module Vcdeps
+  # Diagnoses vcpkg acquisition + mkmf wiring, mirroring Vcvars::Doctor's
+  # Check/icon/Summary pattern. Delegates the toolchain checks to vcvars (a hard
+  # dependency whose Doctor is public API) and adds the vcdeps-specific checks
+  # (§2.9): resolution, manifest baseline, opt-dir shadowing, Ruby-bin DLL
+  # collisions, triplet sanity, binary cache, offline readiness, home hygiene.
+  module Doctor
+    module_function
+
+    Check = Struct.new(:status, :label, :detail, keyword_init: true) do
+      def icon
+        { ok: "[ OK ]", warn: "[WARN]", fail: "[FAIL]", info: "[INFO]" }[status]
+      end
+    end
+
+    # Returns an Array<Check>. `manifest` (a dir) enables the manifest/triplet
+    # checks; `deep: true` adds the home-size INFO.
+    def run(manifest: nil, deep: true)
+      checks = []
+      checks.concat(toolchain_checks)
+      checks.concat(tool_checks)
+      checks.concat(actions_root_checks)
+      checks.concat(manifest_checks(manifest))
+      checks.concat(optdir_checks)
+      checks.concat(collision_checks(manifest))
+      checks.concat(triplet_checks)
+      checks.concat(cache_checks)
+      checks.concat(offline_checks)
+      checks.concat(home_checks(deep: deep))
+      checks
+    end
+
+    def healthy?(checks)
+      checks.none? { |c| c.status == :fail }
+    end
+
+    # 1. mswin Ruby + CRT linkage (delegates to vcvars). 2. vcvars viability.
+    def toolchain_checks
+      out = []
+      out << if Vcvars::Doctor.mswin?
+        Check.new(status: :ok, label: "Ruby is a native MSVC (mswin) build",
+                  detail: "#{RUBY_VERSION} #{RbConfig::CONFIG['arch']}, CRT " \
+                          "#{Vcvars::Doctor.crt_flag}")
+      else
+        Check.new(status: :fail, label: "Ruby is NOT an mswin build",
+                  detail: "vcdeps targets MSVC (mswin) Ruby only. Your Ruby is " \
+                          "#{RbConfig::CONFIG['arch']}. Not supported on MinGW/UCRT.")
+      end
+
+      inst = safe_locate
+      out << if inst
+        Check.new(status: :ok, label: "Visual Studio located", detail: inst.to_s)
+      else
+        Check.new(status: :warn, label: "No Visual Studio located via vcvars",
+                  detail: "vcdeps needs cl.exe to build extensions and to find the " \
+                          "VS-bundled vcpkg. Install \"Desktop development with " \
+                          "C++\"; run `vcvars doctor`.")
+      end
+      out << Check.new(status: (Vcvars.active? ? :ok : :info),
+                       label: "Developer environment #{Vcvars.active? ? 'ACTIVE' : 'not yet active'}",
+                       detail: Vcvars.active? ? nil : "vcdeps activates it on demand " \
+                               "(Vcvars.activate!); harmless if inactive now.")
+      out
+    end
+
+    # 3. vcpkg resolution: source/path/version, or FAIL + the three remedies.
+    def tool_checks
+      tool = safe_tool
+      if tool
+        [Check.new(status: :ok, label: "vcpkg resolved (#{tool.source})",
+                   detail: "#{tool.exe}\n       version #{tool.version}")]
+      else
+        [Check.new(status: :fail, label: "No usable vcpkg found",
+                   detail: "Remedies: (a) install the VS component " \
+                           "Microsoft.VisualStudio.Component.Vcpkg; (b) set " \
+                           "VCPKG_ROOT to an existing instance; (c) run " \
+                           "`vcdeps bootstrap` (or VCDEPS_BOOTSTRAP=1).")]
+      end
+    end
+
+    # 4. VCPKG_INSTALLATION_ROOT set but invalid (issue #9269).
+    def actions_root_checks
+      root = ENV["VCPKG_INSTALLATION_ROOT"]
+      return [] if root.nil? || root.empty?
+      return [] if ToolFinder.valid_root(root)
+
+      [Check.new(status: :warn, label: "VCPKG_INSTALLATION_ROOT is set but invalid",
+                 detail: "#{root.tr('/', '\\')} lacks vcpkg.exe/.vcpkg-root (the " \
+                         "runner-images #9269 bug). vcdeps SKIPS it; nothing to fix " \
+                         "unless you rely on it.")]
+    end
+
+    # 5. Manifest (when given): parses; builtin-baseline present or
+    # vcpkg-configuration.json beside it — else FAIL with the baseline remedy.
+    def manifest_checks(manifest)
+      return [] if manifest.nil?
+
+      dir = File.expand_path(manifest)
+      path = File.join(dir, Manifest::MANIFEST_NAME)
+      return [Check.new(status: :fail, label: "No manifest at #{path.tr('/', '\\')}",
+                        detail: "Create a vcpkg.json there.")] unless File.exist?(path)
+
+      begin
+        Manifest.load!(dir)
+        [Check.new(status: :ok, label: "Manifest is valid and baselined",
+                   detail: path.tr("/", "\\"))]
+      rescue ManifestError => e
+        [Check.new(status: :fail, label: "Manifest problem", detail: e.message)]
+      end
+    end
+
+    # 6. opt-dir shadowing: parse configure_args for --with-opt-dir.
+    def optdir_checks
+      args = RbConfig::CONFIG["configure_args"].to_s
+      m = args.match(/--with-opt-dir=(\S+)/)
+      return [] unless m
+
+      [Check.new(status: :warn, label: "Ruby was built with --with-opt-dir",
+                 detail: "#{m[1]} is folded into EVERY extension's paths AHEAD of " \
+                         "appended dirs (opt-dir shadowing, R§8.4). vcdeps PREPENDS " \
+                         "its -I / -libpath so its vcpkg tree wins; no action needed.")]
+    end
+
+    # 7. Ruby-bin DLL collisions: scan the install's/vendored DLL base names
+    # against Ruby's bindir.
+    def collision_checks(manifest)
+      return [] if manifest.nil?
+
+      bindir = RbConfig::CONFIG["bindir"].to_s
+      return [] if bindir.empty?
+
+      names = manifest_dll_basenames(manifest)
+      collisions = names.select { |n| File.exist?(File.join(bindir, n)) }
+      return [] if collisions.empty?
+
+      collisions.map do |n|
+        Check.new(status: :warn, label: "DLL name collides with Ruby's bin: #{n}",
+                  detail: "#{File.join(bindir, n).tr('/', '\\')} exists; first-loaded " \
+                          "wins process-wide (R§9.2). The preload shim runs first " \
+                          "under normal require order.")
+      end
+    end
+
+    # 8. Triplet sanity: resolved triplet vs §2.6 rules.
+    def triplet_checks
+      triplet = ENV["VCDEPS_TRIPLET"]
+      triplet = (Triplet.default rescue nil) if triplet.nil? || triplet.empty?
+      return [Check.new(status: :warn, label: "Cannot derive a triplet for this arch",
+                        detail: "Set VCDEPS_TRIPLET.")] if triplet.nil?
+
+      begin
+        Triplet.validate!(triplet)
+        [Check.new(status: :ok, label: "Triplet OK: #{triplet}", detail: nil)]
+      rescue TripletError => e
+        [Check.new(status: :fail, label: "Triplet rejected", detail: e.message)]
+      end
+    end
+
+    # 9. Binary cache: %LOCALAPPDATA%\vcpkg\archives (or override) + entry count.
+    def cache_checks
+      cache = ENV["VCPKG_DEFAULT_BINARY_CACHE"]
+      cache = File.join(ENV["LOCALAPPDATA"] || "", "vcpkg", "archives") if cache.nil? || cache.empty?
+      if File.directory?(cache)
+        count = Dir[File.join(cache.tr("\\", "/"), "**", "*.zip")].size
+        [Check.new(status: :info, label: "Binary cache present (#{count} archive(s))",
+                   detail: cache.tr("/", "\\"))]
+      else
+        [Check.new(status: :info, label: "Binary cache not yet created",
+                   detail: "#{cache.tr('/', '\\')} will hold built ports; first cold " \
+                           "build populates it.")]
+      end
+    end
+
+    # 10. Registry/offline readiness: baseline tree under registries.
+    def offline_checks
+      reg = File.join(ENV["LOCALAPPDATA"] || "", "vcpkg", "registries")
+      if File.directory?(reg) && !Dir.empty?(reg.tr("\\", "/"))
+        [Check.new(status: :info, label: "Registry cache present (offline-capable)",
+                   detail: reg.tr("/", "\\"))]
+      else
+        [Check.new(status: :info, label: "Registry cache empty",
+                   detail: "First install of a baseline needs network for the registry " \
+                           "git-tree fetch.")]
+      end
+    end
+
+    # 11. Vcdeps.home hygiene: spaces / non-ASCII WARN; size INFO on deep.
+    def home_checks(deep:)
+      out = []
+      h = Vcdeps.home
+      if h =~ /\s/
+        out << Check.new(status: :warn, label: "VCDEPS_HOME path contains spaces",
+                         detail: "#{h} — naked -I flags and some port builds mishandle " \
+                                 "spaces. Set VCDEPS_HOME to a short ASCII path.")
+      elsif h =~ /[^\x00-\x7F]/
+        out << Check.new(status: :warn, label: "VCDEPS_HOME path has non-ASCII characters",
+                         detail: "#{h} — some port build scripts mishandle it. Set " \
+                                 "VCDEPS_HOME to a short ASCII path.")
+      else
+        out << Check.new(status: :ok, label: "vcdeps home path is clean", detail: h)
+      end
+
+      if deep && File.directory?(h)
+        out << Check.new(status: :info, label: "vcdeps home size: #{home_size_mb(h)} MB",
+                         detail: h)
+      end
+      out
+    end
+
+    # --- internals -----------------------------------------------------------
+
+    def safe_locate
+      Vcvars.locate
+    rescue StandardError
+      nil
+    end
+
+    def safe_tool
+      Vcdeps.tool
+    rescue StandardError
+      nil
+    end
+
+    # Best-effort: the DLL base names a manifest would vendor, read from an
+    # already-installed tree if present (so doctor stays offline and cheap).
+    def manifest_dll_basenames(manifest)
+      dir = File.expand_path(manifest)
+      tool = safe_tool
+      return [] unless tool
+
+      triplet = ENV["VCDEPS_TRIPLET"]
+      triplet = (Triplet.default rescue nil) if triplet.nil? || triplet.empty?
+      return [] unless triplet
+
+      key = Manifest.key(dir, triplet, tool.version)
+      root = File.join(Vcdeps.home, "installed", key)
+      return [] unless File.directory?(root)
+
+      inst = Installed.new(root: root, triplet: triplet, manifest_dir: dir,
+                           key: key, tool: tool)
+      inst.dlls.map { |d| File.basename(d) }
+    rescue StandardError
+      []
+    end
+
+    def home_size_mb(dir)
+      total = 0
+      Dir.glob(File.join(dir.tr("\\", "/"), "**", "*"), File::FNM_DOTMATCH) do |f|
+        total += File.size(f) if File.file?(f)
+      end
+      (total / (1024.0 * 1024.0)).round(1)
+    rescue StandardError
+      0
+    end
+  end
+end

data/lib/vcdeps/installed.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Vcdeps
+  # One installed port (name/version/triplet), parsed from an info-list filename.
+  Port = Struct.new(:name, :version, :triplet, keyword_init: true)
+
+  # An immutable snapshot of one completed out-of-tree install. All paths are
+  # absolute Strings with backslash separators (display-normalized like
+  # Vcvars::Locator#win). Runtime DLLs are enumerated from the authoritative
+  # vcpkg\info\*.list files — NEVER guessed from port names (R§8.2) — and the
+  # debug/ tree is never exposed (R§8.4).
+  class Installed
+    attr_reader :root, :triplet, :manifest_dir, :key, :tool
+
+    # `tool` is nil for a --with-vcdeps-dir bypass install. `prefix:` overrides
+    # the computed <root>\<triplet> (the bypass passes the prefix dir directly).
+    def initialize(root:, triplet:, manifest_dir:, key:, tool:, prefix: nil)
+      @root = win(root)
+      @triplet = triplet
+      @manifest_dir = win(manifest_dir)
+      @key = key
+      @tool = tool
+      @prefix_override = prefix ? win(prefix) : nil
+    end
+
+    # <root>\<triplet> (or the bypass prefix override).
+    def prefix
+      return @prefix_override if @prefix_override
+
+      File.join(@root, @triplet).tr("/", "\\")
+    end
+
+    def include_dir
+      File.join(prefix, "include").tr("/", "\\")
+    end
+
+    # The RELEASE lib dir — never debug\lib (R§8.4).
+    def lib_dir
+      File.join(prefix, "lib").tr("/", "\\")
+    end
+
+    def bin_dir
+      File.join(prefix, "bin").tr("/", "\\")
+    end
+
+    # Accessor only; vcdeps never runs pkg-config (§5.14).
+    def pkgconfig_dir
+      File.join(prefix, "lib", "pkgconfig").tr("/", "\\")
+    end
+
+    # The vcpkg metadata dir holding info\*.list (and status).
+    def info_dir
+      File.join(@root, "vcpkg", "info").tr("/", "\\")
+    end
+
+    # Array<Port> parsed from <root>\vcpkg\info\<name>_<ver>_<triplet>.list
+    # filenames. In bypass mode (no tool) there is no info tree, so this is [].
+    def ports
+      list_files.filter_map { |path| parse_port(File.basename(path, ".list")) }
+    end
+
+    # Array<String> absolute paths of RELEASE runtime DLLs.
+    # Normal mode: read every info-list file, take entries ending in .dll that
+    # are NOT under a debug/ directory, resolve to absolute backslash paths.
+    # Bypass mode (no tool): glob bin\*.dll.
+    def dlls
+      if bypass?
+        Dir[File.join(bin_dir.tr("\\", "/"), "*.dll")].sort.map { |p| win(p) }
+      else
+        out = []
+        list_files.each do |list|
+          read_list_entries(list).each do |entry|
+            next unless entry =~ /\.dll\z/i
+            next if entry =~ %r{(?:\A|/)debug/}i
+
+            out << win(File.join(@root, entry))
+          end
+        end
+        out.uniq.sort
+      end
+    end
+
+    # Hash{ "zlib" => "<prefix>\share\zlib\copyright", ... } for EXISTING files.
+    def copyright_files
+      result = {}
+      ports.each do |port|
+        cand = File.join(prefix, "share", port.name, "copyright")
+        result[port.name] = win(cand) if File.exist?(cand)
+      end
+      # Bypass mode has no ports; scan share\*\copyright directly.
+      if bypass?
+        share = File.join(prefix, "share").tr("\\", "/")
+        Dir[File.join(share, "*", "copyright")].each do |cp|
+          name = File.basename(File.dirname(cp))
+          result[name] ||= win(cp)
+        end
+      end
+      result
+    end
+
+    private
+
+    def bypass?
+      @tool.nil?
+    end
+
+    def win(path)
+      path.nil? ? path : path.tr("/", "\\")
+    end
+
+    # The info-list files for THIS triplet (filenames end in _<triplet>.list).
+    def list_files
+      dir = info_dir.tr("\\", "/")
+      return [] unless File.directory?(dir)
+
+      Dir[File.join(dir, "*_#{@triplet}.list")].sort
+    end
+
+    # info-list entries are "/"-separated relative paths under <root>.
+    def read_list_entries(path)
+      File.readlines(path, encoding: "UTF-8").map { |l| l.strip }.reject(&:empty?)
+    rescue StandardError
+      []
+    end
+
+    # "<name>_<version>_<triplet>" -> Port. Split name on the FIRST "_" and
+    # triplet on the LAST "_" so versions containing "_" (rare) survive.
+    def parse_port(base)
+      first = base.index("_")
+      last  = base.rindex("_")
+      return nil if first.nil? || last.nil? || first == last
+
+      name    = base[0...first]
+      version = base[(first + 1)...last]
+      triplet = base[(last + 1)..]
+      Port.new(name: name, version: version, triplet: triplet)
+    end
+  end
+end