envdoctor 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec3513e2cfdb6870cd1608bf7d5a3cf2c831113187ff3ca34ed6fe9539a231d5
-  data.tar.gz: 76b4d2234288c38d2c20c27ee39db004a69da9adfe945a7ef6a856a5e56f7f5b
+  metadata.gz: c56b394b123626a7937ba9451db0598b9825f3a83d93a8216e973b0c067b8d8a
+  data.tar.gz: 67da28da5cdd7a8bf767435c77251f031dda10c4dd727f867c5d70f5eca871fe
 SHA512:
-  metadata.gz: fc16e6e1ca03e96d1e72a88a05391370afc810790dae1d338a77759d9152b3cdb0ad6ecfd86d51faf093196144eeb2ba66ba352822c3859718114c5a0e0a9fc0
-  data.tar.gz: fada228584d093fb6fc71ecc9dbda5cd2d7fe20b66c646e490383c981e87d01db9b2d3e56fb79ca0a5ac8d831e9fcfd569d7d42e837aca2af1bff8513d9a7e47
+  metadata.gz: 14f9554eedeb73d00fd139a20d24c7491470c56acce2902c3f2fa27039069d918807776bdd85198b479ee88a3ea178e47a9db210f3b86b9e645211ad013fddf0
+  data.tar.gz: 0ee4ca3cf10a6e51b323f8d57ff7babf7b1a6b9050ff1ea6657907129bc66eed67c51a5b874cdda180d9cfafad592ec8e74c825b8c789188916db40e7a9cc28f

data/README.md

