github-script-ruby@v2でRubyのバージョンを指定できるようにした

GitHub Actions Ruby

github-script-rubyが何かについてはペパボのテックブログに書きましたので是非ご覧ください。

tech.pepabo.com

github-script-rubyは、簡単にいうと actions/github-script の Ruby版です。

今回は、github-script-ruby独自の機能としてRubyのバージョンを指定できるようにしました。

具体的には ruby-version: にRubyのバージョンを書くとそのバージョンで動きます。 簡単なサンプルとしては以下のような感じです。

- name: 'Hello Ruby version'
  uses: k1LoW/github-script-ruby@v2
  with:
    script: |
      repo = "#{context.repo.owner}/#{context.repo.repo}"
      number = context.issue.number
      comment = "Hello using Ruby v#{RUBY_VERSION}"
      github.add_comment(repo, number, comment)
    ruby-version: 2.7.5

あまり古いバージョンのRubyで動かすことにモチベーションはないですが、現状2.4.10までは動いています（コードを対応させればもう少し古いバージョンでも動くと思います）。

さて、どのように実現したのかというと ruby/setup-ruby の仕組みを利用させてもらうことで実現しています。

ruby/setup-ruby はどのように ruby-version: の機能を実現しているか

ruby/setup-rubyのREADME.mdに以下のように書かれています。

This action downloads a prebuilt ruby and adds it to the PATH.

The prebuilt releases are generated by ruby-builder and on Windows by RubyInstaller2. mingw and mswin builds are generated by ruby-loco. ruby-head is generated by ruby-dev-builder, jruby-head is generated by jruby-dev-builder, truffleruby-head is generated by truffleruby-dev-builder and truffleruby+graalvm is generated by graalvm-ce-dev-builds. The full list of available Ruby versions can be seen in ruby-builder-versions.js for Ubuntu and macOS and in windows-versions.js for Windows.

つまり、あらかじめruby/ruby-builder をはじめとする各リポジトリでプレビルドしたRubyをReleasesのAssetとして置いておき、ruby/setup-ruby側では ruby-version: で指定されたバージョンのRubyをダウンロード・展開し設置するという形で「任意のバージョンのRubyのセットアップ」を実現しています*1。

github-script-ruby@v2 でも ruby-version: の機能を実現する

github-script-ruby@v2 でもruby/setup-rubyで使用しているAssetを使用させてもらっています。

まず、さまざまな処理系やバージョンにする必要はないと考えて「MRIのみ」かつ「パッチバージョンまで指定する」という制約をつけています。 そうすると対象となるのは ruby/ruby-builder で管理されているプレビルドRubyだけになります。

github-script-ruby@v2をstepで実行するタイミングで ruby-version: が指定されていれば ruby/ruby-builder からプレビルドRubyをダウンロードして設置して使用します。 また、bundlerが標準添付されていないバージョンの場合はbundlerもインストールします。

https://github.com/k1LoW/github-script-ruby/blob/6852aaffa26d2b760ff60c79b7086ef9a248a918/scripts/entrypoint.sh#L9-L23

これだけで簡単な ruby-version: の機能が実現できました。

その他にも

v2で、gemfile-path: （Gemfileのパスを指定する）や command: （github-script-rubyの環境で任意のコマンドを実行する）なども追加しました。

これで、stepだけで独立した任意のバージョンのRuby環境を手に入れることができます。

（必要かどうかはおいておいて）例えば、

- name: 'Capistrano deploy'
  uses: k1LoW/github-script-ruby@v2
  with:
    gemfile-path: path/to/Gemfile
    command: bundle exec cap deploy --gemfile=path/to/Gemfile
    ruby-version: 2.7.5

みたいなこともできたりします。

というわけで、v1からあった gemfile:（Gemfileを書ける） や pre-command: （github-script-rubyの環境で任意のコマンドを実行する）に続いて、さらに元ネタであったactions/github-scriptからさらに逸脱してきた感じです。

何か面白いユースケースを思いついたら是非教えてください。

*1:実際にはダウンロード以外にもキャッシュを使ったりruby-buildでビルドしたりなどをしています

2021年の振り返りと2022年の抱負

2021年の振り返り

2021年も2020年から引き続き内に籠った年だった気がします。

また、厄年だったことは全く関係ないのですが「エンジニアとしてこの先生き残るには」ということを考えることが多かったと思います。

私はこれまであまり将来を深く考えることはあまりなかったのですが、子供の著しい成長を間近で見ていると「ところで私は成長できているのだろうか」という現状に対する思いと「今後子供が十分に成長するまでサポートし続けることができるだろうか」という将来に対する思いとがごちゃ混ぜになって「うっ」となることが何回かありました。世の親をやっている人々はすごい。

