envdoctor 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec3513e2cfdb6870cd1608bf7d5a3cf2c831113187ff3ca34ed6fe9539a231d5
-  data.tar.gz: 76b4d2234288c38d2c20c27ee39db004a69da9adfe945a7ef6a856a5e56f7f5b
+  metadata.gz: 2d2670c59c370dc3e03b3f3e91a28285d064670f6551093d6775eb235ec2b6bb
+  data.tar.gz: 82c7e7a3c9fa5bb3c171cb78cbd90c646a54f699d8063afdf8ce847f4e593082
 SHA512:
-  metadata.gz: fc16e6e1ca03e96d1e72a88a05391370afc810790dae1d338a77759d9152b3cdb0ad6ecfd86d51faf093196144eeb2ba66ba352822c3859718114c5a0e0a9fc0
-  data.tar.gz: fada228584d093fb6fc71ecc9dbda5cd2d7fe20b66c646e490383c981e87d01db9b2d3e56fb79ca0a5ac8d831e9fcfd569d7d42e837aca2af1bff8513d9a7e47
+  metadata.gz: 9a800d6307b081f2509adf2a262de63c5bae54d0b29a441ffb8dfc6daa746097e94410126e255cdaf2c94b8f8aa10667a6955bf4f3ca85284bd6bf0b19cd6ba1
+  data.tar.gz: fc5b091e8345c4da7c7fe02dfa5df00319ef12b8e437b9f910733dadb375e7ab6061773adaed398c09df120f3b27fd87891cec31967503021fcab6322f919fbe

data/README.md

@@ -3,23 +3,49 @@
 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:
+`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) |
 | `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 +55,47 @@ 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).
+## 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:
+
+- [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

@@ -9,12 +9,19 @@ 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
       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 +32,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?
@@ -32,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

@@ -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") }
@@ -63,32 +149,345 @@ module Envdoctor
       end.sort
     end
 
-    def scan(root)
+    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 { |k, v| defined[k] ||= v }
+        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
+      labels_of = {}        # name => { label => value } (first value per label)
+      project_labels = []
+      dup_findings = []
+
+      discover_env_files(root).each do |f|
+        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 = {}
       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 = []
 
-      findings = []
+      # --- 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,
+                              "referenced 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
+
+      # --- 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)
 
-        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.
+    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|
+        {
+          "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.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: envdoctor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  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.'