> ## Documentation Index
> Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 주요 기능들

> Sonamu VS Code Extension의 주요 기능

Sonamu Extension은 Naite 테스트 프레임워크와 통합되어 다양한 개발 지원 기능을 제공합니다.

## Naite 키 자동완성

`Naite.t("`, `Naite.del("`, `Naite.get("` 입력 시 프로젝트의 모든 Naite 키를 자동완성합니다.

{" "}

<Frame>
  <img src="https://mintcdn.com/cartanova-7788888c/s1_oTUDBU5sL85Nu/images/vscode-extension1.png?fit=max&auto=format&n=s1_oTUDBU5sL85Nu&q=85&s=7cbc9862f60e400c93c219de6c79b49f" alt="Naite 키 자동완성 (Naite.t)" width="1050" height="92" data-path="images/vscode-extension1.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/cartanova-7788888c/s1_oTUDBU5sL85Nu/images/vscode-extension2.png?fit=max&auto=format&n=s1_oTUDBU5sL85Nu&q=85&s=3877ba9dce89270bbc3c0e451a2f15e2" alt="Naite 키 자동완성 (Naite.del)" width="908" height="54" data-path="images/vscode-extension2.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/cartanova-7788888c/s1_oTUDBU5sL85Nu/images/vscode-extension3.png?fit=max&auto=format&n=s1_oTUDBU5sL85Nu&q=85&s=b0db38087e9245c661b28ab996c83ee8" alt="Naite 키 자동완성 (Naite.get)" width="1428" height="94" data-path="images/vscode-extension3.png" />
</Frame>

### 동작 방식

Extension은 워크스페이스의 모든 TypeScript 파일을 스캔하여 `Naite.t()` 호출에서 사용된 키들을 수집합니다. 이 키 목록이 자동완성 후보로 제공됩니다.

## 키 네비게이션

Naite 키 문자열에서 정의와 참조 위치로 빠르게 이동할 수 있습니다.

### 정의로 이동 (Go to Definition)

* **단축키**: F12
* **동작**: `Naite.t("key")` 위치로 이동

<Frame>
  <video autoPlay muted loop playsInline controls className="w-full rounded-xl" src="https://mintcdn.com/cartanova-7788888c/gHShQ4W7H-WpAKgp/images/vscode-extension6.mp4?fit=max&auto=format&n=gHShQ4W7H-WpAKgp&q=85&s=c86f7adaaa95e825c0f3661b355d4826" data-path="images/vscode-extension6.mp4" />
</Frame>

### 참조로 이동 (Go to References)

* **단축키**: Shift+F12
* **동작**: `Naite.get("key")`, `Naite.del("key")` 위치 목록 표시

<Frame>
  <video autoPlay muted loop playsInline controls className="w-full rounded-xl" src="https://mintcdn.com/cartanova-7788888c/gHShQ4W7H-WpAKgp/images/vscode-extension7.mp4?fit=max&auto=format&n=gHShQ4W7H-WpAKgp&q=85&s=0a592193730b851732e0595caa1a0561" data-path="images/vscode-extension7.mp4" />
</Frame>

### Cmd+Click

Cmd+Click 동작은 VS Code 설정에 따라 정의 또는 참조로 이동합니다:

* `editor.gotoLocation.multipleDefinitions`: 여러 정의가 있을 때 동작
* `editor.gotoLocation.multipleReferences`: 여러 참조가 있을 때 동작

## 키 하이라이팅

Naite 키 문자열에 시각적 데코레이션을 적용하여 코드에서 쉽게 식별할 수 있습니다.

<Frame caption="키 하이라이팅" />

### 설정

`sonamu.naite.decoration.enabled`로 활성화/비활성화할 수 있으며, `sonamu.naite.decoration.style`로 스타일을 변경할 수 있습니다:

* `underline` (기본값)
* `bold`
* `italic`
* `underline bold`
* `underline italic`
* `none`

## 호버 정보

Naite 키 위에 마우스를 올리면 해당 키의 사용 정보를 표시합니다.

<Frame caption="호버 정보">
  <img src="https://mintcdn.com/cartanova-7788888c/gHShQ4W7H-WpAKgp/images/vscode-extension8.png?fit=max&auto=format&n=gHShQ4W7H-WpAKgp&q=85&s=61394d8df82e50b01d96a783051ae4e2" alt="호버 정보" width="1180" height="178" data-path="images/vscode-extension8.png" />
</Frame>

## 인라인 값 표시

테스트 실행 후 `Naite.t()` 호출 옆에 기록된 값을 인라인으로 표시합니다.

```typescript theme={null}
Naite.t("result", data); // → { id: 1, name: "test" }
```

<Frame caption="인라인 값 표시">
  <video autoPlay muted loop playsInline controls className="w-full rounded-xl" src="https://mintcdn.com/cartanova-7788888c/09gTEtoClHbNLmVh/images/vscode-extension9.mp4?fit=max&auto=format&n=09gTEtoClHbNLmVh&q=85&s=6b7e3ea5577004fc3c0d587d0ff551e7" data-path="images/vscode-extension9.mp4" />
</Frame>

### 설정

* `sonamu.naite.runtimeValue.enabled`: 기능 활성화/비활성화 (기본값: `true`)
* `sonamu.naite.runtimeValue.maxLength`: 표시할 값의 최대 길이 (기본값: `50`)

값이 너무 길면 자동으로 잘립니다.

## Naite Trace Viewer

