ruby-lean 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4553b3d3a834471cf5bfbda717aa0931d752c5d9d198b002c435c7078341d644
+  data.tar.gz: bcd4971c8b74cdfb009f36c373813bfeb4b2a0a1658cb3f681ef713005b882b3
+SHA512:
+  metadata.gz: eca97ad8086fe7fb52844200a0f32a44e0d5fd9629d8722c5a58df8edf43a10ca2b8febca0b00c58f9ce931fb084f746e9ebb5d9655d9fca91250cb8e01feaf1
+  data.tar.gz: 25331d162f42aa60e36dd068fea8a4c70af392bfd19f041d82173af1e14a2f62d0f2079e14d1fbfa5b2bdd9d13e100ce9923ee101e10e023ab99c84b51a29781

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-13
+
+### Added
+
+- __`lint` command__: Checks whether all files declared in `.gemspec` and included in `.gem` packages comply with leanness and packaging rules.
+- __Dual-layer inspection__: Analyzes effective gemspec declarations (`Gem::Specification#files`) and verifies built `.gem` archive contents in isolated temporary storage.
+- __Lint rules__: Comprehensive detection of missing files, invalid paths, test suites, CI metadata, coverage reports, editor settings, development build tools, VCS files, and dynamic `git ls-files` discovery.
+- __`--strict` flag__: Enables failing exit code on advisory warnings for CI pipelines.
+- __`--no-archive` flag__: Allows specification-only inspection without building `.gem` archives.
+- __`--format json` option__: Structured, deterministic JSON output for scripting and CI integration.
+- __`--gemspec` option__: Explicitly specify `.gemspec` file path.

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 - ∞ Raphael Stolt
+
+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,199 @@
+# ruby-lean
+
+Validate and inspect RubyGem package contents to keep your published gems lean.
+
+## Why?
+
+When you publish a Ruby gem to RubyGems.org, RubyGems packages all files resolved by `Gem::Specification#files` in your `.gemspec`. In many gems, files are selected using loose directory globs (`Dir["**/*"]`) or broad `git ls-files` commands. That means your published gem can unintentionally include development artefacts like IDE settings, test suites, build output, documentation drafts, and CI configuration. These files bloat the gem download size, slow down `gem install` and `bundle install`, and expose internal project structure to downstream users.
+
+`ruby-lean` audits your `.gemspec` file list and verifies built `.gem` archives so only the source code and assets your users need end up in the published gem.
+
+## Installation
+
+### From RubyGems
+
+```bash
+gem install ruby-lean
+```
+
+### From source
+
+```bash
+git clone git@github.com:lean-packages/ruby-lean.git && cd ruby-lean
+rake build
+gem install ./ruby-lean-*.gem
+```
+
+This places the `ruby-lean` binary in your Ruby environment's executable directory, which should be on your PATH.
+
+## Usage
+
+```
+ruby-lean <COMMAND>
+```
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `lint`  | Check if any unnecessary or invalid files are included in the gem. |
+
+### `lint` — Check package contents
+
+Verifies that all files declared in `.gemspec` and packaged in `.gem` meet leanness and validity policies.
+
+```bash
+# Check the current directory
+ruby-lean lint
+
+# Check a specific project directory
+ruby-lean lint /path/to/my-gem
+
+# Check a specific gemspec file
+ruby-lean lint --gemspec /path/to/my-gem.gemspec
+
+# Fail on advisory warnings (recommended for CI)
+ruby-lean lint --strict
+
+# Inspect gemspec file list only without building an archive
+ruby-lean lint --no-archive
+
+# JSON output for scripting
+ruby-lean lint --format json
+```
+
+__`--strict` flag:__ Treats advisory warnings (such as development test files, CI metadata, and build tools) as failures, exiting with code `1`.
+
+__`--no-archive` flag:__ Skips building a temporary `.gem` archive and inspects only the effective gemspec file list on disk.
+
+## Options and flags
+
+All commands support these options and flags:
+
+| Option / Flag | Description |
+|---|---|
+| `--gemspec <PATH>` | Path to explicit `.gemspec` file |
+| `-f, --format <FORMAT>` | Output format: `text` or `json` (default: `text`) |
+| `-s, --strict` | Treat advisory warnings as errors |
+| `--no-archive` | Skip building and verifying temporary `.gem` archive |
+| `-q, --quiet` | Suppress non-essential informational output |
+| `-v, --version` | Print version information |
+| `-h, --help` | Show help message |
+
+## Lint rules
+
+`ruby-lean` evaluates package contents against high-signal rules:
+
+### Errors (Always fail policy)
+
+| Rule ID | Description |
+|---|---|
+| `RUBYLEAN_INVALID_SPEC` | Gemspec syntax error, unloadable specification, or validation failure. |
+| `RUBYLEAN_MISSING_FILE` | Declared file does not exist on disk. |
+| `RUBYLEAN_INVALID_PATH` | Absolute path, directory entry, or path escaping the gem root (`../`). |
+| `RUBYLEAN_BUILD_ERROR` | RubyGems archive packaging failure. |
+| `RUBYLEAN_ARCHIVE_MISMATCH` | Discrepancy between gemspec declared files and actual `.gem` archive contents. |
+
+### Advisory warnings (Fail with `--strict`)
+
+| Rule ID | Description |
+|---|---|
+| `RUBYLEAN_DEV_FILE` | Test or specification files (`spec/`, `test/`, `features/`) included in gem. |
+| `RUBYLEAN_CI_METADATA` | CI configuration files (`.github/`, `.gitlab/`, `.circleci/`, etc.) included. |
+| `RUBYLEAN_COVERAGE` | Test coverage artifacts or configs (`coverage/`, `.simplecov`) included. |
+| `RUBYLEAN_EDITOR_CONFIG` | Editor or IDE configuration files (`.vscode/`, `.idea/`, etc.) included. |
+| `RUBYLEAN_BUILD_TOOL` | Development build tools (`Gemfile`, `Gemfile.lock`, `Rakefile`, `.rubocop.yml`) included. |
+| `RUBYLEAN_VCS_METADATA` | VCS metadata (`.gitignore`, `.gitattributes`) included. |
+| `RUBYLEAN_GIT_DEPENDENT` | Gemspec source relies on `git ls-files` for dynamic file discovery (advisory). |
+| `RUBYLEAN_SYMLINK` | Packaged file is a symbolic link. |
+
+*Note:* Standard documentation and runtime assets (`README*`, `LICENSE*`, `CHANGELOG*`, `CONTRIBUTING*`, `docs/`, `lib/`, `exe/`) are explicitly preserved and never flagged.
+
+## Exit codes
+
+| Exit Code | Status | Description |
+|---|---|---|
+| `0` | `SUCCESS` | Gem passed policy (0 errors; warnings allowed unless `--strict`). |
+| `1` | `LINT_FAILED` | Lint policy failed (errors found, or warnings found with `--strict`). |
+| `2` | `EXECUTION_ERROR` | Usage error, invalid options, missing gemspec, or gemspec evaluation failure. |
+
+## CI integration
+
+Add `ruby-lean lint` to your CI pipeline to enforce that gem packages stay clean:
+
+```yaml
+# Example GitHub Actions step
+- name: Check RubyGem package contents
+  run: ruby-lean lint --strict
+```
+
+## JSON output
+
+All commands support `--format json` for scripting and automation. Example `lint` output:
+
+```json
+{
+  "schemaVersion": "1",
+  "tool": {
+    "name": "ruby-lean",
+    "version": "0.1.0"
+  },
+  "package": {
+    "name": "example-gem",
+    "version": "1.0.0",
+    "gemspec": "example-gem.gemspec"
+  },
+  "inspection": {
+    "mode": "archive",
+    "archiveVerified": true,
+    "fileCount": 4,
+    "totalBytes": 1420
+  },
+  "summary": {
+    "errors": 0,
+    "warnings": 1,
+    "info": 0
+  },
+  "findings": [
+    {
+      "rule": "RUBYLEAN_DEV_FILE",
+      "severity": "warning",
+      "message": "Development-oriented test or specification files are included in the package.",
+      "paths": [
+        "spec/example_spec.rb"
+      ],
+      "suggestedAction": "Filter out test directories (spec/, test/, features/) from spec.files in your gemspec."
+    }
+  ]
+}
+```
+
+## Security considerations
+
+A `.gemspec` file contains executable Ruby code. Evaluating a gemspec via RubyGems executes Ruby instructions. `ruby-lean` is intended for **trusted local gem repositories** and maintainers inspecting their own code. Evaluating untrusted gemspecs is not sandboxed.
+
+## AI disclaimer
+
+This package is developed with the assistance of Artificial Intelligence (AI). AI tools are used throughout the development
+process, including code generation, documentation, testing, and maintenance.
+
+While reasonable care is taken to review and validate AI-generated contributions, AI-generated code is not inherently correct,
+secure, or free of defects. All contributions remain subject to human review and project quality standards.
+
+As with any software, use this package at your own risk. No guarantee is made regarding its fitness for a particular purpose,
+and the maintainers assume no liability for damages resulting from its use.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development instructions.
+
+## License
+
+This project is licensed under the MIT license. Please see [LICENSE.md](LICENSE.md) for more details.
+
+## Related projects
+
+- [cargo-lean](https://github.com/lean-packages/cargo-lean) — The `Rust` counterpart.
+- [php-lean](https://github.com/lean-packages/php-lean) — The `PHP` counterpart.
+- [py-lean](https://github.com/lean-packages/py-lean) — The `Python` equivalent.
+- [js-lean](https://github.com/lean-packages/js-lean) — The `JavaScript` equivalent.

data/exe/ruby-lean

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ruby_lean"
+
+exit(RubyLean::CLI.start(ARGV))

data/lib/ruby_lean/archive_inspector.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "rubygems/package"
+require "tmpdir"
+require "open3"
+require "zlib"
+
+module RubyLean
+  class ArchiveInspector
+    ArchiveData = Struct.new(:archive_files, :file_count, :total_bytes, :largest_files, :build_warnings, keyword_init: true)
+
+    def self.inspect_package(package)
+      new.inspect_package(package)
+    end
+
+    def inspect_package(package)
+      Dir.mktmpdir("ruby-lean-") do |tmpdir|
+        output_gem = File.join(tmpdir, "#{package.name}-#{package.version}.gem")
+        gemspec_filename = File.basename(package.gemspec_path)
+
+        cmd = ["gem", "build", gemspec_filename, "--output", output_gem]
+        stdout, stderr, status = Open3.capture3(*cmd, chdir: package.gem_root)
+
+        unless status.success? && File.exist?(output_gem)
+          error_msg = stderr.to_s.strip
+          error_msg = stdout.to_s.strip if error_msg.empty?
+          error_msg = "Unknown gem build error" if error_msg.empty?
+          raise BuildError, error_msg
+        end
+
+        parse_archive(output_gem, stderr)
+      end
+    end
+
+    private
+
+    def parse_archive(gem_path, stderr)
+      archive_files = []
+      file_entries = []
+      total_bytes = 0
+
+      File.open(gem_path, "rb") do |io|
+        Gem::Package::TarReader.new(io) do |reader|
+          reader.each do |entry|
+            next unless entry.full_name == "data.tar.gz"
+
+            gz = Zlib::GzipReader.new(entry)
+            Gem::Package::TarReader.new(gz) do |data_reader|
+              data_reader.each do |data_entry|
+                next unless data_entry.file?
+
+                fname = data_entry.full_name
+                fsize = data_entry.header.size
+
+                archive_files << fname
+                file_entries << { "path" => fname, "bytes" => fsize }
+                total_bytes += fsize
+              end
+            end
+          end
+        end
+      end
+
+      largest_files = file_entries.sort_by { |e| -e["bytes"] }.first(5)
+
+      ArchiveData.new(
+        archive_files: archive_files.sort,
+        file_count: archive_files.size,
+        total_bytes: total_bytes,
+        largest_files: largest_files,
+        build_warnings: stderr.to_s.strip
+      )
+    end
+  end
+end

data/lib/ruby_lean/cli.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module RubyLean
+  class CLI
+    def self.start(args = ARGV)
+      new.start(args)
+    end
+
+    def start(args = ARGV)
+      options = {
+        format: "text",
+        strict: false,
+        archive: true,
+        quiet: false
+      }
+
+      args = args.dup
+
+      # Check top-level flags first
+      if args.include?("-v") || args.include?("--version")
+        puts "ruby-lean #{RubyLean::VERSION}"
+        return 0
+      end
+
+      # Extract command if provided
+      command = "lint"
+      if args.first == "lint"
+        args.shift
+      elsif args.first && !args.first.start_with?("-") && File.exist?(args.first)
+        # First arg is a path
+        options[:path] = args.shift
+      end
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: ruby-lean lint [PATH] [options]"
+        opts.separator ""
+        opts.separator "Options:"
+
+        opts.on("--gemspec PATH", "Path to explicit .gemspec file") do |path|
+          options[:gemspec] = path
+        end
+
+        opts.on("-f", "--format FORMAT", %w[text json], "Output format (text, json; default: text)") do |fmt|
+          options[:format] = fmt
+        end
+
+        opts.on("-s", "--strict", "Fail on warnings as well as errors") do
+          options[:strict] = true
+        end
+
+        opts.on("--no-archive", "Inspect gemspec file list only without building archive") do
+          options[:archive] = false
+        end
+
+        opts.on("-q", "--quiet", "Suppress non-essential informational output") do
+          options[:quiet] = true
+        end
+
+        opts.on_tail("-v", "--version", "Print version and exit") do
+          puts "ruby-lean #{RubyLean::VERSION}"
+          return 0
+        end
+
+        opts.on_tail("-h", "--help", "Show this help message and exit") do
+          puts opts
+          return 0
+        end
+      end
+
+      begin
+        remaining = parser.parse!(args)
+        options[:path] ||= remaining.first || "."
+      rescue OptionParser::InvalidOption, OptionParser::InvalidArgument => e
+        warn "Error: #{e.message}"
+        warn "Run 'ruby-lean --help' for usage instructions."
+        return 2
+      end
+
+      begin
+        Command::Lint.run(options)
+      rescue ExecutionError => e
+        warn "Error: #{e.message}"
+        2
+      rescue StandardError => e
+        warn "Unexpected error: #{e.message}"
+        warn e.backtrace.join("\n") if $DEBUG
+        2
+      end
+    end
+  end
+end

data/lib/ruby_lean/command/lint.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module RubyLean
+  module Command
+    class Lint
+      def self.run(options = {})
+        new(options).run
+      end
+
+      def initialize(options = {})
+        @options = options
+        @target_path = options[:path] || "."
+        @explicit_gemspec = options[:gemspec]
+        @format = (options[:format] || "text").to_s.downcase
+        @strict = !!options[:strict]
+        @archive = options.fetch(:archive, true)
+        @quiet = !!options[:quiet]
+      end
+
+      def run
+        package = GemspecLoader.discover_and_load(@target_path, explicit_gemspec: @explicit_gemspec)
+
+        result = if @archive
+                   inspect_with_archive(package)
+                 else
+                   inspect_specification_only(package)
+                 end
+
+        output = render_result(result)
+
+        if @format == "json"
+          puts output
+        else
+          puts output unless output.empty?
+        end
+
+        result.exit_code(strict: @strict)
+      end
+
+      private
+
+      def inspect_with_archive(package)
+        archive_data = nil
+        build_error_finding = nil
+
+        begin
+          archive_data = ArchiveInspector.inspect_package(package)
+        rescue BuildError => e
+          build_error_finding = Model::Finding.new(
+            rule: "RUBYLEAN_BUILD_ERROR",
+            severity: "error",
+            message: "Failed to build .gem archive: #{e.message}",
+            paths: [package.relative_gemspec_path],
+            suggested_action: "Fix gemspec errors or build issues reported by RubyGems."
+          )
+        end
+
+        if archive_data
+          findings = Rules::Engine.audit(package, archive_files: archive_data.archive_files)
+          Model::Result.new(
+            package: package,
+            inspection_mode: "archive",
+            archive_verified: true,
+            file_count: archive_data.file_count,
+            total_bytes: archive_data.total_bytes,
+            largest_files: archive_data.largest_files,
+            archive_files: archive_data.archive_files,
+            findings: findings
+          )
+        else
+          # Fallback to spec rules plus build error finding
+          findings = Rules::Engine.audit(package, archive_files: nil)
+          findings << build_error_finding if build_error_finding
+
+          Model::Result.new(
+            package: package,
+            inspection_mode: "archive",
+            archive_verified: false,
+            file_count: package.effective_files.size,
+            total_bytes: calculate_disk_bytes(package),
+            findings: findings
+          )
+        end
+      end
+
+      def inspect_specification_only(package)
+        findings = Rules::Engine.audit(package, archive_files: nil)
+
+        Model::Result.new(
+          package: package,
+          inspection_mode: "specification",
+          archive_verified: false,
+          file_count: package.effective_files.size,
+          total_bytes: calculate_disk_bytes(package),
+          findings: findings
+        )
+      end
+
+      def calculate_disk_bytes(package)
+        total = 0
+        package.effective_files.each do |rel_path|
+          full_path = File.join(package.gem_root, rel_path)
+          total += File.size(full_path) if File.file?(full_path)
+        end
+        total
+      rescue StandardError
+        nil
+      end
+
+      def render_result(result)
+        case @format
+        when "json"
+          Reporters::JsonReporter.render(result)
+        else
+          Reporters::TextReporter.render(result, strict: @strict, quiet: @quiet)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_lean/gemspec_loader.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "pathname"
+
+module RubyLean
+  class GemspecLoader
+    def self.discover_and_load(target_path = ".", explicit_gemspec: nil)
+      new.discover_and_load(target_path, explicit_gemspec: explicit_gemspec)
+    end
+
+    def discover_and_load(target_path = ".", explicit_gemspec: nil)
+      gemspec_path = resolve_gemspec_path(target_path, explicit_gemspec)
+      load_gemspec(gemspec_path)
+    end
+
+    def resolve_gemspec_path(target_path = ".", explicit_gemspec = nil)
+      if explicit_gemspec
+        path = File.expand_path(explicit_gemspec)
+        unless File.exist?(path) && File.file?(path)
+          raise ExecutionError, "Specified gemspec does not exist: #{explicit_gemspec}"
+        end
+
+        return path
+      end
+
+      target = File.expand_path(target_path || ".")
+
+      if File.file?(target) && target.end_with?(".gemspec")
+        return target
+      end
+
+      unless File.directory?(target)
+        raise ExecutionError, "Target path is not a directory or gemspec: #{target_path}"
+      end
+
+      matches = Dir.glob(File.join(target, "*.gemspec"))
+      if matches.empty?
+        raise ExecutionError, "No .gemspec file found in #{target_path}. Specify one with --gemspec PATH"
+      elsif matches.size > 1
+        names = matches.map { |m| File.basename(m) }.join(", ")
+        raise ExecutionError, "Multiple .gemspec files found (#{names}). Specify one with --gemspec PATH"
+      end
+
+      matches.first
+    end
+
+    def load_gemspec(gemspec_path)
+      gemspec_path = File.expand_path(gemspec_path)
+      gem_root = File.dirname(gemspec_path)
+
+      source_text = File.read(gemspec_path) rescue ""
+      git_dependent = detect_git_dependency(source_text)
+
+      spec = nil
+      # Evaluate gemspec in its directory context
+      Dir.chdir(gem_root) do
+        begin
+          code = File.read(gemspec_path, mode: "r:UTF-8:-")
+          spec = eval(code, binding, gemspec_path)
+        rescue StandardError, ScriptError => e
+          raise GemspecLoadError, "Failed to evaluate gemspec #{File.basename(gemspec_path)}: #{e.message}"
+        end
+      end
+
+      if spec.nil? || !spec.is_a?(Gem::Specification)
+        raise GemspecLoadError, "Failed to evaluate gemspec: #{File.basename(gemspec_path)} is invalid or empty"
+      end
+
+      spec.loaded_from = gemspec_path
+
+      effective_files = Array(spec.files).map(&:to_s).uniq.sort
+
+      Model::Package.new(
+        name: spec.name || File.basename(gemspec_path, ".gemspec"),
+        version: spec.version ? spec.version.to_s : "0.0.0",
+        gemspec_path: gemspec_path,
+        gem_root: gem_root,
+        effective_files: effective_files,
+        spec: spec,
+        git_dependent: git_dependent
+      )
+    end
+
+    private
+
+    def detect_git_dependency(source)
+      # Check if gemspec uses `git ls-files` or similar git command
+      source.match?(/`\s*git\s+ls-files/i) ||
+        source.match?(/%x\[\s*git\s+ls-files/i) ||
+        source.match?(/IO\.popen\(\s*\[?['"]git['"],\s*['"]ls-files['"]/i) ||
+        source.match?(/Open3\.(?:capture[23]|popen3)\(\s*['"]git\s+ls-files/i)
+    end
+  end
+end

data/lib/ruby_lean/model/finding.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RubyLean
+  module Model
+    class Finding
+      SEVERITIES = %w[error warning info].freeze
+
+      attr_reader :rule, :severity, :message, :paths, :suggested_action
+
+      def initialize(rule:, severity:, message:, paths: [], suggested_action: nil)
+        @rule = rule.to_s
+        @severity = severity.to_s.downcase
+        @message = message.to_s
+        @paths = Array(paths).map(&:to_s).sort
+        @suggested_action = suggested_action&.to_s
+      end
+
+      def error?
+        @severity == "error"
+      end
+
+      def warning?
+        @severity == "warning"
+      end
+
+      def info?
+        @severity == "info"
+      end
+
+      def to_h
+        data = {
+          "rule" => @rule,
+          "severity" => @severity,
+          "message" => @message,
+          "paths" => @paths
+        }
+        data["suggestedAction"] = @suggested_action if @suggested_action
+        data
+      end
+
+      def ==(other)
+        other.is_a?(Finding) &&
+          rule == other.rule &&
+          severity == other.severity &&
+          message == other.message &&
+          paths == other.paths &&
+          suggested_action == other.suggested_action
+      end
+    end
+  end
+end

data/lib/ruby_lean/model/package.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RubyLean
+  module Model
+    class Package
+      attr_reader :name, :version, :gemspec_path, :gem_root, :effective_files, :spec, :git_dependent
+
+      def initialize(name:, version:, gemspec_path:, gem_root:, effective_files: [], spec: nil, git_dependent: false)
+        @name = name.to_s
+        @version = version.to_s
+        @gemspec_path = gemspec_path.to_s
+        @gem_root = File.expand_path(gem_root.to_s)
+        @effective_files = Array(effective_files).map(&:to_s).uniq.sort
+        @spec = spec
+        @git_dependent = !!git_dependent
+      end
+
+      def relative_gemspec_path
+        Pathname.new(@gemspec_path).relative_path_from(Pathname.new(@gem_root)).to_s
+      rescue ArgumentError
+        @gemspec_path
+      end
+    end
+  end
+end

data/lib/ruby_lean/model/result.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module RubyLean
+  module Model
+    class Result
+      attr_reader :package, :inspection_mode, :archive_verified, :file_count, :total_bytes, :largest_files, :archive_files, :findings
+
+      def initialize(package:, inspection_mode: "archive", archive_verified: false, file_count: 0, total_bytes: nil, largest_files: [], archive_files: nil, findings: [])
+        @package = package
+        @inspection_mode = inspection_mode.to_s
+        @archive_verified = !!archive_verified
+        @file_count = Integer(file_count)
+        @total_bytes = total_bytes ? Integer(total_bytes) : nil
+        @largest_files = Array(largest_files)
+        @archive_files = archive_files ? Array(archive_files).map(&:to_s).sort : nil
+        @findings = Array(findings).sort_by { |f| [severity_rank(f.severity), f.rule, f.paths.first || ""] }
+      end
+
+      def errors
+        @findings.select(&:error?)
+      end
+
+      def warnings
+        @findings.select(&:warning?)
+      end
+
+      def info_items
+        @findings.select(&:info?)
+      end
+
+      def errors_count
+        errors.size
+      end
+
+      def warnings_count
+        warnings.size
+      end
+
+      def info_count
+        info_items.size
+      end
+
+      def passed?(strict: false)
+        return false if errors_count > 0
+        return false if strict && warnings_count > 0
+
+        true
+      end
+
+      def exit_code(strict: false)
+        return 1 unless passed?(strict: strict)
+
+        0
+      end
+
+      def to_h
+        data = {
+          "schemaVersion" => "1",
+          "tool" => {
+            "name" => "ruby-lean",
+            "version" => RubyLean::VERSION
+          },
+          "package" => {
+            "name" => @package.name,
+            "version" => @package.version,
+            "gemspec" => @package.relative_gemspec_path
+          },
+          "inspection" => {
+            "mode" => @inspection_mode,
+            "archiveVerified" => @archive_verified,
+            "fileCount" => @file_count
+          },
+          "summary" => {
+            "errors" => errors_count,
+            "warnings" => warnings_count,
+            "info" => info_count
+          },
+          "findings" => @findings.map(&:to_h)
+        }
+
+        data["inspection"]["totalBytes"] = @total_bytes if @total_bytes
+        data
+      end
+
+      private
+
+      def severity_rank(sev)
+        case sev.to_s.downcase
+        when "error" then 0
+        when "warning" then 1
+        when "info" then 2
+        else 3
+        end
+      end
+    end
+  end
+end

data/lib/ruby_lean/reporters/json_reporter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyLean
+  module Reporters
+    class JsonReporter
+      def self.render(result)
+        new(result).render
+      end
+
+      def initialize(result)
+        @result = result
+      end
+
+      def render
+        JSON.pretty_generate(@result.to_h)
+      end
+    end
+  end
+end

data/lib/ruby_lean/reporters/text_reporter.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module RubyLean
+  module Reporters
+    class TextReporter
+      def self.render(result, strict: false, quiet: false)
+        new(result, strict: strict, quiet: quiet).render
+      end
+
+      def initialize(result, strict: false, quiet: false)
+        @result = result
+        @strict = strict
+        @quiet = quiet
+      end
+
+      def render
+        lines = []
+
+        unless @quiet
+          lines << "ruby-lean lint: #{@result.package.name} #{@result.package.version}"
+          lines << "  Gemspec:     #{@result.package.relative_gemspec_path}"
+          mode_label = @result.archive_verified ? "Archive verified (.gem)" : "Specification-only (--no-archive)"
+          lines << "  Mode:        #{mode_label}"
+          lines << "  Files:       #{@result.file_count}"
+          if @result.total_bytes
+            lines << "  Total size:  #{format_bytes(@result.total_bytes)}"
+          end
+          lines << ""
+        end
+
+        if @result.findings.empty?
+          lines << "No issues found. Gem packaging passes policy."
+          lines << "Policy passed."
+        else
+          # Group findings by severity
+          errors = @result.errors
+          warnings = @result.warnings
+          info = @result.info_items
+
+          if errors.any?
+            lines << "ERRORS (#{errors.size}):"
+            errors.each { |f| lines.concat(format_finding(f)) }
+            lines << ""
+          end
+
+          if warnings.any?
+            lines << "WARNINGS (#{warnings.size}):"
+            warnings.each { |f| lines.concat(format_finding(f)) }
+            lines << ""
+          end
+
+          if info.any?
+            lines << "INFO (#{info.size}):"
+            info.each { |f| lines.concat(format_finding(f)) }
+            lines << ""
+          end
+
+          summary_text = "Summary: #{@result.errors_count} error(s), #{@result.warnings_count} warning(s)"
+          summary_text += " (strict mode enabled)" if @strict
+          lines << summary_text
+
+          if @result.passed?(strict: @strict)
+            lines << "Policy passed."
+          else
+            lines << "Policy failed."
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def format_finding(finding)
+        out = []
+        out << "  [#{finding.rule}] #{finding.message}"
+        finding.paths.each do |p|
+          out << "    - #{p}"
+        end
+        if finding.suggested_action
+          out << "    Suggested action: #{finding.suggested_action}"
+        end
+        out
+      end
+
+      def format_bytes(bytes)
+        if bytes < 1024
+          "#{bytes} B"
+        elsif bytes < 1024 * 1024
+          "#{(bytes / 1024.0).round(1)} KB (#{bytes} bytes)"
+        else
+          "#{(bytes / (1024.0 * 1024.0)).round(2)} MB (#{bytes} bytes)"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_lean/rules/engine.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "set"
+
+module RubyLean
+  module Rules
+    class Engine
+      def self.audit(package, archive_files: nil)
+        new(package, archive_files: archive_files).audit
+      end
+
+      def initialize(package, archive_files: nil)
+        @package = package
+        @archive_files = archive_files
+        @gem_root = package.gem_root
+        @effective_files = package.effective_files
+      end
+
+      def audit
+        findings = []
+
+        # 1. Path validity and existence checks (Errors)
+        findings.concat(check_paths_and_missing_files)
+
+        # 2. Advisory warning checks
+        findings.concat(check_dev_files)
+        findings.concat(check_ci_metadata)
+        findings.concat(check_coverage_artifacts)
+        findings.concat(check_editor_configs)
+        findings.concat(check_build_tools)
+        findings.concat(check_vcs_metadata)
+        findings.concat(check_symlinks)
+        findings.concat(check_git_dependency)
+
+        # 3. Archive mismatch checks (if archive was inspected)
+        findings.concat(check_archive_mismatches) if @archive_files
+
+        findings
+      end
+
+      private
+
+      def check_paths_and_missing_files
+        findings = []
+        invalid_paths = []
+        missing_files = []
+
+        gem_root_pathname = Pathname.new(@gem_root).cleanpath
+
+        @effective_files.each do |rel_path|
+          # Check for absolute path or root escaping traversal
+          if rel_path.start_with?("/") || rel_path.start_with?("\\")
+            invalid_paths << rel_path
+            next
+          end
+
+          expanded_path = File.expand_path(rel_path, @gem_root)
+          expanded_pathname = Pathname.new(expanded_path).cleanpath
+
+          # Check if path escapes gem root
+          begin
+            relative_to_root = expanded_pathname.relative_path_from(gem_root_pathname).to_s
+            if relative_to_root.start_with?("..")
+              invalid_paths << rel_path
+              next
+            end
+          rescue ArgumentError
+            invalid_paths << rel_path
+            next
+          end
+
+          # Check existence
+          if !File.exist?(expanded_path)
+            missing_files << rel_path
+          elsif File.directory?(expanded_path)
+            # Declaring a directory as a file entry
+            invalid_paths << rel_path
+          end
+        end
+
+        if invalid_paths.any?
+          findings << Model::Finding.new(
+            rule: "RUBYLEAN_INVALID_PATH",
+            severity: "error",
+            message: "Gemspec contains absolute paths, directory entries, or paths traversing outside the gem root.",
+            paths: invalid_paths,
+            suggested_action: "Remove absolute paths and directory entries; ensure all paths are relative to the gem root."
+          )
+        end
+
+        if missing_files.any?
+          findings << Model::Finding.new(
+            rule: "RUBYLEAN_MISSING_FILE",
+            severity: "error",
+            message: "Files referenced in gemspec effective file list do not exist on disk.",
+            paths: missing_files,
+            suggested_action: "Ensure declared files exist or remove non-existent references from spec.files."
+          )
+        end
+
+        findings
+      end
+
+      def check_dev_files
+        matches = @effective_files.select do |path|
+          dev_file?(path)
+        end
+
+        return [] if matches.empty?
+
+        [
+          Model::Finding.new(
+            rule: "RUBYLEAN_DEV_FILE",
+            severity: "warning",
+            message: "Development-oriented test or specification files are included in the package.",
+            paths: matches,
+            suggested_action: "Filter out test directories (spec/, test/, features/) from spec.files in your gemspec."
+          )
+        ]
+      end
+
+      def dev_file?(path)
+        p = path.downcase
+        # Test directories
+        return true if p.start_with?("spec/", "test/", "tests/", "features/", "benchmarks/")
+        return true if p.match?(%r{^[^/]+/(?:spec|test|tests|features)/})
+
+        # Standalone test files outside lib/
+        return true if !p.start_with?("lib/", "exe/", "bin/", "ext/") && (
+          p.end_with?("_test.rb", "_spec.rb") ||
+          File.basename(p).start_with?("test_")
+        )
+
+        false
+      end
+
+      def check_ci_metadata
+        matches = @effective_files.select do |path|
+          p = path.downcase
+          p.start_with?(".github/", ".gitlab/", ".circleci/", ".buildkite/") ||
+            %w[.travis.yml azure-pipelines.yml appveyor.yml .appveyor.yml .codecov.yml jenkinsfile].include?(File.basename(p))
+        end
+
+        return [] if matches.empty?
+
+        [
+          Model::Finding.new(
+            rule: "RUBYLEAN_CI_METADATA",
+            severity: "warning",
+            message: "Continuous Integration (CI) configuration or workflow files are included in the package.",
+            paths: matches,
+            suggested_action: "Exclude .github/, .gitlab/, and other CI configurations from spec.files."
+          )
+        ]
+      end
+
+      def check_coverage_artifacts
+        matches = @effective_files.select do |path|
+          p = path.downcase
+          p.start_with?("coverage/") || %w[.simplecov .simplecov_spawn].include?(File.basename(p))
+        end
+
+        return [] if matches.empty?
+
+        [
+          Model::Finding.new(
+            rule: "RUBYLEAN_COVERAGE",
+            severity: "warning",
+            message: "Test coverage configuration or generated report artifacts are included in the package.",
+            paths: matches,
+            suggested_action: "Remove coverage reports and .simplecov from spec.files."
+          )
+        ]
+      end
+
+      def check_editor_configs
+        matches = @effective_files.select do |path|
+          p = path.downcase
+          p.start_with?(".idea/", ".vscode/") ||
+            %w[.editorconfig .project .classpath .settings].include?(File.basename(p)) ||
+            p.end_with?(".swp", ".swo", "~")
+        end
+
+        return [] if matches.empty?
+
+        [
+          Model::Finding.new(
+            rule: "RUBYLEAN_EDITOR_CONFIG",
+            severity: "warning",
+            message: "Editor or IDE configuration files are included in the package.",
+            paths: matches,
+            suggested_action: "Exclude editor and IDE configuration directories and files from spec.files."
+          )
+        ]
+      end
+
+      def check_build_tools
+        build_tools_filenames = %w[
+          gemfile gemfile.lock rakefile .rubocop.yml .rubocop_todo.yml
+          .standard.yml .yardopts brewfile procfile .tool-versions .ruby-version
+        ]
+
+        matches = @effective_files.select do |path|
+          base = File.basename(path).downcase
+          build_tools_filenames.include?(base) || path.start_with?("bin/setup", "bin/console")
+        end
+
+        return [] if matches.empty?
+
+        [
+          Model::Finding.new(
+            rule: "RUBYLEAN_BUILD_TOOL",
+            severity: "warning",
+            message: "Development build tools, linters, or lockfiles are included in the package.",
+            paths: matches,
+            suggested_action: "Exclude Gemfile, Rakefile, linters, and development scripts from spec.files."
+          )
+        ]
+      end
+
+      def check_vcs_metadata
+        matches = @effective_files.select do |path|
+          p = path.downcase
+          p.start_with?(".git/", ".hg/", ".svn/") ||
+            %w[.gitignore .gitattributes .gitmodules].include?(File.basename(p))
+        end
+
+        return [] if matches.empty?
+
+        [
+          Model::Finding.new(
+            rule: "RUBYLEAN_VCS_METADATA",
+            severity: "warning",
+            message: "Version control system (VCS) metadata or configuration files are included in the package.",
+            paths: matches,
+            suggested_action: "Exclude .gitignore, .gitattributes, and other repository metadata from spec.files."
+          )
+        ]
+      end
+
+      def check_symlinks
+        matches = @effective_files.select do |path|
+          full_path = File.join(@gem_root, path)
+          File.symlink?(full_path)
+        end
+
+        return [] if matches.empty?
+
+        [
+          Model::Finding.new(
+            rule: "RUBYLEAN_SYMLINK",
+            severity: "warning",
+            message: "Symbolic link included in package files.",
+            paths: matches,
+            suggested_action: "Replace symlinks with regular files or ensure target files are valid package contents."
+          )
+        ]
+      end
+
+      def check_git_dependency
+        return [] unless @package.git_dependent
+
+        [
+          Model::Finding.new(
+            rule: "RUBYLEAN_GIT_DEPENDENT",
+            severity: "warning",
+            message: "Gemspec uses dynamic git ls-files discovery, which may include unneeded files or fail in non-git environments.",
+            paths: [@package.relative_gemspec_path],
+            suggested_action: "Use explicit file lists or filtered Dir.glob expressions instead of invoking git ls-files."
+          )
+        ]
+      end
+
+      def check_archive_mismatches
+        gemspec_set = @effective_files.to_set
+        archive_set = @archive_files.to_set
+
+        missing_in_archive = (gemspec_set - archive_set).to_a.sort
+        extra_in_archive = (archive_set - gemspec_set).to_a.sort
+
+        findings = []
+        if missing_in_archive.any? || extra_in_archive.any?
+          discrepancy_details = []
+          discrepancy_details.concat(missing_in_archive.map { |f| "#{f} (missing in .gem archive)" })
+          discrepancy_details.concat(extra_in_archive.map { |f| "#{f} (present in archive but not in gemspec)" })
+
+          findings << Model::Finding.new(
+            rule: "RUBYLEAN_ARCHIVE_MISMATCH",
+            severity: "error",
+            message: "Discrepancy detected between gemspec declared files and actual built .gem archive contents.",
+            paths: missing_in_archive + extra_in_archive,
+            suggested_action: "Review gemspec file patterns and build process to ensure archive contents match expectations."
+          )
+        end
+
+        findings
+      end
+    end
+  end
+end

data/lib/ruby_lean/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubyLean
+  VERSION = "0.1.0"
+end

data/lib/ruby_lean.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "ruby_lean/version"
+require_relative "ruby_lean/model/finding"
+require_relative "ruby_lean/model/package"
+require_relative "ruby_lean/model/result"
+require_relative "ruby_lean/gemspec_loader"
+require_relative "ruby_lean/archive_inspector"
+require_relative "ruby_lean/rules/engine"
+require_relative "ruby_lean/reporters/text_reporter"
+require_relative "ruby_lean/reporters/json_reporter"
+require_relative "ruby_lean/command/lint"
+require_relative "ruby_lean/cli"
+
+module RubyLean
+  class Error < StandardError; end
+  class ExecutionError < Error; end
+  class GemspecLoadError < ExecutionError; end
+  class BuildError < ExecutionError; end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: ruby-lean
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- lean-packages contributors
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-11-13 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby-native CLI to audit RubyGem package distributions, detect unnecessary
+  files, and inspect archive contents.
+email:
+- maintainers@lean-packages.org
+executables:
+- ruby-lean
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- exe/ruby-lean
+- lib/ruby_lean.rb
+- lib/ruby_lean/archive_inspector.rb
+- lib/ruby_lean/cli.rb
+- lib/ruby_lean/command/lint.rb
+- lib/ruby_lean/gemspec_loader.rb
+- lib/ruby_lean/model/finding.rb
+- lib/ruby_lean/model/package.rb
+- lib/ruby_lean/model/result.rb
+- lib/ruby_lean/reporters/json_reporter.rb
+- lib/ruby_lean/reporters/text_reporter.rb
+- lib/ruby_lean/rules/engine.rb
+- lib/ruby_lean/version.rb
+homepage: https://github.com/lean-packages/ruby-lean
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lean-packages/ruby-lean
+  source_code_uri: https://github.com/lean-packages/ruby-lean
+  changelog_uri: https://github.com/lean-packages/ruby-lean/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+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: Audits RubyGem distribution contents using native RubyGems packaging rules
+test_files: []