blog/3 | ikuma-t.com

[Node/Deno]ちょっとしたCLIで使えるスピナー

2023/6/3

に公開

はじめに

ちょっとした CLI を作っている時に、ある程度長い処理（最近だと OpenAI の API 呼び出しとか）を実行している際に、ローディング時間が気になります。

そんなときにスピナーを表示して、実行中であることを視覚的にわかるようにしたいのですが、これをやるためだけにライブラリを追加するのもやや微妙です。

そのため、Node.js/Deno でちょっとしたスピナーを作ってみました。

実装

いずれの場合も基本形は同じで、それぞれのランタイム固有の API に置き換えているくらいです。

Node.js

const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];

export class Spinner {
  constructor(
    private intervalId: NodeJS.Timer | undefined = undefined,
    private currentCharIndex = 0
  ) {}

  start(message?: string) {
    this.intervalId = setInterval(() => {
      const spinner = FRAMES[this.currentCharIndex++];
      const spinnerMessage = message ? `  ${message}` : "";
      process.stderr.write(`\r${spinner}${spinnerMessage}`);
      this.currentCharIndex %= FRAMES.length;
    }, 100);
  }

  stop(message?: string) {
    clearInterval(this.intervalId);
    process.stderr.write(`\r${message ?? ""}`);
  }
}

Deno 実装

const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];

export class Spinner {
  constructor(
    private intervalId: number | undefined = undefined,
    private currentCharIndex = 0
  ) {}

  start(message?: string) {
    this.intervalId = setInterval(() => {
      const spinner = FRAMES[this.currentCharIndex++];
      const spinnerMessage = message ? `  ${message}` : "";
      Deno.stdout.write(
        new TextEncoder().encode(`\r${spinner}${spinnerMessage}`)
      );
      this.currentCharIndex %= FRAMES.length;
    }, 100);
  }

  stop(message?: string) {
    clearInterval(this.intervalId);
    Deno.stdout.write(new TextEncoder().encode(`\r${message ?? ""}`));
  }
}

使い方

// 使い方（Node.js）
import timers from "node:timers/promises";

(async () => {
  const spinner = new Spinner();
  spinner.start("ロード中...");
  await timers.setTimeout(3000);
  spinner.stop();
})();

// Deno
import { sleep } from "https://deno.land/x/sleep/mod.ts";

const spinner = new Spinner();
spinner.start("ロード中...");
await sleep(3); // sleepはミリ秒ではなく、秒を渡すインターフェース
spinner.stop();

spinner 自体には実行時間等の役割は持たせず、あくまで表示のみを行うようにしています。そのため、何かしら長い処理の前後に spinner.start() と spinner.stop() を挟む形で使うことになります。

このインターフェースは大きめの CLI になるとやや微妙かな？と思ったりしましたが、今回はささっと使える Spinner を用意するのが目的だったのでこれでよしとしています。

解説

NodeJS.Timer

https://nodejs.org/api/timers.html#timers🔗

window.setInterval の場合や Deno の場合も、setInterval の戻り値は number なのですが、Node.js ではイベントループを管理するためのオブジェクトとして NodeJS.Timer という型が用意されています。

Node.js においては、setInterval の戻り値がTimeout クラス🔗であり、このクラスの型が NodeJS.Timer です。

実際の型定義は以下の通りです。

declare module "timers" {
  // ...
  let setInterval: typeof global.setInterval;

  // ...
  global {
    namespace NodeJS {
      interface Timer extends RefCounted {
        hasRef(): boolean;
        refresh(): this;
        [Symbol.toPrimitive](): number;
      }

      // ...
    }
  }
}

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/3197efc097d522c4bf02b94e1a0766d007d6cdeb/types/node/timers.d.ts#L31-L35🔗

interface RefCounted {
  ref(): this;
  unref(): this;
}

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/3197efc097d522c4bf02b94e1a0766d007d6cdeb/types/node/globals.d.ts#L234-L237🔗

ドキュメントを読む限りでは、以下のような感じでした。

デフォルトでは Timer はイベントループが有効な間は生存する
このデフォルトの挙動をカスタマイズできるように、ref() と unref() が用意されている
Timer#refresh() は Timer オブジェクトをリフレッシュする（タイマーがリセットされる）
Timer#Symbol.toPrimitive() は Timer オブジェクトを数値で返す。これによって、ブラウザでの setInterval との実装の互換性を実現できる。

今回のように、ブラウザの setInterval と同じような感覚で使用している場合にはあまり効果はないですが、イベントループを意識した処理を書く際にはこれらのインターフェースが役に立つのかも？

キャリッジリターン

\rのことですが、単純にconsole.log()してしまうと、改行が発生してスピナーのフレームが変わるたびに 1 行ずつ表示されてしまいます。

そのため、それぞれのランタイムの出力を利用して出力し、さらにキャリッジリターンを使って、カーソルを行の先頭に戻すようにしています。これでその位置に留まり続けるスピナーの完成です。

カスタマイズ

ローディングに表示されるアイコンを変える

FRAMES に好きなアイコンを定義すれば、その通りに表示されます。

今回表示している点字は https://github.com/sindresorhus/cli-spinners🔗 を参考にさせてもらいましたが、これ以外にも適当な絵文字（🍣 とか 🍺 とか）を使っても良いかもしれません。

標準出力にまぎれないようにする

こういったことをしたいユースケースとしては、「ターミナル上ではローディングを見せたいけど、処理結果を pipe 等で後続処理に渡したいので、標準出力には出力したくない」というケースかと思います。これは現時点での暫定解なのですが、標準出力ではなく標準エラー出力に出力すればとりあえず解決します。

解決は解決なんですが、本来エラーのために用意されている箇所を、こういったハックのために使うのはいかがなものかという気もしますね…。

おわりに

今回 intervalId を持っていて欲しかったので、イメージしやすくクラスとして作りましたが、関数型でやるとどうなるのかは気になるところ。気が向いたらやってみようと思います。

