Shodo校正APIの結果をpull requestのレビューコメントに自動反映する

Shodo AI校正APIのベータ版に申し込み、利用させていただいています。Shodo、日本語校正のSaaSということで注目していて、今回のAPIベータ版の話がTLに流れてきたので申し込み、当選することができました。

日本語校正サービス・ソフトウェアは商用のものの質はやはり高く、例えば老舗ジャストシステムのJust Right!などは友人のライターが利用していて、評判の良さも聞いています。

ただ、それらはいかんせん良いお値段します。もちろん、良質なサービスに対価を払うことはやぶさかではありませんが、私のようなホビーライターからするとちょっと厳しいお値段です。

ただ、私もブログは細々と継続していて、不定期で有償の記事や執筆をお受けすることもあるため、何らかの校正サービスを使いたいと思っては常々思っていました。

その点、スポットで従量課金的に利用できるSaaSモデルであるShodoは魅力的です。また、APIがあればCI/CDに組み込むのも容易です。私はGitHubで文書を管理することが多いため、そこも嬉しいポイントです。インストールライセンス型のパッケージでは実現しづらい部分でしょう。

action-shodo-lint

ということで、ShodoのAPIを利用して、pull rquestにレビューコメント及び変更提案をしてくれるGitHub Acitonsのカスタムアクションを作りました。

https://github.com/Songmu/action-shodo-lint

ブランチを切ってpull requestを作ると、デフォルトブランチとの差分があるマークダウン(.md)ファイルを校正APIにかけ、以下のような変更提案をしてくれます。

ワークフローも以下のように簡単に書けます。

name: action-shodo-lint
on: [pull_request]
jobs:
  shodo:
    name: runner / shodo
    runs-on: ubuntu-latest
    steps:
    - uses: Songmu/action-shodo-lint@main
      with:
        github_token: ${{ secrets.github_token }}
        api_token: ${{ secrets.SHODO_API_TOKEN }}
        api_root: 'https://api.shodo.ink/@{your_organization}/{your_project}/'

Shodo 校正API自体がベータであるため、このアクションも割と実験的なものにはなりますが、現在のベータ利用者はすぐにご利用いただけます。

スクリーンショットからわかる通り、内部的にはreviewdogを使っています。また、今回別で作った、Go版のShodo API CLIツールであるgoshodoも活用しています。

goshodo

https://github.com/Songmu/goshodo

公式のPython CLIがありますが、個人的にはGoのほうが早く書けるのと、とりあえずやりたいことを実現するためにGoで別のCLIを作りました。

この goshodo は公式の shodo コマンドの lint サブコマンド相当の機能のみ備え、かつ、それを拡張しています。

具体的には、複数ファイルを引数に持てるようにしたことと、-f checkstyle オプションを指定することでCheckstyle形式のXMLを標準出力に出せるようにしたところが拡張点です。

なにがしかの規格に準拠したフォーマットで出力を出せれば、他のツールと連携しやすくなります。実際、reviewdogもcheckstyle入力フォーマットを受け付けているため、とりあえずそれで出せるようにしました。

action.shを見てもらうとわかりますが、やっていることは以下の一行がほぼ全てです。

echo "$files" | xargs goshodo lint -f checkstyle | \
  reviewdog -f="checkstyle" \
    -name="shodo" \
    -reporter=github-pr-review \
...

checkstyle を選んだのは action-textlintでtextlintとreviewdogの連携で使われていたため、それに倣った形です。

ただ、checkstyleフォーマットにも不満があって、具体的には指摘の開始位置を指定できるのですが、仕様上終端を指定できない点が困ります。

なので、現状action-shodo-lintでは無理やりsuggestionsを出力しているのですが、それは校正範囲とその提案が一行に収まる場合のみに限っています。

このあたりの課題感については、reviewdog repository内の以下のドキュメントにまとまっており、読み応えがあるのでおすすめです。

Reviewdog Diagnostic Format (RDFormat)

これを読んだ結論として変更提案をより良く出したい場合には、以下のフォーマットへの対応を検討すると良さそうです。

• SARIF (The Static Analysis Results Interchange Format)
  • ただし仕様が巨大でreviewdogも未対応
• RDFormat (Reviewdog Diagnostic Format)
  • reviewdog独自フォーマット

Shodo APIやCLIへのフィードバック

ベータ版を使わせて頂いている身として、この場でフィードバックを何点か書いてこの記事を終了しようと思います。

校正結果APIのレスポンスの"after"

https://github.com/zenproducts/developers.shodo.ink/blob/master/docs/api.md

レスポンスには必要な情報が網羅されていて良かったです。

一点だけ対応してほしい点として、推奨される置き換えテキストが格納されているafterフィールドに「トル」という校正指示が入るケースがあるのが気になりました。校正後の置き換えテキストは空文字列にしつつ、校正指示文言は別のフィールドに格納されている方がプログラムから扱うには嬉しいです。

また、カラム位置やインデックス番号がすべてUTF-8文字数になっているのはプロダクトの思想の問題だと思うので構わないと思います。ただ、合字などの扱いがどのようになるのかは調べていませんが、気になりました。

校正ルールのAPI管理

校正ルールを設定ファイルやAPIで管理できると、GitHubを用いたような執筆フローにより組み込みやすいと思いました。

公式CLIのlint出力

公式のCLIの出力は、デフォルトでは人間が読みやすい出力になっていて、それは問題ないと思います。

それに加えて、私がgoshodoで拡張したように、複数ファイルを受け取れるようにして、-f オプションで各種出力フォーマットを選択できるようになると嬉しいと思いました。textlintが多くの出力フォーマットに対応していて参考になります。

公式CLIのXDG_CONFIG_HOME対応

これは本当に些細な指摘で好みの話ですが、公式CLIは現状 ~/.shodo/credentials に秘匿情報を書き込みますが、近年はホームディレクトリが汚れないように、 $XDG_CONFIG_HOME/shodo, ~/.config/shodoにこういった情報を書き込むのがセオリーになってきています。特にこだわりがなければそのように変更してみるのはいかがでしょうか。

ref. https://wiki.archlinux.jp/index.php/XDG_Base_Directory

何にせよShodoのことは応援しています!