테스트 실행 중 `Naite.t()`로 기록한 모든 값을 실시간으로 확인할 수 있는 전용 뷰어입니다.

<Frame caption="Naite Trace Viewer">
  <video autoPlay muted loop playsInline controls className="w-full rounded-xl" src="https://mintcdn.com/cartanova-7788888c/09gTEtoClHbNLmVh/images/vscode-extension10.mp4?fit=max&auto=format&n=09gTEtoClHbNLmVh&q=85&s=716921a5755ff687193f1fa7b3807e37" data-path="images/vscode-extension10.mp4" />
</Frame>

### 열기

Command Palette에서 `Sonamu: Open Naite Trace Viewer`를 실행하거나, 테스트 실행 시 자동으로 열립니다.

### 주요 기능

**테스트별 그룹화**

테스트 suite와 case별로 trace가 그룹화되어 표시됩니다.

<Frame caption="테스트별 그룹화">
  <img src="https://mintcdn.com/cartanova-7788888c/09gTEtoClHbNLmVh/images/vscode-extension11.png?fit=max&auto=format&n=09gTEtoClHbNLmVh&q=85&s=5de3d0fc8d46d5fe89d434ebde414de1" alt="테스트별 그룹화" style={{ width: "70%", borderRadius: "8px" }} width="1510" height="1664" data-path="images/vscode-extension11.png" />
</Frame>

**Trace 정보 표시**

각 trace는 다음 정보를 포함합니다:

* 키 이름
* 기록된 값 (JSON 형식)
* 파일 경로 및 라인 번호
* 기록 시간

**코드 위치로 이동**

Trace를 클릭하면 해당 `Naite.t()` 호출 위치로 이동합니다.

<Frame caption="코드 위치로 이동">
  <video autoPlay muted loop playsInline controls className="w-full rounded-xl" src="https://mintcdn.com/cartanova-7788888c/09gTEtoClHbNLmVh/images/vscode-extension12.mp4?fit=max&auto=format&n=09gTEtoClHbNLmVh&q=85&s=6e0ad2503a28ed420594c2b71737fdfc" data-path="images/vscode-extension12.mp4" />
</Frame>

**검색 기능**

Trace 뷰어 내에서 키나 값으로 검색할 수 있습니다.

<Frame caption="Trace 검색">
  <video autoPlay muted loop playsInline controls className="w-full rounded-xl" src="https://mintcdn.com/cartanova-7788888c/09gTEtoClHbNLmVh/images/vscode-extension13.mp4?fit=max&auto=format&n=09gTEtoClHbNLmVh&q=85&s=08cb2e3faae63d408000f9a8af742ce5" data-path="images/vscode-extension13.mp4" />
</Frame>

**Follow Mode**

코드에서 Naite 호출을 선택하면 Trace Viewer에서 자동으로 해당 항목으로 스크롤됩니다.

### Vitest 설정

테스트 케이스의 라인 번호를 표시하려면 `vitest.config.ts`에서 `includeTaskLocation: true`를 설정해야 합니다:

```typescript theme={null}
export default defineConfig({
  test: {
    includeTaskLocation: true,
  },
});
```

## 심볼 검색

Workspace Symbol Search에서 Naite 키를 검색할 수 있습니다.

* **단축키**: Cmd+T
* **사용법**: 키 이름 입력하여 모든 사용 위치 찾기

<Frame caption="심볼 검색">
  <video autoPlay muted loop playsInline controls className="w-full rounded-xl" src="https://mintcdn.com/cartanova-7788888c/09gTEtoClHbNLmVh/images/vscode-extension14.mp4?fit=max&auto=format&n=09gTEtoClHbNLmVh&q=85&s=4ab3677ee5389618cf9195ff6986b99d" data-path="images/vscode-extension14.mp4" />
</Frame>

## 미정의 키 경고

`Naite.get()` 또는 `Naite.del()`에서 `Naite.t()`로 정의되지 않은 키를 참조하면 경고를 표시합니다. 경고는 VS Code Problems 패널(Cmd+Shift+M)에서 확인할 수 있습니다.

<Frame caption="미정의 키 경고">
  <img src="https://mintcdn.com/cartanova-7788888c/E_xghIsQZ4iAGOf_/images/vscode-extension15.png?fit=max&auto=format&n=E_xghIsQZ4iAGOf_&q=85&s=2dc970ded956879c7ab37c8b7bb7036d" alt="미정의 키 경고" style={{ width: "70%", borderRadius: "8px" }} width="1812" height="544" data-path="images/vscode-extension15.png" />
</Frame>

이 기능은 오타나 누락된 키를 빠르게 찾는 데 유용합니다.

## View Container

Extension은 패널 영역에 "Naite" View Container를 추가합니다.

<Frame caption="Naite View Container">
  <img src="https://mintcdn.com/cartanova-7788888c/E_xghIsQZ4iAGOf_/images/vscode-extension16.png?fit=max&auto=format&n=E_xghIsQZ4iAGOf_&q=85&s=78f029d6af34211013ac79d230981784" alt="Naite View Container" style={{ width: "70%", borderRadius: "8px" }} width="2406" height="1032" data-path="images/vscode-extension16.png" />
</Frame>

이 패널에서 Trace 정보를 빠르게 확인할 수 있습니다.

## 상태바 메시지

Naite tracker 액션(키 추가, 삭제 등) 발생 시 상태바에 알림 메시지를 표시합니다.

`sonamu.naite.statusBarMessages.enabled` 설정으로 활성화/비활성화할 수 있습니다 (기본값: `true`).