…こういっていて気が向いたことはないので、多分やりません。どなたか実装されたら教えてください。

[Node/Deno]ちょっとしたCLIで使えるスピナー

公開日: 2023/6/3

『問いのデザイン創造的対話のファシリテーション』を読んだ

2023/6/3

に公開

はじめに

お通夜会議を脱したい

「こういう感じで考えてみたんですけど、ご意見ある方いらっしゃいますか？」

「…」

沈黙が走る。

たたき台を作ってまとめる、そこまでは順調に進んだが、実際にチームにシェアする場面で投げかけた一言にはなかなかレスポンスがなく、どう進めようか画面の前で汗ダラダラ…。何か前に進めなければと思って振り絞るも、結局進め方がわからず「ｱｯ…」となってしまう。なんやかんやしているうちに、1 人が出したよさそうな意見がめちゃめちゃ眩しい…。なんだかいい感じだ！みんなも良さそうと言っているし…ええいもう「なんとかなれ〜！！」。

…とまあここまで極端ではなくても、参加者の意見をリアルタイムに汲み取りながら進めていくタイプのミーティングでこうした状況になってしまうことはままあります。

そのためどうにか再現性高くこのお通夜会議¹を脱したいと思っていました。

『問いのデザイン創造的対話のファシリテーション』を読んだ

book 画像引用元: https://book.gakugei-pub.co.jp/gakugei-book/9784761527433/🔗

前から認識してはいたのですが、課題感が募った今がまさに読み時だろうと思って問いのデザイン創造的対話のファシリテーション🔗を読んでみたので、この本を読んで得たヒントをまとめてみます。

なお本書の構成としては「課題のデザイン」「プロセスのデザイン」の前後編に分かれており、ざっくり前者は What を、後者は How を解説した内容になっています。どちらも参考になる部分がとても多かったですが、今回は特にお通夜会議攻略の糸口という観点で「プロセスのデザイン」に今の自分に刺さるヒントがあったので、そちらの内容を整理してみます。

ファシリテーションのヒント

課題への道を経験のプロセスとしてデザインする

これは 4 章ワークショップのデザインに書かれている内容なので、通常運営のミーティングとはややニュアンスが異なるかもしれませんが、自分としては十分応用できる内容だと思いましたので自分の解釈と共に紹介します。

まず本書におけるワークショップは「普段とは異なる視点から発想する、対話による学びと創造の方法」となっていて、その実現のために経験のプロセスをデザインすることが大事だと言います。具体的には最終的な課題に対して、「導入」「知る活動」「作る活動」「まとめ」の 4 つのプロセスを設計していきます。美味しい料理を作るために下ごしらえが必要なように、課題に対してアウトプットを出す際にも、情報を知ることなり、それぞれがイメージやビジョンを巡らせるなどの下準備が必要というわけです。

よくよく考えてみるとお通夜会議も、得てして「問いかけられた側が答えを持っている」かのような前提で始まることが多い気がします。実際のところは、その会議を持ちかけた側が課題に対しての熱量と情報量が高く、反対に持ちかけられた側は日常の別タスクをこなしているところからその課題に向き合うため、全くもって準備万端ではありません。そう考えると反射的に答えられないこともよく頷けます。

そのため会の目的にもよりますが、最終的な課題へ参加者の頭を切り替えさせるようなアイスブレイクや問いの足場を段階的に設けることが必要になりそうです。例えばスプリントレトロスペクティブであればいきなり KPT をあげるという「作る活動」に移行するのではなく、まずはチームでいいところも悪いところもあげるようなアイスブレイクを「導入」として用意し、そのスプリントでどんな積み上げをしてきたのかを「知る活動」を設けた上で、KPT に挑むという具合です。（これに倣って最近では「賛否両論」というアイスブレイクをレトロスペクティブに取り入れてみたりしています。これはまたいつか紹介します。）

例に挙げたスクラムイベントのようにある程度定期的に開催されるイベントはこのようにかっちりと当てはめやすいですが、日々流動的に発生するミーティングにこれを適用するのはやや難しいなと感じています。そのため、大枠としてミーティング全体を Input・Output の 2 枠で捉えて、Output に対して必要な Input の部分が荒くないか？という観点でミーティングを観察し、必要に応じて後述の制約を設けた問いを投げるようにしてみています。現状成功率は 8 割くらいですが、全く道標がない状態よりも大枠を一定のプロセスとして捉えることは、一定成果があるように思います。

問いに制約を設ける

もう 1 つなるほどと思ったポイントが、問いに対して制約を設けることです。

具体的には以下のようなテクニックを使うことで、問いに対して制約を課し、参加者の思考の足がかりを形成することを試みます。

価値基準を示す形容詞をつける
ポジティブとネガティブを示す
時期や期間を指定する
想定外の制約をつける
アウトプットの形式に制約をつける

お通夜会議でよくある「何か意見あればお願いします」や「感想でもなんでもどうぞ」は、問いかけとしては広すぎるため、参加者からすると「どこから考え始めていいのかわからない」ことに加え、一見どんな意見も許容しているように見えて、参加者心理では回答のガイドラインがないために「この内容を答えてしまっていいのか？」という不安が生まれてしまいます。

各テクニックの詳細は本書を参照していただくとして、自分がいいなと思ったのが「アウトプットの形式に制約をつける」テクニックです。この方法では、「〇〇するための 3 つの条件は？」「〇〇を起承転結で表すと？」といった具合にアウトプットの形式に制約がかかっています。お通夜会議では Input のフェーズで話している内容が絞られておらず、自由に発散しているため議論が収束しにくいです。そのため、いくつかの発散が行われたタイミングで「この中から 1 つだけ対応すると考えた時、どれを選びますか？」と問いかけを行うと、参加者の思考の足がかりになり、議論が進みやすくなるのではないかと思いました。²

感想

本書を読むまでは、お通夜会議に陥った際に、出口までの順路がぐにゃぐにゃになってしまって、着地できるかどうかは運任せでした。

