feat(docs): add fresh-node-ids option to bypass Figma image cache per node

[junghyeonsu]

배경

docs alpha 미리보기에서 특정 컴포넌트 문서의 Figma 이미지가 stale해지는 문제가 있습니다. 캐시(docs/.cache/figma-image/urls)는 노드 ID → 이미지 URL을 저장하는데, Figma에서 디자인을 바꿔도 노드 ID는 그대로라 옛 렌더 URL이 계속 캐시 적중됩니다.

기존 skip-figma-cache=true(FIGMA_CACHE_DISABLED)는 전역이라 전체 이미지를 fresh fetch하는데, fetchFigmaImageUrls가 MAX_CONCURRENCY=1 + 429 재시도 구조라 이미지가 많으면 rate limit으로 "Build Docs"가 실패합니다.

변경

특정 노드만 캐시를 무시(bypass)하는 bypass-cache-node-ids 옵션을 추가합니다.

• env.figmaBypassCacheNodeIds ← FIGMA_BYPASS_CACHE_NODE_IDS (콤마 구분 노드 ID)
• workflow_dispatch input bypass-cache-node-ids → FIGMA_BYPASS_CACHE_NODE_IDS env 배선
• shouldBypassCache(nodeId) = 전역 disable이거나 해당 노드가 목록에 있으면 캐시 우회

fresh fetch 결과는 그대로 캐시에 set/save되므로, 특정 문서 이미지를 한 번 갱신하는 용도입니다. 모든 Figma 이미지 경로(본문 FigmaImage, cover, blog)가 fetchFigmaImageUrls를 통과하므로 일괄 적용됩니다.

사용 예

```bash
gh workflow run deploy-seed-design-docs-alpha-pages.yml
--ref -f bypass-cache-node-ids="1702:4339,1705:5564"
```

Summary by CodeRabbit

• New Features
  • 문서 빌드 과정에서 Figma 디자인 이미지의 캐시를 선택적으로 갱신할 수 있는 기능이 추가되었습니다.
  • GitHub Actions 워크플로우에서 bypass-cache-node-ids로 노드 ID 목록을 지정하면, 해당 이미지에 대해서는 캐시를 건너뛰고 항상 최신 버전으로 다시 로드합니다.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 29de604

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 66891790-4511-47c5-abb3-816e8215f909

📥 Commits

Reviewing files that changed from the base of the PR and between eb11324 and 29de604.

📒 Files selected for processing (3)

• .github/workflows/deploy-seed-design-docs-alpha-pages.yml
• docs/app/env.ts
• docs/components/figma-image/fetch-figma-image-urls.ts

---

📝 Walkthrough

Walkthrough

CI 워크플로우에 bypass-cache-node-ids 입력을 추가하고 FIGMA_BYPASS_CACHE_NODE_IDS 환경변수로 빌드에 전달합니다. env.ts에서 해당 값을 파싱해 배열로 노출하고, fetchFigmaImageUrls에 shouldBypassCache(nodeId) 헬퍼를 추가해 특정 노드 ID의 Figma 이미지 캐시를 선택적으로 우회합니다.

Changes

Figma 노드별 캐시 우회

Layer / File(s)	Summary
CI 입력 및 env 파싱 .github/workflows/deploy-seed-design-docs-alpha-pages.yml, docs/app/env.ts	워크플로우 workflow_dispatch에 bypass-cache-node-ids 문자열 입력을 추가하고 FIGMA_BYPASS_CACHE_NODE_IDS 환경변수로 빌드 단계에 전달하며, env.ts에서 쉼표 분리·trim·빈값 제거 후 figmaBypassCacheNodeIds: string[]로 파싱합니다.
fetchFigmaImageUrls 캐시 우회 로직 docs/components/figma-image/fetch-figma-image-urls.ts	shouldBypassCache(nodeId) 헬퍼를 추가해 figmaCacheDisabled 또는 figmaBypassCacheNodeIds 포함 여부로 우회를 판단하고, 초기 노드 순회와 세마포어 재확인 단계 모두에 이를 적용합니다.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 토끼가 냄새 맡았지, 오래된 이미지 캐시를!
노드 ID 목록 들고서, 콤마로 나눠 쫙~
shouldBypassCache로 살짝 피해가며
Figma에서 신선한 그림 쏙 가져오네.
캐시는 잠깐 비켜봐, 새 이미지가 왔다옹! 🎨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	PR 제목이 주요 변경 사항을 명확하게 요약합니다. Figma 이미지 캐시를 선택적으로 우회하는 기능 추가를 정확하게 나타냅니다.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/figma-fresh-node-ids

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Alpha Preview (Stackflow SPA)

• Branch Preview URL: https://feat-figma-fresh-node-ids.seed-design-stackflow-spa.pages.dev
• Preview URL: https://47522b8e.seed-design-stackflow-spa.pages.dev
• Commit: 29de604

[github-actions]

Alpha Preview (Storybook)

• Branch Preview URL: https://feat-figma-fresh-node-ids.seed-design-storybook.pages.dev
• Preview URL: https://5cc0cb7d.seed-design-storybook.pages.dev
• Commit: 29de604

[github-actions]

Alpha Preview (Docs)

• Branch Preview URL: https://feat-figma-fresh-node-ids.seed-design.pages.dev
• Preview URL: https://53f9772e.seed-design.pages.dev
• Commit: 29de604