develoz-rails 0.1.0

data/lib/generators/develoz/agents_docs/agents_docs_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "develoz"
+
+module Develoz
+  module Generators
+    class AgentsDocsGenerator < Develoz::Generators::Base
+      def self.source_root
+        File.expand_path("templates", __dir__)
+      end
+
+      def add_api_gems
+        add_gem "faraday"
+        add_gem "faraday-retry"
+        add_gem "vcr", group: %i[test]
+        add_gem "webmock", group: %i[test]
+      end
+
+      def create_agents_md
+        template "AGENTS.md.tt", "AGENTS.md"
+      end
+
+      def create_docs
+        template "docs/development.md.tt", "docs/development.md"
+        template "docs/testing.md.tt", "docs/testing.md"
+        template "docs/performance.md.tt", "docs/performance.md"
+      end
+
+      def create_pr_template
+        template ".github/pull_request_template.md.tt",
+                 ".github/pull_request_template.md"
+      end
+
+      def create_vcr_support
+        template "spec/support/vcr.rb.tt", "spec/support/vcr.rb"
+      end
+
+      def create_faraday_support
+        template "spec/support/faraday.rb.tt", "spec/support/faraday.rb"
+      end
+
+      def create_example_api_spec
+        template "spec/requests/example_api_spec.rb.tt",
+                 "spec/requests/example_api_spec.rb"
+        template "spec/cassettes/Example_API/fetches_data_from_an_external_API.yml.tt",
+                 "spec/cassettes/Example_API/fetches_data_from_an_external_API.yml"
+      end
+    end
+  end
+end

data/lib/generators/develoz/agents_docs/templates/.github/pull_request_template.md.tt

@@ -0,0 +1,13 @@
+> [!NOTE]
+> **Changes:** <!-- Describe what has been changed in this PR and, most importantly, why it's changed. Use 3-5 bullet points. -->
+>
+
+> [!TIP]
+> **How to review:** <!-- Describe what the reviewer of this PR should be looking for and what results are expected. -->
+>
+
+> [!WARNING]
+> **Risks:** <!-- Is there any risk attached to merging this PR? Select the appropriate box. -->
+> - [x] none
+> - [ ] low
+> - [ ] high

data/lib/generators/develoz/agents_docs/templates/AGENTS.md.tt

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+This file gives high-level guidance for coding agents working in this repository.
+
+## Development Environment
+
+- Development is Docker-first and uses `docker compose`.
+- Run project commands through `bin/rails` or `bundle exec` as appropriate.
+- For one-off Ruby or Rails runner scripts, prefer checked-in temp files under `tmp/` plus `bin/rails runner tmp/script.rb`.
+- Avoid inline `bin/rails runner "..."` snippets when possible; shell quoting can be fragile.
+- Discover available commands with `bin/rails --help` and `bin/rails runner --help`.
+
+```bash
+bundle exec rspec              # run specs (single process)
+bundle exec rake spec:parallel # run specs in parallel (faster, use for full suite)
+bundle exec rubocop
+bin/rails db:migrate
+```
+
+## Documentation-First Policy
+
+To avoid filling agent context, keep this file brief and reference detailed docs.
+
+- [docs/development.md](docs/development.md)
+- [docs/testing.md](docs/testing.md)
+- [docs/performance.md](docs/performance.md)
+
+## Quality Expectations
+
+- Add or update specs for every behavior change.
+- 100% line and 100% branch coverage is required. Review `coverage/index.html` after running specs.
+- In tests, stub real git commands and filesystem side effects instead of creating real repos or mutating files on disk, unless a true integration path explicitly requires it.
+- Tests must never spawn real external CLI processes. Global stubs in `spec/support/` block these by default — see [docs/testing.md](docs/testing.md) for details.
+- Run relevant checks before finishing work.
+- Keep changes small, explicit, and aligned with existing patterns.
+- Update the relevant document in [docs/](docs/) when behavior changes.

data/lib/generators/develoz/agents_docs/templates/docs/development.md.tt

