figma-json-tree 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# figma-json-tree
+
+Figma JSON을 다운로드하고, 선택자로 트리를 탐색하여 디자인 IR·Tailwind v4 IR·HTML로 변환하는 TypeScript 라이브러리입니다.
+
+## 시작하기
+
+Node.js **22.12 이상**, npm을 사용합니다. 저장소에서 다음 명령으로 개발 환경을 준비합니다.
+
+```sh
+npm install
+npm run check
+```
+
+ESM과 TypeScript 선언 파일을 빌드합니다. 코어와 다운로드 클라이언트는 현대 브라우저에서도 사용할 수 있으며, 브라우저에 비밀 토큰을 포함하지 않고 서버에서 다운로드한 JSON을 전달하는 구성을 권장합니다.
+
+```ts
+import { FigmaTree } from 'figma-json-tree'
+import { FigmaClient } from 'figma-json-tree/figma-json-fetch'
+
+const client = new FigmaClient({ token: process.env.FIGMA_TOKEN! })
+const figmaJson = await client.getFile(fileKey)
+const figma = FigmaTree.fromJson(figmaJson)
+
+const searchFilter = figma.query('FRAME[name="SearchFilter"]')
+const buttons = figma.queryAll('INSTANCE[componentName="Button"]')
+const filters = figma.queryAll('FRAME[name*="Filter"]')
+
+const table = figma
+  .query('FRAME[name="ProductPage"]')
+  ?.query('FRAME[name="ProductTable"]')
+
+const subtrees = figma
+  .queryAll({ name: /^ToBe/ })
+  .map(node => node.toJSON()) // 각 원본 노드 + 전체 children
+
+const ir = searchFilter?.toIR()
+const tailwindIR = ir?.toTailwind()
+```
+
+`fromJson`은 파싱된 파일 전체 응답, `/nodes` 응답, 단일 노드를 받습니다. 다운로드와 파싱을 분리하므로 로컬 JSON도 그대로 사용할 수 있습니다. 일치하지 않으면 `query`는 `undefined`, `queryAll`은 빈 배열을 반환합니다.
+
+## 정규식과 선택자
+
+```ts
+figma.queryAll({ name: /^ToBe/i, type: 'FRAME' })
+figma.queryAll('FRAME[name^="ToBe"]')
+figma.queryAll('FRAME > INSTANCE[visible=true]')
+figma.queryAll('FRAME[name="ProductPage"] TEXT')
+```
+
+타입, 속성 존재, 일치·포함·접두·접미, 복수 조건, 자손과 직계 자식 선택자를 지원합니다. 정규식은 객체 조건에서 JavaScript `RegExp`로 전달합니다. 검색은 `children`만 따라가며, 결과는 깊이 우선 전위 순서입니다. 노드의 `query`는 자신을 제외한 자손만 검색하고 scope 밖의 조상을 참조하지 않습니다.
+
+자세한 문법과 반환 계약은 [API 문서](docs/api.md)를 참고하세요.
+
+## IR 플러그인
+
+```ts
+import { FigmaTree, type IRPlugin } from 'figma-json-tree'
+
+const semanticPlugin: IRPlugin = {
+  name: 'semantic-components',
+  transform(node, { source }) {
+    if (source.type !== 'INSTANCE') return node
+    return {
+      ...node,
+      extensions: { ...node.extensions, semanticRole: 'component' },
+    }
+  },
+}
+
+const tree = FigmaTree.fromJson(figmaJson, { irPlugins: [semanticPlugin] })
+const result = tree.query('INSTANCE')?.toIR().toTailwind()
+```
+
+자식 변환 후 부모를 처리합니다. 각 노드에서 기본 변환, 등록 플러그인, `toIR({ plugins })`의 호출별 플러그인을 순서대로 적용합니다. 플러그인은 읽기 전용 IR을 받아 표준 IR 필드를 교체하거나 JSON `extensions`를 추가합니다.
+
+[IR·플러그인·Tailwind 문서](docs/ir.md)에 지원 속성, 확장 계약, CSS 연결 방법을 정리했습니다.
+
+## 다운로드 CLI
+
+환경에 `FIGMA_TOKEN`을 설정한 후 실행합니다. 토큰 값을 인자나 파일에 넣을 필요는 없습니다.
+
+```sh
+npm run build
+node dist/cli/index.js download --file FILE_KEY --out figma.json
+node dist/cli/index.js download --file FILE_KEY --nodes 49:7390 --out nodes.json
+```
+
+설치된 패키지에서는 `figma-json-tree download ...`로 실행합니다. `--out`이 없으면 JSON을 stdout으로 출력합니다. 기존 파일은 `--force`가 있어야 덮어씁니다. URL의 `node-id=49-7390`은 API 형식인 `49:7390`으로 전달합니다.
+
+## 검색 CLI
+
+로컬 JSON을 `query` 또는 `queryAll`로 검색합니다. 토큰이나 네트워크 요청이 필요하지 않습니다.
+
+```sh
+# 첫 번째 Hover Card Frame과 전체 자식 추출
+node dist/cli/index.js query --input artifacts/live/file.json \
+  --selector 'FRAME[name="Hover Card"]' --out hover-card.json
+
+# 이름이 Hover Card인 모든 노드 추출
+node dist/cli/index.js queryAll --input artifacts/live/file.json \
+  --selector '[name="Hover Card"]'
+
+# JavaScript 정규식으로 이름 검색
+node dist/cli/index.js queryAll --input artifacts/live/file.json \
+  --name-regex '^ToBe' --regex-flags i
+
+# 추출한 단일 subtree에서 다시 검색
+node dist/cli/index.js queryAll --input hover-card.json --selector TEXT
+```
+
+설치된 패키지는 `node dist/cli/index.js` 대신 `figma-json-tree`로 실행합니다. `query`는 원본 노드 객체 하나 또는 `null`, `queryAll`은 원본 노드 배열 또는 `[]`를 출력합니다. 일치 없음은 정상 종료(0)이며 오류는 stderr와 종료 코드 1로 전달합니다.
+
+`--selector`와 `--name-regex` 중 하나를 지정합니다. 정규식은 `/…/`로 감싸지 않고 패턴만 전달하며 플래그는 `--regex-flags`에 지정합니다. `--out`과 `--force`는 다운로드와 동일하게 동작합니다. 파일·노드 API 응답 또는 단일 subtree를 입력받으며 `queryAll` 결과 배열 자체를 재입력하는 기능은 제공하지 않습니다.
+
+## HTML 출력
+
+별도 `figma-html` 모듈에서 표준 IR 또는 Tailwind IR을 HTML 조각으로 변환합니다.
+
+```ts
+import { renderHTML } from 'figma-json-tree/figma-html'
+
+const frame = figma.query('FRAME[name="Hover Card"]')!
+const html = renderHTML(frame.toIR()) // inline CSS
+const tailwindHTML = renderHTML(frame.toIR().toTailwind()) // class + 잔여 inline CSS
+```
+
+라이브러리와 CLI 모두 **body 내부에 삽입할 마크업만** 출력합니다. `doctype`, `html`, `head`, `body`, `style`, `script` 태그는 생성하지 않습니다. Tailwind 모드는 클래스와 잔여 inline 스타일을 출력하며 CSS 빌드는 사용하는 프로젝트에서 처리합니다.
+
+```sh
+node dist/cli/index.js export --input artifacts/live/file.json \
+  --selector 'FRAME[id="41:5868"]' --format html \
+  --out artifacts/live/hover-card.inline.html
+
+node dist/cli/index.js export --input artifacts/live/file.json \
+  --selector 'FRAME[id="41:5868"]' --format html --styles tailwind \
+  --out artifacts/live/hover-card.tailwind.html
+
+# 저장된 IR 또는 Tailwind IR도 입력 가능
+node dist/cli/index.js export \
+  --input artifacts/live/hover-card-frame-41-5868.tailwind-ir.json \
+  --out artifacts/live/hover-card.from-tailwind-ir.html
+```
+
+`--out`을 생략하면 HTML을 stdout으로 출력하며 덮어쓰기에는 `--force`가 필요합니다. 렌더링은 현재 IR의 지원 범위를 따릅니다. 벡터·이미지·효과의 완전한 재현, 폰트 다운로드, hover 동작 같은 인터랙션 생성은 포함하지 않습니다. [HTML API·제약·검증 방법](docs/html.md)을 참고하세요.
+
+## 검증과 예제
+
+```sh
+npm run lint       # lint + 포맷 + import 정렬 검사
+npm run lint:fix   # 안전한 lint 자동 수정 + 포맷 + import 정렬
+npm run format    # 포맷만 자동 수정
+npm run typecheck
+npm test
+npm run build
+npm run test:package
+npm run test:live # FIGMA_TOKEN 필요, 실제 API 요청
+npm run test:html:live # artifacts/live의 실제 다운로드 데이터로 HTML 출력 검증
+
+npx tsx examples/query.ts artifacts/live/file.json
+npx tsx examples/to-ir.ts artifacts/live/file.json 49:7390
+```
+
+`npm run check`는 Biome 검사부터 타입 검사·테스트·빌드·패키지 소비 검증까지 실행합니다. Biome은 공백 2칸, 작은따옴표, 불필요한 세미콜론 생략, 100자 줄 너비를 사용합니다. `.gitignore`의 산출물과 `package-lock.json`은 검사 대상에서 제외합니다. 상세 설정은 [biome.json](biome.json)에 있습니다.
+
+실제 검증의 기본 대상은 파일 `vHYqaZykgJgAjgUs1mxjp3`, 노드 `49:7390`입니다. `FIGMA_FILE_KEY`와 `FIGMA_NODE_ID`로 변경할 수 있습니다. JSON·IR·Tailwind CSS·보고서는 Git에서 제외된 `artifacts/live/`에 저장합니다. 실제 응답에서 `ToBe` 일치 노드가 없으면 0건을 기록하고 별도 fixture에서 양성 사례를 확인합니다.
+
+최초 구현의 실제 실행 결과는 [검증 기록](docs/verification.md)에 정리했습니다.
+
+`FIGMA_LIVE_REPLAY=1`은 저장한 파일·노드 응답으로 변환 검증을 재현합니다. CLI 다운로드는 이 모드에서도 실제 요청하며, 보고서는 replay 사용을 명시합니다. 기본 `test:live`는 새 응답을 다운로드합니다.
+
+모듈 경계와 SOLID·SLAP 적용은 [설계 문서](docs/architecture.md)에 정리했습니다.