samchon/ttsc

A typescript-go toolchain for compiler-powered plugins and type-safe execution.

• ttsc: 빌드(build), 검사(check), 변환(transform).
• ttsx: 타입 검사를 거쳐 TypeScript를 실행합니다.
• @ttsc/lint: 컴파일러 오류로 린트 위반을 처리합니다.
• @ttsc/evidence: 요구사항 커버리지(requirement coverage)가 100%가 아니면 빌드가 실패합니다.
• @ttsc/graph: 에이전트 토큰을 92% 절감하는 컴파일러 지식 그래프(compiler knowledge graph)입니다.
• 플러그인 지원: typia와 같은 컴파일러 기반 라이브러리들.

설정 (Setup)

ttsc는 tsc의 대체재(drop-in replacement)입니다. 동일한 tsconfig.json을 읽고, 동일한 플래그를 사용하며, 동일한 JavaScript를 내보내며, 프로젝트를 타입 검사하는 과정에서 플러그인을 실행합니다.

npm install -D ttsc typescript

npx ttsx src/index.ts   # 파일을 먼저 타입 검사하며 실행
npx ttsc                # 빌드
npx ttsc --noEmit       # 검사만 수행
...

ttsx는 tsx나 ts-node가 파일을 실행하는 방식과 같지만, 프로젝트 전체를 먼저 타입 검사하기 때문에 타입 오류가 발생하면 아무것도 실행되지 않고 중단됩니다.

Node 또는 테스트 러너(test runner)가 프로세스를 소유할 때 동일하게 검사된 런타임(checked runtime)을 미리 로드합니다:

node --require ttsc/register src/index.ts
mocha --require ttsc/register --extension ts,tsx "test/**/*.ts"

ttsc/register는 각 TypeScript 루트에 대해 가장 가까운 tsconfig.json을 찾아내고, 해당 플러그인을 적용하며, 프로젝트가 타입 검사를 통과하지 못하면 실행을 거부합니다.

이것으로 CLI(Command Line Interface) 사용법은 끝났습니다. 각 통합(integration)에는 짧은 가이드가 있습니다:

• @ttsc/unplugin: Vite, Rollup, Rolldown, esbuild, webpack, Rspack, Next.js, Turbopack, Farm, 그리고 Bun을 지원합니다.
• @ttsc/metro: React Native와 Expo를 지원합니다.
• @ttsc/vscode: 라이브 에디터 진단 기능을 제공합니다.

Lint (린트)

이미 실행한 타입 체크 과정에서 린팅과 포맷팅을 수행할 수 있습니다. 21가지 패밀리에 걸쳐 720개 이상의 규칙과 Prettier에서 포팅된 포매터가 포함되어 있습니다.

// src/index.ts
var x: number = 3;
let y: number = 4;
...

$ npx ttsc --noEmit
src/index.ts:3:7 - error TS2322: Type 'number' is not assignable to type 'string'.

...

두 가지 모두 하나의 스트림으로 도착하기 때문에, 이미 ttsc --noEmit을 실행하는 CI 단계는 두 번째 작업이나 두 번째 파싱 없이 린팅을 처리합니다. VS Code에서는 이 체크 내에서 규칙이 ESLint가 자체 명령어로 수행할 때보다 약 900배 빠르게 작동합니다.

npx ttsc fix는 자동 수정 및 포맷팅을 적용하며, npx ttsc format은 오직 포맷팅만 수행합니다. 규칙과 모든 format 키는 Lint and Format guide를 참조하세요.

Evidence Graph (증거 그래프)

모든 명세(specification)가 컴파일 시간의 의무 사항이 됩니다.