@@ -0,0 +1,121 @@
+# Development Guide
+
+This guide covers day-to-day local development.
+
+## Core Rules
+
+- Use Docker-first workflows (`docker compose`).
+- Run project commands through `bin/rails` or `bundle exec`.
+
+## Boot Local Environment
+
+```bash
+cp .env.example .env
+docker compose up --build -d app
+bin/rails db:migrate
+bin/rails db:seed
+```
+
+Useful lifecycle commands:
+
+```bash
+docker compose logs -f app
+docker compose down
+```
+
+## Command Reference
+
+### Tests
+
+```bash
+bundle exec rspec
+bundle exec rspec spec/system/
+bundle exec rspec spec/requests/
+bundle exec rspec spec/models/
+bundle exec rspec spec/system/tickets_spec.rb:25
+bundle exec rspec --only-failures
+bundle exec rspec --next-failure
+```
+
+### Lint and Security
+
+```bash
+bundle exec rubocop
+bundle exec rubocop -A
+bundle exec brakeman
+```
+
+### Rails and DB
+
+```bash
+bin/rails db:migrate
+bin/rails db:seed
+bin/rails console
+bin/rails console --sandbox
+bin/rails runner --help
+RAILS_ENV=test bin/rails console
+```
+
+### Runner Scripts and One-Offs
+
+- Prefer checked-in scripts under `tmp/` for one-off investigation, data fixes, and runner tasks.
+- If you need Rails loaded, either require the environment from a Ruby script or pass a script file to Rails runner.
+
+Recommended patterns:
+
+```bash
+# Plain Ruby with the Rails environment loaded manually
+ruby tmp/my_script.rb
+
+# Rails runner with a script file
+bin/rails runner tmp/my_runner.rb
+
+# Discover runner usage and available flags
+bin/rails runner --help
+bin/rails --help
+```
+
+Example `tmp/my_script.rb`:
+
+```ruby
+require './config/environment'
+
+record = Record.find_by(name: 'example')
+pp(record&.attributes&.slice('name', 'status'))
+```
+
+Use inline runner snippets only when the command is trivial and shell quoting is not a risk.
+
+### Frontend Assets
+
+```bash
+bin/rails tailwindcss:build
+bin/rails tailwindcss:watch
+```
+
+## Recommended Change Workflow
+
+1. Add or update tests first.
+2. Implement in small, reviewable steps.
+3. Run targeted tests while iterating.
+4. Run full checks before finishing:
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+bundle exec brakeman
+```
+
+5. Update the matching document in this folder when behavior changes.
+
+## Troubleshooting
+
+- Docker unavailable: start Docker and rerun commands.
+- Migration issues: run `bin/rails db:migrate:status`.
+- App startup issues: check `docker compose logs -f app postgres redis`.
+- Stale test schema/data: rerun `bin/rails db:migrate` and `bundle exec rspec`.
+
+## Related Docs
+
+- [docs/testing.md](testing.md)
+- [docs/performance.md](performance.md)

data/lib/generators/develoz/agents_docs/templates/docs/performance.md.tt

@@ -0,0 +1,46 @@
+# Performance Guide
+
+This document summarizes current query-performance practices and optimizations.
+
+## N+1 Detection in Development
+
+- `config/environments/development.rb` enables strict-loading N+1 checks.
+- `verbose_query_logs = true` helps trace query origin quickly.
+- Goal: fail in development when lazy-loading patterns introduce N+1 behavior.
+
+## Query Patterns to Prefer
+
+- Use `includes` when iterating associated records.
+- Use DB predicates (`where`) instead of Ruby filtering.
+- Use `pluck` when only IDs or specific columns are needed.
+- Use `find_each` for large batch processing.
+- Use `select` to limit columns on read-heavy paths.
+
+## Index Strategy
+
+- Add indexes for columns used in `where`, `order`, and `join` clauses.
+- Use partial indexes for boolean conditions that filter most rows.
+- Use composite indexes for multi-column query patterns.
+- Review `pg_stat_user_indexes` to identify unused indexes.
+
+## Verification Queries
+
+```sql
+SELECT schemaname, relname, indexrelname, idx_scan, idx_tup_read
+FROM pg_stat_user_indexes
+ORDER BY idx_scan DESC;
+
+EXPLAIN ANALYZE SELECT * FROM records WHERE status = 'active';
+```
+
+## Caching
+
+- Use `Rails.cache` for expensive computations and external API metadata.
+- Scope cache keys per resource to prevent cross-project data leaks.
+- Set TTLs short enough to avoid stale data and long enough to keep UI fast.
+- Invalidate caches when underlying data changes.
+
+## Related Docs
+
+- [docs/development.md](development.md)
+- [docs/testing.md](testing.md)

data/lib/generators/develoz/agents_docs/templates/docs/testing.md.tt

@@ -0,0 +1,92 @@
+# Testing Guide
+
+This guide documents how to run and write tests.
+
+## Test Stack
+
+- RSpec
+- Capybara (system specs)
+- FactoryBot and Faker
+- SimpleCov (line and branch thresholds)
+- WebMock and VCR (`spec/cassettes/`)
+
+## Run Tests
+
+```bash
+bundle exec rake spec:parallel       # full suite in parallel (fastest)
+bundle exec rspec                    # full suite single process
+
+bundle exec rspec spec/system/
+bundle exec rspec spec/requests/
+bundle exec rspec spec/models/
+bundle exec rspec spec/services/
+
+bundle exec rspec spec/system/tickets_spec.rb
+bundle exec rspec spec/system/tickets_spec.rb:25
+
+bundle exec rspec --only-failures
+bundle exec rspec --next-failure
+bundle exec rspec --format documentation
+bundle exec rspec --profile 10
+```
+
+## Coverage Requirement (Mandatory)
+
+100% line and 100% branch coverage is required. This is enforced by SimpleCov in `spec/spec_helper.rb`.
+
+```bash
+bundle exec rspec
+```
+
+Then review `coverage/index.html` for any uncovered lines or branches.
+
+```bash
+xdg-open coverage/index.html  # Linux
+open coverage/index.html      # macOS
+```
+
+## What to Test
+
+- `spec/system/` for user-facing workflows
+- `spec/requests/` for endpoint behavior
+- `spec/models/` for model behavior and validations
+- `spec/services/` and `spec/lib/` for workflow/domain logic
+
+Prefer request and system specs over controller specs.
+
+## Testing Conventions
+
+- Test behavior, not internal implementation.
+- Use descriptive example names.
+- Use FactoryBot (`create`, `build`) for test data.
+- Use `aggregate_failures` for grouped UI assertions when useful.
+- Stub external systems only when necessary.
+- Stub real git commands and filesystem side effects in tests. Do not create real git repos, shell out to git, or write temporary fixture files just to exercise parsing or state handling when a stubbed command/service response covers the behavior.
+- If a test truly needs filesystem or git integration, keep it explicit about why the integration boundary matters.
+
+## External API Tests
+
+- Use `:vcr` for external calls.
+- Keep cassettes in `spec/cassettes/`.
+- Avoid storing secrets in cassette data.
+- Refresh stale cassettes when upstream API behavior changes.
+
+## Validation Before PR
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+bundle exec brakeman
+```
+
+## Troubleshooting
+
+- Migration mismatch: `bin/rails db:migrate`.
+- Coverage below threshold: inspect `coverage/index.html` and add missing specs.
+- JS/system issues: verify Selenium is up with `docker compose ps`.
+- VCR mismatch: refresh cassette and rerun the failing spec.
+
+## Related Docs
+
+- [docs/development.md](development.md)
+- [docs/performance.md](performance.md)

