project

name	project
description	Defines the ttsc product contract, workspace layout, package boundaries, and canonical commands. Use when orienting in the repository, working inside any package, or choosing a build, test, or format command.

Project Outline

Product Contract

ttsc is a standalone TypeScript-Go compiler, runtime, plugin host, and LSP host. It ships three CLIs and a plugin protocol:

• ttsc: build, check, watch, and source-to-source transform on top of typescript (the native TypeScript-Go compiler).
• ttsx: run a TypeScript entrypoint after a real type-check (a typed tsx/ts-node).
• ttscserver: LSP host wrapping tsc --lsp --stdio and proxying JSON-RPC so ttsc plugin diagnostics, code actions, and workspace/executeCommand handlers reach the editor through one stream.
• Plugins: Go source packages that share TypeScript-Go's AST/Checker. Executable package main sources build as sidecars; non-main transform packages link into a native host. ttsc builds plugin source on demand and caches the binary.

The contract is general-purpose. Downstream projects like typia and nestia are compatibility fixtures, not the product definition.

Graph MCP work has an additional contract in graph.md. Read it before changing packages/graph, graph benchmark prompts, graph benchmark runners, or the graph benchmark website.

Layout

• packages/ttsc: JS launcher/API plus Go host (cmd/*, driver, internal, utility, shim/). driver.PluginSource is the public seam embedders implement; NativePluginSource adapts capabilities.lsp sidecars. internal/lspserver is the byte-level LSP proxy ttscserver uses.
• packages/{banner,paths,strip}: utility transform plugins with package-owned driver/ logic linked into a generic native host.
• packages/lint: @ttsc/lint with its own native engine, exposing LSP verbs from linthost/lsp.go so ttscserver and packages/vscode call them through the language client. Rules may consult the TypeScript-Go Checker directly via ctx.Checker; third-party rules ship through the public rule package and may use the rule/astutil helpers.
• packages/evidence: @ttsc/evidence, a lint contributor that turns a configured requirement into a compile error until code, tests, or docs acknowledge it by name. Ships Go source under native/ rather than a module, because ttsc copies a contributor's source directory into @ttsc/lint's own Go module and rejects a go.mod inside it; the one a level above exists for local tooling and points at the sibling packages. Its domain model is the project/evidence skill.
• packages/wasm: @ttsc/wasm, Go host helper plus JS boot scaffolding for in-browser ttsc playgrounds. host.Expose binds globalThis[apiName] with the standard verbs (build/check/transform/plugin/plugins/version) plus fountain verbs (snapshot/getDiagnostics/getNodeAtPosition/...) over a snapshot handle table.
• packages/playground: @ttsc/playground, reusable Web Worker + React shell built on @ttsc/wasm. Exports createWorkerCompiler (worker-side ICompilerService factory), PlaygroundShell (Tailwind 4 React component), runtime npm dependency installer, typia source/runtime pack helpers, and Monaco editor wrappers. Consumed by website/ and typia/website/.
• packages/factory: @ttsc/factory, a hand-written, zero-dependency TypeScript AST factory and width-aware printer (no typescript import) for source-code generation that survives the tsgo migration. Standalone published library; nothing else in the workspace depends on it yet.
• packages/unplugin: bundler adapters.
• packages/metro: React Native and Expo Metro adapter built on @ttsc/unplugin.
• packages/vscode: VS Code extension that wires vscode-languageclient to ttscserver, exposes the built-in lint/format command bridge, and lets other plugin command ids execute through the language client with editor-applied WorkspaceEdits.
• packages/ttsc-*: per-platform packages (native helper + bundled Go SDK). Each ships both the ttsc helper and the ttscserver binary.
• tests/projects: project-shaped fixtures copied into temp dirs by TestProject.copyProject.
• tests/test-*: feature-test packages (run via pnpm test:features).
• tests/utils: shared helpers (@ttsc/testing).
• tests/<plugin-name>: workspace packages that need to be require.resolve-able from a fixture's node_modules (e.g. tests/lint-contributor-demo). Built by scripts/build-current.cjs before tests run.
• benchmarks/*: one private workspace package per benchmark, and the three differ in kind. graph and performance are this repository's own harnesses, each holding short, export-free executable bootstraps and reusable TtscBenchmark* / ITtscBenchmark* implementations, with the graph prompt assets under benchmarks/graph/assets. evidence is vendored from samchon/lint-plugin-evidence and keeps that project's conventions.
• website: Nextra-based docs site (src/content/docs/**/*.mdx) that is the canonical home for guides, shipped to https://ttsc.dev.
• config, scripts: shared tsconfig and workspace scripts.

Commands

pnpm install
pnpm format
pnpm build
pnpm test:go
pnpm test