envspec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 28f13d06ae0882152222605d7b631f76f181c63fd91544ace2e53c33cc718ffa
+  data.tar.gz: 616d302174e177c0cce5864a4a12533710ea4823c528496a0e88a9f1466462be
+SHA512:
+  metadata.gz: 9b57dba76d1e5862c97548c1c0b040e1147ce3abac04e3034d9ae313f46c27fbbdb9a3105d776a7da2d5d066412a05373dfc19c769698222c25406f9d9b651d0
+  data.tar.gz: a19532006f8fc6822fa3a8b4ed7a17f4ba6485547233819e76c762df9a22b79b09a6ab52adf36401d760bc0ae0265939ad9e848d967ccb0f349b0572ca0db65d

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 — 2026-05-04
+
+Initial release.
+
+- Parser for `env.spec` syntax v5 (`[secrets]` modifier, `[env: …]` selector, scoped configmap/secrets, types `str | int | bool | dsn | enum`).
+- Validator: presence + type-level checks (int/bool/enum/dsn).
+- CLI: `envspec lint`, `envspec check`, `envspec init`.
+- `init` scans Ruby/Python/JS/Go/Shell sources and generates a starter `env.spec` with heuristic-based suggestions.
+- Zero runtime dependencies; Ruby ≥ 2.5.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leadfy
+
+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,74 @@
+# envspec
+
+Declarative env var contract for apps. Pure-Ruby gem with **zero runtime dependencies**.
+
+`envspec` parses `env.spec` files — a small DSL that describes which env vars an app expects, their types, optionality, and ConfigMap-vs-Secret classification. Use it as a CI lint, a Rails boot check, or a deploy-time contract.
+
+## Install
+
+```sh
+gem install envspec
+```
+
+Requires Ruby ≥ 2.5. No native extensions, no other gems.
+
+## Quick start
+
+```sh
+# Generate env.spec from a scan of your repo
+envspec init
+
+# Validate the spec syntactically
+envspec lint env.spec
+
+# Check current ENV against the spec
+envspec check env.spec --env=production
+```
+
+## env.spec syntax
+
+```
+# shared (all envs)
+APP_NAME
+LOG_LEVEL: enum(debug, info, warn, error) = info
+DEBUG?: bool
+PORT: int = 3000
+
+[secrets]
+DB_PASS
+OPENAI_API_KEY
+
+[env: production]
+DB_HOST
+[secrets]
+STRIPE_LIVE_KEY
+
+[env: production, staging]
+SENTRY_DSN: dsn
+```
+
+- `KEY` — required string in shared scope, ConfigMap
+- `KEY?` — optional
+- `KEY: type` — typed (`str | int | bool | dsn | enum(a,b,c)`)
+- `KEY = default` — default value (configmap only; secrets cannot have defaults)
+- `[secrets]` — modifier; subsequent keys become Secrets (scope unchanged)
+- `[env: name]` / `[env: a, b]` — selector; subsequent keys scoped to those envs (also resets type back to ConfigMap — explicit beats implicit)
+
+## Library API
+
+```ruby
+require "envspec"
+
+spec = EnvSpec.parse_file("env.spec")
+
+spec.configmap        # => { "*" => {...}, "production" => {...} }
+spec.secrets          # => { "*" => {...}, "production" => {...} }
+spec.envs             # => ["production", "staging"]
+spec.configmap_for("production")  # merged shared + production
+
+spec.validate!(ENV.to_h, env: "production")  # raises EnvSpec::ValidationError if anything missing or wrong type
+```
+
+## License
+
+MIT.

data/exe/envspec

