ficha 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ac8590b6ab46f565f13b1bb959e55c790f8ecebb62a7946b47be7e3acd94a88
+  data.tar.gz: 6290916d3e12018298de9343a6d4803ce2b7beb5d983c19a9f26c1b32993426f
+SHA512:
+  metadata.gz: 68dbe337310fa333176a6b7341d479dec441af04de24dc1e811307631432c3d459b4aaf31fbbf5272148e2b9cef6971aeb9f43e6703f129b2c9314d66236a4d7
+  data.tar.gz: b5216fd9da5ed299891069e10101af2598a3a68c36cdd31ef2b02b7d59e42be5a1d32dd596d8aaf963418c57e752718d44fa5167371362aa15b8c9f7a1c8fe07

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to `ficha` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),  
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- Refactored `Ficha::CLI#run` into smaller private methods to improve readability and comply with RuboCop metrics (ABC size, method length).
+
+### Fixed
+
+- Auto-corrected code style with RuboCop.
+
+### Internal
+
+- Added RuboCop linting to GitHub Actions CI.
+
+## [0.1.0] - 2025-12-09
+
+### Added
+
+- Initial CLI with `--help` flag and basic argument parsing.
+- Core `Engine` class for resolving and filtering project files based on strategies.
+- Support for `--dry-run` mode with end-to-end tests.
+- Config file loading mechanism.
+- Basic templating capabilities (foundation for future expansion).
+- End-to-end test suite with fixtures.
+
+### Internal
+
+- Improved test fixtures and added e2e test scaffolding.
+- Finalized `ficha.gemspec` for public release under AGPL-3.0.
+- Added LICENSE file (AGPL-3.0).
+- Initial `.gitignore` and gem scaffolding.
+
+### Changelog
+
+- This changelog was introduced retroactively to document project evolution from the first commit.

data/README.md