最近では少しずつちいかわ状態に陥った際にもリカバリがわかってきて、「今はインプット・アウトプットどちらに当てるべき時間か」「場に投げられている問いは広いか？広いならどう制約をつけたせそうか？」といったことを考えながら発言したりしています³。これは別に自分がファシリテーターではなくても有効な考え方で、自分が一参加者の場合もお通夜会議になりそうだったら、今回挙げたようなポイントで出口を探っています。ファシリテーターはあまり余裕がないので、共通認識として本書の考え方が通っていると、全体の議論の質も上がりそうです。

色々試しつつ、少し成果を出しつつもありますが、まだまだ課題も色々あります。

ファシリテーターとしての帽子と開発者としての帽子を同時に被るのは大変
- 基本的に「この問いが広いのか、狭いのか」「全体の熱量はどのくらいか」といった観点は、議論から一歩引いた姿勢になる。
- 日常に湧き起こるミーティングのほとんどは自身も当事者であり、それだけがうまくできていればいいわけではない（本質は課題を解くこと）。
- 別の誰かがコントロールしてくれている、誰かが意識しなくても自然とうまく進んでいるときであれば、当事者としてのアクセルを全開にするような切替が求められそうだけど、難しい。
ファシリテーターは黒子だけど、うまく解決できることが楽しくなってくると黒子ではなくなる
- この手法で楽しくなっちゃっているレベルはまだまだなんだろうなという気持ち
- エンジニアの麻疹のように、まずはガッチリ使い込んで、その後に自分なりの解釈を加えていきたい
いつも成功するわけではない
- いろいろ試している感覚として、お通夜になったときにそこに再度アクセルをかけるのは 8 割 5 分くらいの成功できていますが、それ以降確実に収束の方向性へ迎えるかは正直運なので、確度をあげたい

というわけでもう少し意識的に続けてもっと良くできるように頑張ってみたいと思います。

別名ちいかわ会議 ↩
ちょくちょく仕事でもこの質問を投げる機会があるんですが、聞く時には脳内で BUMP OF CHICKEN の「ダイヤモンド」が流れています（サビの歌詞参照）。 ↩
しかしこれが周囲から見て機能しているかはまた別問題である。。。 ↩

『問いのデザイン創造的対話のファシリテーション』を読んだ

公開日: 2023/6/3

アイコンが重なってて、ホバーするとニュッとするそれ

2023/5/28

に公開

アイコンが重なってて、ホバーするとニュッとするそれを作ろう

dev_to_sample

これは dev.to の記事リアクションの表示です。Slack でハドルミーティングが発生している時の参加者の表示にもこういったアイコンを重ねるレイアウトがよく見られます。

よく見かけるけど自分では作ったことがなかったので、CSS Animated Grid Layouts🔗を参考にしつつ、今回はこちらを少し捻ったもの練習として作ってみました。

sample

要件

アイコンの数は 1〜5 個
アイコンは重ねて表示する
アイコンのいずれかをホバーすると、全体が広がり、後ろのアイコンも見えるようになる

実装

https://codepen.io/ikumatadokoro/pen/RweOMXb?editors=1100🔗

実装メモ

1 次元配置なので、Flexbox でもいけると思うのですが、今回は参考ソースに合わせて GridLayout での実装になります。

アイコンを重ねて表示する

このレイアウトの中核は、アイコンより狭めに設定された列トラックです。

今回は横方向にアイコンを積んでいくため、grid-auto-flow: columnを指定した上で、grid-template-columnsで列の数を指定します。

このとき、列幅を以下のように定義しています（必要部分のみ抜粋）。

.icons {
  --gap: 1em;
  --icon-size: 5em; /* 実際のアイコンのサイズ */
  --overlap-size: 2em; /* 列トラックのサイズ。アイコンよりも小さめ */
  --num-children-1: calc(var(--num-children) - 1);
  --grid-cell-size: var(
    --overlap-size
  ); /* アイコンよりも小さめの列トラックが定義されているので、重なって見える */

  display: grid;
  grid-auto-flow: column;
  grid-template-columns: repeat(var(--num-children), var(--grid-cell-size));
  grid-auto-columns: var(--grid-cell-size);
  gap: var(--gap);
  /* 植木算的な感じで全体の幅を要素に応じて調整している */
  width: calc(
    var(--grid-cell-size) * var(--num-children-1) + var(--gap) * var(
        --num-children
      ) + var(--icon-size) + var(--border-size)
  );
}

これで各列が重なるようになりました。

ホバー表示

ホバー時は、scaleを使って拡大表示しています。また、z-indexを指定して、ホバーしたアイコンが最前面に表示されるようにしています。

.icons > div:hover {
  scale: 1.1;
  z-index: 100;
  border-width: var(--border-size);
  border-color: var(--icon-color);
}

要素数に応じて幅計算を行うための CSS 変数

.icons:where(:has(> *:nth-of-type(1):last-child)) {
  --num-children: 1;
}
.icons:where(:has(> *:nth-of-type(2):last-child)) {
  --num-children: 2;
}
.icons:where(:has(> *:nth-of-type(3):last-child)) {
  --num-children: 3;
}
.icons:where(:has(> *:nth-of-type(4):last-child)) {
  --num-children: 4;
}
.icons:where(:has(> *:nth-of-type(5):last-child)) {
  --num-children: 5;
}

だいぶ力技感がありますが、5 個までの制約のもとに CSS だけで幅を計算するために、上記のような CSS 変数を定義しています。

where: 条件を満たす要素を選択する。
has：子要素又は子孫要素の中に、指定したセレクタにマッチする要素が存在する場合に、その親要素を選択する。

つまりこのセレクタでは「.iconsクラスの要素で、その最後の子要素がnth-of-type(1)の要素を持っているもの（=1 番目の要素）を選択する」という意味になります。要素数が 2 個の場合は、nth-of-type(2)の要素を持っているもの（=2 番目の要素）を選択する、というように、要素数に応じて幅を計算することが可能になります。