data/lib/generators/develoz/agents_docs/templates/spec/cassettes/Example_API/fetches_data_from_an_external_API.yml.tt

@@ -0,0 +1,23 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://api.example.com/data
+    body:
+      encoding: US-ASCII
+      string: ""
+    headers:
+      User-Agent:
+      - Faraday
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Content-Type:
+      - application/json
+    body:
+      encoding: UTF-8
+      string: '{"status":"ok"}'
+  recorded_at: Mon, 01 Jan 2024 00:00:00 GMT
+recorded_with: VCR

data/lib/generators/develoz/agents_docs/templates/spec/requests/example_api_spec.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require "support/faraday"
+
+RSpec.describe "Example API", :vcr do
+  it "fetches data from an external API" do
+    # VCR cassette: spec/cassettes/Example_API/fetches_data_from_an_external_API.yml
+    # This example demonstrates the VCR + Faraday pattern.
+    # Record a real cassette by running this spec once with VCR record mode enabled.
+    response = FaradayFactory.build(url: "https://api.example.com").get("/data")
+    expect(response.status).to eq(200)
+  end
+end

data/lib/generators/develoz/agents_docs/templates/spec/support/faraday.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+
+module FaradayFactory
+  def self.build(url: nil)
+    Faraday.new(url: url) do |conn|
+      conn.request :retry, {
+        max: 3,
+        interval: 0.5,
+        backoff_factor: 2
+      }
+      conn.request :json
+      conn.response :json
+      conn.adapter Faraday.default_adapter
+    end
+  end
+end

