feat: C 시뮬레이터 char 배열 문자열 리터럴 + 전역 struct 지원 추가

- array.handler: char str[] = "Hello", char str[20] = "Hello" 패턴 추가
- simulator: 전역 struct 정의 사전 처리 (멀티라인 병합 포함)
- simulator: clearStructDefs() 호출로 실행 간 상태 정리

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jammy0903

.claude/plans/c-simulator-char-struct-support.md

@@ -0,0 +1,75 @@
+# C Playground 시뮬레이터: char 배열 + struct 지원 추가
+
+**작성일**: 2026-02-04
+**상태**: 완료
+
+---
+
+## 문제 분석
+
+### 1. Char 배열 (`char str[] = "Hello"`) - 패턴 누락
+- `array.handler.ts`의 `PATTERNS`에 문자열 리터럴 초기화 패턴이 없었음
+- `char arr[4] = {'a','b','c','d'}` (brace init)만 지원
+- `char str[] = "Hello"`, `char str[20] = "Hello"` 패턴 추가 필요
+
+### 2. Struct - 두 가지 문제
+
+**문제 A: 파서가 전역 struct 정의를 무시**
+- `function-parser.ts`의 `parseCode()`는 함수 정의만 추출
+- `struct Point { int x; int y; };`가 함수 바깥에 있으면 파서가 스킵 → StructHandler에 전달 안 됨
+
+**문제 B: 멀티라인 struct가 한 줄 regex에 매칭 안 됨**
+- `STRUCT_DEF` regex: `/^struct\s+(\w+)\s*\{([^}]+)\}\s*;?\s*$/`
+- 한 줄 완결 struct만 매칭
+- 여러 줄로 쓰면 매칭 실패
+
+---
+
+## 수정 내용 (3개 파일)
+
+### 1. `packages/backend/src/modules/simulators/c/handlers/array.handler.ts`
+- **STRING_INIT_SIZED** 패턴 추가: `char str[20] = "Hello"` (크기 명시)
+- **STRING_INIT_AUTO** 패턴 추가: `char str[] = "Hello"` (크기 자동 = 문자 수 + 1)
+- `canHandle()`, `handle()`에 새 패턴 분기 추가 (ARRAY_INIT보다 먼저)
+- `handleStringLiteral()` 함수 추가:
+  - 각 문자를 ASCII 바이트로 변환
+  - null terminator `\0` 자동 추가
+  - 명시 크기보다 짧으면 0 패딩
+  - Phase 4 이벤트 발생
+
+### 2. `packages/backend/src/modules/simulators/c/simulator.ts`
+- `clearStructDefs` import 추가 (from `./handlers/struct.handler`)
+- `simulate()` 시작 시 `clearStructDefs()` 호출 (이전 실행 잔여 정의 제거)
+- `preprocessGlobalStructs()` private 메서드 추가:
+  - 함수 영역(bodyStart~bodyEnd)을 파악하여 함수 바깥만 스캔
+  - `struct Name {`로 시작하는 줄 감지
+  - 한 줄 완결 struct → 그대로 `analyzeLine()` 호출
+  - 멀티라인 struct → `}`까지 병합하여 한 줄로 만든 후 `analyzeLine()` 호출
+  - StructHandler가 정의를 파싱하여 `structDefs` 맵에 저장
+
+### 3. `packages/backend/src/modules/simulators/c/handlers/struct.handler.ts`
+- 코드 변경 없음 (`clearStructDefs()`는 이미 export되어 있음)
+- simulator.ts에서 import하여 호출만 추가
+
+---
+
+## 검증 방법
+
+```bash
+# 빌드 확인
+pnpm --filter @codeinsight/backend build  # ✅ 통과
+
+# API 테스트 - char 배열
+curl -X POST http://localhost:3002/api/v1/simulators/c/trace \
+  -H "Content-Type: application/json" \
+  -d '{"code": "#include <stdio.h>\nint main() {\n    char str[] = \"Hello\";\n    printf(\"%s\\n\", str);\n    return 0;\n}"}'
+
+# API 테스트 - struct
+curl -X POST http://localhost:3002/api/v1/simulators/c/trace \
+  -H "Content-Type: application/json" \
+  -d '{"code": "#include <stdio.h>\nstruct Point {\n    int x;\n    int y;\n};\nint main() {\n    struct Point p;\n    p.x = 10;\n    p.y = 20;\n    printf(\"(%d, %d)\\n\", p.x, p.y);\n    return 0;\n}"}'
+```
+
+### 확인 포인트
+- char[]: stack에 변수 나타남, value가 "Hello", bytes에 ASCII 값 + 0 (null terminator)
+- struct: structDefs에 정의 등록됨, stack에 p 나타남, is_struct: true, 멤버 접근 동작