おわりに

全ての要素を削減したくはないけど、なんとなくの全体感を把握したい。そんなときに使えるのが「重ねて表示する」レイアウトと考えており、その目的に hover での展開を加えるメリットがあまりないので、実際にはこのレイアウトを使う日は少ないかも？と思っています（hover を実装したい時は「各要素は細かく見えるようにしたいけど、全体を見た時に他の要素も多いため、通常時は少し詰めて表示したい」と考えるときではないでしょうか）。

いずれにせよアイコンを重ねる実装自体は共通で使えるので、grid によるレイアウトの引き出しとして今後も活用していきたいと思います！

アイコンが重なってて、ホバーするとニュッとするそれ

公開日: 2023/5/28

書籍「Web Workers」を読んだ

2023/5/21

に公開

picture_large978-4-87311-596-2

画像引用元：https://www.oreilly.co.jp/books/9784873115962/🔗

オライリーのWeb Workers🔗を読みました。そろそろ Cloudflare Workers を触ろうと思っていて、そしたら Service Worker は知らんとな → そもそも Worker ってなんとなくわかるけど、ちゃんと説明できないな、ということで少し古めですが本書を読んで基本をかじってみることにしました。

この本で学んだこと

Web Worker は HTML5 の機能の一つで、JavaScript でマルチスレッドを実現するためのもの。メインスレッドの DOM を操作できない制約がある。
main と worker でオブジェクトは共有されない。メッセージをやりとりすることで通信するが、オブジェクトのコピーによりパフォーマンスに影響が出る場合は、移譲可能オブジェクト🔗を利用できる。
Web Worker の種類には Dedicated Worker（専有）と Shared Worker（共有）がある。前者は 1 つのスクリプトからしかアクセスできないが、後者は複数のスクリプトからアクセスできる。

総じて「そもそも Web Worker ってなにもの？？」という超初歩的な問いに対しての答えを得ることができました。Web Worker における Hello World 的な存在が素数計算だということも初耳でした（今後サンプル作る時にやろう）。

読んでいる中でいくつか「これはどうなんだろう？」と疑問に思って調べたポイントをいくつかまとめます。

Web Worker VS Promise

「メインスレッドから処理を移譲することで、コンテンツの描画をブロックしないでおくことができる」という内容を見た際に、 これは Promise でも実現できるのでは？ と思いました。例えばインポート処理を行うボタンを押した際に、取り込み処理自体は Promise で非同期に実施し、適当にローディングアニメーションを付けて他の箇所は操作可能にしておくという実装はそれほど難しくありません。

この質問に対しての 1 つの回答は、 「CPU に負荷のかかる処理は、メインスレッドで順序を入れ替えても解決しないので Web Worker を使う意味はある」 です。

例として処理時間が 30 秒かかる画像のリサイズ処理を考えます。Promise で非同期に実行する場合、結局は画像のリサイズ処理を行うスレッドが 1 つしかないので、同期的に 30 秒待つことはなくとも、トータルとしては 30 秒の処理時間が必要になります。

一方で Web Worker を複数起動すれば、それらはメインスレッドとは別のスレッドとなり、その処理を並列で処理することができます。3 つの Worker をたて、1 つの Worker が捌く量を全体の 1/3 にすることで、ガバガバ計算ですが各スレッド単位での実行時間は 10 秒になります。そしてこれらは並列に処理されるので総実行時間も 10 秒です。

そのため計算処理自体が重い場合は Web Worker の使用を検討する材料の 1 つになりうるでしょう。

Shared Worker VS BroadCastChannel

これは半分勘違いだったのですが、 「複数のブラウジング・コンテキスト間で情報を共有できるという側面だけからこれらを見た時に、それぞれをいつ使うのか？」 と疑問に思いました。

そこであらためてそれぞれがどういう API なのか書き出してみました。

BroadCastChannelAPI: 異なる文書やウィンドウ間でメッセージを送信するための API
Shared Worker: 複数の文書やウィンドウから利用可能な共有のワーカースレッドを作成するための API

「複数のブラウジング・コンテキスト」をターゲットに機能していることは共通していますが、単純にメッセージを送信するのか、それとも実際に計算処理やコネクションを保持するといった具体的な処理を行うのかという点で、そもそもの目的が異なっています。

そのためこれらは競合するものではありません。例えば Shared Worker で Web Socker のコネクションを共有し、各ブラウジング・コンテキストに対しては BroadCastChannelAPI を使ってメッセージを送信するといった使い方もできるでしょう。

実際に実装していないので動くのかはわかりませんが、HTTP/1.1 における Server Sent Event のドメイン接続上限（6 つまで）を、Shared Worker を使って回避するといった使い方も可能なのではないでしょうか。

この本で学べなかったこと

Service Worker について
結局 Worker を実際のアプリケーションレベルでどう使用すべきか
- comlink を使うとか？
TypeScript における Worker の利用方法

この本を読む際の注意点

この本は 2013 年に出版された本です。そのため、以下の点に注意して読む必要があります。

出版当時にまだ世に出ていなかった Service Worker についての解説がありません。
全体的にサンプルコードが古いです。具体的には、大きいところで現状と異なる仕様の Twitter からのデータ取得を行うサンプル（これは今年の頭に出しても動かなくなっていそうですが）や、https ではなく http が使われている、細かいところでは変数宣言でvarが多用されているなど。
ブラウザの対応状況が諸々異なっています。Can I Use などで適宜確認してください。

感想

やや内容は古めでしたが、内容がコンパクトだったので数時間で読め、ざっくりと Web Worker とは何者かについて知ることができました。

Web Worker がメインスレッドの DOM 操作ができないことがわかると、PartyTown が Service Worker から同期 XHR で DOM を参照している仕組みが、俄然興味深いものに感じます。

というわけで今度は MDN と web.dev あたりを読みながら Service Worker に対する理解を深めていきたいです。

書籍「Web Workers」を読んだ

公開日: 2023/5/21

