daifuku 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1fdf491fb8af78cfb95b601dd4f4fad28a1a4c73003498de29b929206199beb6
+  data.tar.gz: 9efe45238a4ea0ea0ae5d06b88b440f84044c520af425b7e35e5e8f653bbcf10
+SHA512:
+  metadata.gz: fcaa3cb1c984235e7e383d63896352966ee649bb858b4865faa1c0598335439d2467c8993bd50dcbb07ef69035aa6b21c6d0f7c4cfd0ca8c4f0172dff325af73
+  data.tar.gz: 8de8c756e0264b0cb353b14115fd93a0d7cf3ac787e41eec267c9fb375cd80def016423de3145be69216268738422c95132d71ed97a383a654c2103e5d4a6275

data/.github/workflows/ruby.yml

@@ -0,0 +1,31 @@
+name: Ruby
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.1', head]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,56 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*

data/.ruby-version

@@ -0,0 +1 @@
+3.2

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec
+gem 'pry'
+gem 'activesupport-inflector', '~> 0.1.0'
+gem 'i18n'

data/Gemfile.lock

@@ -0,0 +1,55 @@
+PATH
+  remote: .
+  specs:
+    daifuku (0.9.0)
+      nokogiri
+      redcarpet
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport-inflector (0.1.0)
+    coderay (1.1.3)
+    concurrent-ruby (1.2.2)
+    diff-lcs (1.5.0)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    method_source (1.0.0)
+    mini_portile2 (2.8.4)
+    nokogiri (1.15.3)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.7.1)
+    rake (13.0.6)
+    redcarpet (3.6.0)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport-inflector (~> 0.1.0)
+  bundler (~> 2.0)
+  daifuku!
+  i18n
+  pry
+  rake (~> 13.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.4.14

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Cookpad Inc.
+
+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,149 @@
+# daifuku
+A markdown parser and compiler for log definitions in mobile applications
+
+## Usage 
+Automatic generation of document-based type-safe log implementation code
+
+![Transpile](docs/images/transpile.png)
+
+### Step 1
+Consider log specifications and write documentation. 
+
+- Syntax: [docs/syntax.ja.md](docs/syntax.ja.md)
+- Example: [example/LogDefinitions/recipe_search.md](./example/LogDefinitions/recipe_search.md)
+
+#### Log definition documents (Markdown)
+
+```md
+# recipe_search
+
+An category of events related to recipe search.
+
+## search
+
+An event sent when users perform a recipe search.
+
+- keyword: !string 256
+    - Search keyword
+- order: SearchOrder
+   - latest, popularity
+
+## show_recipe
+
+An event sent when users move from the search results screen to the recipe details screen.
+
+- recipe_id: !integer
+    - ID of the selected recipe
+
+```
+
+### Step 2
+
+Run the script. 
+
+- Example: [example/iOS/generate-log-classes.rb](./example/iOS/generate-log-classes.rb)
+
+```sh
+bundle install
+ruby example/iOS/generate-log-classes.rb
+```
+
+After that, the following `.swift` files will be automatically generated.
+
+```sh
+ls example/AutoGenerated 
+# CommonPayload.swift  LogCategories.swift
+```
+
+#### Log definition code (Swift)
+
+```swift
+/// Events on the recipe search screen
+public enum RecipeSearch: LogCategory {
+    /// An event sent when users perform a recipe search.
+    case search(keyword: String, order: SearchOrder)
+    ///  An event sent when users move from the search results screen to the recipe details screen.
+    case showRecipe(recipeId: Int64)
+}
+```
+
+### Step 3
+
+Send logs with the enums of the log definition.
+
+#### Log implementation code (Swift)
+
+```swift
+// After the search request 
+logger.post(
+    RecipeSearch.search(
+        keyword: keyword, // “egg" 
+        order: order // .latest
+    )
+)
+```
+
+## What makes you happy?
+
+### Fully documented at all times
+Because of the way it works, you cannot implement logging without writing documentation. This means that there will always be documentation. 
+
+Happy implementers and happy analysts 😊
+
+### Type safety
+#### No unintended values are introduced
+
+Because the possible values, such as character limits, patterns, and numeric ranges, are guaranteed at the type level, it prevents unintended values from entering the log database.
+
+#### Comfortable to be complemented by IDE
+
+Completion during implementation also improves the development experience and reduces mistakes.
+
+![Code Completion](docs/images/code-completion.png)
+
+### Easy to read for both humans and machines
+
+Markdown is excellent as a format for log definition documents that anyone could easily read and write.
+
+In addition, it was useful to be able to statically analyze both the definition document and the implementation.
+
+For example, mistakes such as "I defined it in the document but forgot to implement it" could be detected automatically.
+
+This mechanism has actually been useful several times in regular CI runs.
+(It was also useful to be able to notice when a log was accidentally deleted during refactoring, etc.).
+
+## Case Study
+
+### Git version control in the same repository as the app
+In Cookpad (Japan), log definitions and mobile application source code are managed in the same git repository.
+
+#### Everything in one place (easy to find)
+It is all in one place, so there is no need to wander around looking for information in logs.
+
+#### Background of log definitions can also be checked by following pull requests
+
+It is also possible to run `git blame` on log markdown definitions and follow pull requests to find out which version of the log was added, who implemented the log, and with what intention.
+
+
+## Articles (Japanese)
+- ドキュメントベースの型安全なモバイルアプリ行動ログ基盤の構築 - クックパッド開発者ブログ https://techlife.cookpad.com/entry/2020/11/05/110000
+- モバイルアプリの行動ログの「仕込み」を快適にする https://speakerdeck.com/yujif/iosdc-japan-2022-mobile-app-logging
+
+## Original Author
+[@giginet](https://github.com/giginet)
+
+## Contributors
+[@hiragram](https://github.com/hiragram)
+[@litmon](https://github.com/litmon)
+[@ksfee684](https://github.com/ksfee684)
+[@aamine](https://github.com/aamine)
+[@vincentisambart](https://github.com/vincentisambart)
+[@kalupas226](https://github.com/kalupas226)
+[@yujif](https://github.com/yujif)
+
+## Contributing
+This repo is basically *read-only*. We publish this code for knowledge sharing purposes.
+Please note that we cannot guarantee continuous maintenance or responses to Issues or Pull Requests.
+
+## License
+MIT License

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/daifuku.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "daifuku/version"
+
+Gem::Specification.new do |spec|
+    spec.name          = "daifuku"
+    spec.version       = Daifuku::VERSION
+    spec.authors       = ["Kohki Miki"]
+    spec.email         = ["giginet.net@gmail.com"]
+
+    spec.summary       = "A markdown parser and compiler for log definitions in mobile applications"
+    spec.description = <<~EOF
+    Daifuku is a markdown parser and compiler for log definitions in mobile applications. It provides an
+    automatic generation of document-based type-safe log implementation code from markdown.
+    EOF
+    spec.homepage      = "https://github.com/cookpad/daifuku"
+    spec.license       = 'MIT'
+
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = spec.homepage
+
+    # Specify which files should be added to the gem when it is released.
+    # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+    spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    end
+    spec.bindir        = "exe"
+    spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+    spec.require_paths = ["lib"]
+
+    spec.add_dependency "redcarpet", "~> 3.6"
+    spec.add_dependency "nokogiri", "~> 1.15"
+
+    spec.add_development_dependency "bundler", "~> 2.0"
+    spec.add_development_dependency "rake", "~> 13.0"
+    spec.add_development_dependency "rspec", "~> 3.0"
+end

data/daifuku.rb

@@ -0,0 +1,9 @@
+require "daifuku/version"
+require "daifuku/compiler"
+require "daifuku/parser"
+require "daifuku/models"
+require "daifuku/renderer"
+require 'daifuku/validator'
+
+COMMON_CATEGORY_NAME = 'common'
+COMMON_EVENT_NAME = 'common'

data/docs/syntax.ja.md

@@ -0,0 +1,143 @@
+# daifuku ログ定義用 Markdown 形式
+
+## 要素
+ログは**カテゴリ**、**イベント**、**カラム**の3要素からなります。
+
+- カテゴリ：イベントの集合。近しい機能を同一のカテゴリとして扱う（`RecipeSearch`など）
+- イベント：ログを送るきっかけとなる動作単位
+- カラム：イベントの持つ値。型と名前を持つ
+
+それぞれの名前は `/\w+/` であることが期待されています。
+
+# ログ定義の記述
+
+```markdown
+# recipe_search
+
+レシピ検索に関するログです。
+
+## search
+
+ユーザーがレシピをキーワード検索したときに送信されます。
+
+- keyword: !string 256
+   - 検索キーワード
+- order: SearchOrder
+   - 新着順, 人気順
+
+## show_recipe
+
+ユーザーが検索結果画面でレシピを選択したときに送信されます。
+
+- recipe_id: !integer
+    - 選択されたレシピのID
+- position: !integer
+  - タップしたクエリが上から何番目か (0始まり)
+```
+
+## カテゴリ
+
+ドキュメントのトップレベルに記述した文章は全てカテゴリの説明として扱われます。
+
+文中のインライン要素は十分にテストされていません。
+**文章の記述にはボールドやコードブロックなどのインライン要素を使わない方が無難です。**
+
+**仕様上はカテゴリ共通カラムの定義が可能ですが、現段階では未対応です。**
+
+ファイル名がカテゴリ名として扱われますが、分かりやすさのために、`#` 見出しをファイル名と同じにしましょう。`snake_case`が推奨されます。
+
+## イベント
+
+`##` 見出し以下の文章はイベントの説明、カラム定義はイベント内のカラムとして扱われます。
+
+見出しがイベント名として扱われます。`snake_case`が推奨されます。
+
+## カラム
+
+イベント以下にあるリスト要素はカラムとして扱われます。カラムは以下のようなシンタックスで定義できます。
+
+```markdown
+- <カラム名>: !<カラム型>(?)
+    - カラムの説明1
+    - カラムの説明2
+```
+
+### 型
+
+- `!`から始まる型はプリミティブ型です。
+- 末尾に`?`をつけることでオプショナル型として定義することができます。
+- 未知の型を利用したとき、生成に失敗します。
+
+クックパッドでは データウェアハウス に Amazon Redshift を利用しており、[Redshift でサポートされているデータ型](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html)を前提として以下の利用可能な型を定義しています。
+
+- !smallint : 16ビット符号付き整数
+- !integer : 32ビット符号付き整数
+- !bigint : 64ビット符号付き整数
+- !real : 32ビット浮動小数点数
+- !double : 64ビット浮動小数点数
+- !boolean : 真偽値
+- !string <バイト数> : 文字列型
+- !date : 日付型
+- !timestamp : 日付時刻型（タイムゾーンなし）
+- !timestamptz : 日付時刻型（タイムゾーンあり）
+
+
+文字列型は定義時に文字列長の指定が可能です。
+
+```markdown
+- message: !string 256
+```
+
+
+### カスタム型
+
+カスタム型を定義、利用することもできます。
+アプリケーション側で enum などを定義して特定の定義域を表現するのに利用できます。
+
+ログ定義側でカスタム型を利用するには、`!`から始まらない型名を直接指定してください。
+
+```markdown
+# user
+
+## set_profile
+
+- user_status: UserStatus
+    - ユーザー状態
+```
+
+### obsolete指定
+
+利用しなくなったイベントやカラムには `[obsolete]` 指定が使えます。これを含んだイベントやカラムはコード生成から除外されますが、古いログの調査のためにドキュメントには残ります。
+
+descriptionに使用できなくなったアプリのバージョン名を明記しておくと便利です。
+
+```markdown
+- [obsolete] user_status: UserStatus
+    - ユーザー状態
+    - v2020.34.0 から廃止されました
+```
+
+# CommonPayload
+
+すべてのイベントが共通して持つカラムを`CommonPayload`と呼んでいます。
+これはUser AgentやユーザーID、OSバージョンなどを想定しています。
+
+`common`というカテゴリ名のログ定義は特別に`CommonPayload`として扱われます。
+すなわち、`LogDefinitions/common.md`にカラムを記述することで、`CommonPayload`として処理されます。
+
+記述方法は普通のカテゴリと同様ですが、トップレベルのカラムだけがパースされ、イベント定義は無視されます。
+
+```markdown
+# common
+
+- user_id: !bigint?
+    - ユーザーID
+- user_agent: !string 1000
+    - ユーザーエージェント
+- os_version: !string 32
+    - iOSバージョン
+- application_version: !string 32
+    - アプリケーションバージョン
+- time_zone: !string 64
+    - タイムゾーン(Asia/Tokyoなど)
+```

data/example/LogDefinitions/common.md

@@ -0,0 +1,20 @@
+# common
+
+- user_id: !bigint?
+    - ユーザーID
+- user_agent: !string 1000
+    - ユーザーエージェント
+- os_version: !string 32
+    - iOSバージョン
+- application_version: !string 32
+    - アプリケーションバージョン
+- time_zone: !string 64
+    - タイムゾーン(Asia/Tokyoなど)
+- [obsolete] user_status: !string 32
+    - example1, example2, example3
+- device_kind: DeviceKind
+    - 端末の種類
+    - phone, tablet, unknown
+- device_model: !string 16
+    - 端末のモデル
+    - 実機だと「iPhoneXX,X」または「iPadXX.X」形式

data/example/LogDefinitions/recipe_search.md

@@ -0,0 +1,19 @@
+# recipe_search
+
+An category of events related to recipe search.
+
+## search
+
+An event sent when users perform a recipe search.
+
+- keyword: !string 256
+    - Search keyword
+- order: SearchOrder
+   - latest, popularity
+
+## show_recipe
+
+Sent when users move from the search results screen to the recipe details screen.
+
+- recipe_id: !integer
+    - ID of the selected recipe

data/example/iOS/Templates/CommonPayload.swift.erb

@@ -0,0 +1,25 @@
+import Foundation
+
+// This file is automatically generated by generate-log-classes.
+public struct CommonPayload {
+    <%- columns.each do |column| -%>
+    <%- column.descriptions.flat_map(&:lines).each do |description_line| -%>
+    /// <%= description_line.strip %>
+    <%- end -%>
+    var <%= column.variable_name %>: <%= column.swift_type %>
+    <%- end -%>
+
+    public func makePayload() -> [String: JSONCodable] {
+        return [
+            <%- columns.each do |column| -%>
+            "<%= column.original_name %>": <%= column.call_dump %>,
+            <%- end -%>
+        ].compactMapValues { $0 }
+    }
+
+    public init(<%= columns.map { |column| column.as_argument }.join(', ') -%>) {
+        <%- columns.each do |column| -%>
+        self.<%= column.variable_name %> = <%= column.variable_name %>
+        <%- end -%>
+    }
+}

data/example/iOS/Templates/LogCategories.swift.erb

@@ -0,0 +1,33 @@
+// This file is automatically generated by generate-log-classes.
+import Foundation
+<%- categories.each do |category| -%>
+<%- category.descriptions.flat_map(&:lines).each do |description_line| -%>
+/// <%= description_line.strip %>
+<%- end -%>
+public enum <%= category.class_name %> {
+    public static var categoryName: String { "<%= category.name %>" }
+    public var eventName: String {
+        <%- if category.available_events.empty? -%>
+        assertionFailure("No events are available in category <%= category.class_name %>")
+        return ""
+        <%- else -%>
+        switch self {
+        <%- category.available_events.each do |event| -%>
+        case .<%= event.variable_name %>: return "<%= event.name %>"
+        <%- end -%>
+        }
+        <%- end -%>
+    }
+
+    <%- category.events.each do |event| -%>
+    <%- event.descriptions.flat_map(&:lines).each do |description_line| -%>
+    /// <%= description_line.strip %>
+    <%- end -%>
+    <%- if event.columns.empty? -%>
+    <%= event.availability_annotation %>case <%= event.variable_name %>
+    <%- else -%>
+    <%= event.availability_annotation %>case <%= event.variable_name %>(<%= event.associated_types %>)
+    <%- end -%>
+    <%- end -%>
+}
+<%- end -%>