-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit d4a13fa
Showing
57 changed files
with
2,389 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
name: Ruby | ||
|
||
on: | ||
push: | ||
branches: | ||
- master | ||
|
||
pull_request: | ||
|
||
jobs: | ||
build: | ||
runs-on: ubuntu-latest | ||
name: Ruby ${{ matrix.ruby }} | ||
strategy: | ||
matrix: | ||
ruby: | ||
- '3.0.4' | ||
|
||
steps: | ||
- uses: actions/checkout@v2 | ||
- name: Set up Ruby | ||
uses: ruby/setup-ruby@v1 | ||
with: | ||
ruby-version: ${{ matrix.ruby }} | ||
bundler-cache: true | ||
- name: Run the default task | ||
run: bundle exec rake |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
/.bundle/ | ||
/.yardoc | ||
/_yardoc/ | ||
/coverage/ | ||
/doc/ | ||
/pkg/ | ||
/spec/reports/ | ||
/tmp/ | ||
/*.rb | ||
/*.yml |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
## [Unreleased] | ||
|
||
"Solution does non exists unless tested" | ||
|
||
TODO | ||
|
||
- [ ] TODO `<% include Punch::ErbHelper -%>` why this does not work? | ||
- [ ] content MD5 hashing; a file was "punched" but was it touched after? | ||
- [ ] `punch stat` prints some "punching" statistic based on MD5 and log | ||
|
||
## [0.1.0] - 2022-07-27 | ||
|
||
- Initial release | ||
|
||
## 2022-07-11 | ||
|
||
- Project started |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
# frozen_string_literal: true | ||
|
||
source "https://rubygems.org" | ||
|
||
# Specify your gem's dependencies in punch.gemspec | ||
gemspec | ||
|
||
gem "clean", "~> 0.1.0", git: "https://github.com/nvoynov/clean.git" | ||
# gem "clean", path: "../clean" | ||
gem "rake", "~> 13.0" | ||
gem "minitest", "~> 5.0" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
GIT | ||
remote: https://github.com/nvoynov/clean.git | ||
revision: 05d2b24137452cebbcaa1202089b678ebfb7b998 | ||
specs: | ||
clean (0.1.0) | ||
|
||
PATH | ||
remote: . | ||
specs: | ||
punch (0.1.0) | ||
|
||
GEM | ||
remote: https://rubygems.org/ | ||
specs: | ||
minitest (5.16.2) | ||
rake (13.0.6) | ||
|
||
PLATFORMS | ||
x64-mingw32 | ||
|
||
DEPENDENCIES | ||
clean (~> 0.1.0)! | ||
minitest (~> 5.0) | ||
punch! | ||
rake (~> 13.0) | ||
|
||
BUNDLED WITH | ||
2.3.5 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
The MIT License (MIT) | ||
|
||
Copyright (c) 2022 Nikolay Voynov | ||
|
||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,147 @@ | ||
# Punch | ||
|
||
The Punch is a source code generator based on [Clean](https://github.com/nvoynov/clean) that is my sort of adaptation of The Clean Architecture principles. | ||
|
||
It was born for the purpose of boosting code architecture with Clean concepts and increasing productivity by eliminating tedious work by generating source code skeletons instead of writing it manually. You can look through [User Stories](User Stories.md) for basic ideas. | ||
|
||
Punch also plays for Clean as some kind promoter and varnisher - 1) it is an example of direct utilizing Clean's architecture, and 2) it is the first user who gives feedback. | ||
|
||
Keep code clean, and happy punching! | ||
|
||
## Installation | ||
|
||
I'm still not push it to rubygems.org, so it should be installed manually | ||
|
||
$ git clone https://github.com/nvoynov/punch.git | ||
$ cd punch | ||
$ bundle | ||
$ rake install | ||
|
||
Then you can add this line to your application's Gemfile: | ||
|
||
```ruby | ||
gem "punch", "~> 0.1.0", git: "https://github.com/nvoynov/punch.git" | ||
``` | ||
|
||
And then execute: | ||
|
||
$ bundle install | ||
|
||
Or you can just start punching and "punch" Gemfile :) | ||
|
||
$ punch new some_app | ||
|
||
## Usage | ||
|
||
Run `$ punch` to see its banner and get the basics | ||
|
||
### Punching projects | ||
|
||
To "punch" a new project run the following command | ||
|
||
$ punch new PROJECT | ||
|
||
the command will create the following project structure | ||
|
||
<project> | ||
<project>/Gemfile | ||
<project>/Rakefile | ||
<project>/test | ||
<project>/test/test_helper | ||
|
||
You can also start "punching" inside an empty directory | ||
|
||
$ mkdir punch_demo | ||
$ cd punch_demo | ||
$ punch init | ||
|
||
and it will do actually the same as `$ punch punch_demo` except creating a directory | ||
|
||
### Preview "in action" | ||
|
||
Instead of writing expressive commands description here I encourage everyone to try it "in actions" at the very beginning. Just run the commands followed one by one and see over the output | ||
|
||
$ punch preview sentry integer "must be integer" "v.is_a?(Integer)" | ||
$ punch preview service create_user name email | ||
$ punch preview service create_user name: email: | ||
$ punch preview service create_user name:string email: | ||
$ punch preview service create_user name:string email: | ||
$ punch preview entity user name:string email:email | ||
$ punch preview entity users/user name:string email:email | ||
$ punch preview entity credentials email:email password:password | ||
|
||
The `preview` command reads punched directory but does not touch existing source files; it only shows filenames and content for source files to be generated by regular `punch` command that can be useful to asses for possible changes. | ||
|
||
### Punching sources | ||
|
||
At first, I see an app as it has dozens services and entities, but just a few gateways sort of one data storage, and maybe a few external systems to interact. So one would rather "punch" entities and services and I deliberately refused to punch `Clean::Gateway`. | ||
|
||
That's why the basic and only commands are `punch sentry/service/entity` those will create source files based on `Clean::Sentry`, `Clean::Service`, and `Clean::Entity` templates (see `lib/assets/erb` for templates). | ||
|
||
That should be also mentioned that instead of having regular `punch sentry` command, I'd prefer to create it inside particular services and entities passing necessary sentry into parameters like `punch service create_user name:string` inside which will be called `punch sentry string` and ready `MustbeString` sentry will be used inside `CreateUser` service. | ||
|
||
__The only current problem with templates__ relates to requiring basic concepts to inherit inside punched sources. I can't guess all the possible strategies one could prefer for storing basic concepts | ||
|
||
- in the separated directory, like `lib/gadgets` | ||
- together with descendants, like `lib/services/service` and `lib/services/create_user` | ||
- straight inheriting from Clean::Service | ||
|
||
So today it is just the `require_relative 'service'` and it should be fixed manually. | ||
|
||
I rather prefer to create project-specific gadgets | ||
|
||
```ruby | ||
# lib/gadgets/service.rb | ||
require 'clean' | ||
require 'forwardable' | ||
|
||
module App | ||
class Service < Clean::Service | ||
extend Forwardable | ||
def_delegator :StoragePort, :gateway, :storage | ||
def_delegator :PlayboxPort, :gateway, :playbox | ||
# ... | ||
end | ||
end | ||
``` | ||
|
||
### Configuration | ||
|
||
Punch can be configured a bit through `punch.yml` configuration file that actually points directory paths to write source files. | ||
|
||
```yaml | ||
--- !ruby/object:Punch::Config | ||
lib: lib | ||
test: test | ||
sentries: sentries | ||
entities: entities | ||
services: services | ||
``` | ||
You can interpret it as "services will be placed to lib/services directory and its tests to test/services". So you can change it for `lib: app` and the service will be placed in "app/services/" | ||
|
||
### Logging | ||
|
||
The last thing is logger. Punch logs commands and possible exceptions inside `punch.log` | ||
|
||
## History | ||
|
||
This gem stands on the shoulders of [Cleon](https://github.com/nvoynov/cleon) and [Dogen](https://github.com/nvoynov/dogen), developing and systematizing their ideas, even grabbing some of their source code. | ||
|
||
As for [Cleon](https://github.com/nvoynov/cleon), firstly, I am confused that it sort of breaks the SRP by being responsible for both data (basics sources) and behavior (code generation). Secondly, it is slightly over-engineered being requiring working folder with gem. | ||
|
||
As for [Dogen](https://github.com/nvoynov/dogen), being a really curious idea by adding DSL, it still remains a code generator. | ||
|
||
## Development | ||
|
||
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. | ||
|
||
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org). | ||
|
||
## Contributing | ||
|
||
Bug reports and questions are welcome on GitHub at https://github.com/nvoynov/punch. | ||
|
||
## License | ||
|
||
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,12 @@ | ||
# frozen_string_literal: true | ||
|
||
require "bundler/gem_tasks" | ||
require "rake/testtask" | ||
|
||
Rake::TestTask.new(:test) do |t| | ||
t.libs << "test" | ||
t.libs << "lib" | ||
t.test_files = FileList["test/**/test_*.rb"] | ||
end | ||
|
||
task default: :test |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
% User Stories | ||
|
||
As a developer who start a new project ... | ||
|
||
# Architecture | ||
|
||
I want to design my code base in accord with The Clean Architecture, so it will be easy to write, read, test, and evolve. | ||
|
||
# Basic concepts | ||
|
||
I want to start as small as possible from PORO domain services by adopting just a few core concepts (Service, Entity, Gateway) so that I will have a clean domain at the beginning. Then as the project goes further I'll get to particular interfaces (CLI, Web, API, Message Broker, etc.) | ||
|
||
# Generators | ||
|
||
I want to have a few generators for my basic concepts and its tests (entities, services, gateways), that way I'll boost my productivity and reduce mistakes through generating instead of writing manually. | ||
|
||
Some sort of Rake tasks? | ||
|
||
# Containers | ||
|
||
I want to have a basic helpers to start development inside containers (Docker and Compose, Podman, k8s, etc.), that way my development machine will still clear from required technologies like database servers, message brokers, etc. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
#!/usr/bin/env ruby | ||
# frozen_string_literal: true | ||
|
||
require "bundler/setup" | ||
require "punch" | ||
|
||
# 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. | ||
|
||
# (If you use this, don't forget to add pry to your Gemfile!) | ||
# require "pry" | ||
# Pry.start | ||
|
||
require "irb" | ||
IRB.start(__FILE__) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,32 @@ | ||
#!/usr/bin/env ruby | ||
|
||
require "bundler/setup" | ||
require "punch" | ||
require "punch/gateways" | ||
require "punch/cli" | ||
include Punch::CLI | ||
include Punch::Gateways | ||
|
||
# initialize logger in pwd | ||
LoggerPort.gateway = Logr.new('punch.log') | ||
|
||
if ARGV.empty? | ||
puts banner | ||
exit | ||
end | ||
|
||
command = ARGV.shift.downcase | ||
case command | ||
when 'new' # create new punched | ||
create(ARGV.shift) | ||
when 'init' # init punch there | ||
init | ||
when 'clone' # punch could be cloning some other than Clean in future | ||
clone(ARGV.shift) | ||
when /(sentry|entity|service)/ | ||
punch(ARGV.unshift(command)) | ||
when /preview/ | ||
preview(ARGV) | ||
else | ||
unknown(command) | ||
end |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,32 @@ | ||
<% | ||
require 'punch/gadgets/erb_helper' | ||
# why the next line does not work? | ||
# include Punch::ErbHelper | ||
-%> | ||
# frozen_string_literal: true | ||
|
||
require_relative 'dummy' | ||
|
||
<%= open_namespace %> | ||
<%= @spacer %>class <%= @model.const %> < Entity | ||
<%= define_properties %> | ||
<%= @spacer %> def initialize(<%= parameters_string %>) | ||
<%= assing_properties -%> | ||
<%= @spacer %> end | ||
<%= @spacer %>end | ||
|
||
<%= close_namespace %> | ||
<%= open_namespace %> | ||
<%= @spacer %>class <%= @model.const %> < Service | ||
<%= @spacer %> def initialize(<%= parameters_string %>) | ||
<%= assing_properties -%> | ||
<%= @spacer %> end | ||
|
||
<%= @spacer %> def call | ||
<%= @spacer %> # entity = Entity.new(<%= arguments_string %>) | ||
<%= @spacer %> # gateway.<%= @model.name %>(entity) | ||
<%= @spacer %> end | ||
<%= @spacer %>end | ||
|
||
<%= close_namespace %> |
Oops, something went wrong.