vcvars 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6bb5fa446867714c5eb7e04d78c0cee7a28785239113c15c3e52e2ed35986997
+  data.tar.gz: 6cbaa625a124f24b3a374d6a35b74fb53adc27a987b1c7ba0f90443d6d1ca79e
+SHA512:
+  metadata.gz: 3dcea9523fe8ed74df9d29add3d0b01ca3258dc87a36dba383a274e0650aa034cc290e7361269fe34cff18d6611c89eb99e155fa63f46a5dcefa32858519c3ff
+  data.tar.gz: 2d92d0fd458e2261984e5dc80b69c96abcaa8dd8abd7b302fcafad46530fa656465f84b1029651db7d6681e46d0700562e3dfeca5a8f3c04dbcd65a093fd7fb6

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-30
+
+### Added
+- `Vcvars.activate!` — locate Visual Studio via vswhere (with `-find`, plus
+  `installationPath`, `VSINSTALLDIR`, and well-known-root fallbacks) and import
+  the MSVC environment (`vcvars*.bat`) into the current process. Idempotent.
+- `Vcvars.locate`, `Vcvars.active?`, `Vcvars.env` library helpers.
+- `require "vcvars/rake"` — auto-activates the toolchain so rake-compiler's
+  `rake compile` works on an mswin Ruby without a Developer Command Prompt.
+- `vcvars doctor` — diagnoses the common MSVC extension-build failures
+  (dev env not loaded, C1083, LNK2019/2001, LNK2005 CRT mismatch, LNK1112 arch
+  mismatch, LNK1104, warnings-as-errors, mswin-vs-mingw confusion).
+- `vcvars exec -- <cmd>` — run any command inside the MSVC environment.
+- `vcvars env` — emit the MSVC env delta as bat/powershell/sh/dotenv/json.
+- `vcvars where` — show the located Visual Studio install and vcvars script.
+- `vcvars new NAME` — scaffold a warning-clean, MSVC-ready C-extension gem.
+
+[Unreleased]: https://github.com/ned-xvi/vcvars/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ned-xvi/vcvars/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ned
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,139 @@
+# vcvars
+
+**Load the MSVC build environment for native Ruby extensions on Windows — no Developer Command Prompt required.**
+
+If you use a [native **MSVC** build of Ruby](https://rubyinstaller.org/) (an
+`x64-mswin64` Ruby, built with `cl.exe` + `nmake`), building C extensions is
+painful: `cl.exe` and `nmake.exe` aren't on your `PATH` until you open a
+"Developer Command Prompt" and run `vcvars64.bat`. Forget that step and you get:
+
+```
+'nmake' is not recognized as an internal or external command
+```
+
+`vcvars` is to MSVC Ruby what `ridk enable` is to RubyInstaller's MinGW: it
+finds Visual Studio (via `vswhere`), loads the toolchain into your process, and
+gets out of the way. Pure Ruby — **no compiler needed to install it** (which is
+the whole point).
+
+> This is the gap nothing else filled: `rake-compiler` hardcodes `nmake` and
+> assumes `cl` is already on `PATH`; `rb_sys`, `ffi-compiler`, and
+> `rake-compiler-dock` are all MinGW/GCC-oriented. None of them activate the
+> MSVC environment for a native `mswin` build.
+
+## Install
+
+```sh
+gem install vcvars
+```
+
+## Quick start
+
+### Build a C extension without a Developer Prompt
+
+In a `Rakefile` that uses `rake-compiler`:
+
+```ruby
+require "vcvars/rake"          # <- finds VS and loads the MSVC toolchain (mswin only)
+require "rake/extensiontask"
+
+spec = Gem::Specification.load("my_ext.gemspec")
+Rake::ExtensionTask.new("my_ext", spec) { |e| e.lib_dir = "lib/my_ext" }
+```
+
+Now `rake compile` just works from an ordinary shell. (`require "vcvars/rake"`
+is a no-op on a MinGW/UCRT Ruby and inside an already-active dev environment.)
+
+### Run any command inside the MSVC environment
+
+```sh
+vcvars exec -- rake compile
+vcvars exec -- nmake
+vcvars exec -- ruby extconf.rb
+```
+
+### Diagnose a broken toolchain
+
+```sh
+vcvars doctor
+```
+
+```
+[ OK ] Ruby is a native MSVC (mswin) build
+       3.4.8 x64-mswin64_140  RUBY_SO_NAME=x64-vcruntime140-ruby340
+[INFO] Ruby CRT linkage: MD
+[ OK ] Ruby headers present
+[ OK ] Ruby import library present
+[WARN] Developer environment is NOT active
+       cl.exe / nmake.exe are not on PATH ... Use `vcvars exec -- <cmd>` ...
+[ OK ] Visual Studio located
+       Visual Studio Community 2026 (18.5...) at C:\Program Files\Microsoft Visual Studio\18\Community
+[ OK ] vcvars activation works (cl.exe resolvable)
+```
+
+`doctor` knows the usual suspects and how to fix each: dev env not loaded,
+`C1083` (missing `ruby.h`), `LNK2019/LNK2001` (unresolved externals),
+`LNK2005` (CRT `/MD` vs `/MT` mismatch), `LNK1112` (x64/x86 arch mismatch),
+`LNK1104` (`LIB` unset), warnings-promoted-to-errors, and mswin-vs-mingw mix-ups.
+
+### Scaffold a new MSVC-ready extension gem
+
+```sh
+vcvars new my_ext
+cd my_ext
+bundle install
+rake compile && rake test
+```
+
+The generated gem has a correct, portable `extconf.rb`, a warning-clean sample
+`.c` (clean under Ruby's aggressive `-we` flags), a `Rakefile` already wired to
+`vcvars/rake`, and a passing test.
+
+### Emit the environment for your shell
+
+```powershell
+vcvars env --format powershell | Invoke-Expression
+```
+
+```sh
+vcvars env --format bat > vcenv.bat && call vcenv.bat   # cmd.exe
+vcvars env --format json                                # machine-readable
+```
+
+## Library API
+
+```ruby
+require "vcvars"
+
+Vcvars.mswin?       # => true on a native MSVC Ruby
+Vcvars.active?      # => is a developer environment already loaded in this process?
+Vcvars.activate!    # locate VS + import the MSVC env into ENV (idempotent); => true/false
+Vcvars.locate       # => Vcvars::Locator::Installation (vs_path, vcvars, arch, version, name)
+Vcvars.env          # => Hash of the env vars vcvars adds/changes (no ENV mutation)
+
+# Target a different toolchain arch:
+Vcvars.activate!(arch: "arm64")
+```
+
+## How it works
+
+`vcvars` runs the located `vcvars*.bat` inside a short-lived `cmd.exe`, dumps the
+resulting environment with `set` (separated from banner noise by a marker line),
+diffs it against the current environment, and imports the new/changed variables
+(`PATH`, `INCLUDE`, `LIB`, `LIBPATH`, the `VSCMD_*`/`VC*` markers, …) into `ENV`.
+rake-compiler shells out with `FileUtils#sh`, which inherits that `ENV`, so a
+single activation covers the `extconf.rb`, `nmake`, and `nmake install` steps.
+
+Activation is idempotent (it no-ops when `VSCMD_VER` is set or `cl.exe` is
+already on `PATH`), so it's safe to call from every Rake invocation.
+
+## Requirements
+
+- Windows with a native **MSVC** Ruby (`x64-mswin64` / `RUBY_SO_NAME` containing
+  `vcruntime`). On a MinGW/UCRT Ruby, use RubyInstaller's `ridk enable` instead.
+- Visual Studio 2017+ or the Build Tools with the **Desktop development with
+  C++** workload (provides `cl.exe`, `nmake.exe`, and `vcvars*.bat`).
+
+## License
+
+[MIT](LICENSE.txt).

data/exe/vcvars

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vcvars/cli"
+
+exit Vcvars::CLI.start(ARGV)

data/lib/vcvars/cli.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "vcvars"
+
+module Vcvars
+  # Command-line interface for the `vcvars` executable.
+  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 "env"                         then cmd_env(argv)
+      when "exec"                        then cmd_exec(argv)
+      when "new"                         then cmd_new(argv)
+      when "version", "-v", "--version"  then cmd_version
+      when nil, "help", "-h", "--help"   then print_help; 0
+      else
+        warn "vcvars: unknown command #{command.inspect}\n\n"
+        print_help
+        1
+      end
+    rescue Vcvars::Error, ArgumentError => e
+      # ArgumentError covers user input like an unsupported `--arch` value, which
+      # Locator.vcvars_name raises; report it the same clean way as other errors.
+      warn "vcvars: #{e.message}"
+      1
+    rescue Interrupt
+      130
+    end
+
+    # --- commands ------------------------------------------------------------
+
+    def cmd_version
+      puts "vcvars #{Vcvars::VERSION}"
+      0
+    end
+
+    def cmd_doctor(argv)
+      require "vcvars/doctor"
+      deep = !argv.include?("--quick")
+      checks = Doctor.run(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)
+      arch = extract_opt(argv, "--arch")
+      inst = arch ? Vcvars.locate(arch: arch) : Vcvars.locate
+      if inst
+        puts inst.to_s
+        puts "vcvars script: #{inst.vcvars}"
+        puts "target arch:   #{inst.arch}"
+        0
+      else
+        warn "vcvars: no Visual Studio with the C++ tools was found."
+        warn "Install the \"Desktop development with C++\" workload, then retry."
+        1
+      end
+    end
+
+    def cmd_env(argv)
+      format = (extract_opt(argv, "--format") || "bat").downcase
+      arch   = extract_opt(argv, "--arch")
+      delta  = arch ? Vcvars.env(arch: arch) : Vcvars.env
+      print_env(delta, format)
+      0
+    end
+
+    def cmd_exec(argv)
+      arch, command = parse_exec_args(argv)
+      if command.nil? || command.empty?
+        warn "vcvars exec: no command given."
+        warn "Example: vcvars exec -- rake compile"
+        return 1
+      end
+
+      arch ? Vcvars.activate!(arch: arch) : Vcvars.activate!
+
+      ok = system(*command)
+      if ok.nil?
+        warn "vcvars exec: failed to run #{command.first.inspect} (not found?)."
+        return 127
+      end
+      $?.exitstatus || (ok ? 0 : 1)
+    end
+
+    def cmd_new(argv)
+      require "vcvars/scaffold"
+      force = argv.delete("--force") ? true : false
+      dir   = extract_opt(argv, "--dir")
+      name  = argv.shift
+
+      unless name
+        warn "vcvars new: missing NAME."
+        warn "Example: vcvars new my_ext"
+        return 1
+      end
+
+      scaffold = Scaffold.new(name, dir: dir)
+      created  = scaffold.generate(force: force)
+
+      puts "Created gem '#{scaffold.name}' (module #{scaffold.module_name}) in #{scaffold.dest}:"
+      prefix = scaffold.dest + File::SEPARATOR
+      created.each { |f| puts "  #{f.start_with?(prefix) ? f[prefix.length..] : f}" }
+      puts
+      puts "Next steps:"
+      puts "  cd #{scaffold.dest}"
+      puts "  bundle install"
+      puts "  rake compile && rake test"
+      0
+    end
+
+    # --- helpers -------------------------------------------------------------
+
+    # Splits exec args into [arch, command]. Flags (a leading --arch, or
+    # anything before a "--" separator) are parsed; the rest is the command.
+    def parse_exec_args(argv)
+      if (sep = argv.index("--"))
+        head = argv[0...sep]
+        command = argv[(sep + 1)..]
+        [extract_opt(head, "--arch"), command]
+      else
+        rest = argv.dup
+        arch = nil
+        # Only honor flags that appear before the command.
+        if rest.first == "--arch"
+          rest.shift
+          arch = rest.shift
+        elsif rest.first.to_s.start_with?("--arch=")
+          arch = rest.shift.split("=", 2)[1]
+        end
+        [arch, rest]
+      end
+    end
+
+    # Pulls "--opt value" or "--opt=value" out of argv (mutating it). Returns
+    # the value or nil.
+    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_env(delta, format)
+      keys = delta.keys.sort_by(&:upcase)
+      case format
+      when "bat", "cmd"
+        keys.each { |k| puts %{set "#{k}=#{delta[k]}"} }
+      when "powershell", "ps", "ps1"
+        keys.each { |k| puts %{$env:#{k} = '#{delta[k].to_s.gsub("'", "''")}'} }
+      when "sh", "bash"
+        keys.each { |k| puts %{export #{k}="#{sh_escape(delta[k])}"} }
+      when "dotenv", "env"
+        keys.each { |k| puts "#{k}=#{delta[k]}" }
+      when "json"
+        require "json"
+        puts JSON.pretty_generate(delta)
+      else
+        raise Error, "unknown --format #{format.inspect} " \
+          "(use bat, powershell, sh, dotenv, or json)."
+      end
+    end
+
+    def sh_escape(value)
+      value.to_s.gsub(/[\\"$`]/) { |c| "\\#{c}" }
+    end
+
+    def print_help
+      puts <<~HELP
+        vcvars #{Vcvars::VERSION} — load the MSVC build environment for native Ruby extensions.
+
+        Usage:
+          vcvars doctor [--quick]          Diagnose the MSVC extension toolchain
+          vcvars where  [--arch ARCH]      Show the located Visual Studio + vcvars script
+          vcvars env    [--arch ARCH] [--format bat|powershell|sh|dotenv|json]
+                                           Print the MSVC env vars (the vcvars delta)
+          vcvars exec   [--arch ARCH] -- CMD [ARGS...]
+                                           Run CMD inside the MSVC environment
+          vcvars new    NAME [--dir DIR] [--force]
+                                           Scaffold a new MSVC-ready C-extension gem
+          vcvars version
+          vcvars help
+
+        Examples:
+          vcvars doctor
+          vcvars exec -- rake compile
+          vcvars exec -- nmake
+          vcvars env --format powershell | Invoke-Expression
+          vcvars new my_ext
+
+        In a Rakefile, `require "vcvars/rake"` before Rake::ExtensionTask.new to
+        auto-load the toolchain so `rake compile` works without a Developer Prompt.
+      HELP
+    end
+  end
+end

data/lib/vcvars/doctor.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+require "vcvars/locator"
+require "vcvars/environment"
+
+module Vcvars
+  # Diagnoses the common reasons a native C-extension build fails under an MSVC
+  # (mswin) Ruby on Windows, and explains how to fix each one. The checks are
+  # derived from the actual RbConfig of the running Ruby plus live probes of the
+  # toolchain, so the advice is specific rather than generic.
+  module Doctor
+    module_function
+
+    Check = Struct.new(:status, :label, :detail, keyword_init: true) do
+      # :ok | :warn | :fail | :info
+      def icon
+        { ok: "[ OK ]", warn: "[WARN]", fail: "[FAIL]", info: "[INFO]" }[status]
+      end
+    end
+
+    # ---- RbConfig-based primitives (cheap, no shell-out) --------------------
+
+    def mswin?
+      RbConfig::CONFIG["target_os"].to_s =~ /mswin/ ? true : false
+    end
+
+    # :mswin | :mingw_ucrt | :mingw_msvcrt | :other
+    def toolchain
+      os = RbConfig::CONFIG["target_os"].to_s
+      so = RbConfig::CONFIG["RUBY_SO_NAME"].to_s
+      return :mswin        if os =~ /mswin/
+      return :mingw_ucrt   if so =~ /ucrt/i || os =~ /ucrt/i
+      return :mingw_msvcrt if os =~ /mingw/
+      :other
+    end
+
+    # CRT linkage Ruby itself was built with: :MD | :MDd | :MT | :MTd | :unknown
+    def crt_flag(cflags = RbConfig::CONFIG["CFLAGS"].to_s)
+      case cflags
+      when %r{(?:^|\s)[-/]MDd\b} then :MDd
+      when %r{(?:^|\s)[-/]MTd\b} then :MTd
+      when %r{(?:^|\s)[-/]MD\b}  then :MD
+      when %r{(?:^|\s)[-/]MT\b}  then :MT
+      else :unknown
+      end
+    end
+
+    # Target machine the linker must produce: :x64 | :x86 | :arm64 | :unknown
+    def arch
+      a = RbConfig::CONFIG["arch"].to_s
+      return :x64   if a =~ /\A(?:x64|x86_64|amd64)/i
+      return :arm64 if a =~ /arm64|aarch64/i
+      return :x86   if a =~ /\A(?:i[3-6]86|x86)/i
+      :unknown
+    end
+
+    # If the given extension flags use a static CRT while Ruby uses a dynamic
+    # one (or vice-versa), return the offending flag (:MT/:MTd/:MD/:MDd); else nil.
+    def crt_conflict(ext_cflags, ruby_crt = crt_flag)
+      return nil if ext_cflags.to_s.empty?
+      ruby_dynamic = %i[MD MDd].include?(ruby_crt)
+      if ruby_dynamic && ext_cflags =~ %r{(?:^|\s)[-/]MT(d?)\b}
+        Regexp.last_match(1) == "d" ? :MTd : :MT
+      elsif !ruby_dynamic && ext_cflags =~ %r{(?:^|\s)[-/]MD(d?)\b}
+        Regexp.last_match(1) == "d" ? :MDd : :MD
+      end
+    end
+
+    # Warnings Ruby promotes to hard errors, e.g. ["-we4028", "-we4047"].
+    def werror_flags(cflags = RbConfig::CONFIG["CFLAGS"].to_s)
+      cflags.scan(/-we\d{4}/).uniq
+    end
+
+    def import_lib_path
+      File.join(RbConfig::CONFIG["libdir"], RbConfig::CONFIG["LIBRUBYARG_SHARED"].to_s)
+    end
+
+    def ruby_header_path
+      File.join(RbConfig::CONFIG["rubyhdrdir"].to_s, "ruby.h")
+    end
+
+    # `where <tool>` prints "INFO: Could not find files..." and exits non-zero
+    # when a tool is absent. Returns the resolved path, or nil.
+    def which(tool)
+      out, status = Open3.capture2("where", tool)
+      return nil unless status.success?
+      line = out.lines.map(&:strip).find { |l| !l.empty? && l !~ /Could not find/ }
+      line
+    rescue StandardError
+      nil
+    end
+
+    # ---- The diagnostic run --------------------------------------------------
+
+    # Returns an Array<Check>. When deep: true, also locates VS and tries a real
+    # environment capture (so it can confirm a build would actually find cl).
+    def run(deep: true)
+      checks = []
+      checks.concat(ruby_checks)
+      checks.concat(header_checks)
+      checks.concat(env_checks)
+      checks.concat(vs_checks(deep: deep))
+      checks.concat(hygiene_checks)
+      checks
+    end
+
+    def ruby_checks
+      ver = "#{RUBY_VERSION} #{RbConfig::CONFIG['arch']}"
+      tc = toolchain
+      out = []
+      out << if mswin?
+        Check.new(status: :ok, label: "Ruby is a native MSVC (mswin) build",
+                  detail: "#{ver}  RUBY_SO_NAME=#{RbConfig::CONFIG['RUBY_SO_NAME']}")
+      else
+        Check.new(status: :warn, label: "Ruby is NOT an mswin build (#{tc})",
+                  detail: "vcvars targets the MSVC (mswin) Ruby. On a MinGW/UCRT " \
+                          "Ruby use RubyInstaller's `ridk enable` instead — the MSVC " \
+                          "toolchain is ABI-incompatible with this build.")
+      end
+      out << Check.new(status: :info, label: "Ruby CRT linkage: #{crt_flag}",
+                       detail: "Extensions must use the same CRT. mkmf inherits this " \
+                               "automatically — never force /MT or /MTd.")
+      we = werror_flags
+      unless we.empty?
+        out << Check.new(status: :info, label: "Warnings promoted to errors: #{we.join(' ')}",
+                         detail: "Missing prototypes (C4013) and pointer/type mismatches " \
+                                 "(C4047/C4028) will hard-fail. Include the right headers; " \
+                                 "do not strip these flags.")
+      end
+      out
+    end
+
+    def header_checks
+      out = []
+      out << if File.exist?(ruby_header_path)
+        Check.new(status: :ok, label: "Ruby headers present", detail: ruby_header_path)
+      else
+        Check.new(status: :fail, label: "ruby.h NOT found",
+                  detail: "Expected at #{ruby_header_path}. C1083 'Cannot open include " \
+                          "file' results. Reinstall Ruby's dev headers, and always run " \
+                          "`ruby extconf.rb` (which injects the -I paths) before nmake.")
+      end
+      out << if File.exist?(import_lib_path)
+        Check.new(status: :ok, label: "Ruby import library present", detail: import_lib_path)
+      else
+        Check.new(status: :fail, label: "Ruby import library NOT found",
+                  detail: "Expected #{import_lib_path}. Missing it causes LNK2019/LNK1104. " \
+                          "Link through mkmf, which adds it via LIBRUBYARG.")
+      end
+      out
+    end
+
+    def env_checks
+      out = []
+      if Environment.active?
+        cl = which("cl") || "(on PATH)"
+        out << Check.new(status: :ok, label: "Developer environment is ACTIVE in this process",
+                         detail: "cl: #{cl}")
+        out << if (ENV["LIB"] || "").strip.empty?
+          Check.new(status: :warn, label: "LIB is empty despite an active dev env",
+                    detail: "The linker may fail with LNK1104. Re-activate with a full vcvars.")
+        else
+          Check.new(status: :ok, label: "LIB / library search path is set", detail: nil)
+        end
+        if ENV["VSCMD_ARG_TGT_ARCH"] && !ENV["VSCMD_ARG_TGT_ARCH"].casecmp?(arch.to_s)
+          out << Check.new(status: :fail,
+                           label: "Toolchain arch (#{ENV['VSCMD_ARG_TGT_ARCH']}) != Ruby arch (#{arch})",
+                           detail: "Causes LNK1112. For #{arch} Ruby use vcvars64.bat, not vcvars32.bat.")
+        end
+      else
+        out << Check.new(status: :warn, label: "Developer environment is NOT active",
+                         detail: "cl.exe / nmake.exe are not on PATH, so `rake compile` / " \
+                                 "`gem install <native>` will fail with \"'nmake' is not " \
+                                 "recognized\". Use `vcvars exec -- <cmd>`, `require \"vcvars/rake\"` " \
+                                 "in your Rakefile, or `vcvars env` to load it.")
+      end
+      out
+    end
+
+    def vs_checks(deep:)
+      out = []
+      inst = Locator.find
+      if inst.nil?
+        out << Check.new(status: :fail, label: "No Visual Studio with C++ tools found",
+                         detail: "Looked via vswhere (#{Locator::VSWHERE}) and known install " \
+                                 "roots. Install the \"Desktop development with C++\" workload.")
+        return out
+      end
+
+      out << Check.new(status: :ok, label: "Visual Studio located", detail: inst.to_s)
+      out << Check.new(status: :info, label: "vcvars script", detail: inst.vcvars)
+
+      return out unless deep
+
+      begin
+        captured = Environment.capture(vcvars: inst.vcvars)
+        cl_dir = (captured.find { |k, _| k.casecmp("PATH").zero? }&.last || "")
+                 .split(File::PATH_SEPARATOR).find { |d| !d.empty? && File.exist?(File.join(d, "cl.exe")) }
+        out << if cl_dir
+          Check.new(status: :ok, label: "vcvars activation works (cl.exe resolvable)",
+                    detail: File.join(cl_dir, "cl.exe"))
+        else
+          Check.new(status: :warn, label: "vcvars ran but cl.exe was not found on the new PATH",
+                    detail: "The C++ toolset may not be installed for this arch.")
+        end
+      rescue Error => e
+        out << Check.new(status: :fail, label: "vcvars activation failed", detail: e.message)
+      end
+      out
+    end
+
+    def hygiene_checks
+      out = []
+      # A GNU `link` (from Git/MSYS) on PATH shadows the MSVC linker and causes
+      # baffling link failures.
+      link = which("link")
+      if link && link =~ %r{[\\/](Git|usr|msys|mingw)[\\/]}i
+        out << Check.new(status: :warn, label: "A non-MSVC `link` is on PATH",
+                         detail: "#{link} is the GNU coreutils `link`, not the MSVC linker. " \
+                                 "Inside an active dev env the MSVC link.exe should win; if you " \
+                                 "see strange linker errors, check PATH order.")
+      end
+
+      # User-injected CRT flags that would conflict with Ruby's CRT.
+      ext_flags = "#{ENV['CL']} #{ENV['CFLAGS']}".strip
+      if (bad = crt_conflict(ext_flags))
+        out << Check.new(status: :fail, label: "CRT conflict in CL/CFLAGS: #{bad}",
+                         detail: "Ruby uses #{crt_flag}; your environment forces #{bad}. " \
+                                 "This causes LNK2005 'already defined' and runtime heap " \
+                                 "corruption. Remove /#{bad} from the CL and CFLAGS env vars.")
+      end
+      out
+    end
+
+    # Convenience: did the run surface any hard failure?
+    def healthy?(checks)
+      checks.none? { |c| c.status == :fail }
+    end
+  end
+end