envdoctor 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c56b394b123626a7937ba9451db0598b9825f3a83d93a8216e973b0c067b8d8a
-  data.tar.gz: 67da28da5cdd7a8bf767435c77251f031dda10c4dd727f867c5d70f5eca871fe
+  metadata.gz: 2d2670c59c370dc3e03b3f3e91a28285d064670f6551093d6775eb235ec2b6bb
+  data.tar.gz: 82c7e7a3c9fa5bb3c171cb78cbd90c646a54f699d8063afdf8ce847f4e593082
 SHA512:
-  metadata.gz: 14f9554eedeb73d00fd139a20d24c7491470c56acce2902c3f2fa27039069d918807776bdd85198b479ee88a3ea178e47a9db210f3b86b9e645211ad013fddf0
-  data.tar.gz: 0ee4ca3cf10a6e51b323f8d57ff7babf7b1a6b9050ff1ea6657907129bc66eed67c51a5b874cdda180d9cfafad592ec8e74c825b8c789188916db40e7a9cc28f
+  metadata.gz: 9a800d6307b081f2509adf2a262de63c5bae54d0b29a441ffb8dfc6daa746097e94410126e255cdaf2c94b8f8aa10667a6955bf4f3ca85284bd6bf0b19cd6ba1
+  data.tar.gz: fc5b091e8345c4da7c7fe02dfa5df00319ef12b8e437b9f910733dadb375e7ab6061773adaed398c09df120f3b27fd87891cec31967503021fcab6322f919fbe

data/README.md

@@ -20,11 +20,15 @@ envdoctor scan --json         # emit findings as a JSON array (values never incl
 ## What it detects
 
 Reconciles variables **used** in Ruby source (`ENV["X"]`, `ENV['X']`,
-`ENV.fetch("X")`) against those **defined** in `.env` files:
+`ENV.fetch("X")`) against those **defined** in `.env` files. Interpolated
+references in **Docker Compose** (`${VAR}`), **GitHub Actions** workflows
+(`${{ secrets.X }}`, `${{ vars.X }}`, `${{ env.X }}`) and **Kubernetes**
+manifests (`${VAR}`) also count as usage, so those files feed the same
+missing/undefined and unused checks:
 
 | Rule | Severity | Meaning |
 |------|----------|---------|