data/lib/generators/develoz/agents_docs/templates/spec/support/vcr.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "vcr"
+require "webmock"
+
+VCR.configure do |config|
+  config.cassette_library_dir = "spec/cassettes"
+  config.hook_into :webmock
+  config.configure_rspec_metadata!
+  config.ignore_localhost = true
+end

data/lib/generators/develoz/api/api_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "develoz"
+
+module Develoz
+  module Generators
+    class ApiGenerator < Develoz::Generators::Base
+      def self.source_root
+        File.expand_path("templates", __dir__)
+      end
+
+      def add_api_gems
+        add_gem "blueprinter"
+        add_gem "rswag-api"
+        add_gem "rswag-ui"
+        add_gem "rswag-specs", group: %i[test]
+      end
+
+      def create_base_controller
+        template "app/controllers/api/v1/base_controller.rb.tt",
+                 "app/controllers/api/v1/base_controller.rb"
+      end
+
+      def create_blueprinter_initializer
+        template "config/initializers/blueprinter.rb.tt",
+                 "config/initializers/blueprinter.rb"
+      end
+
+      def create_example_blueprint
+        template "app/blueprints/example_blueprint.rb.tt",
+                 "app/blueprints/example_blueprint.rb"
+      end
+
+      def create_rswag_api_initializer
+        template "config/initializers/rswag_api.rb.tt",
+                 "config/initializers/rswag_api.rb"
+      end
+
+      def create_rswag_ui_initializer
+        template "config/initializers/rswag_ui.rb.tt",
+                 "config/initializers/rswag_ui.rb"
+      end
+
+      def insert_rswag_routes
+        insert_route "mount Rswag::Ui::Engine => '/api-docs'"
+        insert_route "mount Rswag::Api::Engine => '/api-docs'"
+      end
+
+      def create_example_request_spec
+        template "spec/requests/api/v1/examples_spec.rb.tt",
+                 "spec/requests/api/v1/examples_spec.rb"
+      end
+    end
+  end
+end

data/lib/generators/develoz/api/templates/app/blueprints/example_blueprint.rb.tt

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class ExampleBlueprint < Blueprinter::Base
+  identifier :id
+  fields :name, :created_at, :updated_at
+end