@@ -3,12 +3,21 @@
 Native Ruby port of [envdoctor](https://github.com/arun-skg/envdoctor) — a
 local-first environment-variable consistency checker, packaged as a gem.
 
+## Install
+
 ```bash
 gem install envdoctor
-envdoctor scan --dir .
 ```
 
-## What it does
+## Quick start
+
+```bash
+envdoctor scan --dir .        # audit; exit 1 on errors
+envdoctor scan --strict       # treat warnings as errors too
+envdoctor scan --json         # emit findings as a JSON array (values never included)
+```
+
+## What it detects
 
 Reconciles variables **used** in Ruby source (`ENV["X"]`, `ENV['X']`,
 `ENV.fetch("X")`) against those **defined** in `.env` files:
@@ -16,10 +25,23 @@ Reconciles variables **used** in Ruby source (`ENV["X"]`, `ENV['X']`,
 | Rule | Severity | Meaning |
 |------|----------|---------|
 | `undefined-in-source` | error | Used in code but not defined in any `.env` file |
+| `duplicates` | error | Same key defined 2+ times in a single `.env` file |
+| `public-prefix` | error | Secret-looking variable exposed to client bundles via a public prefix (`NEXT_PUBLIC_`, `VITE_`, `REACT_APP_`, …) |
+| `type-mismatch` | error | Variable's inferred value type differs across environments (e.g. integer vs string) |
 | `unused` | warning | Defined in `.env` but never referenced in source |
+| `environment-diff` | warning | Defined in some environments but missing from others |
+| `weak-secret` | warning | Secret-looking variable has an empty, short, or placeholder value |
+| `typo` | warning | Used name closely matches a defined name (likely misspelling) |
+
+Environment labels come from the `.env` filename (`.env`→`default`,
+`.env.local`→`local`, `.env.production`→`production`,
+`.env.production.local`→`production`); `*.example` files are skipped. Values are
+read only to power detection and are **never** included in any output.
 
 Comments and `=begin/=end` blocks are stripped before scanning. `scan` exits
-`1` on errors (or warnings with `--strict`). Values are never printed.
+`1` on errors (or warnings with `--strict`). Pass `--json` to emit the findings
+as a JSON array (keys: `rule`, `severity`, `name`, `message`, `file`, `line`) —
+still without any values.
 
 ## Development
 
@@ -29,5 +51,10 @@ 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).
+## Other languages
+
+envdoctor ships as a standalone native port for each ecosystem:
+
+- [Node (reference)](..) · [Python](../python) · [Go](../go) · [PHP](../php) · [Java](../java) · [Perl](../perl)
+- 📖 Docs: [arun-skg.github.io/envdoctor](https://arun-skg.github.io/envdoctor/)
+- Main repository: [github.com/arun-skg/envdoctor](https://github.com/arun-skg/envdoctor)

data/lib/envdoctor/cli.rb

@@ -11,10 +11,12 @@ module Envdoctor
     def run(argv)
       dir = "."
       strict = false
+      json = 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 }
+        o.on("--json", "Emit findings as a JSON array") { json = true }
       end
       args = argv.dup
       args.shift if args.first == "scan"
@@ -25,6 +27,11 @@ module Envdoctor
       errors = findings.select { |f| f.severity == "error" }
       warnings = findings.select { |f| f.severity == "warning" }
 
+      if json
+        puts Scanner.to_json_array(findings)
+        return (!errors.empty? || (strict && !warnings.empty?)) ? 1 : 0
+      end
+
       puts "ENVIRONMENT AUDIT"
       puts "=" * 40
       if findings.empty?

data/lib/envdoctor/scanner.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Envdoctor
   # Core scanner: reconcile ENV usage in Ruby source against .env definitions.
   # Local-first — no network, values never printed.
@@ -13,7 +15,18 @@ module Envdoctor
 
     ENV_LINE = /\A\s*(?:export\s+)?([A-Za-z_]\w*)\s*=/.freeze
 
+    PUBLIC_PREFIXES = %w[
+      NEXT_PUBLIC_ VITE_ REACT_APP_ EXPO_PUBLIC_ GATSBY_ NUXT_PUBLIC_ VUE_APP_ PUBLIC_
+    ].freeze
+
+    SECRET_RE = /SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE|CREDENTIAL|API_?KEY|ACCESS_?KEY|AUTH/i.freeze
+
+    WEAK_VALUE_RE =
+      /\A(changeme|change_me|placeholder|x{3,}|todo|secret|password|passwd|test|example|sample|dummy|your[_-].*|<.*>|\$\{.*\})\z/i.freeze
+
     Origin = Struct.new(:file, :line)
+    # A single .env definition occurrence: its line and parsed value.
+    Definition = Struct.new(:line, :value)
     Finding = Struct.new(:rule, :severity, :name, :message, :origin)
 
     # Blank comments and =begin/=end blocks, preserving line structure.
@@ -38,6 +51,21 @@ module Envdoctor
       used
     end
 
+    # Parse the VALUE to the right of the first `=`: trim, then strip one pair
+    # of matching surrounding quotes. Values are used ONLY for detection and are
+    # never surfaced in any output.
+    def parse_value(raw)
+      idx = raw.index("=")
+      return "" if idx.nil?
+
+      value = raw[(idx + 1)..].to_s.strip
+      if value.length >= 2 && %w[" '].include?(value[0]) && value[-1] == value[0]
+        value = value[1..-2]
+      end
+      value
+    end
+
+    # Returns { name => [Definition, ...] } with ALL occurrences per key in order.
     def parse_env(path, content)
       defined = {}
       content.split("\n").each_with_index do |raw, i|
@@ -45,12 +73,70 @@ module Envdoctor
         next if stripped.empty? || stripped.start_with?("#")
 
         if (m = raw.match(ENV_LINE))
-          defined[m[1]] ||= Origin.new(path, i + 1)
+          (defined[m[1]] ||= []) << Definition.new(i + 1, parse_value(raw))
         end
       end
       defined
     end
 
+    # Derive the environment label from a .env filename.
+    def env_label(filename)
+      base = File.basename(filename)
+      return "default" if base == ".env"
+
+      label = base.sub(/\A\.env\./, "")
+      label = label.sub(/\.local\z/, "") if label.end_with?(".local")
+      label
+    end
+
+    def public_prefix?(name)
+      PUBLIC_PREFIXES.any? { |p| name.start_with?(p) } && SECRET_RE.match?(name)
+    end
+
+    # Infer the coarse type of a value string.
+    def infer_type(value)
+      return "empty" if value.empty?
+      return "integer" if value.match?(/\A-?\d+\z/)
+      return "float" if value.match?(/\A-?\d+\.\d+\z/)
+      return "boolean" if value.match?(/\A(true|false)\z/i)
+      return "url" if value.match?(%r{\Ahttps?://})
+
+      if value.start_with?("{", "[")
+        begin
+          JSON.parse(value)
+          return "json"
+        rescue JSON::ParserError
+          # fall through to string
+        end
+      end
+      "string"
+    end
+
+    # Compatibility group for an inferred type (integer/float collapse to numeric).
+    def type_group(type)
+      %w[integer float].include?(type) ? "numeric" : type
+    end
+
+    def weak_secret?(value)
+      value.empty? || value.length < 8 || WEAK_VALUE_RE.match?(value)
+    end
+
+    def levenshtein(a, b)
+      return b.length if a.empty?
+      return a.length if b.empty?
+
+      prev = (0..b.length).to_a
+      a.each_char.with_index do |ca, i|
+        curr = [i + 1]
+        b.each_char.with_index do |cb, j|
+          cost = ca == cb ? 0 : 1
+          curr << [curr[j] + 1, prev[j + 1] + 1, prev[j] + cost].min
+        end
+        prev = curr
+      end
+      prev[b.length]
+    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") }
@@ -64,9 +150,32 @@ module Envdoctor
     end
 
     def scan(root)
-      defined = {}
+      defined = {}          # name => Origin (first definition wins)
+      defined_value = {}    # name => value at first definition
+      labels_of = {}        # name => { label => value } (first value per label)
+      project_labels = []
+      dup_findings = []
+
       discover_env_files(root).each do |f|
-        parse_env(relative(root, f), File.read(f)).each { |k, v| defined[k] ||= v }
+        rel = relative(root, f)
+        label = env_label(f)
+        project_labels << label unless project_labels.include?(label)
+        parse_env(rel, File.read(f)).each do |name, defs|
+          if defs.length >= 2
+            lines = defs.map(&:line)
+            dup_findings << Finding.new("duplicates", "error", name,
+                                        "defined #{defs.length} times in the same file " \
+                                        "(lines #{lines.join(', ')})",
+                                        Origin.new(rel, defs.first.line))
+          end
+          # First occurrence (first file wins) counts as the definition.
+          unless defined.key?(name)
+            defined[name] = Origin.new(rel, defs.first.line)
+            defined_value[name] = defs.first.value
+          end
+          bucket = (labels_of[name] ||= {})
+          bucket[label] = defs.first.value unless bucket.key?(label)
+        end
       end
 
       used = {}
@@ -74,21 +183,115 @@ module Envdoctor
         scan_source(relative(root, f), File.read(f)).each { |k, v| used[k] ||= v }
       end
 
-      findings = []
+      errors = []
+      warnings = []
+
+      # --- errors: undefined-in-source ---
       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])
+        errors << Finding.new("undefined-in-source", "error", name,
+                              "used in source code but not defined in any environment file",
+                              used[name])
+      end
+
+      # --- errors: duplicates ---
+      dup_findings.sort_by(&:name).each { |finding| errors << finding }
+
+      # --- errors: public-prefix ---
+      defined.keys.sort.each do |name|
+        next unless public_prefix?(name)
+
+        errors << Finding.new("public-prefix", "error", name,
+                              "secret-looking variable is exposed to client bundles " \
+                              "via a public prefix", defined[name])
       end
+
+      # --- errors: type-mismatch ---
+      defined.keys.sort.each do |name|
+        labels = labels_of[name] || {}
+        next if labels.size < 2
+
+        groups = labels.values.map { |v| infer_type(v) }.reject { |t| t == "empty" }
+                       .map { |t| type_group(t) }.uniq
+        next if groups.size < 2
+
+        errors << Finding.new("type-mismatch", "error", name,
+                              "inferred type differs across environments", defined[name])
+      end
+
+      # --- warnings: unused ---
       defined.keys.sort.each do |name|
         next if used.key?(name)
 
-        findings << Finding.new("unused", "warning", name,
+        warnings << Finding.new("unused", "warning", name,
                                 "defined but never referenced in source", defined[name])
       end
-      findings
+
+      # --- warnings: environment-diff ---
+      if project_labels.length >= 2
+        defined.keys.sort.each do |name|
+          present = (labels_of[name] || {}).keys.sort
+          absent = (project_labels - present).sort
+          next if present.empty? || absent.empty?
+
+          warnings << Finding.new("environment-diff", "warning", name,
+                                  "defined in #{present.join(', ')} but missing in " \
+                                  "#{absent.join(', ')}", defined[name])
+        end
+      end
+
+      # --- warnings: weak-secret ---
+      defined.keys.sort.each do |name|
+        next unless SECRET_RE.match?(name)
+        next unless weak_secret?(defined_value[name].to_s)
+
+        warnings << Finding.new("weak-secret", "warning", name,
+                                "secret-looking variable has a weak or placeholder value",
+                                defined[name])
+      end
+
+      # --- warnings: typo ---
+      defined_names = defined.keys
+      used.keys.sort.each do |u|
+        next if defined.key?(u)
+
+        best = nil
+        best_dist = nil
+        defined_names.each do |d|
+          next if d == u
+
+          limit = [u.length, d.length].min <= 4 ? 1 : 2
+          dist = levenshtein(u, d)
+          next if dist > limit
+
+          if best.nil? || dist < best_dist || (dist == best_dist && d < best)
+            best = d
+            best_dist = dist
+          end
+        end
+        next if best.nil?
+
+        warnings << Finding.new("typo", "warning", u,
+                                "\"#{u}\" is not defined; did you mean \"#{best}\"?",
+                                used[u])
+      end
+
+      errors + warnings
+    end
+
+    # Serialize findings to the shared JSON shape. Values never appear.
+    def to_json_array(findings)
+      JSON.generate(findings.map do |f|
+        {
+          "rule" => f.rule,
+          "severity" => f.severity,
+          "name" => f.name,
+          "message" => f.message,
+          "file" => f.origin&.file,
+          "line" => f.origin&.line
+        }
+      end)
     end
 
     def relative(root, path)

data/lib/envdoctor.rb

@@ -4,5 +4,5 @@ require_relative "envdoctor/scanner"
 require_relative "envdoctor/cli"
 
 module Envdoctor
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: envdoctor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Arun Natesan