一方で「自分が何が好きなのか」は言語化できました。

私はいろいろ好きだし大抵のものには意義を見出せる質なのですが、特に「開発者のための開発」が好きです。

その言語化を得て冷静に振り返ってみると「結局自分がやり続けたこととか成功体験の積み重ねの結果の"好き"なんだなあ」とも思いました。

会社では全方位でいろいろやらせてもらえる（結果は求められる）ので、引き続きやっていきたいです。

2021年の抱負は「インプットができるようにする」でした。

結果はどうだったかというと「できてないな」というのが正直な感想です。

「手持ちのカードが増えない」という事実は結構自分の心を乱している要因にもなっています。せめて強いカードを持っていればいいのですが難しい。

増えていない原因も自分なので、これはもう自分で動き出す以外は方法はないです。がんばれ。

OSS

今年はGitHub関係のものが多かった印象があります。GitHub Actionsは本当に良いですね。

今年最も力を入れたOSSは何かと問われたら octocov だと思います。

個人的にはtblsに近いレベルで「うまく設計がまとまったな」という感覚があります。うまくまとまると「小さな世界」を作れた感覚があって好きです。これを求めて懲りずにツールを作っている面もありそう。

octocovは2022年ももう少しだけやり残した実装を続けると思います。そしたらまたアイデアが降ってくるまでは手を離すことができそうです。

発表

継続的ドキュメンテーション関係の発表が多かったです。もう個人的には研究課題みたいになっています。もしくは趣味。

2022年の抱負

今年は「挑戦する」です。1年が終わった時に「今年はこれをやったな〜」と言いたい。

コンフォートゾーンから抜けるのが本当に苦手なので（むしろ嫌がる）、なんでもいいので、失敗でもいいので「やったな〜」を成し遂げたい。

チャンス（特に自身の感情の高まり）を逃さずに2022年もコードを書いていきたいです。

あ、あと分割キーボードを今年こそ手に入れたい。

今年もよろしくお願いします。

せめてリポジトリの各ディレクトリの概要説明だけでも欲しい思ったので dirmap というツールを作ってみた

Go

既存の開発に参加するときや、0->1の開発をしているとき、いつも「せめてリポジトリの各ディレクトリの概要説明だけでも欲しい」と思っていました。

既存のプロジェクトに参加するときは「プロジェクトの理解をする側」、0->1のプロジェクトで開発をしているときは「説明をする側の立場」で、です。

Ruby on Railsのような基本のディレクトリレイアウト決まっていてもそのプロジェクトの独自性がでてきますし、Goのようにスタンダードなレイアウトがないのであればなおさら初見ではわかりません。

「じゃあREADME.mdにでも書いておけばいい」というのはその通りです。

ただ、概要説明であっても一度書いたら終わりではなく、更新は必要になります。特に0->1のプロジェクトの初期ではディレクトリレイアウトすら途中で変わるということはままあります。

（ここらへんは「継続的ドキュメンテーション」として私の興味のある分野です。私のSpeaker Deckのドキュメント系の発表は大体が継続的ドキュメンテーションにつながっています）

そこで、できるだけ簡単に各ディレクトリの概要説明を実現するために dirmap というツールを作ってみました。

github.com

dirmap

dirmapはディレクトリを再帰的に走査して各ディレクトリの「概要を説明していそうな箇所の文字列」を取得し「各ディレクトリの概要説明＝ディレクトリマップ」を生成するツールです。

たとえば dirmap のリポジトリルートで dirmap generate を実行すると以下のような tree に近い出力を得ることができます。

$ dirmap generate
.
├── .github/
│   └── workflows/
├── cmd/ ... Commands.
├── config/ ... Configuration file.
├── matcher/ ... Implementation to find the string that will be the overview from the code or Markdown.
├── output/ ... Output format of the directory map.
├── scanner/ ... Implementation of scanning the target directory and its overview from the file system based on the configuration.
├── scripts/ ... scripts for Dockerfile.
└── version/ ... Version.

この Commands. や scripts for Dockerfile. のような概要っぽい文字列はどこから取得しているかというと、「そのディレクトリにあるMarkdownファイルの見出しではない最初のパラグラフ」や「そのディレクトリにあるGoのソースコードに書かれているgodocのpackages Overviewにあたる部分」などです。

このように「そのディレクトリにあるファイルからそのディレクトリの説明となる文章を抽出すれば、各ディレクトリの概要説明の管理も最小限になるだろう」という算段です。