GitHub Actionsをローカルで試せるactを試してみる

2023/5/10

に公開

最近開発生産性を取得したりで GitHub Actions をよく書いています。最近では GitHub Actions の VSCode 拡張が出てきたことで、構文的なエラーには気が付きやすくなりましたが、やはり実際に動作するかは GitHub に push しなければならず、やや面倒でした。

N 番煎じではありますが、ローカルで GitHub Actions を実行できるnektos/act🔗を使って、GitHub Actions のローカル実行を試してみました。

act の概要

act は Docker を利用して、.github/workflows のワークフローを実行するための Go 製のツールです。実行環境は現時点で ubuntu のみです。

https://github.com/nektos/act#runners🔗

インストール方法はこちら🔗の通りで、今回は Mac で使用するため、HomeBrew でインストールします。

brew install act

act の使い方

https://github.com/IkumaTadokoro/forke🔗

ここからはこのリポジトリをサンプルに進めていきます。このリポジトリでは以下の GitHub Actions が定義されています。

.github/workflows
├── lint.yml
├── test.yml
└── release.yml

リポジトリのワークフローの確認

まずは対象のワークフローが認識されているかを確認します。

$ act -l

WARN  ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠
Stage  Job ID   Job name  Workflow name  Workflow file  Events
0      lint     lint      Lint           lint.yml       push
0      release  release   Release        release.yml    push
0      test     test      Test           test.yml       push

期待通り、3 つのワークフローが認識されています。 M1 Mac を使っているので、実行時にエラーが出るかもと警告が出ていますが、一旦無視して進めます。

ワークフローの実行

今回は vitest によるテストを実行する Job「test」を実行してみます。特定の Job を指定するには-jオプションを使います。初回なので、DryRun（-n）で実行してみます。

$ act -j test -n

? Please choose the default image you want to use with act:

  - Large size image: +20GB Docker image, includes almost all tools used on GitHub Actions (IMPORTANT: currently only ubuntu-18.04 platform is available)
  - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with all actions
  - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions

Default image and other options can be changed manually in ~/.actrc (please refer to https://github.com/nektos/act#configuration for additional information about file structure)  [Use arrows to move, type to filter, ? for more help]
  Large
> Medium
  Micro

*DRYRUN* [Test/test-1] 🚀  Start image=catthehacker/ubuntu:act-latest
*DRYRUN* [Test/test-2] 🚀  Start image=catthehacker/ubuntu:act-latest
*DRYRUN* [Test/test-3] 🚀  Start image=catthehacker/ubuntu:act-latest
*DRYRUN* [Test/test-2]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=true
*DRYRUN* [Test/test-3]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=true
*DRYRUN* [Test/test-1]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=true
*DRYRUN* [Test/test-3]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[]
*DRYRUN* [Test/test-3]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[]
*DRYRUN* [Test/test-2]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[]
*DRYRUN* [Test/test-2]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[]
*DRYRUN* [Test/test-1]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[]
*DRYRUN* [Test/test-1]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[]
*DRYRUN* [Test/test-2]   ☁  git clone 'https://github.com/actions/setup-node' # ref=v3
*DRYRUN* [Test/test-3]   ☁  git clone 'https://github.com/actions/setup-node' # ref=v3
*DRYRUN* [Test/test-1]   ☁  git clone 'https://github.com/actions/setup-node' # ref=v3
*DRYRUN* [Test/test-2] 🧪  Matrix: map[node-version:18.x os:ubuntu-latest]
*DRYRUN* [Test/test-2] ⭐ Run Main actions/checkout@v3
*DRYRUN* [Test/test-2]   ✅  Success - Main actions/checkout@v3
*DRYRUN* [Test/test-2] ⭐ Run Main Use Node.js 18.x
*DRYRUN* [Test/test-2]   ✅  Success - Main Use Node.js 18.x
*DRYRUN* [Test/test-2] ⭐ Run Main Install
*DRYRUN* [Test/test-2]   ✅  Success - Main Install
*DRYRUN* [Test/test-2] ⭐ Run Main Unit Test
*DRYRUN* [Test/test-2]   ✅  Success - Main Unit Test
*DRYRUN* [Test/test-2] ⭐ Run Post Use Node.js 18.x
*DRYRUN* [Test/test-2]   ✅  Success - Post Use Node.js 18.x
*DRYRUN* [Test/test-2] 🏁  Job succeeded
*DRYRUN* [Test/test-3] 🧪  Matrix: map[node-version:20.x os:ubuntu-latest]
*DRYRUN* [Test/test-3] ⭐ Run Main actions/checkout@v3
*DRYRUN* [Test/test-3]   ✅  Success - Main actions/checkout@v3
*DRYRUN* [Test/test-3] ⭐ Run Main Use Node.js 20.x
*DRYRUN* [Test/test-3]   ✅  Success - Main Use Node.js 20.x
*DRYRUN* [Test/test-3] ⭐ Run Main Install
*DRYRUN* [Test/test-3]   ✅  Success - Main Install
*DRYRUN* [Test/test-3] ⭐ Run Main Unit Test
*DRYRUN* [Test/test-3]   ✅  Success - Main Unit Test
*DRYRUN* [Test/test-3] ⭐ Run Post Use Node.js 20.x
*DRYRUN* [Test/test-3]   ✅  Success - Post Use Node.js 20.x
*DRYRUN* [Test/test-3] 🏁  Job succeeded
*DRYRUN* [Test/test-1] 🧪  Matrix: map[node-version:16.x os:ubuntu-latest]
*DRYRUN* [Test/test-1] ⭐ Run Main actions/checkout@v3
*DRYRUN* [Test/test-1]   ✅  Success - Main actions/checkout@v3
*DRYRUN* [Test/test-1] ⭐ Run Main Use Node.js 16.x
*DRYRUN* [Test/test-1]   ✅  Success - Main Use Node.js 16.x
*DRYRUN* [Test/test-1] ⭐ Run Main Install
*DRYRUN* [Test/test-1]   ✅  Success - Main Install
*DRYRUN* [Test/test-1] ⭐ Run Main Unit Test
*DRYRUN* [Test/test-1]   ✅  Success - Main Unit Test
*DRYRUN* [Test/test-1] ⭐ Run Post Use Node.js 16.x
*DRYRUN* [Test/test-1]   ✅  Success - Post Use Node.js 16.x
*DRYRUN* [Test/test-1] 🏁  Job succeeded

初回ではどのサイズの image を利用するか聞かれます。一般的なワークフローであれば Medium で良さそうです。無事にワークフロー自体は正常終了したようなので、今度はテストの内容を変えて再度実行してみます。

# 日付差分を分単位で計測する関数の期待値を変えて失敗させてみる。
  test.each<[Date, Date, number]>([
    [new Date("2021-01-01T00:00:00Z"), new Date("2021-01-01T01:00:00Z"), 60],
   [new Date("2021-01-01T00:00:00Z"), new Date("2021-01-01T00:06:00Z"), 6],
   [new Date("2021-01-01T00:00:00Z"), new Date("2021-01-01T00:06:00Z"), 7],
    [new Date("2021-01-01T00:00:00Z"), new Date("2021-01-01T00:05:00Z"), 5],
    [new Date("2021-01-01T00:00:00Z"), new Date("2021-01-01T00:01:00Z"), 1],
    [new Date("2021-01-01T00:00:00Z"), new Date("2021-01-01T00:00:01Z"), 0],
  ])(`[DEFAULT: minute]calcTimeDiff(%s, %s): %s`, (date1, date2, expected) => {
    expect(calcTimeDiff(date1, date2)).toBe(expected);
  });

$ act -j test

...

[Test/test-1]   ✅  Success - Main Install
[Test/test-1] ⭐ Run Main Unit Test
[Test/test-1]   🐳  docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/3] user= workdir=
|
| > [email protected] test:ci
| > vitest run
|
|
|  RUN  v0.30.1 /Users/ikuma/src/github.com/IkumaTadokoro/forke
|
|  ✓ src/lib/__test__/mathUtil.test.ts  (12 tests) 5ms
|  ✓ src/lib/__test__/stat.test.ts  (9 tests) 8ms
|  ❯ src/lib/__test__/dateUtil.test.ts  (24 tests | 1 failed) 56ms
|    ❯ src/lib/__test__/dateUtil.test.ts > calcTimeDiff > [DEFAULT: minute]calcTimeDiff(2021-01-01T00:00:00.000Z, 2021-01-01T00:06:00.000Z): 7
|      → expected 6 to be 7 // Object.is equality
|
| ⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯
|
|  FAIL  src/lib/__test__/dateUtil.test.ts > calcTimeDiff > [DEFAULT: minute]calcTimeDiff(2021-01-01T00:00:00.000Z, 2021-01-01T00:06:00.000Z): 7
| AssertionError: expected 6 to be 7 // Object.is equality
|  ❯ src/lib/__test__/dateUtil.test.ts:41:40
|      39|     [new Date("2021-01-01T00:00:00Z"), new Date("2021-01-01T00:00:01Z"…
|      40|   ])(`[DEFAULT: minute]calcTimeDiff(%s, %s): %s`, (date1, date2, expec…
|      41|     expect(calcTimeDiff(date1, date2)).toBe(expected);
|        |                                        ^
|      42|   });
|      43|
|
|   - Expected  - 1
|   + Received  + 1
|
|   - 7
|   + 6
| ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯
|
|  Test Files  1 failed | 2 passed (3)
|       Tests  1 failed | 44 passed (45)
|    Start at  20:40:05
|    Duration  868ms (transform 143ms, setup 0ms, collect 456ms, tests 69ms, environment 0ms, prepare 514ms)
|
[Test/test-1]   ❌  Failure - Main Unit Test
[Test/test-1] exitcode '1': failure
[Test/test-1] 🏁  Job failed