packages/backend/src/modules/simulators/c/handlers/array.handler.ts

@@ -6,6 +6,8 @@
  * - int arr[5] = {1, 2, 3, 4, 5};
  * - float arr[3] = {1.5, 2.5, 3.5};
  * - char arr[4] = {'a', 'b', 'c', 'd'};
+ * - char str[] = "Hello";
+ * - char str[20] = "Hello";
  * - double arr[2];
  * - arr[0] = 10;
  */
@@ -15,6 +17,10 @@ import { cTypeRegistry, type TypeInfo } from '../types';
 
 // 패턴 정의 (모든 타입 지원)
 const PATTERNS = {
+  // char str[20] = "Hello";  (크기 명시, 더 구체적이므로 먼저)
+  STRING_INIT_SIZED: /^char\s+(\w+)\s*\[\s*(\d+)\s*\]\s*=\s*"([^"]*)"/,
+  // char str[] = "Hello";  (크기 자동 계산)
+  STRING_INIT_AUTO: /^char\s+(\w+)\s*\[\s*\]\s*=\s*"([^"]*)"/,
   // type arr[5] = {values};
   ARRAY_INIT: /^(unsigned\s+)?(\w+(?:\s+\w+)?)\s+(\w+)\s*\[\s*(\d+)\s*\]\s*=\s*\{([^}]+)\}/,
   // type arr[5];