@@ -0,0 +1,204 @@
+# ficha
+
+> **Feature-aware file dumper for Ruby projects**  
+> Extract only the files you need — by model, endpoint, feature, or safe subset — without manual grepping.
+
+![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)
+![Ruby](https://img.shields.io/badge/ruby-3.0%2B-red)
+
+`ficha` helps you **dump relevant files** from large Ruby/Rails codebases based on **semantic strategies**, not just file extensions.  
+Think of it as `grep` + `find` + domain knowledge — for developers who know *what* they need, but not *where* it is.
+
+Perfect for:
+
+- Preparing minimal bug reproductions
+- Sharing feature context with teammates
+- Migrating subsystems
+- Auditing legacy code
+- Generating focused backups
+
+---
+
+## 🔍 Quick Example
+
+```sh
+# Dump all files related to the `User` model
+ficha by-model:User
+
+# Dump a "safe" subset (models, serializers, controllers, specs)
+ficha full-safe
+
+# Preview without writing
+ficha by-model:Order --dry-run
+```
+
+Output (dry-run):
+
+```
+app/models/user.rb
+app/controllers/users_controller.rb
+app/serializers/user_serializer.rb
+spec/models/user_spec.rb
+...
+```
+
+---
+
+## 🧩 Core Concepts
+
+`ficha` works by combining:
+
+1. **Strategies** — rules that define *what to include* (e.g. `by-model`, `full-safe`)
+2. **Config** — your project-specific paths, conventions, and overrides (`ficha.yml`)
+3. **Engine** — the resolver that applies strategies to your codebase
+4. **CLI** — your interface to run queries
+
+```mermaid
+graph LR
+  A[CLI: ficha by-model:User] --> B(Engine)
+  B --> C{Strategy: by-model}
+  B --> D[Config: ficha.yml]
+  C --> E[Match model, controller, serializer...]
+  D --> F[Custom paths, excludes]
+  E --> G[File list]
+  F --> G
+  G --> H[Output or copy]
+```
+
+---
+
+## 🚀 Installation
+
+Add to your project’s `Gemfile`:
+
+```ruby
+group :development do
+  gem "ficha", require: false
+end
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+> 💡 `ficha` is designed as a **dev-only CLI tool** — it doesn’t affect your runtime.
+
+---
+
+## ⚙️ Configuration
+
+By default, `ficha` looks for `config/ficha.yml` (in Rails) or `.ficha.yml` (in any project).
+
+### Example `config/ficha.yml`
+
+```yaml
+# ficha.yml — declarative, extensible, no Ruby code!
+
+strategies:
+  by-model:
+    include:
+      - "app/models/{{name}}.rb"
+      - "app/controllers/{{name.pluralize}}_controller.rb"
+      - "app/serializers/{{name}}_serializer.rb"
+      - "spec/models/{{name}}_spec.rb"
+      - "spec/requests/{{name.pluralize}}_spec.rb"
+    exclude:
+      - "app/models/concerns/*"
+
+  full-safe:
+    include:
+      - "app/models/**/*.rb"
+      - "app/controllers/**/*.rb"
+      - "app/serializers/**/*.rb"
+      - "spec/{models,controllers,serializers}/**/*.rb"
+    exclude:
+      - "spec/support/**/*"
+
+paths:
+  root: "."                 # project root
+  output: "/tmp/ficha-out"  # (future: where to copy files)
+
+excludes:
+  - "tmp/**/*"
+  - "log/**/*"
+  - "vendor/**/*"
+```
+
+> ✅ **Philosophy**: Keep logic in config, not code.  
+> 🔒 Config supports ERB if you *really* need dynamic values (but avoid it for reproducibility).
+
+---
+
+## 🎯 Built-in Strategies
+
+| Strategy      | Purpose |
+|---------------|--------|
+| `full-safe`   | Dumps core app code: models, controllers, serializers, related specs |
+| `by-model:X`  | Dumps everything related to model `X` (convention-based) |
+| *(more coming)* | — |
+
+You can **extend strategies** in your `ficha.yml` — no need to fork the gem.
+
+---
+
+## 🛠 CLI Usage
+
+```text
+ficha [STRATEGY:PARAMS...] [options]
+
+Examples:
+  ficha                     # runs 'full-safe'
+  ficha by-model:User       # model-aware dump
+  ficha full-safe --dry-run # preview only
+
+Options:
+  --help          Show help
+  --dry-run       Print matched files (default)
+  --exclude GLOB  Exclude additional paths (can be used multiple times)
+```
+
+> ⚠️ **Non-dry-run mode** (actual file copying) is **not implemented yet** — coming soon!  
+> You’ll be able to dump to a directory, zip, or tar.
+
+---
+
+## 🧪 Testing & Development
+
+```sh
+bundle exec rake          # runs tests + RuboCop
+bundle exec bin/ficha     # run from source
+```
+
+Tests use real fixtures in `test/fixtures/rails_app/` — easy to extend.
+
+---
+
+## 📜 License
+
+AGPL-3.0 — because **privacy, self-hosting, and user freedom matter**.
+
+You’re free to use `ficha` in any project, but if you modify and redistribute it (e.g. as a hosted service), you must share the source.
+
+---
+
+## 🙌 Contributing
+
+PRs welcome! Especially:
+
+- New strategies
+- Non-dry-run output formats (dir, zip, tar)
+- Better Rails/7+ support
+- Performance optimizations
+
+Please:
+
+- Write tests
+- Keep config declarative
+- Respect the AGPL spirit
+
+---
+
+> Made with 💎 by a Ruby dev who hates manual file hunting.  
+> Inspired by `rails:template`, `bundle gem`, and the pain of legacy monoliths.

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ficha"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/ficha

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# bin/ficha
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ficha/cli"
+
+Ficha::CLI.start(ARGV)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/ficha

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# exe/ficha
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ficha"
+
+Ficha::CLI.start(ARGV)

data/ficha.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/ficha/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "ficha"
+  spec.version       = Ficha::VERSION
+  spec.authors       = ["Ilmir Karimov"]
+  spec.email         = ["code.for.func@gmail.com"]
+
+  spec.summary       = "Feature-aware file dumper for Ruby projects"
+  spec.description = <<~DESCRIPTION
+    Extract only the files you need — by model, endpoint, feature, or safe subset —
+    without manual grepping.
+  DESCRIPTION
+  spec.homepage      = "https://github.com/ilmir/ficha"
+  spec.license       = "AGPL-3.0-or-later"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.files = Dir[
+    "lib/**/*",
+    "bin/*",
+    "README.md",
+    "LICENSE.txt",
+    "CHANGELOG.md",
+    "ficha.gemspec"
+  ].reject { |f| File.directory?(f) }
+
+  spec.bindir        = "exe"
+  spec.executables   = ["ficha"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 6.0", "< 9.0"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => "https://github.com/ilmir/ficha",
+    "changelog_uri" => "https://github.com/ilmir/ficha/blob/main/CHANGELOG.md",
+    "bug_tracker_uri" => "https://github.com/ilmir/ficha/issues",
+    "rubygems_mfa_required" => "true"
+  }
+end

data/lib/ficha/config.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ficha
+  class Config
+    DEFAULT_CONFIG_PATH = File.expand_path("../../data/base.ficha.yml", __dir__)
+
+    def self.load(config_path = nil)
+      config_path ||= find_config
+      if config_path && File.exist?(config_path)
+        raw = YAML.safe_load_file(config_path, aliases: true)
+        raw ||= {}
+      else
+        raw = YAML.safe_load_file(DEFAULT_CONFIG_PATH, aliases: true)
+      end
+      new(raw)
+    end
+
+    def initialize(data)
+      @data = data
+    end
+
+    def strategies
+      @data.fetch("strategies", {})
+    end
+
+    def defaults
+      @data.fetch("defaults", {})
+    end
+
+    def self.find_config
+      ["./.ficha.yml", "./ficha.yml"].find { |f| File.exist?(f) }
+    end
+  end
+end

data/lib/ficha/engine.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "template"
+require_relative "config"
+
+module Ficha
+  class Engine
+    SENSITIVE_PATTERNS = [
+      /\.env/,
+      /master\.key/,
+      /credentials\.yml\.enc/
+    ].freeze
+
+    def initialize(config:, queries:, overrides: {})
+      @config = config
+      @queries = queries
+      @overrides = overrides
+    end
+
+    def run
+      files = @queries.flat_map { |q| resolve_query(q) }
+      files = apply_filters(files)
+      files.uniq.sort
+    end
+
+    private
+
+    def resolve_query(query_str)
+      parsed = parse_query(query_str)
+      strategy_name = parsed[:name]
+      params = parsed[:params]
+
+      strategy = @config.strategies[strategy_name]
+      raise "strategy '#{strategy_name}' not found in .ficha.yml" unless strategy
+
+      param_hash = build_param_hash(strategy["params"] || [], params)
+
+      # Раскрываем include_paths через шаблоны и glob
+      strategy["include_paths"].flat_map do |pattern|
+        rendered = Template.render(pattern, param_hash)
+        Dir.glob(rendered)
+      end
+    end
+
+    def parse_query(query_str)
+      if query_str.include?(":")
+        parts = query_str.split(":", 2)
+        name = parts[0]
+        param_str = parts[1]
+        params = param_str.include?(",") ? param_str.split(",") : [param_str]
+        { name: name, params: params }
+      else
+        { name: query_str, params: [] }
+      end
+    end
+
+    def build_param_hash(expected_params, given_params)
+      expected_params.map(&:to_sym).zip(given_params).to_h
+    end
+
+    def apply_filters(files)
+      files = filter_by_sensitive_names(files)
+      files = filter_by_cli_excludes(files)
+      filter_by_ignored_extensions(files)
+    end
+
+    def filter_by_sensitive_names(files)
+      files.reject do |path|
+        SENSITIVE_PATTERNS.any? { |pat| path.match?(pat) }
+      end
+    end
+
+    def filter_by_cli_excludes(files)
+      excludes = @overrides[:exclude_paths] || []
+      files.reject do |path|
+        excludes.any? do |exclude_glob|
+          # Если glob не содержит *, **, ? — считаем, что это директория → добавляем /**
+          glob = exclude_glob.include?("*") || exclude_glob.include?("?") ? exclude_glob : "#{exclude_glob}/**/*"
+          File.fnmatch(glob, path, File::FNM_PATHNAME | File::FNM_DOTMATCH)
+        end
+      end
+    end
+
+    def filter_by_ignored_extensions(files)
+      ignored_exts = (@config.defaults["ignored_extensions"] || []).map(&:downcase)
+      files.reject do |path|
+        ext = File.extname(path).downcase
+        ignored_exts.include?(ext)
+      end
+    end
+  end
+end

data/lib/ficha/template.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "active_support/inflector"
+
+module Ficha
+  module Template
+    FILTERS = {
+      "underscore" => lambda(&:underscore),
+      "pluralize" => lambda(&:pluralize),
+      "singularize" => lambda(&:singularize),
+      "camelize" => lambda(&:camelize)
+    }.freeze
+
+    def self.render(template_str, bindings = {})
+      template_str.gsub(/\{\{\s*(.+?)\s*\}\}/) do
+        expr = ::Regexp.last_match(1)
+        apply_filters(expr.strip, bindings)
+      end
+    end
+
+    def self.apply_filters(expr, bindings)
+      parts = expr.split("|").map(&:strip)
+      var_name = parts.first
+      value = bindings[var_name.to_sym] || var_name
+      apply_pipeline(value, parts.drop(1))
+    end
+
+    def self.apply_pipeline(value, filters)
+      filters.reduce(value) do |acc, filter_name|
+        FILTERS.fetch(filter_name, ->(x) { x }).call(acc)
+      end
+    end
+  end
+end

data/lib/ficha/version.rb

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

data/lib/ficha.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "ficha/version"
+require_relative "ficha/config"
+require_relative "ficha/template"
+require_relative "ficha/engine"
+require "optparse"
+
+module Ficha
+  class CLI
+    def self.start(argv)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv = argv
+      @options = { dry_run: false }
+      @queries = []
+    end
+
+    def run
+      parse!
+
+      handle_help! if @options[:help]
+      ensure_default_query!
+
+      files = execute_engine
+      process_files(files)
+    rescue StandardError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    private
+
+    def handle_help!
+      puts help_text
+      exit 0
+    end
+
+    def ensure_default_query!
+      @queries << "full-safe" if @queries.empty?
+    end
+
+    def process_files(files)
+      if @options[:dry_run]
+        files.each { |f| puts f }
+      else
+        warn "Non-dry-run mode not implemented yet"
+        exit 1
+      end
+    end
+
+    def execute_engine
+      config = Config.load
+      engine = Engine.new(
+        config: config,
+        queries: @queries,
+        overrides: {
+          exclude_paths: @options[:exclude_paths],
+          dry_run: @options[:dry_run]
+        }
+      )
+      engine.run
+    end
+
+    def parse!
+      @options[:exclude_paths] = []
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: ficha [STRATEGY:PARAMS...] [options]"
+        opts.on("--help", "Show this help") { @options[:help] = true }
+        opts.on("--dry-run", "Show files without copying") { @options[:dry_run] = true }
+        opts.on("--exclude PATTERN", "Exclude paths matching glob pattern") do |pattern|
+          @options[:exclude_paths] << pattern
+        end
+      end.parse!(@argv)
+
+      @queries = @argv.dup
+    end
+
+    def help_text
+      <<~HELP
+        ficha — feature-aware file dumper for Ruby projects
+
+        Usage:
+          ficha [STRATEGY:PARAMS...] [options]
+
+        Examples:
+          ficha                     # full-safe dump
+          ficha by-model:User       # dump User-related files
+          ficha full-safe --dry-run
+
+        Options:
+      HELP
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: ficha
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ilmir Karimov
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: |
+  Extract only the files you need — by model, endpoint, feature, or safe subset —
+  without manual grepping.
+email:
+- code.for.func@gmail.com
+executables:
+- ficha
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- bin/console
+- bin/ficha
+- bin/setup
+- exe/ficha
+- ficha.gemspec
+- lib/ficha.rb
+- lib/ficha/config.rb
+- lib/ficha/engine.rb
+- lib/ficha/template.rb
+- lib/ficha/version.rb
+homepage: https://github.com/ilmir/ficha
+licenses:
+- AGPL-3.0-or-later
+metadata:
+  homepage_uri: https://github.com/ilmir/ficha
+  source_code_uri: https://github.com/ilmir/ficha
+  changelog_uri: https://github.com/ilmir/ficha/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ilmir/ficha/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Feature-aware file dumper for Ruby projects
+test_files: []