...

マトリクス実行しているのと、act 側のログが大量に出ているので実行部分のみ抜粋ですが、ローカルファイルの変更を反映してワークフローが実行されていることがわかります。これは便利。

ログ出力を抑制する

「act 側のログが大量に出ている」と先に挙げましたが、実例としては次のようなものです。

[Test/test-3]   💬  ::debug::{"archiveLocation":"***","cacheKey":"node-cache-linux-npm-eb3cb123726e2245d1ac05822a0ed4f5b7ab0e59926ef990db3189e8565ae3f7","result":"hit"}
[Test/test-3]   💬  ::debug::Archive Path: /tmp/71f659f3-b296-414e-a049-7495a8b9fd5e/cache.tzst
[Test/test-3]   💬  ::debug::Use Azure SDK: true
[Test/test-3]   💬  ::debug::Download concurrency: 8
[Test/test-3]   💬  ::debug::Request timeout (ms): 30000
[Test/test-3]   💬  ::debug::Cache segment download timeout mins env var: undefined
[Test/test-3]   💬  ::debug::Segment download timeout (ms): 3600000
| Cache Size: ~39 MB (40876809 B)
| [command]/usr/bin/tar --use-compress-program unzstd -xf /tmp/71f659f3-b296-414e-a049-7495a8b9fd5e/cache.tzst -P -C /Users/ikuma/src/github.com/IkumaTadokoro/forke
| Cache restored successfully
| Cache restored from key: node-cache-linux-npm-eb3cb123726e2245d1ac05822a0ed4f5b7ab0e59926ef990db3189e8565ae3f7
[Test/test-3]   ❓ add-matcher /run/act/actions/actions-setup-node@v3/.github/tsc.json
[Test/test-3]   ❓ add-matcher /run/act/actions/actions-setup-node@v3/.github/eslint-stylish.json
[Test/test-3]   ❓ add-matcher /run/act/actions/actions-setup-node@v3/.github/eslint-compact.json
[Test/test-3]   ✅  Success - Main Use Node.js 20.x
[Test/test-3]   ⚙  ::set-env:: NPM_CONFIG_USERCONFIG=/tmp/.npmrc
[Test/test-3]   ⚙  ::set-env:: NODE_AUTH_TOKEN=XXXXX-XXXXX-XXXXX-XXXXX
[Test/test-3]   ⚙  ::set-output:: node-version=v20.1.0
[Test/test-3]   ⚙  ::set-output:: cache-hit=true
[Test/test-3]   ⚙  ::add-path:: /opt/hostedtoolcache/node/20.1.0/arm64/bin
[Test/test-3] ⭐ Run Main Install
[Test/test-3]   🐳  docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/2] user= workdir=