data/lib/generators/develoz/api/templates/app/controllers/api/v1/base_controller.rb.tt

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    class BaseController < ApplicationController
+      include Pagy::Backend
+
+      skip_forgery_protection
+      before_action :authenticate
+
+      rescue_from ActiveRecord::RecordNotFound do |e|
+        render_json_error(:not_found, e.message)
+      end
+
+      rescue_from ActiveRecord::RecordInvalid do |e|
+        render_json_error(:unprocessable_content, e.message)
+      end
+
+      def self.default_page_size(size = nil)
+        @default_page_size = size if size
+        @default_page_size || 20
+      end
+
+      delegate :default_page_size, to: :class
+
+      private
+
+      # Override in subclasses to implement authentication
+      # (e.g. Cognito, Devise, API token). The default stub allows
+      # all requests through so the API is usable out of the box.
+      def authenticate; end
+
+      def render_json_error(status, message, extra = {})
+        status = Rack::Utils::SYMBOL_TO_STATUS_CODE[status] if status.is_a?(Symbol)
+
+        error = { detail: message, status: }.merge(extra)
+
+        render json: { error: }, status:
+      end
+
+      def render_resource(resource, options = {})
+        if (pagination_options = Array(options[:paginate])).present?
+          resource = resource.limit(limit) if pagination_options.include?(:force_limit) && common_params[:page].blank?
+          pager = :arel if pagination_options.include?(:arel) || common_params[:countless] == "false"
+          pager ||= :countless
+          resource = paginated(resource, force: pagination_options.include?(:force), pager:)
+        end
+
+        options = { meta:, view: }.merge(options).compact
+
+        render json: render_json(resource, options)
+      end
+      alias render_resources render_resource
+
+      def render_json(resource, options = {})
+        return resource.serialize_as_json(options) if resource.respond_to?(:serialize_as_json)
+
+        return options[:blueprint].render(resource, options) if options[:blueprint].present?
+
+        Rails.logger.warn "Couldn't find blueprint for #{resource}, falling back to ruby JSON serializer."
+        resource.to_json
+      end
+
+      def view
+        common_params[:view]&.to_sym
+      end
+
+      def paginated(resources, force: false, pager: :arel)
+        return resources unless common_params[:page].present? || force
+
+        @pagy, resources = send(["pagy", pager].join("_"), resources, limit:, countless_minimal: true)
+        resources
+      end
+
+      def limit
+        common_params[:limit].presence || default_page_size
+      end
+
+      def meta
+        meta = common_params.to_h.compact
+
+        if @pagy
+          meta[:recordCount] = @pagy.count
+          meta[:pageCount] = @pagy.pages
+          meta[:countless] = @pagy.is_a?(Pagy::Countless)
+        end
+
+        meta
+      end
+
+      def common_params
+        params.permit(:filter, :page, :limit, :sort, :view, :countless)
+      end
+    end
+  end
+end

data/lib/generators/develoz/api/templates/config/initializers/blueprinter.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class LowerCamelTransformer < Blueprinter::Transformer
+  def transform_key(key)
+    key.to_s.camelize(:lower)
+  end
+
+  def transform(hash, _object = nil, _options = nil)
+    hash.deep_transform_keys! { |key| transform_key(key).to_sym }
+  end
+end
+
+Blueprinter.configure do |config|
+  config.default_transformers = [LowerCamelTransformer]
+  config.datetime_format = ->(datetime) { datetime&.to_fs(:api) }
+end

data/lib/generators/develoz/api/templates/config/initializers/rswag_api.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Rswag::Api.configure do |c|
+  # Specify a root folder where Swagger JSON files are located
+  # This is used by the Swagger middleware to serve requests for API descriptions
+  # NOTE: If you're using rswag-specs to generate Swagger, you'll need to ensure
+  # that it's configured to generate files in the same folder
+  c.openapi_root = Rails.root.join('swagger')
+
+  # Inject a lambda function to alter the returned Swagger prior to serialization
+  # The function will have access to the rack env for the current request
+  # For example, you could leverage this to dynamically assign the "host" property
+  #
+  # c.swagger_filter = lambda { |swagger, env| swagger['host'] = env['HTTP_HOST'] }
+end

data/lib/generators/develoz/api/templates/config/initializers/rswag_ui.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Rswag::Ui.configure do |c|
+  # List the Swagger endpoints that you want to be documented through the
+  # swagger-ui. The first parameter is the path (absolute or relative to the UI
+  # host) to the corresponding endpoint and the second is a title that will be
+  # displayed in the document selector.
+  # NOTE: If you're using rspec-api to expose Swagger files
+  # (under openapi_root) as JSON or YAML endpoints, then the list below should
+  # correspond to the relative paths for those endpoints.
+
+  c.openapi_endpoint '/api-docs/v1/swagger.yaml', 'API V1'
+
+  # Add Basic Auth in case your API is private
+  # c.basic_auth_enabled = true
+  # c.basic_auth_credentials 'username', 'password'
+end

data/lib/generators/develoz/api/templates/spec/requests/api/v1/examples_spec.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Examples', type: :request do
+  path '/api/v1/examples' do
+    get 'Lists examples' do
+      tags 'Examples'
+      produces 'application/json'
+      description 'Returns a paginated list of examples'
+
+      response '200', 'successfully' do
+        schema type: :object,
+               properties: {
+                 examples: { type: :array, items: { type: :object } },
+                 meta: { type: :object }
+               }
+
+        run_test! do
+          expect(response).to have_http_status(:ok)
+        end
+      end
+    end
+  end
+end