Des2Code Code Import — 使い方

Summary

フロントエンド codebase の Storybook component を Guinness project へインポートし、 Des2Code の照合対象として使用できるようにします。component の source と style を送信し、 Storybook Story を rendered variation として取り込みます。index の再構築は別コマンドで実行します。

importer を取得する

script/des2code-code-import/ を .env.example ごと、フロントエンドリポジトリのルートに des2code-code-import/ としてコピーします。

project に未定義の場合は、以下の package script を追加します。

{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "gen:storybook-screenshots": "node des2code-code-import/generate-screenshots.mjs",
    "guinness:des2code-code-import": "node des2code-code-import/import.mjs"
  }
}

storybook-static/index.json がない場合、importer は npm run build-storybook を実行するため、 build-storybook という script 名が必要です。Storybook の開発用 command が異なる場合は、デフォルトの npm run storybook -- --ci の代わりに STORYBOOK_SERVER_COMMAND を設定します。

事前準備

Node.js 22 以上と、実行可能な npm command
project の依存関係がインストール済みであること
フロントエンド project に Storybook がインストール・設定済みであること
npm run build-storybook が Storybook index を storybook-static/index.json に出力すること
設定した component root 内に 1 件以上の Storybook Story があること
project に playwright がインストール済みであること
Google Chrome、または bundled-browser mode 用の Playwright Chromium
Story が使用する component source、style、font、asset への read access
設定したローカル output directory への write access
対象 Guinness backend への network access
対象 organization と project へのアクセス権を持つユーザーの有効な Cognito user access token

Playwright が未導入の場合はインストールします。

npm install --save-dev playwright

デフォルトではローカルの Google Chrome channel を使用します。Chrome がない場合は Playwright Chromium をインストールし、bundled-browser mode を使用します。

npx playwright install chromium

PLAYWRIGHT_CHANNEL=bundled

Screenshot 用に Storybook を準備する

Guinness variation として取り込む各 component state を Storybook Story として用意します。 Story の import path は CODE_IMPORT_COMPONENTS_DIR の配下にある必要があります。

Story file と実装は以下のように同じ directory に配置します。

components/
└── button/
    ├── index.stories.tsx
    ├── index.tsx
    └── index.module.scss

importer は Story の import path ごとに、同じ directory にある .cjs、.js、.jsx、.mjs、 .ts、.tsx の実装 file と、.css、.less、.sass、.scss の style file を読み込みます。別 directory への import はたどりません。Story と component source が別の directory にある場合や、 style が共有 global import にしかない場合は、完全な source record を作成できません。

各 Story は単独かつ安定して render できるようにします。

必要な style、font、icon、image、その他の asset を Storybook で読み込む。
必要に応じて authentication、API data、date、その他の外部状態を mock する。
初回 render 後も loading state のまま残らないようにする。
手動操作なしで Storybook iframe に表示できるようにする。
Storybook iframe から font、image、その他の network asset を取得できるようにする。

storybook-static/index.json がない場合、importer は Storybook を build します。必要に応じて設定した Storybook server を起動し、Story root、500 ms、font の順に待ち、CSS animation を無効化して component を撮影します。application 固有の非同期処理までは待たないため、data-dependent state はこの時間内に準備される必要があります。通常の import では 1280 × 720 の desktop viewport を使用します。

既存 screenshot は再利用されます。明示的に再生成を指定しない限り、不足している Story のみ撮影します。

インポートを設定する

以下のコマンドはフロントエンドリポジトリのルートで実行します。

ローカル環境ファイルを作成します。

cp des2code-code-import/.env.example des2code-code-import/.env

des2code-code-import/.env に対象、project path、認証情報を設定します。

変数	値
`GUINNESS_API_URL`	対象 Guinness backend の stage URL、または `/api/v1` で終わる URL
`GUINNESS_USER_TOKEN`	有効な Cognito user access token。メールアドレスとパスワードの組み合わせは使用しない
`GUINNESS_ORGANIZATION_ID`	対象 organization ID
`GUINNESS_PROJECT_ID`	対象 project ID
`CODE_IMPORT_COMPONENTS_DIR`	Storybook component source を含む root
`CODE_IMPORT_OUTPUT_DIR`	screenshot、manifest、report の保存先。デフォルトは `des2code-code-import/output`
`STORYBOOK_BASE_URL`	Storybook server URL。デフォルトは `http://127.0.0.1:6006`
`STORYBOOK_SERVER_COMMAND`	server が利用できない場合に Storybook を起動する command
`PLAYWRIGHT_CHANNEL`	browser channel。デフォルトは `chrome`。bundled 版は `bundled`
`GUINNESS_CONNECT_TO`	対象 URL の TLS hostname を保持したまま使用する任意のローカル `host:port`

