こんにちは。AWS事業本部コンサルティング部に所属している今泉(@bun76235104)です。
みなさん技術ブログ書かれていますか?
弊社では多くの社員が毎日とんでもない数のブログアウトプットをしています。
その中でもやはりAWS系のサービスに関する記事は多いです。
AWS系のサービス・プロダクトは非常に多く、微妙にtypoしてしまうことがありませんか?
私はかなりあります。代表的な例だと以下のような形ですね。
OK: AWS Security Hub
OK: Security Hub
NG: Amazon Security Hub
NG: SecurityHub
今回はこのような間違いに気づけるようにtextlintルールを作成するとともに、ルール更新を自動化できるようにスクリプトを組んでみました。
npmモジュールとしても公開して、できるだけ使いやすいようにいたしました。
なお、この課題に同じようにtextlintのルールを作ってくれたエンジニアがすでに弊社にいます!(2019年!)
今回はこのイカしたエンジニアの活動を真似しつつ、最近使えるようになったAWSのJSONフィードなどを使って、できるだけルール更新を自動化できるように活動してみた次第です!
本人にも直接言おうと思いますが、この場でもビッグリスペクトを表明させていただきます!
先に結論(何ができるようにしたのか)
たとえば以下のようにtypoを含んだ文章を用意します。
test.md
これはテストです。
Security Hubは間にスペースが必要です。これはOKです。
SecurityHubの書き方ではスペースが足りないので指摘します。これはNGです。
AWSとAmazonの接頭辞も重要です。AWS Security HubはOKです。
Amazon Security Hubは誤っているため指摘します。これはNGです。
同様にAmazon EC2はOKです。
しかし、AWS EC2はNGです。
また、大文字とすべき箇所を小文字にするなどの表記揺れも指摘します。
たとえば、Security HUBはNGです。
当然Ec2もNGです。
これに対して以下のように作成したルールを適用してみます。
# インストール
npm i -g textlint textlint-rule-aws-service-name
# 実行
textlint --rule aws-service-name test.md
こんな感じで指摘してくれます。
5:1 ✓ error SecurityHub => Security Hub aws-service-name
9:1 ✓ error Amazon Security Hub => AWS Security Hub aws-service-name
13:5 ✓ error AWS EC2 => Amazon EC2 aws-service-name
17:6 ✓ error Security HUB => Security Hub aws-service-name
19:3 ✓ error Ec2 => EC2 aws-service-name
23:1 ✓ error vPC => VPC aws-service-name
✖ 6 problems (6 errors, 0 warnings)
✓ 6 fixable problems.
また、VSCodeの拡張機能などを使うことで執筆中にリアルタイムで指摘を表示できます。
使用方法・できること
以下のGitHubリポジトリのREADMEを参照してください。
現状できること・できないこともまとめています。ざっくりまとめると以下のような形です。
指摘可: Amazon Security Hub # AWS Security Hubと指摘してくれる
指摘可: Ec2 # EC2と大文字・小文字の揺れを指摘してくれる
指摘可: SecurityHub #スペースが必要なサービスにスペースがないことを指摘してくれる
指摘不可: Cloud Front #スペースが必要ないサービスにスペースがある 正: CloudFront
ルールファイルの更新について
ルールファイル(auto-create-regular-rules.yml)については、src配下のtsファイルで生成されるロジックを組んでいます。
更新の元ネタとなっているのは、こちらのJSONフィードです。
こちらから必要な情報だけを抜き取り・加工・ymlファイルを生成しています。
ルールファイルの作成ってどうしているの?と少し興味を持たれた方はbun913/textlint-rule-aws-service-nameをご参照ください。
今後の課題について
以下のようなパッションのままに、今回は2,3日くらいでルールを突貫で作ってみました。
- 私が困っているから誰かも困っているだろう
- 今年は初めてOSSにコントリビュートしたりしたけど、もう少しガッツリコードも書いてみたい
- どうせなら初めてnpmパッケージも公開してみたいな
まさにBetter than Nothingという考えでスピードを重視したため、以下のような課題・展望があります。
- 各種自動化
- ルールファイルの変更を検知して、必要な時だけ自動でPullRequestを作成する
- semantic-releaseの導入によるバージョン管理とnpmパッケージ更新の自動化
- Dependabotの導入によるパッケージ更新
- テストの充実
- ルールファイルの検証テストを増やす(あまり書いていない)
- ルールファイルを更新するためのコードのテストを増やす(ほとんど書いていない)
- パッケージの軽量化・パフォーマンス検証
- ざっとVSCodeで記事を書いている感じだとそこまで影響はないように思える
- READMEの充実化
かなり雑なところもありますが、気になる点や改善点があれば以下リポジトリにてIssue・Pull Request作成をお待ちしています!
この記事・このルールが誰かの時間を1秒でも削減することになればうれしいです!
以上、今泉でした!