/**
 * @evidence docs/discount.md#coupon-stacking 구매자 관점에서 정의하는 발행사별 스태킹 한도를 명시합니다.
 * @evidence POST:/orders/{orderId}/coupons 과도하게 쌓인 쿠폰 세트에 대해 이 엔드포인트가 반환하는 거부 사유를 설명합니다.
...

각 태그는 선언된 의무 사항이며, 컴파일러가 모든 것을 감사하므로 요구사항이나 원칙이 답변 없이 넘어가는 일이 없습니다.

lint.config.ts에서 누가 무엇을 빚지고 있는지 선언하며, the guide document에 모든 옵션이 있습니다.

$ npx ttsc
error TS16411: [evidence/graph] 'docs/discount.md#coupon-stacking'에 대한 확인(acknowledgement) 누락
  (Markdown H2 'Coupon Stacking' at docs/discount.md:3)
...

이러한 @evidence 태그가 없으면, 답변되지 않은 모든 의무 사항은 타입 오류와 같은 스트림에서 자체적으로 빌드를 실패하게 만듭니다.

에이전트는 답변되지 않은 것이 남아있는 동안에는 끝낼 수 없으므로, 건너뛴 것도 보이지 않게 남지 않습니다.

그 결과는 첫 번째 패스에서 100% 커버리지를 달성하며, 이러한 의무가 없는 동일한 프로젝트를 비용으로 할 때보다 훨씬 적은 토큰과 시간을 사용합니다.

컴파일러 지식 그래프 (Compiler Knowledge Graph)

코딩 에이전트는 파일을 검색하고 다시 읽는 대신 컴파일러로부터 답변을 얻습니다.

{
  "mcpServers": {
    "ttsc-graph": {
...

해당 서버는 타입 검사기가 해결한 그래프 위에서 하나의 타입이 지정된 MCP 도구를 노출합니다. 따라서 답변은 파일 본문을 포함하지 않으므로, 저장소 크기가 응답을 부풀릴 수 없습니다.

중앙값 답변 비용은 동일한 질문에 대한 토큰 및 도구 호출 횟수보다 훨씬 적습니다. 설계와 비교기는 @ttsc/graph에서 확인할 수 있습니다.

플러그인 (Plugins)

플러그인은 컴파일 과정에 추가 검사, 변환 또는 타입 기반 코드 생성을 연결합니다. 이 모든 것은 검사기가 이미 해결한 타입을 통해 구동됩니다. 이는 추가 단계 없이 모든 ttsc 빌드 및 ttsx 실행에서 작동합니다.

typia가 대표적인 예입니다. 어떤 타입의 유효성 검사기(validator)를 요청하면, 변환은 빌드 시간에 구현을 작성합니다:

import typia from "typia";

export const isStringArray = typia.createIs<string[]>();

스키마도 없고, 데코레이터(decorator)도 없습니다. 이 호출은 일반 함수로 컴파일됩니다:

export const isStringArray = (() => {
  return (input) =>
    Array.isArray(input) && input.every((elem) => "string" === typeof elem);
...

이 저장소에 포함된 유틸리티 플러그인들:

• @ttsc/banner: @packageDocumentation JSDoc 배너를 추가합니다.
• @ttsc/evidence: 요구사항을 코드, 테스트 또는 문서가 이름으로 인지할 때까지 컴파일 오류로 만듭니다.
• @ttsc/graph: 코딩 에이전트에게 검사기(checker)가 해결한 코드 그래프를 노출하는 MCP 서버입니다.
• @ttsc/lint: TypeScript 소스를 린팅하고 포맷합니다.
• @ttsc/paths: 소스 경로 별칭(path aliases)을 재작성하여 JS 및 선언(declaration) emit이 상대 임포트를 받도록 합니다.
• @ttsc/strip: 구성된 호출과 debugger 구문을 제거합니다.
• @ttsc/unplugin: unplugin이 지원하는 번들러 내부에서 ttsc 플러그인을 실행합니다.
• @ttsc/metro: React Native 및 Expo용 Metro 내부에서 ttsc 플러그인을 실행합니다.

에코시스템 플러그인입니다. 여러분이 추가한 PR도 환영합니다:

• nestia: NestJS 라우트, OpenAPI 및 SDK를 생성합니다.
• typia: 유효성 검사기(validators), 직렬화기(serializers) 및 타입 기반 런타임 코드를 생성합니다.

직접 플러그인을 작성하려면 Plugin Development를 참고하세요.

스폰서 (Sponsors)

후원에 감사드립니다.

여러분의 기부금은 ttsc 개발을 장려합니다.

참고 자료 (References)

• TypeScript 러너: ts-node 및 tsx
• 트랜스포머 도구링 (Transformer tooling): ttypescript 및 ts-patch
• 영감을 받은 프로젝트: typical, tsgonest 및 codegraph.