fix: invisible-layer severity blocking→suggestion + slot recommendation (#23)

[let-sunny]

Summary

hidden layer 룰의 심각도를 현실에 맞게 조정하고, 상태 레이어가 많을 때 Slot 사용을 추천.

변경 사항

심각도 조정

• severity: blocking → suggestion
• score: -10 → -1
• Hidden layer는 Figma 정상 워크플로 (버전 보관, A/B 시안, 상태 레이어)
• design-tree가 이미 visible: false skip → 코드 생성에 영향 없음

메시지 개선

• 기존: "Delete hidden layers or move them to a separate 'archive' page"
• 개선: "no impact on code generation, clean up if unused"

Slot 추천 (신규)

3개 이상의 hidden sibling이 있으면 상태 관리 목적일 가능성이 높으므로:

"StateA is hidden (3 hidden siblings) — if these represent states, consider using Figma Slots instead"

룰 정의 업데이트

• why: 실제 영향 수준 반영 (token overhead만, 구현 차단 아님)
• impact: design-tree가 이미 skip한다는 사실 명시
• fix: Slot 추천 포함

Test plan

• pnpm test:run — 302 tests passed (7 new)
• pnpm lint — clean
• 기본 hidden → "clean up if unused" 메시지
• 3+ hidden siblings → "Slot" 추천 메시지
• parent도 hidden → skip (기존 동작 유지)

Closes #23

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Detection now recognizes multiple hidden siblings and recommends using Figma Slots for state-like hidden children when appropriate.

• Changes

  • Downgraded invisible-layer finding from blocking to suggestion and reduced its impact score.
  • Messaging clarified: hidden layers don’t block code generation; cleanup is suggested if unused.

• Tests

  • Added comprehensive tests validating detection, messaging, and slot-recommendation behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: dfe78cbf-c687-425f-94ad-4f55241b9dc9

📥 Commits

Reviewing files that changed from the base of the PR and between 67f6729 and e61d5df.

📒 Files selected for processing (2)

• src/core/rules/ai-readability/index.ts
• src/core/rules/rule-config.ts

---

📝 Walkthrough

Walkthrough

The invisible-layer AI readability rule's severity and score were reduced from blocking / -10 to suggestion / -1. The rule logic now counts hidden siblings and, when thresholded (default 3), recommends using Figma Slots for state-like hidden children. Documentation and tests were added/updated accordingly.

Changes

Cohort / File(s)	Summary
Documentation & Reference docs/REFERENCE.md	Updated AI Readability table entry for invisible-layer default severity (from blocking → suggestion) and default score (from -10 → -1).
Rule Configuration src/core/rules/rule-config.ts	Adjusted RULE_CONFIGS["invisible-layer"]: severity → suggestion, score → -1, and added options: { slotRecommendationThreshold: 3 }.
Rule Implementation src/core/rules/ai-readability/index.ts	Rewrote invisibleLayerCheck messaging to state no code-generation blocking, added import/use of getRuleOption, compute hidden-sibling count from context.siblings, and emit an alternate diagnostic recommending Figma Slots when hidden siblings ≥ threshold; updated why/impact/fix text.
Tests src/core/rules/ai-readability/invisible-layer.test.ts	Added comprehensive Jest tests: metadata assertions, visible vs hidden node behavior, parent-hidden skip, sibling-count branching (Slot recommendation when ≥3), and handling siblings: undefined.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• chore: full calibration run + add-rule pipeline test #18 — modifies RULE_CONFIGS entries (severity/score/options) in src/core/rules/rule-config.ts, overlapping with this PR's config changes.

Poem

"I hopped through layers quiet and light,
Found three small shadows, tucked out of sight.
A gentle nudge—no panic or slotless grief,
Just tidy whispers and a tidy motif. 🐇✨"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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	The title accurately and concisely describes the main changes: severity adjustment (blocking→suggestion) and the new slot recommendation feature.
Linked Issues check	✅ Passed	All coding requirements from issue #23 are met: severity/score adjustment, message clarification, slot recommendation logic, and configurable threshold implementation.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #23 objectives; no unrelated modifications to other rules, features, or components are present.

_{✏️ 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 fix/invisible-layer-severity

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/core/rules/ai-readability/index.ts`:
- Around line 213-225: Extract the hardcoded threshold "3" into rule-config.ts
and read it here via the existing rule options helper: add an
options.slotRecommendationThreshold entry under the "invisible-layer" rule in
rule-config.ts, then replace the literal 3 in the check that computes
hiddenSiblingCount with a call to getRuleOption/getRuleConfig (or the project's
options helper) to fetch "slotRecommendationThreshold" (provide a sensible
default like 3). Update the conditional that returns the invisibleLayerDef
suggestion to use that fetched threshold so hiddenSiblingCount >=
slotRecommendationThreshold drives the recommendation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: a5aa6ea9-8031-4d32-a021-00c629e6ee49

📥 Commits

Reviewing files that changed from the base of the PR and between d46da34 and 67f6729.

📒 Files selected for processing (4)

• docs/REFERENCE.md
• src/core/rules/ai-readability/index.ts
• src/core/rules/ai-readability/invisible-layer.test.ts
• src/core/rules/rule-config.ts