.env.example の URL、organization、project、component path はすべて確認して置き換えてください。 template が意図した Guinness project を指しているとは限りません。

token を設定する前に、リポジトリルートの .gitignore に以下を追加します。

/des2code-code-import/.env
/des2code-code-import/output/

access token には環境ファイルまたは --token-file を使用します。package manager や process output に表示される可能性があるため、command line に token を直接渡さないでください。

GUINNESS_CONNECT_TO を使用する場合は runtime dependency をインストールします。

npm install --save-dev undici

Screenshot capture を検証する

<story-filter> は project 内の Storybook title、Story ID、name、または import path に置き換えます。 screenshot command では、この正規表現は大文字と小文字を区別します。

Storybook index を build し、browser を起動せずに一致する Story を確認します。

npm run build-storybook
npm run gen:storybook-screenshots -- \
  --dry-run \
  --include '<story-filter>'

一致する Story を 1 件撮影します。

npm run gen:storybook-screenshots -- \
  --include '<story-filter>' \
  --limit 1

Guinness import を試す前に、des2code-code-import/output/screenshots/ 配下に screenshot と manifest.json があることを確認します。

インポートを検証する

Guinness を変更せず、1 component の screenshot と source discovery を確認します。

npm run guinness:des2code-code-import -- \
  --dry-run \
  --include '<story-filter>' \
  --limit-components 1

dry run は Guinness API を呼び出しません。ただし、discovery に必要な Storybook の build または起動と、ローカル screenshot や manifest の書き込みは行う場合があります。

dry run が成功したら、1 component の実インポートを試します。

npm run guinness:des2code-code-import -- \
  --include '<story-filter>' \
  --limit-components 1

component processing が completed になり、variation request に submission failure がないことを確認します。 variation request が 202 Accepted を返した後、importer は variation worker の完了を poll しません。

全件インポートを実行する

npm run guinness:des2code-code-import

コマンドは以下を実行します。

設定した component root 配下の Storybook Story を検出する。
既存 screenshot を再利用し、不足している Story のみ撮影する。
Story を component source 単位でまとめる。
各 component の実装、ローカル style、preview screenshot をインポートする。
各非同期 component import の完了を待つ。
成功した Story の screenshot を code variation としてインポートする。

component ID は決定的に生成され、デフォルト mode は upsert のため、同じコマンドを安全に再実行できます。

結果を確認する

最終 report を確認します。

des2code-code-import/output/import-report.json

対象 organization と project、検出件数とインポート件数、component failure、variation submission failure が記録されます。screenshot と manifest は des2code-code-import/output/screenshots/ 配下に保存されます。

index を個別に再構築する

インポートでは code index を再構築しません。component と variation の処理完了後、以下を実行します。このコマンドは再構築をキューに登録しますが、worker の処理完了は検証しません。

# variation processing の完了後に実行します。
npm run guinness:des2code-code-import -- --rebuild-index-only

主なオプション

オプション	用途
`--components-dir <path>`	component root を上書きする
`--include <regexp>`	Story title、ID、name、import path で絞り込む
`--limit-components <n>`	一致した先頭 `n` component のみインポートする
`--mode <upsert\\|create\\|skip-existing>`	既存 component の扱いを選択する
`--reuse-manifest <path>`	別 manifest の screenshot を再利用する。複数回指定可能
`--strict-screenshots`	Storybook screenshot が 1 件でも失敗した場合に import を失敗させる
`--skip-variations`	rendered variation を除き component のみインポートする
`--rebuild-index-only`	インポートせず code index の再構築を登録する
`--dry-run`	Guinness API を呼ばずに検出と検証を行う

既存ファイルを再利用せず、すべての Storybook screenshot を再撮影する場合は以下を実行します。

npm run gen:storybook-screenshots -- --no-skip-existing

worker の processing contract は AI Code Import を参照してください。