@@ -0,0 +1,106 @@
+#!/usr/bin/env ruby
+require "optparse"
+require "envspec"
+
+def die(msg, code = 1)
+  warn "envspec: #{msg}"
+  exit code
+end
+
+def usage
+  <<~USAGE
+    Usage: envspec <command> [options]
+
+    Commands:
+      lint <file>                 Parse and validate syntax of an env.spec file
+      check <file> [--env=NAME]   Check current ENV against the spec
+                                  (presence + type validation)
+      init [--force] [--output=PATH]
+                                  Scan repo for env var usages and generate env.spec
+
+    Options:
+      -h, --help     Show this help
+      -v, --version  Show version
+
+  USAGE
+end
+
+cmd = ARGV.shift
+
+case cmd
+when nil, "-h", "--help", "help"
+  puts usage
+  exit 0
+
+when "-v", "--version", "version"
+  puts EnvSpec::VERSION
+  exit 0
+
+when "lint"
+  file = ARGV.shift or die "lint: missing file argument\n\n#{usage}"
+  die "file not found: #{file}" unless File.exist?(file)
+  begin
+    EnvSpec.parse_file(file)
+    puts "✓ #{file} is valid"
+  rescue EnvSpec::ParseError => e
+    die e.message
+  end
+
+when "check"
+  file = nil
+  env = "*"
+  strict = false
+
+  parser = OptionParser.new do |o|
+    o.on("--env=NAME") { |v| env = v }
+    o.on("--strict") { strict = true }
+  end
+  rest = parser.parse(ARGV)
+  file = rest.shift or die "check: missing file argument\n\n#{usage}"
+  die "file not found: #{file}" unless File.exist?(file)
+
+  spec = begin
+    EnvSpec.parse_file(file)
+  rescue EnvSpec::ParseError => e
+    die e.message
+  end
+
+  begin
+    spec.validate!(ENV.to_h, env: env, strict: strict)
+    scope_label = env == "*" ? "shared" : env
+    puts "✓ ENV satisfies #{file} (env: #{scope_label})"
+  rescue EnvSpec::ValidationError => e
+    die e.message
+  end
+
+when "init"
+  force = false
+  output = "env.spec"
+  root = Dir.pwd
+
+  parser = OptionParser.new do |o|
+    o.on("--force") { force = true }
+    o.on("--output=PATH") { |v| output = v }
+    o.on("--root=PATH") { |v| root = v }
+  end
+  parser.parse(ARGV)
+
+  result = EnvSpec::Init.run(root: root, force: force, output: output)
+
+  unless result[:ok]
+    die "#{output} already exists (use --force to overwrite)" if result[:reason] == :exists
+    die "init failed: #{result[:reason]}"
+  end
+
+  puts "✓ Scanned in #{format('%.2fs', result[:elapsed])}"
+  puts "✓ Found #{result[:keys]} env vars across #{result[:files]} files"
+  puts "✓ Wrote #{result[:path]}"
+  puts ""
+  puts "Next steps:"
+  puts "  1. Edit #{output} — review heuristic suggestions, classify secrets"
+  puts "  2. Run `envspec lint #{output}` to validate"
+  puts "  3. Run `envspec check #{output}` to test against your current ENV"
+
+else
+  die "unknown command: #{cmd}\n\n#{usage}"
+end

data/lib/envspec/entry.rb

@@ -0,0 +1,3 @@
+class EnvSpec
+  Entry = Struct.new(:type, :optional, :default, :enum_values, :line, keyword_init: true)
+end

data/lib/envspec/errors.rb

@@ -0,0 +1,20 @@
+class EnvSpec
+  class Error < StandardError; end
+
+  class ParseError < Error
+    attr_reader :line_no
+    def initialize(msg, line_no = nil)
+      super(line_no ? "line #{line_no}: #{msg}" : msg)
+      @line_no = line_no
+    end
+  end
+
+  class ValidationError < Error
+    attr_reader :problems
+    def initialize(problems)
+      @problems = Array(problems)
+      lines = ["env validation failed:"] + @problems.map { |p| "  - #{p}" }
+      super(lines.join("\n"))
+    end
+  end
+end

data/lib/envspec/heuristics.rb