「概要っぽい文字列」の取得ルールは設定ファイルを渡すことで変更も可能です。built-inな markdown markdownHeading godoc 以外にも正規表現マッチもサポートしています。

設定ファイルは dirmap init で生成可能です。書かれている設定は dirmap のデフォルト設定（設定ファイルなしの場合の挙動と同じ）になります。

$ dirmap init
Create .dirmap.yml
# $ cat .dirmap.yml
targets:
- file: .dirmap.md
  matcher: markdown
- file: README.md
  matcher: markdown
- file: doc.go
  matcher: godoc
- file: "*.go"
  matcher: godoc

各ディレクトリの概要は targets: に指定した走査条件に最初にマッチした文字列になります。

dirmap generate で出力できるフォーマットは今の所「treeライクなASCIIの出力」と「Markdown(GFM)のテーブル形式」の2つです（以下はテーブル形式）。

$ dirmap generate -t table
| Directory | Overview |
| --- | --- |
| .github/ |  |
| .github/workflows/ |  |
| cmd/ | Commands. ( [ref](cmd/doc.go) ) |
| config/ | Configuration file ( [ref](config/config.go) ) |
| matcher/ | Implementation to find the string that will be the overview from the code or Markdown. ( [ref](matcher/matcher.go) ) |
| output/ | Output format of the directory map ( [ref](output/output.go) ) |
| scanner/ | Implementation of scanning the target directory and its overview from the file system based on the configuration. ( [ref](scanner/scanner.go) ) |
| scripts/ | Scripts for Dockerfile ( [ref](scripts/.dirmap.md) ) |
| version/ | Version ( [ref](version/version.go) ) |

とりあえずdirmapを使って各ディレクトリの概要説明をいれつつ、新しくプロジェクトに入るメンバーのために開発者用ドキュメントをメンテナンスしてみようと思います。

Goのプロジェクトならgodocのpackage overviewの箇所だけ書いておけばいいだけなので楽です（他の言語も良いドキュメントフォーマットが存在するなら対応したいと思っています。ぜひ教えてください）。

これだけで開発開始までのオーバーヘッドが大幅に減るとは思ってはいませんが、継続的ドキュメンテーションの1つとして試してみようと思います。

ディレクトリ内のPDFとEPUBをタイトル付きでリストアップする ebk ls を作った

Go

私は買った電子書籍を1つのディレクトリに保存しているのですが、ファイル名はダウンロードしたときのそのままにしていることが多いので、良く「あの書籍はどのファイルだっけ？」が発生していました。

電子書籍リーダーで管理すればいいとは思うのですが、それを整備することすらしていない有様です。

とりあえず「あの書籍はどのファイルだっけ？」や「あの書籍って買ってたっけ？」をなんとか解消したいと思っていました。

PDFファイルやEPUBファイルの電子書籍のタイトルだけでも一覧表示できれば上記が解消すると思っていたので、重い腰をあげて作りました。

github.com

ebk

上に貼ったツイート以上の情報はないのですが、 ebk ls [DIR] を実行するとディレクトリ内のPDFとEPUBのタイトルとファイル名をデリミタ（デフォルトは :）で区切って出力します。

$ ebk ls ~/path/to/books/ | grep oreilly
NFS & NIS 第2版:oreilly-4-87311-078-5e.pdf
ウェブオペレーション:oreilly-978-4-87311-493-4e.pdf
SQLアンチパターン:oreilly-978-4-87311-589-4e.epub
[...]
Go言語による並行処理:oreilly-978-4-87311-846-8e.epub
入門　監視:oreilly-978-4-87311-864-2e.epub
入門 Prometheus:oreilly-978-4-87311-877-2e.epub
みんなでアジャイル:oreilly-978-4-87311-909-0e.epub
ユニコーン企業のひみつ:oreilly-978-4-87311-946-5e.epub

使い方としては peco などのツールと合わせて使うことを想定していて、macOSだと以下のようなコマンドで、選択した電子書籍を電子書籍リーダーで開くことができます。

$ open $(ebk ls /path/to/books/ --with-path -d '\t' | peco | awk -F '\t' '{print $2}')

f:id:k1LoW:20211122072335p:plain

タイトルを取得できなかった場合は ??? で表示されます。

というわけで

個人的にはもう満足していて ebk ls 以外のコマンドは作らなそうですが、また電子書籍のメタデータで何かしたくなったら ebk に追加しようと思います。

私は、ebk のおかげで早速間違って二重購入するのを防げました。作った甲斐がありました。もっとちゃんと管理しろというお話ですが。

もし同じように「あの書籍はどのファイルだっけ？」に困っている方がいましたら使ってみてください。

