envdoctor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec3513e2cfdb6870cd1608bf7d5a3cf2c831113187ff3ca34ed6fe9539a231d5
+  data.tar.gz: 76b4d2234288c38d2c20c27ee39db004a69da9adfe945a7ef6a856a5e56f7f5b
+SHA512:
+  metadata.gz: fc16e6e1ca03e96d1e72a88a05391370afc810790dae1d338a77759d9152b3cdb0ad6ecfd86d51faf093196144eeb2ba66ba352822c3859718114c5a0e0a9fc0
+  data.tar.gz: fada228584d093fb6fc71ecc9dbda5cd2d7fe20b66c646e490383c981e87d01db9b2d3e56fb79ca0a5ac8d831e9fcfd569d7d42e837aca2af1bff8513d9a7e47

data/README.md

@@ -0,0 +1,33 @@
+# envdoctor (Ruby)
+
+Native Ruby port of [envdoctor](https://github.com/arun-skg/envdoctor) — a
+local-first environment-variable consistency checker, packaged as a gem.
+
+```bash
+gem install envdoctor
+envdoctor scan --dir .
+```
+
+## What it does
+
+Reconciles variables **used** in Ruby source (`ENV["X"]`, `ENV['X']`,
+`ENV.fetch("X")`) against those **defined** in `.env` files:
+
+| Rule | Severity | Meaning |
+|------|----------|---------|
+| `undefined-in-source` | error | Used in code but not defined in any `.env` file |
+| `unused` | warning | Defined in `.env` but never referenced in source |
+
+Comments and `=begin/=end` blocks are stripped before scanning. `scan` exits
+`1` on errors (or warnings with `--strict`). Values are never printed.
+
+## Development
+
+```bash
+cd ruby
+ruby -Ilib test/test_scanner.rb
+gem build envdoctor.gemspec
+```
+
+One of several native, per-ecosystem ports; the reference implementation lives
+in the [main repository](https://github.com/arun-skg/envdoctor).

data/exe/envdoctor

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/envdoctor"
+exit Envdoctor::CLI.run(ARGV)

data/lib/envdoctor/cli.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "scanner"
+
+module Envdoctor
+  # Command-line entry point.
+  module CLI
+    module_function
+
+    def run(argv)
+      dir = "."
+      strict = false
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: envdoctor scan [options]"
+        o.on("-d", "--dir DIR", "Project root (default: cwd)") { |v| dir = v }
+        o.on("--strict", "Treat warnings as errors") { strict = true }
+      end
+      args = argv.dup
+      args.shift if args.first == "scan"
+      parser.parse!(args)
+
+      root = File.expand_path(dir)
+      findings = Scanner.scan(root)
+      errors = findings.select { |f| f.severity == "error" }
+      warnings = findings.select { |f| f.severity == "warning" }
+
+      puts "ENVIRONMENT AUDIT"
+      puts "=" * 40
+      if findings.empty?
+        puts "\nNo issues found."
+        return 0
+      end
+
+      unless errors.empty?
+        puts "\nErrors"
+        errors.each { |f| puts "  x #{f.name} #{f.origin.file}:#{f.origin.line}  #{f.message}" }
+      end
+      unless warnings.empty?
+        puts "\nWarnings"
+        warnings.each { |f| puts "  ! #{f.name} #{f.origin.file}:#{f.origin.line}  #{f.message}" }
+      end
+      puts "\nSummary: #{errors.length} error(s), #{warnings.length} warning(s)"
+
+      (!errors.empty? || (strict && !warnings.empty?)) ? 1 : 0
+    end
+  end
+end

data/lib/envdoctor/scanner.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Envdoctor
+  # Core scanner: reconcile ENV usage in Ruby source against .env definitions.
+  # Local-first — no network, values never printed.
+  module Scanner
+    module_function
+
+    USAGE_PATTERNS = [
+      /\bENV\[\s*["']([A-Za-z_]\w*)["']\s*\]/,
+      /\bENV\.fetch\(\s*["']([A-Za-z_]\w*)["']/
+    ].freeze
+
+    ENV_LINE = /\A\s*(?:export\s+)?([A-Za-z_]\w*)\s*=/.freeze
+
+    Origin = Struct.new(:file, :line)
+    Finding = Struct.new(:rule, :severity, :name, :message, :origin)
+
+    # Blank comments and =begin/=end blocks, preserving line structure.
+    def strip_noise(code)
+      code = code.gsub(/^=begin\b.*?^=end\b[^\n]*/m) { |m| m.gsub(/[^\n]/, " ") }
+      code.gsub(/#[^\n]*/) { |m| " " * m.length }
+    end
+
+    def scan_source(path, content)
+      text = strip_noise(content)
+      used = {}
+      USAGE_PATTERNS.each do |re|
+        text.to_enum(:scan, re).each do
+          match = Regexp.last_match
+          name = match[1]
+          next if used.key?(name)
+
+          line = text[0...match.begin(0)].count("\n") + 1
+          used[name] = Origin.new(path, line)
+        end
+      end
+      used
+    end
+
+    def parse_env(path, content)
+      defined = {}
+      content.split("\n").each_with_index do |raw, i|
+        stripped = raw.strip
+        next if stripped.empty? || stripped.start_with?("#")
+
+        if (m = raw.match(ENV_LINE))
+          defined[m[1]] ||= Origin.new(path, i + 1)
+        end
+      end
+      defined
+    end
+
+    def discover_env_files(root)
+      files = Dir.glob(File.join(root, ".env"))
+      files += Dir.glob(File.join(root, ".env.*")).reject { |f| f.end_with?(".example") }
+      files.sort
+    end
+
+    def discover_source_files(root)
+      Dir.glob(File.join(root, "**", "*.rb")).reject do |p|
+        p.split(File::SEPARATOR).any? { |part| %w[.git vendor node_modules].include?(part) }
+      end.sort
+    end
+
+    def scan(root)
+      defined = {}
+      discover_env_files(root).each do |f|
+        parse_env(relative(root, f), File.read(f)).each { |k, v| defined[k] ||= v }
+      end
+
+      used = {}
+      discover_source_files(root).each do |f|
+        scan_source(relative(root, f), File.read(f)).each { |k, v| used[k] ||= v }
+      end
+
+      findings = []
+      used.keys.sort.each do |name|
+        next if defined.key?(name)
+
+        findings << Finding.new("undefined-in-source", "error", name,
+                                "used in source code but not defined in any environment file",
+                                used[name])
+      end
+      defined.keys.sort.each do |name|
+        next if used.key?(name)
+
+        findings << Finding.new("unused", "warning", name,
+                                "defined but never referenced in source", defined[name])
+      end
+      findings
+    end
+
+    def relative(root, path)
+      path.sub(/\A#{Regexp.escape(root)}#{Regexp.escape(File::SEPARATOR)}?/, "")
+    end
+  end
+end

data/lib/envdoctor.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "envdoctor/scanner"
+require_relative "envdoctor/cli"
+
+module Envdoctor
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: envdoctor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Arun Natesan
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-08-22 00:00:00.000000000 Z
+dependencies: []
+description: 'Reconciles ENV usage in Ruby source against .env files: reports undefined-in-source
+  (error) and unused (warning). Local-first, no network.'
+email:
+executables:
+- envdoctor
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/envdoctor
+- lib/envdoctor.rb
+- lib/envdoctor/cli.rb
+- lib/envdoctor/scanner.rb
+homepage: https://github.com/arun-skg/envdoctor
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/arun-skg/envdoctor
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Local-first consistency checker for environment variables (native Ruby port)
+test_files: []