Files

T

Antigravity Agent f8b21af4be Wiki cleanup: error-doc removal, dedup merge, link normalization

10_Wiki/Topics 대규모 정리:
- 오류 캡처/미완성 stub 문서 227개 제거
- 교차폴더 중복 43클러스터 병합 (63파일 → redirect)
- 링크명 정규화: 깨진 링크 수정·redirect 직결·개념 매핑 ~2,400건
- 카테고리 MOC 6개 신규 생성
- Graph 섹션 미해결 related-keyword 링크 10,058건 제거

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-20 23:52:15 +09:00

4.7 KiB

Raw Blame History

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

title

Issue 001 Combat Reference Error Troubleshooting

매 한 줄

"매 ReferenceError 의 root cause 매 hoisting, TDZ, circular import, async timing 의 4 가지로 collapse". 매 case study (combat system 의 reference error) 를 통해 매 systematic debug pipeline 정리.

매 핵심

매 ReferenceError 4 카테고리

Undeclared: variable 매 declare 안됨 (typo, missing import).
TDZ: let/const 매 init 전 access (temporal dead zone).
Circular import: A imports B, B imports A → 매 partially-loaded module.
Async timing: top-level await, dynamic import 의 race.

매 Combat case (post-mortem 요약)

Symptom: ReferenceError: CombatEngine is not defined 매 production only.
Root cause: Vite tree-shaking 의 side-effect import 의 elimination.
Fix: package.json 의 "sideEffects": ["./src/combat/registry.ts"].

매 Debug 절차

Reproduce: minimal repo.
Stack trace: 매 first frame 의 file:line.
Bisect: git bisect or feature flag.
Verify: regression test 추가.

💻 패턴

TDZ 의 detection

// BAD — TDZ
console.log(x); // ReferenceError
let x = 1;

// GOOD — declare 먼저
let x: number;
x = 1;
console.log(x);

Circular import resolve

// a.ts
import { B } from './b';
export class A { b = new B(); }

// b.ts — circular
// import { A } from './a';  // 매 X
// 매 type-only import 로 break:
import type { A } from './a';
export class B { parent?: A; }

Vite sideEffects 의 protect

// package.json
{
  "sideEffects": [
    "./src/combat/registry.ts",
    "./src/polyfills/*.ts",
    "*.css"
  ]
}

Webpack module federation 의 안전한 dynamic

const Combat = await import(/* webpackChunkName: "combat" */ './combat')
  .catch(err => {
    console.error('Combat module failed', err);
    return { CombatEngine: class FallbackEngine {} };
  });

Stack trace parser

function parseRefError(err: Error): { name: string; file?: string; line?: number } {
  const m = err.message.match(/(\w+) is not defined/);
  const frame = err.stack?.split('\n')[1]?.match(/at .* \((.+):(\d+):\d+\)/);
  return {
    name: m?.[1] ?? 'unknown',
    file: frame?.[1],
    line: frame ? Number(frame[2]) : undefined
  };
}

Regression test

import { describe, it, expect } from 'vitest';
import { CombatEngine } from '@/combat';

describe('combat module loading', () => {
  it('exports CombatEngine after tree-shake', () => {
    expect(CombatEngine).toBeDefined();
    expect(typeof CombatEngine).toBe('function');
  });

  it('registry has registered abilities', async () => {
    const { abilityRegistry } = await import('@/combat/registry');
    expect(abilityRegistry.size).toBeGreaterThan(0);
  });
});

import * as Sentry from '@sentry/node';
Sentry.init({
  beforeSend(event, hint) {
    if (hint.originalException instanceof ReferenceError) {
      event.tags = { ...event.tags, error_class: 'reference' };
    }
    return event;
  }
});

매 결정 기준

상황	Approach
TDZ 의 의심	매 declaration 위치 의 audit
Circular import	type-only import or DI
Tree-shake elimination	sideEffects 명시
Async race	top-level await guard

기본값: 매 minimal repro → bisect → regression test 의 add.

🔗 Graph

부모: Debugger_Techniques
Adjacent: Source Maps · Sentry

🤖 LLM 활용

언제: stack trace + module graph paste → root cause hypothesis. 언제 X: 매 production memory dump 매 직접 read X — local repro 가 우선.

❌ 안티패턴

Catch and ignore: try { ... } catch {} — error 매 silently 사라짐.
No regression test: fix 후 test 매 추가 X → 매 regression repeat.
Random side-effect import: import './magic' — tree-shake 가 죽임.
Production-only debug: local 매 repro 안하고 prod 에서 console.log.

🧪 검증 / 중복

Verified (MDN ReferenceError, Vite tree-shake docs).
신뢰도 B (case-specific 의 detail).

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — ReferenceError 의 4 카테고리 + combat case

4.7 KiB Raw Blame History