go-githubのClientをいい感じに組み立ててインスタンスを生成するだけのgo-github-clientを作った

Go GitHub

GitHubやGitHub Actionsが好きで、いろいろツールを作ったりするのですが、毎回毎回go-githubのClientのインスタンス生成のために何行かコードを書いています。

最初の頃は GITHUB_TOKEN のことだけを考えていていたのが、その後GitHub Enterpriseのエンドポイントも考えるようになり、GitHub Actionsの登場からはActions上の環境変数をうまく使いたくもなり、GitHub CLI extensionがでてきてからは、GH_* という環境変数も考慮する必要がでてきています。

その都度過去のツールのコードをまるっとコピペしつつもgo-githubのClientインスタンス生成コードは変わってきています。

また、go-githubはセマンティックバージョニングを採用している（？）のか、既にv39まできています。 go-githubのClientを引数に受け取るような外部パッケージがあったとき、その外部パッケージが採用しているgo-githubのメジャーバージョンに合わせないといけないのも苦でした。

毎回コピペコードを書いたり、過去ツールの実装を直したりするのも嫌になってきたので、go-github-clientとしてコード片をパッケージ化しました。

github.com

go-github-client

使い方は go-github のメジャーバージョンに合わせて go-github-client/[VERSION]/factory をimportして使うだけです。

package main

import (
    "context"
    "fmt"

    "github.com/k1LoW/go-github-client/v39/factory"
)

func main() {
    ctx := context.Background()
    c, _ := factory.NewGithubClient()
    u, _, _ := c.Users.Get(ctx, "k1LoW")
    fmt.Printf("%s\n", u.GetLocation())
}

factory.NewGithubClient() 内で、環境変数からトークンやエンドポイントの解決をし生成したClientインスタンスを返します。

また、Functional Option Patternを採用しているので、外部からトークンやエンドポイントなどを差し込むことも可能です。

例えば、go-githubをモック化したい場合は、 *http.Client を外部から差し込むことで解決します。

package main

import (
    "context"
    "testing"

    "github.com/google/go-github/v39/github"
    "github.com/k1LoW/go-github-client/v39/factory"
    "github.com/migueleliasweb/go-github-mock/src/mock"
)

func TestUsingMock(t *testing.T) {
    mockedHTTPClient := mock.NewMockedHTTPClient(
        mock.WithRequestMatch(
            mock.GetUsersByUsername,
            github.User{
                Name: github.String("foobar"),
            },
        ),
    )
    c, err := factory.NewGithubClient(factory.HTTPClient(mockedHTTPClient))
    if err != nil {
        t.Fatal(err)
    }

    ctx := context.Background()
    user, _, err := c.Users.Get(ctx, "myuser")
    if err != nil {
        t.Fatal(err)
    }
    got := user.GetName()
    if want := "foobar"; got != want {
        t.Errorf("got %v\nwant %v", got, want)
    }
}

バージョニング

バージョニングは少し特殊です。

このgo-github-clientパッケージ自体がgo-githubのClientを生成するだけのものなので、基本的にgo-githubバージョンと合わせてタグやディレクトリを切っています。

ただ、go-github-client自体の機能追加もあるので、それにはパッチバージョンに加算することで対応します。

表で表すと以下のような感じです。

バージョン 構成
Major google/go-github のmajorバージョン
Minor google/go-github のminorバージョン
Patch google/go-github のpatchバージョンにk1LoW/go-github-clientの更新を加算

まあちょっとひどいですが、利便性を考えて割り切ります。

というわけで

ただのコード片ですが、これからもGitHub APIを叩くツールや実装は作りそうなので、個人的にはこれを使っていこうかと思っています。

そういえば昔もawsecretsというgemを作ったりしていて、成長していないなーなどと思いました。

Monorepoなリポジトリでgo.modがネストされた位置にあるときのgoplsの設定

Emacs Go LSP 
$ gopls version
golang.org/x/tools/gopls v0.7.3
    golang.org/x/tools/gopls@v0.7.3 h1:Lru57ht8vtDMouRskFC085VAjBAZRAISd/lwvwOOV0Q=

Monorepoなリポジトリ内のサブプロジェクトの開発でEmacs + goplsが動かないなーと思っていて *lsp-log* bufferをみると以下のようなエラーが出ていました。

 errors loading workspace: gopls requires a module at the root of your workspace.
You can work with multiple modules by opening each one as a workspace folder.
Improvements to this workflow will be coming soon, and you can learn more here:
https://github.com/golang/tools/blob/master/gopls/doc/workspace.md.
  snapshot=0
  directory=file:///Users/k1low/src/path/to/monorepo