-| `undefined-in-source` | error | Used in code but not defined in any `.env` file |
+| `undefined-in-source` | error | Referenced (in source or infra files) 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) |
@@ -51,6 +55,43 @@ ruby -Ilib test/test_scanner.rb
 gem build envdoctor.gemspec
 ```
 
+## Subcommands
+
+Alongside `scan`, every port shares two environment subcommands:
+
+```bash
+envdoctor diff <envA> <envB>       # compare two environments (add --json)
+envdoctor sync <from> <to>         # copy missing keys (add --dry-run)
+envdoctor init                     # generate .env.example + ENVIRONMENT.md (add --force)
+envdoctor fix                      # always (re)generate both files
+```
+
+`diff` reports which variable names are only in one environment; `sync` appends
+the missing keys to the target `.env` file as empty `KEY=` placeholders — values
+are never copied.
+
+`init` / `fix` generate two files at the project root from the union of defined
+(`.env*`) and used (source + Compose/Actions/K8s) variable names: `.env.example`
+(one `KEY=` per variable) and `ENVIRONMENT.md` (a Defined/Used table). Values are
+never written. `init` writes each file only if absent (`--force` overwrites);
+`fix` always rewrites both. Both accept `-d/--dir PATH`.
+
+## Schema validation
+
+Add an `envdoctor.schema.json` at your project root to validate `.env` values:
+
+```json
+{
+  "PORT":  { "type": "integer", "min": 1, "max": 65535 },
+  "LEVEL": { "enum": ["debug", "info", "warn", "error"] },
+  "TOKEN": { "type": "string", "optional": true }
+}
+```
+
+Supported rule fields: `type` (string/integer/float/boolean/url/json), `enum`,
+`regex`, `min`, `max`, `optional`. Values that fail are reported as
+`schema-validation` errors (values are never printed).
+
 ## Other languages
 
 envdoctor ships as a standalone native port for each ecosystem:

data/lib/envdoctor/cli.rb

@@ -9,6 +9,11 @@ module Envdoctor
     module_function
 
     def run(argv)
+      return run_diff(argv[1..]) if argv.first == "diff"
+      return run_sync(argv[1..]) if argv.first == "sync"
+      return run_init(argv[1..]) if argv.first == "init"
+      return run_fix(argv[1..]) if argv.first == "fix"
+
       dir = "."
       strict = false
       json = false
@@ -39,17 +44,118 @@ module Envdoctor
         return 0
       end
 
+      loc = ->(f) { f.origin ? " #{f.origin.file}:#{f.origin.line}" : "" }
       unless errors.empty?
         puts "\nErrors"
-        errors.each { |f| puts "  x #{f.name} #{f.origin.file}:#{f.origin.line}  #{f.message}" }
+        errors.each { |f| puts "  x #{f.name}#{loc.call(f)}  #{f.message}" }
       end
       unless warnings.empty?
         puts "\nWarnings"
-        warnings.each { |f| puts "  ! #{f.name} #{f.origin.file}:#{f.origin.line}  #{f.message}" }
+        warnings.each { |f| puts "  ! #{f.name}#{loc.call(f)}  #{f.message}" }
       end
       puts "\nSummary: #{errors.length} error(s), #{warnings.length} warning(s)"
 
       (!errors.empty? || (strict && !warnings.empty?)) ? 1 : 0
     end
+
+    def run_diff(argv)
+      dir = "."
+      json = false
+      pos = []
+      OptionParser.new do |o|
+        o.on("-d", "--dir DIR") { |v| dir = v }
+        o.on("--json") { json = true }
+      end.order!(argv.dup) { |a| pos << a }
+      a, b = pos[0], pos[1]
+      d = Scanner.diff_labels(File.expand_path(dir), a, b)
+      if json
+        require "json"
+        puts JSON.generate({ "a" => a, "b" => b }.merge(d))
+        return 0
+      end
+      puts "ENVIRONMENT DIFF: #{a} vs #{b}"
+      puts "=" * 40
+      unless d["onlyInA"].empty?
+        puts "Only in #{a}:"
+        d["onlyInA"].each { |k| puts "  + #{k}" }
+      end
+      unless d["onlyInB"].empty?
+        puts "Only in #{b}:"
+        d["onlyInB"].each { |k| puts "  + #{k}" }
+      end
+      puts "Common: #{d['common'].length} variable(s)"
+      0
+    end
+
+    # Generate `.env.example` and `ENVIRONMENT.md`, writing each only if absent
+    # (or always with --force).
+    def run_init(argv)
+      dir = "."
+      force = false
+      OptionParser.new do |o|
+        o.on("-d", "--dir DIR") { |v| dir = v }
+        o.on("--force") { force = true }
+      end.parse!(argv.dup)
+
+      root = File.expand_path(dir)
+      files = {
+        ".env.example" => Scanner.env_example_content(root),
+        "ENVIRONMENT.md" => Scanner.environment_doc_content(root)
+      }
+      files.each do |name, content|
+        path = File.join(root, name)
+        if File.exist?(path) && !force
+          puts "skipped #{name} (exists)"
+        else
+          File.write(path, content)
+          puts "#{force ? 'wrote' : 'created'} #{name}"
+        end
+      end
+      0
+    end
+
+    # Always (re)write both generated files.
+    def run_fix(argv)
+      dir = "."
+      OptionParser.new do |o|
+        o.on("-d", "--dir DIR") { |v| dir = v }
+      end.parse!(argv.dup)
+
+      root = File.expand_path(dir)
+      example = Scanner.env_example_content(root)
+      doc = Scanner.environment_doc_content(root)
+      File.write(File.join(root, ".env.example"), example)
+      puts "wrote .env.example"
+      File.write(File.join(root, "ENVIRONMENT.md"), doc)
+      puts "wrote ENVIRONMENT.md"
+      0
+    end
+
+    def run_sync(argv)
+      dir = "."
+      json = false
+      dry = false
+      pos = []
+      OptionParser.new do |o|
+        o.on("-d", "--dir DIR") { |v| dir = v }
+        o.on("--dry-run") { dry = true }
+        o.on("--json") { json = true }
+      end.order!(argv.dup) { |a| pos << a }
+      from, to = pos[0], pos[1]
+      added = Scanner.sync_labels(File.expand_path(dir), from, to, dry_run: dry)
+      if json
+        require "json"
+        puts JSON.generate({ "from" => from, "to" => to, "added" => added, "dryRun" => dry })
+        return 0
+      end
+      if added.empty?
+        puts "Already in sync."
+        return 0
+      end
+      verb = dry ? "Would sync" : "Synced"
+      puts "#{verb} #{added.length} variable(s) from #{from} to #{to}:"
+      added.each { |k| puts "  + #{k}" }
+      0
+    end
   end
 end

data/lib/envdoctor/scanner.rb

@@ -149,6 +149,135 @@ module Envdoctor
       end.sort
     end
 
+    COMPOSE_RE = /\A(docker-)?compose([.-].*)?\.ya?ml\z/i.freeze
+
+    def skip_infra_path?(path)
+      path.split(File::SEPARATOR).any? { |part| %w[.git vendor node_modules target].include?(part) }
+    end
+
+    # Walk the project and classify infra YAML files. Returns [[path, kind], ...]
+    # where kind is one of :compose, :actions, :k8s.
+    def discover_infra_files(root)
+      out = []
+      Dir.glob(File.join(root, "**", "*"), File::FNM_DOTMATCH).each do |path|
+        next unless File.file?(path)
+        next if skip_infra_path?(path)
+
+        base = File.basename(path)
+        segments = path.split(File::SEPARATOR)
+        if base.match?(COMPOSE_RE)
+          out << [path, :compose]
+        elsif base =~ /\.ya?ml\z/i &&
+              segments.each_cons(2).any? { |a, b| a == ".github" && b == "workflows" }
+          out << [path, :actions]
+        elsif base =~ /\.ya?ml\z/i
+          content = File.read(path)
+          out << [path, :k8s] if content.match?(/^apiVersion:/m) && content.match?(/^kind:/m)
+        end
+      end
+      out.sort_by(&:first)
+    end
+
+    INTERP_PATTERNS = [
+      /\$\{([A-Za-z_][A-Za-z0-9_]*)/,
+      /\$([A-Za-z_][A-Za-z0-9_]*)/
+    ].freeze
+
+    ACTIONS_CONTEXT_RE = /\b(?:secrets|vars|env)\.([A-Za-z_][A-Za-z0-9_]*)/.freeze
+
+    # Extract used variable NAMES (with origin) from an infra YAML file. First
+    # removes escaped `$$` (two spaces, offsets preserved), then scans for
+    # interpolation and, for GitHub Actions, the secrets/vars/env contexts.
+    def scan_infra(path, content, kind)
+      text = content.gsub("$$", "  ")
+      used = {}
+      patterns = INTERP_PATTERNS.dup
+      patterns << ACTIONS_CONTEXT_RE if kind == :actions
+      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
+
+    # Map each environment label to the set of variable names defined in it.
+    def defined_by_label(root)
+      labels = {}
+      discover_env_files(root).each do |f|
+        set = (labels[env_label(f)] ||= [])
+        parse_env(f, File.read(f)).each_key { |name| set << name unless set.include?(name) }
+      end
+      labels
+    end
+
+    def diff_labels(root, a, b)
+      labels = defined_by_label(root)
+      da = labels[a] || []
+      db = labels[b] || []
+      {
+        "onlyInA" => (da - db).sort,
+        "onlyInB" => (db - da).sort,
+        "common" => (da & db).sort
+      }
+    end
+
+    # Append keys present in `from` but missing from `to` as `KEY=` placeholders.
+    # Values are never copied.
+    def sync_labels(root, from, to, dry_run: false)
+      labels = defined_by_label(root)
+      missing = ((labels[from] || []) - (labels[to] || [])).sort
+      if !missing.empty? && !dry_run
+        target = File.join(root, to == "default" ? ".env" : ".env.#{to}")
+        existing = File.exist?(target) ? File.read(target) : ""
+        prefix = (existing.empty? || existing.end_with?("\n")) ? "" : "\n"
+        File.open(target, "a") { |fh| fh.write(prefix + missing.map { |k| "#{k}=\n" }.join) }
+      end
+      missing
+    end
+
+    # Collect the DEFINED (from .env*) and USED (source + infra) name sets for a
+    # project. Returns [defined_hash, used_hash] with name => true entries.
+    def collect_names(root)
+      defined = {}
+      discover_env_files(root).each do |f|
+        parse_env(relative(root, f), File.read(f)).each_key { |name| defined[name] = true }
+      end
+      used = {}
+      discover_source_files(root).each do |f|
+        scan_source(relative(root, f), File.read(f)).each_key { |k| used[k] = true }
+      end
+      discover_infra_files(root).each do |f, kind|
+        scan_infra(relative(root, f), File.read(f), kind).each_key { |k| used[k] = true }
+      end
+      [defined, used]
+    end
+
+    # Exact `.env.example` content: header, then `NAME=` per (defined ∪ used),
+    # sorted ascending. Values are never written.
+    def env_example_content(root)
+      defined, used = collect_names(root)
+      names = (defined.keys + used.keys).uniq.sort
+      "# Generated by envdoctor. Fill in values; do not commit secrets.\n" +
+        names.map { |n| "#{n}=\n" }.join
+    end
+
+    # Exact `ENVIRONMENT.md` content: a table of Defined/Used per variable.
+    def environment_doc_content(root)
+      defined, used = collect_names(root)
+      names = (defined.keys + used.keys).uniq.sort
+      lines = ["# Environment variables", "", "| Variable | Defined | Used |", "| --- | --- | --- |"]
+      names.each do |n|
+        lines << "| #{n} | #{defined.key?(n) ? 'yes' : 'no'} | #{used.key?(n) ? 'yes' : 'no'} |"
+      end
+      lines.join("\n") + "\n"
+    end
+
     def scan(root)
       defined = {}          # name => Origin (first definition wins)
       defined_value = {}    # name => value at first definition
@@ -182,6 +311,11 @@ module Envdoctor
       discover_source_files(root).each do |f|
         scan_source(relative(root, f), File.read(f)).each { |k, v| used[k] ||= v }
       end
+      # Infra sources (Docker Compose / GitHub Actions / Kubernetes) contribute
+      # additional used names; first origin wins.
+      discover_infra_files(root).each do |f, kind|
+        scan_infra(relative(root, f), File.read(f), kind).each { |k, v| used[k] ||= v }
+      end
 
       errors = []
       warnings = []
@@ -191,7 +325,7 @@ module Envdoctor
         next if defined.key?(name)
 
         errors << Finding.new("undefined-in-source", "error", name,
-                              "used in source code but not defined in any environment file",
+                              "referenced but not defined in any environment file",
                               used[name])
       end
 
@@ -220,6 +354,19 @@ module Envdoctor
                               "inferred type differs across environments", defined[name])
       end
 
+      # --- errors: schema-validation ---
+      load_schema(root).sort.each do |name, rule|
+        next unless rule.is_a?(Hash)
+
+        if defined.key?(name)
+          msg = schema_failure(rule, defined_value[name])
+          errors << Finding.new("schema-validation", "error", name, msg, defined[name]) if msg
+        elsif !rule["optional"]
+          errors << Finding.new("schema-validation", "error", name,
+                                "required by schema but not defined", nil)
+        end
+      end
+
       # --- warnings: unused ---
       defined.keys.sort.each do |name|
         next if used.key?(name)
@@ -281,6 +428,55 @@ module Envdoctor
     end
 
     # Serialize findings to the shared JSON shape. Values never appear.
+    NUMERIC_RE = /\A-?\d+(\.\d+)?\z/.freeze
+
+    def load_schema(root)
+      require "json"
+      data = JSON.parse(File.read(File.join(root, "envdoctor.schema.json")))
+      data.is_a?(Hash) ? data : {}
+    rescue StandardError
+      {}
+    end
+
+    def schema_type_ok(value, declared)
+      case declared
+      when "string" then true
+      when "integer" then value.match?(/\A-?\d+\z/)
+      when "float" then value.match?(/\A-?\d+(\.\d+)?\z/)
+      when "boolean" then %w[true false].include?(value.downcase)
+      when "url" then value.match?(%r{\Ahttps?://})
+      when "json" then (JSON.parse(value); true rescue false)
+      else true
+      end
+    end
+
+    def schema_failure(rule, value)
+      t = rule["type"]
+      return "value does not match schema type #{t}" if t.is_a?(String) && !schema_type_ok(value, t)
+
+      enum = rule["enum"]
+      return "value is not one of the allowed values" if enum.is_a?(Array) && !enum.include?(value)
+
+      pattern = rule["regex"]
+      if pattern.is_a?(String)
+        begin
+          return "value does not match the required pattern" if value !~ Regexp.new(pattern)
+        rescue RegexpError
+          # ignore invalid pattern
+        end
+      end
+
+      if value.match?(NUMERIC_RE)
+        num = value.to_f
+        lo = rule["min"]
+        return "value is below the minimum" if lo.is_a?(Numeric) && num < lo
+
+        hi = rule["max"]
+        return "value exceeds the maximum" if hi.is_a?(Numeric) && num > hi
+      end
+      nil
+    end
+
     def to_json_array(findings)
       JSON.generate(findings.map do |f|
         {

data/lib/envdoctor.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: envdoctor
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Arun Natesan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-22 00:00:00.000000000 Z
+date: 2026-08-23 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.'