feat: enrich --json output for AI agent consumption

[let-sunny]

Summary

--json 출력을 AI 에이전트가 소비할 수 있는 수준으로 고도화.

추가된 필드:

• analyzedAt — 분석 시점 (before/after 비교용)
• fileKey — 어떤 Figma 파일인지 식별
• issues — 개별 이슈 상세 목록 (ruleId, severity, nodeId, nodePath, message)

유저 스토리: Figma 플러그인에서 JSON export → AI 에이전트가 받아서 이슈 파악 → use_figma로 수정

Before: issuesByRule에 룰별 개수만 (어떤 노드인지, 뭐가 문제인지 모름)
After: 개별 이슈마다 노드 위치 + severity + 메시지 포함 → AI가 판단 가능

Refs #92

Test plan

• pnpm lint — type check pass
• pnpm test:run — 592 tests pass (+2 new)
• pnpm build + npx canicode analyze fixtures/x --json — 새 필드 확인

https://claude.ai/code/session_017n9jQMQWFoEE3Mje7MfgXs

Summary by CodeRabbit

• New Features

  • JSON results now include analyzedAt, optional file identifiers, and a detailed issues list with node-specific IDs/paths and messages.
  • Diagnostics improved to be more prescriptive and include computed values (colors in hex, font descriptors, dimensions, spacing suggestions).

• Tests

  • Updated and added tests to validate the new JSON shape and the revised diagnostic messages.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Adds optional fileKey, analyzedAt, and a detailed issues array to the analysis JSON output (via buildResultJson), updates call-sites to pass fileKey, and refines many rule diagnostic messages and corresponding tests to be more explicit and actionable.

Changes

Cohort / File(s)	Summary
Scoring & JSON output src/core/engine/scoring.ts, src/core/engine/scoring.test.ts	buildResultJson signature now accepts options?: { fileKey?: string }; JSON includes analyzedAt, conditional fileKey, and an issues array (ruleId, severity, nodeId, nodePath, message). Tests updated to assert new fields.
CLI & MCP call-sites src/cli/commands/analyze.ts, src/cli/commands/implement.ts, src/mcp/server.ts	Updated calls to buildResultJson(...) to pass { fileKey: file.fileKey } as the fourth argument so serialized outputs include file identification when available.
Behavior rules src/core/rules/behavior/index.ts	Rewrote messages for text-truncation-unhandled, prototype-link-in-design, overflow-behavior-unknown, and wrap-behavior-unknown to include concrete measurements/actions (e.g., text length, container width, explicit settings).
Component rules & tests src/core/rules/component/index.ts, src/core/rules/component/missing-component.test.ts	Reworded missing-component, detached-instance, missing-component-description, and variant-structure-mismatch messages to be more prescriptive (extract shared component, create new variant, add usage guidelines). Tests adjusted for new message text.
Naming rules src/core/rules/naming/index.ts	Enhanced messages for default-name, non-semantic-name, inconsistent-naming-convention, numeric-suffix-name, and too-long-name to include node type context and clearer rename suggestions.
Structure rules & tests src/core/rules/structure/index.ts, src/core/rules/structure/no-auto-layout.test.ts	Updated noAutoLayoutCheck to include child count and direction hint; converted many structure messages to explicit Auto Layout and constraint guidance. Test string case adjusted.
Token rules & tests src/core/rules/token/index.ts, src/core/rules/token/raw-color.test.ts	Enhanced token-related messages: computed uppercase #RRGGBB colors, font descriptor strings, spacing rounding suggestions, shadow offsets/radii, opacity binding guidance, and color consolidation messaging. Test expectation updated.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: track failed rules in AnalysisResult #64: Similar edits to buildResultJson JSON shape — both add/modify fields in the scoring output (this PR adds analyzedAt/issues/fileKey; #64 adds conditional failedRules).
• test: scoring.ts, rule-engine.ts 핵심 모듈 유닛 테스트 추가 #58: Related adjustments to buildResultJson tests and output structure; overlaps in unit-test expectations for scoring JSON.
• refactor: split CLI index.ts into per-command modules (#47) #59: Changes the same CLI/MCP call-sites around buildResultJson usage and fileKey propagation.

Poem

🐰 I hop through logs with tiny cheer,

I pack fileKeys so outputs are clear,
Issues listed, timestamps bright,
Messages sharpened, guidance right,
A carrot-coded JSON near 🥕✨

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: enrich --json output for AI agent consumption' directly and clearly describes the main objective of this PR—enriching the JSON output for AI agents to consume analysis results.

_{✏️ 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/json-output-enrich

---

_{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/token/index.ts`:
- Line 145: The message construction uses gridBase in arithmetic (e.g.,
`"${node.name}" has padding ${padding}px not on ${gridBase}pt grid — round to
nearest ${gridBase}pt multiple (${Math.round(padding / gridBase) *
gridBase}px)`), which can produce NaN/Infinity when gridBase is zero/negative;
update the relevant rule(s) in src/core/rules/token/index.ts to validate/guard
gridBase before any division/modulo, e.g., ensure gridBase is a positive
non-zero number (or fall back to a safe default) before computing
Math.round(padding / gridBase) * gridBase and when formatting messages, and add
or reuse the Zod schema validation for the option that supplies gridBase so
downstream code (the message construction and any checks around padding,
node.name, padding, gridBase) never performs arithmetic with invalid gridBase.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: afc805d7-4006-4c31-b6fb-bf3be5f340db

📥 Commits

Reviewing files that changed from the base of the PR and between 3e90df9 and d2bf2d3.

📒 Files selected for processing (13)

• src/cli/commands/analyze.ts
• src/cli/commands/implement.ts
• src/core/engine/scoring.test.ts
• src/core/engine/scoring.ts
• src/core/rules/behavior/index.ts
• src/core/rules/component/index.ts
• src/core/rules/component/missing-component.test.ts
• src/core/rules/naming/index.ts
• src/core/rules/structure/index.ts
• src/core/rules/structure/no-auto-layout.test.ts
• src/core/rules/token/index.ts
• src/core/rules/token/raw-color.test.ts
• src/mcp/server.ts