https://github.com/golang/tools/blob/master/gopls/doc/workspace.md によると、通常の設定+Multiple modules構成*1では動かないらしいとのこと。

goplsの experimentalWorkspaceModule の設定を有効にすることで、The workspace moduleという機能を有効になりMultiple modules構成に対応ができるとのこと。

手元の環境では上記を設定とりあえず有効にしてみたらちゃんと補完されました。

Emacsだと以下のような感じ。

(lsp-register-custom-settings
 '(
;; [...]
   ("gopls.experimentalWorkspaceModule" t t)
;; [...]
   ))

*1:私は、「プロジェクトルート以外にgo.modがある構成」と理解しました

GitHub上にあるリポジトリに対してAPIを通じてgit grepライクに走査できるツール gh-grep (gh grep) を作った

Go GitHub

git grep 便利ですよね。

私は git grep と git gsub は本当によく使います。

ところで git grep はローカルリポジトリがないと実行できません。

ローカルにリポジトリがなければ git clone して、 git grep すればいいのですが、もう少し簡単にgrepするために gh-grep を作りました。

github.com

gh-grep

gh-grepはGitHub APIを使ってGitHub上のリポジトリに対してgrepをするツールです。

特徴は、全てGitHub APIを通じて実行するためローカルに git clone することなくgrepできることです。

また、APIを使っている特徴を活用して複数リポジトリに対してgrepすることなども可能になっています。

あと実行が遅いです。ひたすらGitHub APIを叩いているので...*1。

インストール

gh-grep というコマンドとしてHomebrewなどでのインストールも可能ですが、

$ brew install k1LoW/tap/gh-grep

GitHub CLI extensionとしてもインストールできるようにしています。この場合は gh grep というサブコマンドになります。

$ gh extension install k1LoW/gh-grep

使い方

git grep に近いですが、 --owner だけは必須オプションになっています。

例えば、自分のリポジトリのプロジェクトルートにおいてあるDockerfileのベースイメージを検索したい時、

$ gh grep ^FROM --include=Dockerfile --owner k1LoW
k1LoW/centve:Dockerfile:FROM centos:7
k1LoW/docker-alpine-pandoc-ja:Dockerfile:FROM frolvlad/alpine-glibc
k1LoW/docker-sshd:Dockerfile:FROM docker.io/alpine:3.9
k1LoW/gh-grep:Dockerfile:FROM debian:buster-slim
k1LoW/ghdag:Dockerfile:FROM debian:buster-slim
k1LoW/ghdag-action:Dockerfile:FROM ghcr.io/k1low/ghdag:v0.16.0
k1LoW/ghput:Dockerfile:FROM alpine:3.13
k1LoW/ghput-release-action:Dockerfile:FROM ghcr.io/k1low/ghput:v0.12.0
k1LoW/github-script-ruby:Dockerfile:FROM ghcr.io/k1low/github-script-ruby-base:v1.1.0
[...]

という感じで書けます。

「使っているActionをリストアップする」などは、以下のように書けます。

$ gh grep uses: --include=.github/workflows/* --owner k1LoW | sed -e 's/.*uses:\s*//g' | sort | uniq -c
   9 ./
   1 EndBug/add-and-commit@v7
   2 actions/checkout@master
  10 actions/checkout@v1
  50 actions/checkout@v2
  18 actions/setup-go@v1
  21 actions/setup-go@v2
   4 aquasecurity/trivy-action@master
[...]

--owner オプションは Organization(org) に対してもそのまま使えますので、「orgで使っているActionをリストアップする」ということも実施可能です。

また、gh-grep ならではのオプションとして --url というのがあり、grepでマッチした行のURLを出力してくれます。

「まだioutilを使っているところを探してWebUIで確認したい」というときなどは

$ gh grep 'ioutil\.' --include=**/*.go --owner k1LoW --repo ghput --url
https://github.com/k1LoW/ghput/blob/main/gh/gh.go#L300
https://github.com/k1LoW/ghput/blob/main/gh/gh.go#L313
$ gh grep 'ioutil\.' --include=**/*.go --owner k1LoW --repo ghput --url | xargs open

という感じで、macOSならパイプで open コマンドに値を渡すことでそれぞれブラウザで開いてくれます。

今後

git grep を参考に、欲しいと思ったオプションを追加していこうと思います。UTF-8以外の文字コードにも対応したいです。

あと、APIに優しくできる機能は追加したいです。

カジュアルにリポジトリにgrepしたくなったとき、是非使ってみてください。

*1:並行処理できるようにすればもう少し早くなるとは思いますが、APIエンドポイントに対して優しくないので高速化だけを目的としたチューニングは今のところしない予定です。