TypeScript

이것은 TypeScript 7.0.2의 회귀 버그입니다 (6.0.3에서는 정상 작동했습니다): 패키지의 모듈 선언 파일 내부의 declare global 블록이 변경될 때 .tsbuildinfo 캐시가 무효화되지 않기 때문에 증분 빌드가 오래된 진단 정보를 유지합니다. 증분 실행에서는 오류를 보고하지 않지만 클린 빌드에서는 오류를 보고합니다 (예: TS2345).

수정 및 해결 방법:
1. TypeScript 7.1+로 업그레이드 — 해당 버그는 7.1 nightly에서 수정된 것이 확인되었습니다 (npm i typescript@next).
2. 7.0.x 버전을 계속 사용해야 하는 경우, 매번 실행 전에 빌드 정보 파일을 삭제하여 전체 재검사를 강제하세요: rm -f <path>.tsbuildinfo && tsc --noEmit --incremental --tsBuildInfoFile <path>.tsbuildinfo -p tsconfig.json.
3. 또는 클린 비증분 실행으로 타입을 검증하세요: tsc --noEmit -p tsconfig.json.

참고: 이 문제는 일반적으로 node_modules에 있는 패키지의 전역 타입 확장에 대해 tsc --noEmit --incremental을 실행하는 타입 테스트 설정 (예: Vitest/expect-webdriverio)에서 발생합니다.

이는 TypeScript 7.0.2의 알려진 버그입니다. isolatedModules + declaration + incremental을 함께 사용할 때, 전역 스코프 파일(예: declare global 또는 @types/node)이 소스 파일과 같은 실행에서 변경되면, 종속 파일의 .d.ts가 다시 생성되지 않고 .tsbuildinfo가 이를 최신 상태로 잘못 기록하므로, 오래된 출력이 빌드 전반에 걸쳐 계속 유지됩니다.

해당 수정(microsoft/typescript-go#4665)은 7.0.x로 백포트되지 않습니다 — 팀은 중요한 보안/안정성 수정만 백포트합니다. 해결 방법:

1. TypeScript 7.1(또는 nightly typescript@7.1.0-dev.20261011.1 이상)로 업그레이드: npm install typescript@next.
2. 7.0.2에서의 우회 방법: 의존성 버전 업그레이드나 편집으로 전역 선언이 변경될 때마다 .tsbuildinfo 파일을 삭제하거나(또는 클린 빌드를 실행하여) 모든 선언 파일의 전체 재생성을 강제합니다.

이는 네이티브 TypeScript 7.0.2 컴파일러(tsgo)에서 발생한 회귀(regression)이며, 동일한 코드는 TS 5.9.3 및 6.0.3에서는 문제없이 컴파일됩니다. 해결 방법: Exclude로 재매핑된 키 집합을 다시 계산하는 대신 매핑된 타입 자체의 keyof로 인덱싱하세요. 매핑된 타입을 별칭으로 추출하고 Map<T>[keyof Map<T>]를 사용하세요:

type EntryPathMap<T> = {
  [K in keyof T & string as K extends '_key' ? never : K]: [PathTuples<T[K]>] extends [never]
    ? never
    : readonly [K, ...ChildPaths<T[K]>];
};
type PathTuples<T> = T extends object ? EntryPathMap<T>[keyof EntryPathMap<T>] : [];

keyof EntryPathMap<T>는 Exclude<keyof T & string, '_key'>와 동일한 키 집합으로 해석되며 모든 컴파일러에서 허용됩니다. 또는 네이티브 컴파일러 회귀가 수정될 때까지 TypeScript를 5.9.3 또는 6.0.3(@typescript/typescript6)으로 고정하세요.

이것은 typescript-go LSP 파일 감시자(lspwatcher.WatchFiles)의 경쟁 상태(race condition)입니다. 감시자는 구독을 설치하는 동안 락을 해제하는데, 이때 Watcher.Close가 그 사이에 실행되면 w.watches = nil로 설정되고 이후의 맵 할당에서 패닉이 발생합니다. 일반적으로 백그라운드 프로젝트 스냅샷 업데이트가 감시를 다시 등록하는 동안 클라이언트가 문서를 닫고 종료할 때, 즉 클라이언트가 동적 workspace/didChangeWatchedFiles 등록을 알리지 않아 서버가 내부 감시자를 사용하는 경우에 발생합니다. tsgo --lsp --stdio가 상태 코드 2로 종료됩니다.

**수정 방법:** TypeScript 네이티브 프리뷰(typescript@7.x / tsgo)를 microsoft/typescript-go#4845의 수정이 포함된 빌드로 업데이트하세요. 해당 수정은 구독을 게시하기 전에 락이 유지된 상태에서 closed를 다시 확인하여, 패닉을 일으키는 대신 lspwatcher: closed 오류를 반환합니다.

**업그레이드할 수 있을 때까지의 우회 방법:**
1. LSP 클라이언트가 동적 파일 감시 등록(workspace.didChangeWatchedFiles.dynamicRegistration: true)을 알리도록 하여, 서버가 경쟁 상태가 존재하는 내부 감시자 대신 클라이언트가 관리하는 감시자를 사용하게 하세요.
2. 소스에서 직접 빌드하는 경우, internal/lsp/lspwatcher/lspwatcher.go(WatchFiles)를 패치하세요: w.mu를 다시 획득한 후 w.closed를 다시 확인하고, 닫혀 있는 경우 아직 게시되지 않은 구독을 닫은 뒤 기존 lspwatcher: closed 오류를 반환하세요. 패닉을 억제하거나 감시자를 비활성화하지 마세요.

이것은 TypeScript 5.0.4의 lib.decorators.d.ts에 있는 문서 버그입니다. 예제에서 ClassMethodDecoratorFunction을 참조하지만, 해당 타입은 lib 파일에 포함된 적이 없습니다(예제에는 잘못된 함수 구문도 포함되어 있습니다). 해결 방법: 프로젝트에서 해당 타입을 직접 선언하세요:

type ClassMethodDecoratorFunction<
  This = unknown,
  Value extends (this: This, ...args: any[]) => any = (this: This, ...args: any[]) => any
> = (
  value: Value,
  context: ClassMethodDecoratorContext<This, Value>
) => Value | void;

그러면 바인딩된 메서드 예제가 동작합니다:

const bound: ClassMethodDecoratorFunction = function (value, context) {
  if (context.private) throw new TypeError("Not supported on private methods.");
  context.addInitializer(function (this: any) {
    this[context.name] = this[context.name].bind(this);
  });
};

참고: 일반 function 표현식을 사용하고(공식 예제의 단축 구문은 잘못된 구문입니다), this[context.name]에서 발생하는 implicit-any 오류를 피하려면 this를 any로 캐스팅하세요(또는 매핑된 접근 방식을 사용하세요). lib.decorators.d.ts의 잘못된 예제는 5.0.x 이후에 수정되었으므로 최신 TypeScript 버전으로 업그레이드하는 것도 권장됩니다. 커뮤니티의 ajvincent/es-membrane(ClassMethodDecoratorFunction.d.mts)에서 미리 만들어진 타입을 사용할 수도 있습니다.