@@ -0,0 +1,38 @@
+class EnvSpec
+  # Best-effort, conservative inference of envspec syntax from a key name and
+  # observed usage data. Output is ALWAYS suggestive — the generated env.spec
+  # file marks heuristic decisions as TODO comments so the dev reviews them.
+  module Heuristics
+    SECRET_NAME_RE = /(?:KEY|SECRET|TOKEN|PASSWORD|PASS|CREDENTIAL|PRIVATE)\b/.freeze
+    DSN_NAME_RE    = /(?:_URL|_URI|_DSN|DATABASE_URL|REDIS_URL|MONGO_URL|AMQP_URL)\z/.freeze
+    INT_NAME_RE    = /(?:PORT|TIMEOUT|INTERVAL|SIZE|COUNT|LIMIT|MAX_|MIN_)/.freeze
+    BOOL_NAME_RE   = /\A(?:DEBUG|VERBOSE|ENABLE_|.*_ENABLED|IS_|HAS_|USE_)/.freeze
+
+    def self.infer(name, usages)
+      {
+        secret:   secret?(name),
+        type:     infer_type(name),
+        optional: usages.any? { |u| u[:optional] },
+        default:  pick_default(usages),
+      }
+    end
+
+    def self.secret?(name)
+      return true if name =~ SECRET_NAME_RE
+      return true if name =~ DSN_NAME_RE
+      false
+    end
+
+    def self.infer_type(name)
+      return :dsn  if name =~ DSN_NAME_RE
+      return :int  if name =~ INT_NAME_RE
+      return :bool if name =~ BOOL_NAME_RE
+      :str
+    end
+
+    def self.pick_default(usages)
+      defaults = usages.map { |u| u[:default] }.compact.uniq
+      defaults.first
+    end
+  end
+end

data/lib/envspec/init.rb