毎回この量が出るのはしんどいので、これを-q, --quietオプションで抑制します。

$ act -j test -q

…が、期待通りにはなりませんでした。この--quietオプションはワークフロー側のログ出力レベルを抑制するもので、今回のワークフローの例で言えば、vitest の実装結果が省略されることになります。

おわりに

ログ出力の多さゆえに使えないということはないですが、このツールは試行錯誤中に利用したいものだと思うので、デバッグ用の情報はシンプルな方が嬉しい気がします。それを加味してもローカルで検証できることで GitHub への push 回数は抑制できると思うので、しかるべきときに使っていきたいですね。

GitHub Actionsをローカルで試せるactを試してみる

公開日: 2023/5/10

ワークスペース内の画像のパスをパンッとはれるVSCode拡張をリリースした

2023/5/6

に公開

はじめに

demo

ワークスペースにある画像のパスをそのまま or Markdown 形式でパンッと簡単にエディタに挿入できる VSCode 拡張、その名も SrcPan をリリースしました。

https://marketplace.visualstudio.com/items?itemName=IkumaTadokoro.srcpan🔗

この VSCode 拡張機能には現時点で以下の機能があります。

ワークスペース内の画像ファイルをサイドバーに一覧表示する機能
選択した画像をサイドバーでプレビュー表示する機能
選択した画像のパスをそのまま or Markdown 形式でエディタに挿入する機能

なぜ作ったか

このブログは各記事を MDX で作成しています。記事には画像をしばしば挿入しているのですが、これに際して私が感じていた課題点は以下の 2 点です。

ブログコンテンツとブログ自体のコードが 1 つのリポジトリに共存しているため、画像以外のものがファイルエクスプローラーに表示されてしまい、画像を探すのが面倒である
astro では静的コンテンツのパスは「public」を省略して記述するルールだが、しばしば忘れる

これを解決するために、最初に述べたような「画像だけを一覧して、プレビューした上で、Markdown のパスですぐ挿入できる」VSCode 拡張を作りました。

何ができるのか

基本機能

srcpan-view

拡張機能をアクティビティバーで選択すると、2 つのペインが開きます。

上部は現在開いてるワークスペースに含まれる画像を、ディレクトリ構造そのままに表示するペインです。そして下部がプレビュー表示ペインで、上部で選択した画像をプレビュー表示します。

上部のペインで画像をホバーすると、リンク挿入ボタンが表示されます。このボタンをクリックすると、画像のパスをそのまま or Markdown 形式でエディタに挿入します。

【設定】挿入するパスのフォーマット変更

デフォルトでは、画像のパスをそのまま挿入します。しかし、astro では静的コンテンツのパスは「public」を省略して記述するルールなので、そのディレクトリにある画像だけは、最初のパス部分を省略した形式で挿入したいという要望がありました。これに対応するため、正規表現でフォーマットを変更したいパスと、変更後のパス形式を指定すると、その形式でパスを挿入できるようにしました。

例えばこのブログでは先のとおり astro のルールに合わせて「public」から始まるディレクトリでは、その一つ下の階層からのパスを貼り付けるようにしたいです。そこで、settings.json に以下のように設定します。

"srcpan.pathFormatRules": [
    {
        "pathRegExp": "^\\/public(\\/.+)$",
        "replacement": "$1"
    }
],

pathRegExp には正規表現を指定することができ、replacement には任意の文字列を指定することができます。pathRegExp にキャプチャグループを指定した場合は、replacement に$1のように指定することで、キャプチャされた部分を挿入することができます。この設定により以下のように、/publicから始まるパスでは、/publicの 1 つ下の階層から始まるパスを挿入できるようになりました。

本来のパス： /public../../assets/images/publish-srcpan/srcpan-view.png
挿入されるパス： ../../assets/images/publish-srcpan/srcpan-view.png

このルールは配列形式で指定するので、複数のルールを指定することができます。public ディレクトリ、assets ディレクトリでそれぞれ最初の階層を省略したい場合は以下のようにします。

"srcpan.pathFormatRules": [
    {
        "pathRegExp": "^\\/public(\\/.+)$",
        "replacement": "$1"
    },
    {
        "pathRegExp": "^\\/assets(\\/.+)$",
        "replacement": "$1"
    }
],

【設定】一覧から除外するディレクトリを指定

デフォルトではワークスペースに含まれる.gitignoreを読み取り、そこに含まれるディレクトリは表示から除外するようになっています（これ自体も設定: useGitIgnore を false にすることで無効化できます）。

// 無効にする場合
"srcpan.useGitIgnore": false

.gitignore にはないが、一覧に表示する必要ないディレクトリがある場合は、追加で設定を記述することで対象外とすることができます。例えばこのブログではpublic以外は記事を作成する際に不要です。そのため、src/, integrations/ それぞれのディレクトリを除外するように設定します。

"srcpan.excludePatterns": [
    "src/**/*",
    "integrations/**/*"
]

ややこしいですが、こちらは glob パターンを配列で指定します。本当はいずれのオプションとも正規表現か glob パターンのどちらかに寄せようと考えていたんですが、パスの方は置換後の文字列を宣言的にかけた方が良いと思い正規表現を採用し、除外するディレクトリの方は glob パターンで指定する方が一般的だと思い glob パターンを採用しました 😅。

今後の改修予定

