lex-codegen 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 410e07dba313fed006a63a77643c2cdf1e03dbe41c17f895725ceb710f10f8fb
+  data.tar.gz: 45a9d37de9308cdfc113b3b83d0bd222b1f5879198d01fd8b8b152fbfafa83e0
+SHA512:
+  metadata.gz: f57fbf2f6f9f899ee3cadf673ba72f5c47b58de1ad789a560aa1aaca9dedc314d9d5991f9af795ea58075c38ed6b9dc135df6ada5677de35dcd2c0add19a8972
+  data.tar.gz: 63a20b03008b9e1442b44170725615a3757222816c9ed983d33d88e6106c8a36c1d7ae3903a55e2588afaa3d1f0a5422ce19c274830843dfca4744b5bd1a273d

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,62 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [0.1.0] - 2026-03-13
+
+### Added
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,209 @@
+# lex-codegen: Code Generation Engine for LegionIO
+
+**Repository Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-core/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Legion Extension that provides code generation for LegionIO extensions. Scaffolds complete new LEX gems from scratch, renders individual ERB templates, validates existing extension structure and configuration, and generates companion RSpec files. Used by the `legion lex create` CLI command and by agentic swarm pipelines that construct new extensions programmatically.
+
+**GitHub**: https://github.com/LegionIO/lex-codegen
+**License**: MIT
+**Version**: 0.1.0
+
+## Architecture
+
+```
+Legion::Extensions::Codegen
+├── Runners/
+│   ├── Generate       # Scaffold entire extension trees; generate individual files
+│   ├── Template       # List templates, render a template, inspect required variables
+│   └── Validate       # Check extension directory structure, rubocop config, gemspec fields
+├── Helpers/
+│   ├── Constants      # All ERB template strings + defaults (author, version, ruby, license)
+│   ├── TemplateEngine # ERB renderer; isolates each render into a fresh binding
+│   ├── SpecGenerator  # Builds RSpec source strings for runners, clients, helpers
+│   └── FileWriter     # Writes rendered content to disk, creates directories as needed
+└── Client             # Thin wrapper; includes all three runner modules
+```
+
+No explicit actors directory. The framework auto-generates subscription actors for each runner.
+
+## Gem Info
+
+| Field | Value |
+|-------|-------|
+| Gem name | `lex-codegen` |
+| Module | `Legion::Extensions::Codegen` |
+| Version | `0.1.0` |
+| Ruby | `>= 3.4` |
+| Runtime dep | `erb` (stdlib, declared explicitly) |
+
+## File Structure
+
+```
+lex-codegen/
+├── lex-codegen.gemspec
+├── Gemfile
+├── lib/
+│   └── legion/
+│       └── extensions/
+│           ├── codegen.rb                        # Entry point; requires all helpers/runners/client
+│           └── codegen/
+│               ├── version.rb
+│               ├── client.rb                     # Client class; includes all three runner modules
+│               ├── helpers/
+│               │   ├── constants.rb              # TEMPLATE_MAP, TEMPLATE_TYPES, all ERB strings
+│               │   ├── template_engine.rb        # TemplateEngine class (ERB renderer)
+│               │   ├── spec_generator.rb         # SpecGenerator class (RSpec source builder)
+│               │   └── file_writer.rb            # FileWriter class (disk writer)
+│               └── runners/
+│                   ├── generate.rb               # scaffold_extension, generate_file
+│                   ├── template.rb               # list_templates, render_template, template_variables
+│                   └── validate.rb               # validate_structure, validate_rubocop_config, validate_gemspec
+└── spec/
+```
+
+## Key Constants
+
+Defined in `Helpers::Constants`:
+
+| Constant | Value |
+|----------|-------|
+| `TEMPLATE_TYPES` | `[:gemspec, :gemfile, :rubocop, :ci, :rspec, :gitignore, :license, :version, :entry_point, :spec_helper, :runner, :client]` |
+| `DEFAULT_RUBY_VERSION` | `'3.4'` |
+| `DEFAULT_LICENSE` | `'MIT'` |
+| `DEFAULT_AUTHOR` | `'Esity'` |
+| `DEFAULT_EMAIL` | `'matthewdiverson@gmail.com'` |
+| `DEFAULT_GEM_VERSION` | `'0.1.0'` |
+| `TEMPLATE_MAP` | Hash mapping each symbol in `TEMPLATE_TYPES` to its ERB string |
+
+Defined in `Runners::Template`:
+
+| Constant | Value |
+|----------|-------|
+| `TEMPLATE_REQUIRED_VARS` | Hash mapping each template type to its required variable keys |
+
+Defined in `Runners::Validate`:
+
+| Constant | Value |
+|----------|-------|
+| `REQUIRED_FILES` | `['Gemfile', '.rubocop.yml', 'spec/spec_helper.rb']` |
+| `REQUIRED_RUBOCOP_KEYS` | `['AllCops', 'Layout/LineLength', 'Metrics/MethodLength', 'Style/FrozenStringLiteralComment']` |
+| `REQUIRED_GEMSPEC_FIELDS` | `['name', 'version', 'authors', 'email', 'summary', 'description', 'homepage', 'license']` |
+
+## Runners
+
+### Generate (`Runners::Generate`)
+
+`extend self` — all methods callable on the module directly.
+
+**`scaffold_extension(name:, module_name:, description:, category: :cognition, helpers: [], runner_methods: [], base_path: nil, **)`**
+- Creates a complete extension directory tree at `<base_path>/lex-<name>/`
+- Writes: gemspec, Gemfile, .rubocop.yml, .github/workflows/ci.yml, .rspec, .gitignore, LICENSE, version.rb, entry point, spec_helper, client, one file per helper, one runner file + one runner spec per `runner_methods` entry, client_spec
+- `helpers` accepts either plain strings (helper name) or hashes `{ name:, methods: [] }`
+- `runner_methods` accepts hashes with `:name` and `:params` keys; each becomes one runner module and one spec file
+- Returns `{ success: true, path:, files_created:, name: }` or `{ success: false, error: }`
+
+**`generate_file(template_type:, output_path:, variables: {}, **)`**
+- Renders a single named template and writes it to `output_path`
+- Creates parent directories via `FileUtils.mkdir_p`
+- Returns `{ success: true, path:, bytes: }` or `{ success: false, error: }`
+
+### Template (`Runners::Template`)
+
+`extend self` — all methods callable on the module directly.
+
+**`list_templates(**)`**
+- Returns `{ success: true, templates: <array of 12 template type symbols> }`
+
+**`render_template(template_type:, variables: {}, **)`**
+- Renders the named template with provided variables
+- Returns `{ success: true, content:, template_type: }` or `{ success: false, error: }`
+
+**`template_variables(template_type:, **)`**
+- Returns the list of required variable keys for the given template type
+- Returns `{ success: true, template_type:, required_variables: [] }` or `{ success: false, error: }`
+
+### Validate (`Runners::Validate`)
+
+`extend self` — all methods callable on the module directly.
+
+**`validate_structure(path:, **)`**
+- Checks for required files: Gemfile, .rubocop.yml, spec/spec_helper.rb, *.gemspec, lib entry point, version.rb
+- Returns `{ valid:, missing: [], present: [] }` or adds `:error` key on ArgumentError
+
+**`validate_rubocop_config(path:, **)`**
+- Parses `.rubocop.yml` and checks for required top-level keys
+- Verifies `AllCops/TargetRubyVersion` equals `DEFAULT_RUBY_VERSION` (`'3.4'`)
+- Returns `{ valid:, issues: [] }`
+
+**`validate_gemspec(path:, **)`**
+- Reads the `*.gemspec` file and checks for required field names via string inclusion
+- Also checks for `rubygems_mfa_required` metadata and `required_ruby_version`
+- Returns `{ valid:, issues: [], path: }`
+
+## Helpers
+
+### TemplateEngine
+
+Class. No persistent state.
+
+**`render(template_type, variables = {})`**
+- Looks up `TEMPLATE_MAP[template_type.to_sym]`, raises `ArgumentError` on unknown type
+- Delegates to `render_string`
+
+**`render_string(template_string, variables = {})`**
+- Renders an arbitrary ERB string with `trim_mode: '-'`
+- Each variable becomes a method on a fresh `Object` context — no shared state between renders
+
+### SpecGenerator
+
+Class. No persistent state.
+
+**`generate_runner_spec(module_name:, runner_name:, methods: [])`**
+- Returns RSpec source as a string; one `describe` block per method, tests `respond_to` and `{ success: }` key presence
+
+**`generate_client_spec(module_name:, runner_name: nil, methods: [])`**
+- Returns RSpec source as a string; tests `instantiates successfully` and `responds_to` each method
+
+**`generate_helper_spec(module_name:, helper_name:, methods: [])`**
+- Returns RSpec source as a string; tests instantiation and `responds_to` each method
+
+### FileWriter
+
+Class. Initialized with `base_path:`.
+
+**`write(relative_path, content)`**
+- Resolves `File.join(@base_path, relative_path)`, creates parent directories, writes content
+- Returns `{ path:, bytes: }`
+
+**`write_all(files)`**
+- Accepts a hash of `{ relative_path => content }` and calls `write` for each
+- Returns array of `{ path:, bytes: }` results
+
+## Integration Points
+
+- **`legion lex create`** CLI command calls `scaffold_extension` to bootstrap new extension repos
+- **`lex-swarm-github`** swarm pipeline uses codegen to produce runner and spec files during automated extension construction
+- **`lex-exec`** is the natural companion: codegen produces the files, exec runs `bundle install` and `bundle exec rspec` against the output
+
+## Development Notes
+
+- All runners use `extend self`; methods are callable on the module directly without instantiation
+- The `Client` class includes all three runner modules, making all runner methods available on a `Client.new` instance
+- `TemplateEngine#binding_with` creates a fresh `Object` subcontext for each render; variable names become singleton methods, not local variables — ERB must reference them without `@` prefix
+- `scaffold_extension` accepts `category:` but does not use it (marked with `Lint/UnusedMethodArgument`); present for future routing support
+- `generate_client_spec` accepts `runner_name:` but does not use it (same reason)
+- Validate methods check file existence by string inclusion on file content, not by loading/evaluating the gemspec
+
+```bash
+bundle install
+bundle exec rspec     # 82 examples, 0 failures
+bundle exec rubocop   # 0 offenses
+```
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec', '~> 3.13'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec'
+  gem 'simplecov'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Matthew Iverson
+
+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,173 @@
+# lex-codegen
+
+Code generation engine for LegionIO extensions. Scaffolds complete `lex-*` gem trees from scratch, renders individual ERB templates, validates existing extension structure, and generates companion RSpec files. Used by the `legion lex create` CLI command and by agentic swarm pipelines.
+
+## Installation
+
+Add to your Gemfile or gemspec:
+
+```ruby
+gem 'lex-codegen'
+```
+
+Or install directly:
+
+```bash
+gem install lex-codegen
+```
+
+## Usage
+
+### Scaffold a complete extension
+
+```ruby
+require 'legion/extensions/codegen'
+
+client = Legion::Extensions::Codegen::Client.new(base_path: '/path/to/output')
+
+result = client.scaffold_extension(
+  name:        'myextension',
+  module_name: 'Myextension',
+  description: 'Does something useful',
+  helpers:     ['config'],
+  runner_methods: [
+    { name: 'run_job', params: ['job_id:'] },
+    { name: 'check_status', params: ['job_id:', 'verbose: false'] }
+  ]
+)
+
+result[:success]        # => true
+result[:path]           # => '/path/to/output/lex-myextension'
+result[:files_created]  # => 15
+```
+
+This writes a fully structured gem including gemspec, Gemfile, .rubocop.yml, GitHub Actions CI workflow, .rspec, .gitignore, LICENSE, version.rb, entry point, client, helpers, runners, and RSpec files for all of the above.
+
+### Generate a single file
+
+```ruby
+result = client.generate_file(
+  template_type: :runner,
+  output_path:   '/tmp/myrunner.rb',
+  variables: {
+    module_name:          'Myextension',
+    gem_name_underscored: 'myextension',
+    runner_class:         'RunJob',
+    methods: [{ name: 'run_job', params: ['job_id:'] }]
+  }
+)
+
+result[:bytes]  # => number of bytes written
+```
+
+### Render a template to a string (without writing to disk)
+
+```ruby
+runner = Legion::Extensions::Codegen::Runners::Template
+
+content = runner.render_template(
+  template_type: :version,
+  variables: { module_name: 'Myextension', gem_version: '0.1.0' }
+)
+
+puts content[:content]
+# frozen_string_literal: true
+# module Legion::Extensions::Myextension; VERSION = '0.1.0'; end
+```
+
+### List available templates
+
+```ruby
+runner.list_templates
+# => { success: true, templates: [:gemspec, :gemfile, :rubocop, :ci, :rspec, :gitignore,
+#                                  :license, :version, :entry_point, :spec_helper, :runner, :client] }
+```
+
+### Inspect required variables for a template
+
+```ruby
+runner.template_variables(template_type: :gemspec)
+# => { success: true, template_type: :gemspec,
+#      required_variables: [:gem_name, :module_name, :description, :author, :email,
+#                           :ruby_version, :license, :extra_deps] }
+```
+
+### Validate an existing extension
+
+```ruby
+validator = Legion::Extensions::Codegen::Runners::Validate
+
+# Check directory structure
+validator.validate_structure(path: '/path/to/lex-myextension')
+# => { valid: true, missing: [], present: ['Gemfile', '.rubocop.yml', ...] }
+
+# Check rubocop config
+validator.validate_rubocop_config(path: '/path/to/lex-myextension')
+# => { valid: true, issues: [] }
+
+# Check gemspec fields
+validator.validate_gemspec(path: '/path/to/lex-myextension')
+# => { valid: true, issues: [], path: '/path/to/lex-myextension/lex-myextension.gemspec' }
+```
+
+### Generate spec files directly
+
+```ruby
+spec_gen = Legion::Extensions::Codegen::Helpers::SpecGenerator.new
+
+# Runner spec
+puts spec_gen.generate_runner_spec(
+  module_name:  'Myextension',
+  runner_name:  'run_job',
+  methods:      [{ name: 'run_job', params: ['job_id:'] }]
+)
+
+# Client spec
+puts spec_gen.generate_client_spec(module_name: 'Myextension')
+
+# Helper spec
+puts spec_gen.generate_helper_spec(
+  module_name:  'Myextension',
+  helper_name:  'config',
+  methods:      [{ name: 'load', params: [] }]
+)
+```
+
+## Available Templates
+
+| Template | Generates |
+|----------|-----------|
+| `gemspec` | `lex-name.gemspec` |
+| `gemfile` | `Gemfile` with gemspec + test group |
+| `rubocop` | `.rubocop.yml` with LegionIO defaults |
+| `ci` | `.github/workflows/ci.yml` (calls shared reusable workflow) |
+| `rspec` | `.rspec` with `--format documentation` |
+| `gitignore` | `.gitignore` with standard Ruby entries |
+| `license` | `LICENSE` (MIT) |
+| `version` | `lib/legion/extensions/<name>/version.rb` |
+| `entry_point` | `lib/legion/extensions/<name>.rb` |
+| `spec_helper` | `spec/spec_helper.rb` with Legion::Logging stub |
+| `runner` | One runner module with stubbed methods |
+| `client` | `Client` class including runner modules |
+
+## Defaults
+
+| Setting | Default |
+|---------|---------|
+| Ruby version | `3.4` |
+| License | `MIT` |
+| Author | `Esity` |
+| Email | `matthewdiverson@gmail.com` |
+| Gem version | `0.1.0` |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lex-codegen.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/codegen/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-codegen'
+  spec.version       = Legion::Extensions::Codegen::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'Legion::Extensions::Codegen'
+  spec.description   = 'Code generation engine for LegionIO extensions'
+  spec.homepage      = 'https://github.com/LegionIO/lex-codegen'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-codegen'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-codegen'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-codegen'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-codegen/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'erb'
+
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rspec_junit_formatter'
+  spec.add_development_dependency 'rubocop', '~> 1.75'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'simplecov'
+end

data/lib/legion/extensions/codegen/client.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Codegen
+      class Client
+        include Runners::Generate
+        include Runners::Template
+        include Runners::Validate
+
+        def initialize(base_path: ::Dir.pwd)
+          @base_path = base_path
+        end
+      end
+    end
+  end
+end