@@ -29,13 +35,27 @@ export const ArrayHandler: CodeHandler = {
 
   canHandle(code: string): boolean {
     return (
+      PATTERNS.STRING_INIT_SIZED.test(code) ||
+      PATTERNS.STRING_INIT_AUTO.test(code) ||
       PATTERNS.ARRAY_INIT.test(code) ||
       PATTERNS.ARRAY_DECL.test(code) ||
       PATTERNS.ARRAY_ASSIGN.test(code)
     );
   },
 
   handle(ctx: SimContext, lineNum: number, code: string): Step | null {
+    // char str[20] = "Hello";  (크기 명시 — 더 구체적이므로 먼저 체크)
+    const strSized = code.match(PATTERNS.STRING_INIT_SIZED);
+    if (strSized) {
+      return handleStringLiteral(ctx, lineNum, code, strSized[1], strSized[3], parseInt(strSized[2]));
+    }
+
+    // char str[] = "Hello";  (크기 자동)
+    const strAuto = code.match(PATTERNS.STRING_INIT_AUTO);
+    if (strAuto) {
+      return handleStringLiteral(ctx, lineNum, code, strAuto[1], strAuto[2]);
+    }
+
     // type arr[5] = {values};
     const arrInit = code.match(PATTERNS.ARRAY_INIT);
     if (arrInit) {
@@ -304,4 +324,67 @@ function handleArrayAssign(
   return ctx.createStep(lineNum, code, explanation);
 }
 
+/**
+ * 문자열 리터럴로 char 배열 선언
+ * char str[] = "Hello";  또는  char str[20] = "Hello";
+ */
+function handleStringLiteral(
+  ctx: SimContext,
+  lineNum: number,
+  code: string,
+  name: string,
+  literal: string,
+  explicitSize?: number
+): Step {
+  const chars = literal.split('');
+  const size = explicitSize || chars.length + 1; // +1 for null terminator
+  const addr = ctx.allocateStack(size);
+
+  // 바이트 배열: 각 문자 ASCII + null terminator + 패딩
+  const bytes = chars.map((c) => c.charCodeAt(0));
+  bytes.push(0); // null terminator '\0'
+  while (bytes.length < size) bytes.push(0); // 나머지 패딩
+
+  // 표시용 문자 목록
+  const displayChars = [...chars.map((c) => `'${c}'`), "'\\0'"];
+
+  ctx.variables.set(name, {
+    address: ctx.toHex(addr),
+    type: `char[${size}]`,
+    size,
+    bytes,
+    value: `"${literal}"`,
+    is_array: true,
+    array_size: size,
+    element_type: 'char',
+    element_size: 1,
+  });
+
+  // Phase 4: 배열 선언 이벤트
+  if (ctx.addEvent && ctx.getCurrentFrame) {
+    ctx.addEvent({
+      type: 'variable',
+      action: 'declare',
+      frame: ctx.getCurrentFrame(),
+      name,
+      varType: `char[${size}]`,
+      value: `"${literal}"`,
+      address: ctx.toHex(addr),
+      size,
+    });
+  }
+
+  const explanation = `📚 문자열 '${name}' 선언: "${literal}"
+
+• 타입: char[${size}] (${size}바이트)
+• 스택 주소: ${ctx.toHex(addr)}
+• 문자 구성: {${displayChars.join(', ')}}
+• 바이트: [${bytes.slice(0, chars.length + 1).join(', ')}]
+
+💡 C 문자열은 char 배열 + null terminator('\\0')
+   "${literal}" → ${chars.length}글자 + '\\0' = ${chars.length + 1}바이트 필요${explicitSize && explicitSize > chars.length + 1 ? `\n   선언 크기 ${explicitSize} > 필요 크기 ${chars.length + 1} → 나머지는 0으로 채워짐` : ''}`;
+
+  return ctx.createStep(lineNum, code, explanation);
+}
+
 export default ArrayHandler;

packages/backend/src/modules/simulators/c/simulator.ts

@@ -11,6 +11,7 @@ import { CallStack, ScopeManager, type Step, type MemoryBlock, type Variable, ty
 import { registry, type SimContext } from './handlers';
 import { ExpressionEvaluator, type EvalContext } from './evaluator';
 import { FrameManager, ParameterSetup } from './execution';
+import { clearStructDefs } from './handlers/struct.handler';
 import type { VisualizationEvent } from '@codeinsight/shared';
 
 /**
@@ -92,6 +93,12 @@ class CSimulator implements SimContext, EvalContext {
     this.parseResult = parseCode(code);
     const { functions, sourceLines } = this.parseResult;
 
+    // 이전 실행 잔여 struct 정의 정리
+    clearStructDefs();
+
+    // 전역 struct 정의 사전 처리 (함수 바깥의 struct 정의를 스캔)
+    this.preprocessGlobalStructs(sourceLines);
+
     // main 함수 찾기
     const mainFunc = functions.get('main');
     if (!mainFunc) {
@@ -192,6 +199,68 @@ ${headerExplanations}
     return steps;
   }
 
+  /**
+   * 전역 struct 정의 사전 처리
+   * 함수 바깥의 struct 정의를 찾아 StructHandler에 위임
+   * 멀티라인 struct도 한 줄로 병합하여 처리
+   */
+  private preprocessGlobalStructs(sourceLines: string[]): void {
+    // 함수 영역을 파악 (함수 본문 내부인지 판별용)
+    const functionRanges: Array<{ start: number; end: number }> = [];
+    if (this.parseResult) {
+      for (const [, func] of this.parseResult.functions) {
+        // bodyStart/bodyEnd는 1-indexed
+        functionRanges.push({ start: func.bodyStart, end: func.bodyEnd });
+      }
+    }
+
+    const isInsideFunction = (lineIdx: number): boolean => {
+      const lineNum = lineIdx + 1; // 1-indexed
+      return functionRanges.some((r) => lineNum >= r.start && lineNum <= r.end);
+    };
+
+    let i = 0;
+    while (i < sourceLines.length) {
+      if (isInsideFunction(i)) {
+        i++;
+        continue;
+      }
+
+      const line = sourceLines[i].trim();
+
+      // struct 키워드로 시작하고 멤버 정의를 포함하는 패턴 감지
+      if (/^struct\s+\w+\s*\{/.test(line)) {
+        // 한 줄에 완결되는 경우: struct Point { int x; int y; };
+        if (/\}/.test(line)) {
+          const cleanCode = line.replace(/;$/, '').trim();
+          this.analyzeLine(i + 1, cleanCode);
+          i++;
+          continue;
+        }
+
+        // 멀티라인 struct: 닫는 }까지 병합
+        let merged = line;
+        let j = i + 1;
+        while (j < sourceLines.length) {
+          const nextLine = sourceLines[j].trim();
+          merged += ' ' + nextLine;
+          if (nextLine.includes('}')) {
+            break;
+          }
+          j++;
+        }
+
+        // 병합된 한 줄을 정리하고 analyzeLine에 전달
+        const cleanMerged = merged.replace(/\s+/g, ' ').replace(/;$/, '').trim();
+        this.analyzeLine(i + 1, cleanMerged);
+        i = j + 1;
+        continue;
+      }
+
+      i++;
+    }
+  }
+
   /**
    * 함수 진입 스텝 생성
    */