現時点では必要最低限の機能（README もろくに書いてない）しか実装していないのですが、今後は以下のような機能を追加していきたいと考えています。

ファイルのアップロード・更新機能

現在のファイルツリーは、変更・更新・削除に追随して更新されるようにはなっているのですが、あくまでファイルの更新はエクスプローラーから実施する必要があります。

一応回避策として、下図のように SrcPan をエクスプローラーに D&D してドッキングすることで一つのサイドバーで完結させることができるのですが、サイドバーの表示領域が窮屈なのでどうにかしたいところです。

docking

ディレクトリの絞り込み

特定のディレクトリの画像のみ表示しているとはいえ、ファイル数が多いとそれでも探すのが大変です。そこで、ディレクトリを絞り込む機能を追加したいと考えています。 1 つの記事を書いている際に参照するディレクトリはせいぜい 1 つなので、記事名を入力して絞り込むか、現在開いているファイル名で絞り込む、みたいな機能があるといいかもです。

プレーン形式と Markdown 以外の形式でのパス挿入

これは今後自分の中で需要がどれだけ出てくるかにもよるのですが、import 文と HTML の img タグの形式でパスを挿入する機能があると便利かもしれないな〜と思っています。

おわりに

今回初めて VSCode 拡張機能を作ってみたんですが、環境構築が結構簡単で、API も多く想像よりも簡単に実装できました。パッケージ公開のためのvsceコマンドで*.vsixファイルを作ってしまえば、開発チーム内でのみ使用する Extension を作成することができ、チーム内の DX 向上の選択肢が増えたのは大きいですね。

今回作成した Extension は、こちら🔗からインストールできます。ぜひお試しください。 README 含めてまだまだ整備できていないので、徐々に改善していきたいと思います（機能要望、バグ等あれば GitHub の Issue へどうぞ）！

余談：名前

「img の src をパンッと挿入できる」と「ソースパン（フライパン）」を掛けて「SrcPan」と名付けました。音優先でソースパン →「パンッと貼り付けられる」とこじつけましたが、たぶんこの擬音は「パンッ」ではなく、「シュッ」な気がしています 😅。

ワークスペース内の画像のパスをパンッとはれるVSCode拡張をリリースした

公開日: 2023/5/6

VSCode拡張、GistPadを試してみた

2023/5/4

に公開

GistPad が便利という Tweet を見かけたので、自分も導入してみました。

概要

https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gistfs🔗

GistPad は、お気に入りのエディタで快適に GitHub の Gist やリポジトリを編集できる Visual Studio Code の拡張機能です。Gist やリポジトリを開く、作成する、削除する、フォークする、スターを付けることができ、クローン、プッシュ、プルすることなく、まるでローカルにあるかのようにシームレスにファイルの編集を開始することができます。コードスニペット、よく使われる設定やスクリプト、プログラミング関連のメモ、ナレッジベース、インタラクティブなサンプルなどを構築し、参照するためのあなただけの開発者ライブラリのようなものです。 - マーケットプレイス紹介文を DeepL で翻訳

導入

VSCode に GistPad をインストール
アクティビティーバーの GistPad をクリック
GitHub にログイン

これで自分が作成した Gist の一覧が見られるようになります（鍵付きのものは Secret Gist。鍵がついているけど別に見られて困るものではないのでそのままスクショ掲載しています）。

気になった機能：Scratch Notes

表題の決まった Gist とは別に、メモを取るための Gist を作成できる機能が備わっている。デフォルトでは Markdown が生成され、そこに自由にメモができる。

内部的には Secret Gist が生成されているだけですが、削除・生成を GistPad 側でやってくれるので、気軽にメモができるというメリットがあります。開発時のちょっとしたメモを取りたいときに使えるかなあと思ったけど、Secret Gist はリンクがわかれば誰でも見れるので、業務用のメモには使えないですね〜。

上述のように業務の開発時の TODO メモ等には使いにくいですが、個人的な開発のメモや、コードスニペット管理には使えそうです。

VSCode拡張、GistPadを試してみた

公開日: 2023/5/4

zshrcが吹き飛んだので、修復ついでについでに色々整理する

2023/4/15

に公開

雑に作業しすぎて zshrc は吹っ飛んだし、雑に管理してたので復帰できなかった

昨日 GitHub Copilot for CLI の順番待ちがようやくまわってきたので設定を.zshrc に追加したんですが、雑にやりすぎて完全に上書きしていました（シェルの再起動をしていなかったので、事態を把握するまでに少し時間がかかった）。

幸い吹っ飛んだのは.zshrc だけで、エイリアス等を書いている別の config は無事だったため、そこまで被害は出なかったのですが、これを機にちゃんと dotfiles もコミットしておこう& ついでに色々シェルを整理しようと思ったので、やったことをまとめておきます。

chezmoi への反映を簡易化する

もともと dotfiles の管理にはchezmoi🔗を使っていたのですが、.zshrc を直接更新した際に、これをどう chezmoi 側のコピーに反映するかがよくわからず、ほったらかしにしていました。

直接更新してしまった場合は、chezmoi addで現在のファイルの内容をそのまま chezmoi 管理下に追加するか、chezmoi mergeで chezmoi 管理下のファイルと現在のファイルをマージするかを選ぶことができます。

chezmoi add ~/.zshrc
# or
chezmoi merge ~/.zshrc # デフォルトではvimdiffが開く

上記は直接編集してしまった場合ですが、基本的には chezmoi 管理下のファイルを更新して apply するのが正しいので、以下手順で反映させます。

chezmoi edit ~/.zshrc
chezmoi apply ~/.zshrc
source ~/.zshrc

ただ毎度これをやるのは面倒臭いので、シェルスクリプト化しておきます。

# moi ~/.zshrc のように呼び出すことで、対象のファイルをchezmoi管理下に追加してapplyし、現在のシェルにも反映する
moi() {
  local target_file=$1
  chezmoi edit $target_file && chezmoi apply $target_file && source $target_file
}