@@ -0,0 +1,103 @@
+require_relative "scanner"
+require_relative "heuristics"
+
+class EnvSpec
+  # Generates an initial env.spec by scanning a repo for env var usages.
+  module Init
+    HEADER = <<~HEADER
+      # env.spec — generated by `envspec init` %s
+      #
+      # This is a starting point. Review and adjust:
+      #   1. Move secrets (passwords, tokens, keys) under [secrets]
+      #   2. Add types: str (default) | int | bool | dsn | enum(a,b,c)
+      #   3. Mark optional vars with ?
+      #   4. Add defaults for configmap vars: KEY: type = value
+      #   5. Group per-env vars under [env: production], [env: staging], etc
+      #
+      # Discovered usages are listed as comments above each key.
+      # Confirm or remove before committing.
+      #
+      # Validate: envspec lint env.spec
+      # See docs:  https://github.com/repleadfy/envspec
+    HEADER
+
+    def self.run(root: Dir.pwd, force: false, output: "env.spec")
+      out_path = File.expand_path(output, root)
+      if File.exist?(out_path) && !force
+        return { ok: false, reason: :exists, path: out_path }
+      end
+
+      t0 = Time.now
+      results = Scanner.scan(root)
+      elapsed = Time.now - t0
+
+      content = render(results, root)
+      File.write(out_path, content)
+
+      {
+        ok:      true,
+        path:    out_path,
+        keys:    results.size,
+        files:   results.values.flatten.map { |u| u[:file] }.uniq.size,
+        elapsed: elapsed,
+      }
+    end
+
+    def self.render(results, root)
+      out = []
+      out << format(HEADER, Time.now.strftime("%Y-%m-%d"))
+      out << ""
+
+      configmap_keys = []
+      secret_keys    = []
+
+      results.keys.sort.each do |name|
+        usages    = results[name]
+        inference = Heuristics.infer(name, usages)
+        block = render_key(name, usages, inference, root)
+        if inference[:secret]
+          secret_keys << block
+        else
+          configmap_keys << block
+        end
+      end
+
+      out.concat(configmap_keys) unless configmap_keys.empty?
+
+      unless secret_keys.empty?
+        out << ""
+        out << "[secrets]"
+        out.concat(secret_keys)
+      end
+
+      out.join("\n").gsub(/\n{3,}/, "\n\n").strip + "\n"
+    end
+
+    def self.render_key(name, usages, inference, root)
+      lines = []
+
+      usages.first(3).each do |u|
+        rel = u[:file].sub(/\A#{Regexp.escape(root)}\/?/, "")
+        lines << "# Found in: #{rel}:#{u[:line]}"
+      end
+      lines << "# (and #{usages.size - 3} more usages)" if usages.size > 3
+
+      hints = []
+      hints << "name suggests #{inference[:type]}" if inference[:type] != :str
+      hints << "name suggests secret" if inference[:secret] && Heuristics::SECRET_NAME_RE.match?(name) && inference[:type] != :dsn
+      hints << "uses fetch with default" if inference[:optional] && inference[:default]
+      lines << "# Heuristic: #{hints.join(', ')}" unless hints.empty?
+
+      decl = name.dup
+      decl << "?" if inference[:optional]
+
+      type = inference[:type]
+      decl << ": #{type}" if type != :str || (inference[:default] && type == :str)
+      decl << " = #{inference[:default]}" if inference[:default] && !inference[:secret]
+
+      lines << decl
+      lines << ""
+      lines.join("\n")
+    end
+  end
+end

data/lib/envspec/parser.rb

@@ -0,0 +1,186 @@
+# Parses env.spec files -- declarative contract for ConfigMap and Secret keys
+# an app expects.
+#
+# Syntax (v5):
+#   KEY                       # str, required, configmap, shared (all envs)
+#   KEY?                      # optional
+#   KEY: int                  # typed (str|int|bool|dsn|enum(a,b))
+#   KEY: str = default        # with default (configmap only)
+#
+#   [secrets]                 # MODIFIER: type flips to secret (scope unchanged)
+#   [env: production]         # SELECTOR: scope -> production, type RESETS to configmap
+#   [env: production, staging]# multi-env scope
+#
+# Output:
+#   configmap = { "*" => { "KEY" => Entry }, "production" => {...} }
+#   secrets   = { "*" => { "DB_PASS" => Entry }, "production" => {...} }
+class EnvSpec
+  SHARED = "*".freeze
+  VALID_TYPES = %i[str int bool dsn enum].freeze
+  ENV_NAME_RE = /\A[A-Za-z0-9_-]+\z/.freeze
+
+  attr_reader :configmap, :secrets
+
+  def self.parse(text)
+    new.tap { |spec| spec.send(:_parse, text) }
+  end
+
+  def self.parse_file(path)
+    parse(File.read(path))
+  end
+
+  def initialize
+    @configmap = {}
+    @secrets   = {}
+  end
+
+  # Returns array of env names declared in the spec (excluding "*").
+  def envs
+    (@configmap.keys + @secrets.keys).uniq.reject { |e| e == SHARED }.sort
+  end
+
+  # Returns merged keys (shared + given env) for configmap.
+  def configmap_for(env)
+    merge_scope(@configmap, env)
+  end
+
+  def secrets_for(env)
+    merge_scope(@secrets, env)
+  end
+
+  private
+
+  def merge_scope(bucket, env)
+    out = {}
+    out.merge!(bucket[SHARED]) if bucket[SHARED]
+    out.merge!(bucket[env])    if bucket[env]
+    out
+  end
+
+  def _parse(text)
+    scope = [SHARED]
+    type  = :configmap
+
+    text.each_line.with_index(1) do |raw, line_no|
+      line = raw.sub(/#.*/, "").strip
+      next if line.empty?
+
+      if line.start_with?("[") && line.end_with?("]")
+        inner = line[1..-2].strip
+        if inner == "secrets"
+          type = :secret
+        elsif inner.start_with?("env:")
+          envs = inner.sub(/\Aenv:/, "").split(",").map(&:strip).reject(&:empty?)
+          raise ParseError.new("empty [env: ...] selector", line_no) if envs.empty?
+          envs.each do |e|
+            unless ENV_NAME_RE.match?(e)
+              raise ParseError.new(
+                "invalid env name '#{e}' in [env: ...] (must match #{ENV_NAME_RE.source}; use commas to separate envs)",
+                line_no
+              )
+            end
+          end
+          scope = envs
+          type  = :configmap
+        else
+          raise ParseError.new("unknown header [#{inner}] (only [secrets] and [env: ...] allowed)", line_no)
+        end
+        next
+      end
+
+      entry = parse_key_line(line, line_no)
+      if type == :secret && !entry[:default].nil?
+        raise ParseError.new("secret '#{entry[:name]}' cannot have a default value", line_no)
+      end
+
+      store_entry(type, scope, entry, line_no)
+    end
+  end
+
+  def parse_key_line(line, line_no)
+    m = line.match(/\A([A-Z][A-Z0-9_]*)(\?)?(?:\s*:\s*([a-z]+(?:\([^)]*\))?))?(?:\s*=\s*(.+))?\z/)
+    raise ParseError.new("invalid key line: #{line.inspect}", line_no) unless m
+
+    name      = m[1]
+    optional  = !m[2].nil?
+    type_str  = m[3] || "str"
+    default   = m[4] && m[4].strip
+
+    type, enum_values = parse_type(type_str, line_no)
+    { name: name, type: type, optional: optional, default: default, enum_values: enum_values }
+  end
+
+  def parse_type(type_str, line_no)
+    if type_str.start_with?("enum(")
+      unless (em = type_str.match(/\Aenum\((.+)\)\z/))
+        raise ParseError.new("malformed enum type: #{type_str}", line_no)
+      end
+      values = em[1].split(",").map(&:strip).reject(&:empty?)
+      raise ParseError.new("enum requires at least one value", line_no) if values.empty?
+      [:enum, values]
+    else
+      sym = type_str.to_sym
+      unless VALID_TYPES.include?(sym)
+        raise ParseError.new("unknown type '#{type_str}' (valid: #{VALID_TYPES.join(', ')})", line_no)
+      end
+      [sym, nil]
+    end
+  end
+
+  def store_entry(type, scope, e, line_no)
+    bucket = (type == :secret ? @secrets : @configmap)
+
+    scope.each do |env|
+      bucket[env] ||= {}
+
+      if (existing = find_overlapping(bucket, env, e[:name]))
+        raise ParseError.new(
+          "key '#{e[:name]}' defined in overlapping scopes ('#{existing[:env]}' line #{existing[:entry].line} and '#{env}' here)",
+          line_no
+        )
+      end
+
+      bucket[env][e[:name]] = Entry.new(
+        type: e[:type],
+        optional: e[:optional],
+        default: e[:default],
+        enum_values: e[:enum_values],
+        line: line_no
+      )
+    end
+
+    check_cross_env_type_consistency(bucket, e[:name], e[:type], e[:enum_values], line_no)
+  end
+
+  def find_overlapping(bucket, env, key)
+    bucket.each do |existing_env, keys|
+      next unless keys.key?(key)
+      next if existing_env == env
+      if existing_env == SHARED || env == SHARED
+        return { env: existing_env, entry: keys[key] }
+      end
+    end
+    if bucket[env] && bucket[env].key?(key)
+      return { env: env, entry: bucket[env][key] }
+    end
+    nil
+  end
+
+  def check_cross_env_type_consistency(bucket, key, type, enum_values, line_no)
+    seen = nil
+    bucket.each do |env, keys|
+      next unless keys.key?(key)
+      e = keys[key]
+      if seen.nil?
+        seen = [env, e.type, e.enum_values]
+      else
+        if seen[1] != e.type || seen[2] != e.enum_values
+          raise ParseError.new(
+            "key '#{key}' has different types across envs ('#{seen[0]}' is #{seen[1]}, '#{env}' is #{e.type})",
+            line_no
+          )
+        end
+      end
+    end
+  end
+end

data/lib/envspec/scanner.rb

@@ -0,0 +1,161 @@
+require "find"
+require "set"
+
+class EnvSpec
+  # Scans a directory tree for env var usages across multiple languages.
+  # Pure regex (no AST parser) to keep zero-deps requirement.
+  #
+  # Returns:
+  #   { "OPENAI_API_KEY" => [{ file: "...", line: 9, default: nil, optional: true }, ...] }
+  module Scanner
+    SKIP_DIRS = %w[
+      .git node_modules vendor tmp log logs coverage
+      .bundle .yarn .pnpm-store dist build target
+      __pycache__ .venv venv .pytest_cache .next .nuxt .turbo
+    ].to_set.freeze
+
+    SKIP_FILE_RE = /
+      \.lock\z |
+      \.min\.(js|css)\z |
+      \.svg\z |
+      \.png\z | \.jpg\z | \.jpeg\z | \.gif\z | \.ico\z | \.webp\z |
+      \.pdf\z | \.zip\z | \.tar\z | \.gz\z |
+      \.woff2?\z | \.ttf\z | \.eot\z |
+      \.map\z
+    /x.freeze
+
+    MAX_FILE_BYTES = 1_048_576  # 1 MB
+
+    EXT_LANG = {
+      ".rb"     => :ruby,
+      ".rake"   => :ruby,
+      ".gemspec"=> :ruby,
+      ".py"     => :python,
+      ".js"     => :js,
+      ".jsx"    => :js,
+      ".ts"     => :js,
+      ".tsx"    => :js,
+      ".mjs"    => :js,
+      ".cjs"    => :js,
+      ".go"     => :go,
+      ".sh"     => :shell,
+      ".bash"   => :shell,
+    }.freeze
+
+    SPECIAL_FILES = {
+      "Dockerfile"   => :shell,
+      "Rakefile"     => :ruby,
+      "Gemfile"      => :ruby,
+      "config.ru"    => :ruby,
+    }.freeze
+
+    PATTERNS = {
+      ruby: [
+        /ENV\s*\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\]/,
+        /ENV\.fetch\s*\(\s*["']([A-Z][A-Z0-9_]*)["'](?:\s*,\s*([^)]+))?\s*\)/,
+      ],
+      python: [
+        /os\.environ\s*\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\]/,
+        /os\.environ\.get\s*\(\s*["']([A-Z][A-Z0-9_]*)["'](?:\s*,\s*([^)]+))?\s*\)/,
+        /os\.getenv\s*\(\s*["']([A-Z][A-Z0-9_]*)["'](?:\s*,\s*([^)]+))?\s*\)/,
+      ],
+      js: [
+        /process\.env\.([A-Z][A-Z0-9_]*)/,
+        /process\.env\s*\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\]/,
+        /import\.meta\.env\.([A-Z][A-Z0-9_]*)/,
+      ],
+      go: [
+        /os\.Getenv\s*\(\s*["']([A-Z][A-Z0-9_]*)["']\s*\)/,
+        /os\.LookupEnv\s*\(\s*["']([A-Z][A-Z0-9_]*)["']\s*\)/,
+      ],
+      shell: [
+        /\$\{([A-Z][A-Z0-9_]*)(?::[-=?+][^}]*)?\}/,
+        /\$([A-Z][A-Z0-9_]{2,})\b/,  # require ≥ 3 chars to dodge $PATH-style false positives... actually $PATH is fine, but cuts $A
+      ],
+    }.freeze
+
+    def self.scan(root, ignore_globs: [])
+      results = Hash.new { |h, k| h[k] = [] }
+      gitignore_globs = parse_gitignore(File.join(root, ".gitignore"))
+      all_globs = (ignore_globs + gitignore_globs).uniq
+
+      Find.find(root) do |path|
+        rel = path.sub(/\A#{Regexp.escape(root)}\/?/, "")
+
+        if File.directory?(path)
+          base = File.basename(path)
+          if SKIP_DIRS.include?(base) || ignored?(rel, all_globs, dir: true)
+            Find.prune
+          end
+          next
+        end
+
+        next if File.basename(path).start_with?(".") && File.basename(path) != ".envrc"
+        next if path =~ SKIP_FILE_RE
+        next if File.size(path) > MAX_FILE_BYTES rescue next
+        next if ignored?(rel, all_globs, dir: false)
+
+        lang = lang_for(path)
+        next unless lang
+
+        scan_file(path, lang, results)
+      end
+
+      results
+    end
+
+    def self.lang_for(path)
+      base = File.basename(path)
+      return SPECIAL_FILES[base] if SPECIAL_FILES.key?(base)
+      EXT_LANG[File.extname(path)]
+    end
+
+    def self.scan_file(path, lang, results)
+      content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace)
+      patterns = PATTERNS[lang] || []
+
+      content.each_line.with_index(1) do |line, line_no|
+        patterns.each do |re|
+          line.scan(re) do |captures|
+            name    = captures[0]
+            default = captures[1] && captures[1].strip
+            results[name] << {
+              file: path,
+              line: line_no,
+              default: extract_default(default),
+              optional: !default.nil?,
+            }
+          end
+        end
+      end
+    rescue ArgumentError, Errno::ENOENT
+      # Skip unreadable / binary files
+    end
+
+    def self.extract_default(raw)
+      return nil if raw.nil? || raw.empty?
+      # strip surrounding quotes if literal string
+      m = raw.match(/\A["']([^"']*)["']\z/)
+      m ? m[1] : nil
+    end
+
+    # Minimal .gitignore parser — supports literal patterns and globs (no
+    # full git semantics, just common cases).
+    def self.parse_gitignore(path)
+      return [] unless File.exist?(path)
+      File.readlines(path).map(&:strip).reject { |l| l.empty? || l.start_with?("#") }
+    rescue
+      []
+    end
+
+    def self.ignored?(rel, globs, dir:)
+      globs.any? do |pat|
+        clean = pat.sub(/\A\//, "").sub(/\/\z/, "")
+        next false if clean.empty?
+        File.fnmatch?(clean, rel, File::FNM_PATHNAME) ||
+          File.fnmatch?(clean, File.basename(rel)) ||
+          rel.start_with?("#{clean}/")
+      end
+    end
+  end
+end

data/lib/envspec/validator.rb

@@ -0,0 +1,70 @@
+class EnvSpec
+  # Validates an env hash (or ENV) against a parsed spec.
+  #
+  # Checks:
+  #   - required keys are present
+  #   - typed values parse cleanly (int, bool, dsn, enum)
+  #   - reports unknown keys as warnings (extras), not errors
+  #
+  # Usage:
+  #   spec.validate!(ENV.to_h, env: "production")
+  #
+  # Raises EnvSpec::ValidationError with a list of all problems found.
+  def validate!(env_hash, env: SHARED, strict: false)
+    problems = validate(env_hash, env: env, strict: strict)
+    raise ValidationError.new(problems) unless problems.empty?
+    true
+  end
+
+  def validate(env_hash, env: SHARED, strict: false)
+    problems = []
+
+    keys = configmap_for(env).merge(secrets_for(env))
+
+    keys.each do |name, entry|
+      raw = env_hash[name]
+      if raw.nil? || raw.empty?
+        next if entry.optional || !entry.default.nil?
+        problems << "missing required env var '#{name}' (declared at line #{entry.line})"
+        next
+      end
+
+      err = type_problem(name, raw, entry)
+      problems << err if err
+    end
+
+    if strict
+      known = keys.keys
+      env_hash.each_key do |k|
+        next unless k =~ /\A[A-Z][A-Z0-9_]*\z/
+        problems << "unknown env var '#{k}' (not declared in spec)" unless known.include?(k)
+      end
+    end
+
+    problems
+  end
+
+  private
+
+  def type_problem(name, raw, entry)
+    case entry.type
+    when :str, :dsn
+      nil
+    when :int
+      Integer(raw, 10)
+      nil
+    when :bool
+      unless %w[true false 1 0 yes no].include?(raw.downcase)
+        return "env var '#{name}' = #{raw.inspect} is not a valid bool (expected true/false/1/0/yes/no)"
+      end
+      nil
+    when :enum
+      unless entry.enum_values.include?(raw)
+        return "env var '#{name}' = #{raw.inspect} is not in enum(#{entry.enum_values.join(', ')})"
+      end
+      nil
+    end
+  rescue ArgumentError
+    "env var '#{name}' = #{raw.inspect} is not a valid #{entry.type}"
+  end
+end

data/lib/envspec/version.rb

@@ -0,0 +1,3 @@
+class EnvSpec
+  VERSION = "0.1.0".freeze
+end

data/lib/envspec.rb

@@ -0,0 +1,6 @@
+require_relative "envspec/version"
+require_relative "envspec/errors"
+require_relative "envspec/entry"
+require_relative "envspec/parser"
+require_relative "envspec/validator"
+require_relative "envspec/init"

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: envspec
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leadfy
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 'Parses env.spec files: a declarative contract describing which env vars
+  an app expects, their types, optionality, and ConfigMap-vs-Secret classification.
+  Pure stdlib, zero runtime dependencies.'
+email:
+- dev@leadfy.com
+executables:
+- envspec
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/envspec
+- lib/envspec.rb
+- lib/envspec/entry.rb
+- lib/envspec/errors.rb
+- lib/envspec/heuristics.rb
+- lib/envspec/init.rb
+- lib/envspec/parser.rb
+- lib/envspec/scanner.rb
+- lib/envspec/validator.rb
+- lib/envspec/version.rb
+homepage: https://github.com/repleadfy/envspec
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.32
+signing_key:
+specification_version: 4
+summary: Declarative env var contract for apps (parser + validator + scaffolder)
+test_files: []