ttsc 0.19.0 → 0.19.2

package/README.md

@@ -9,135 +9,104 @@ A `typescript-go` toolchain for compiler-powered plugins and type-safe execution
 - **`ttsc`**: build, check, and transform.
 - **`ttsx`**: execute TypeScript with type checking.
 - [**`@ttsc/lint`**](https://github.com/samchon/ttsc/tree/master/packages/lint): lint violations as compiler errors.
-- [**`@ttsc/graph`**](https://github.com/samchon/ttsc/tree/master/packages/graph): MCP code graph that reduce token usage.
+- [**`@ttsc/graph`**](https://github.com/samchon/ttsc/tree/master/packages/graph): MCP code graph that reduces agent token usage.
 - **plugin support**: compiler-powered libraries, such as `typia`.
 
 ## Setup
 
-### Install
-
-Install `ttsc`, `@ttsc/lint`, and the native TypeScript compiler:
+`ttsc` is a drop-in replacement for `tsc`. It reads the same `tsconfig.json`, takes the same flags, and emits the same JavaScript, then runs your plugins in the pass that type-checks the project.
 
 ```bash
-npm install -D ttsc @ttsc/lint typescript
+npm install -D ttsc typescript
 ```
 
-### Commands
-
-Run TypeScript directly with `ttsx` (CLI command):
-
 ```bash
-npx ttsx src/index.ts
+npx ttsx src/index.ts   # run a file, type-checked first
+npx ttsc                # build
+npx ttsc --noEmit       # check only
+npx ttsc --watch        # rebuild on save
 ```
 
-Build, check, or watch the project with `ttsc`:
+`ttsx` runs a file the way `tsx` or `ts-node` does, but it type-checks the whole project first, so a type error stops the run before anything executes.
 
-```bash
-npx ttsc
-npx ttsc --noEmit
-npx ttsc --watch
-```
+That covers the CLI. The integrations each have a short guide:
 
-Rewrite source files in place with the `@ttsc/lint` format rules:
+- [`@ttsc/unplugin`](https://ttsc.dev/docs/setup/unplugin): Vite, Rollup, Rolldown, esbuild, webpack, Rspack, Next.js, Turbopack, Farm, and Bun.
+- [`@ttsc/metro`](https://ttsc.dev/docs/setup/metro): React Native and Expo.
+- [`@ttsc/vscode`](https://ttsc.dev/docs/setup/vscode): live editor diagnostics.
 
-```bash
-npx ttsc format
-```
+## Lint
 
-### Bundlers
+Lint and format at compiler speed: up to 800x faster than ESLint.
 
-Use `@ttsc/unplugin` when a bundler owns your build.
+`@ttsc/lint` replaces ESLint and Prettier with rules that run inside the type-check. It shares one AST pass with the compiler, so linting and formatting add almost nothing to the build you already run.
 
-It runs `ttsc` plugins inside supported bundlers.
+Configuration is a single file. Each rule takes `"error"`, `"warning"`, or `"off"`, and the `format` block mirrors `.prettierrc`.
 
 ```bash
-npm install -D ttsc @ttsc/lint typescript
-npm install -D @ttsc/unplugin
+npm install -D @ttsc/lint
 ```
 
-Minimal Vite setup:
-
 ```ts
-// vite.config.ts
-import ttsc from "@ttsc/unplugin/vite";
-import { defineConfig } from "vite";
-
-export default defineConfig({
-  plugins: [ttsc()],
-});
-```
-
-Supported bundlers:
-
-- Vite
-- Rollup
-- Rolldown
-- esbuild
-- Webpack
-- Rspack
-- Next.js
-- Turbopack
-- Farm
-- Bun
-
-See [`@ttsc/unplugin`](https://github.com/samchon/ttsc/tree/master/packages/unplugin) for full setup and adapter options.
+// lint.config.ts
+import type { ITtscLintConfig } from "@ttsc/lint";
 
-### React Native / Expo
-
-React Native and Expo bundle with Metro, so the `ttsc` CLI and `@ttsc/unplugin` never run. `@ttsc/metro` is a Metro transformer that runs `ttsc` plugins on each TypeScript file, then hands the result to your existing Expo or React-Native Babel transformer.
-
-```bash
-npm install -D ttsc @ttsc/lint typescript
-npm install -D @ttsc/metro
+export default {
+  rules: {
+    "no-var": "error",
+    "prefer-const": "error",
+    "typescript/no-explicit-any": "warning",
+  },
+  format: {
+    printWidth: 100,
+    singleQuote: true,
+    trailingComma: "all",
+  },
+} satisfies ITtscLintConfig;
 ```
 
-Wrap your Metro config (CommonJS, the standard for `metro.config.js`):
+Violations surface as compiler diagnostics, in the same stream as type errors, so the CI step that already runs `ttsc --noEmit` gates lint without a second job:
 
-```js
-// metro.config.js (Expo)
-const { getDefaultConfig } = require("expo/metro-config");
-const { withTtsc } = require("@ttsc/metro");
-
-module.exports = withTtsc(getDefaultConfig(__dirname));
+```ts
+// src/index.ts
+var count = 3;
+let total = count;
 ```
 
-For bare React Native, wrap `getDefaultConfig` from `@react-native/metro-config` instead. See [`@ttsc/metro`](https://github.com/samchon/ttsc/tree/master/packages/metro) for options and the v1 caveats.
-
-### VS Code Extension
+```text
+$ npx ttsc --noEmit
+src/index.ts:2:5 - error TS17397: [prefer-const] Use const instead of let.
 
-Install the VS Code extension for live TypeScript-Go editor features plus saved-state ttsc plugin diagnostics and actions.
+2 let total = count;
+      ~~~~~~~~~~~~~
 
-Install it from the VS Code Marketplace by searching `ttsc`, or run:
+src/index.ts:1:1 - error TS11966: [no-var] Unexpected var, use let or const instead.
 
-```bash
-npx @ttsc/vscode
+1 var count = 3;
+  ~~~~~~~~~~~~~~
 ```
 
-Then turn on format-on-save in `.vscode/settings.json`:
+Clean the project in place:
 
-```jsonc
-"[typescript][typescriptreact]": {
-  "editor.defaultFormatter": "samchon.ttsc",
-  "editor.formatOnSave": true
-}
+```bash
+npx ttsc fix      # lint autofixes + format edits
+npx ttsc format   # format edits only, never changes behavior
 ```
 
-Lint fixes stay off-save by default; opt in with `"editor.codeActionsOnSave": { "source.fixAll.ttsc": "explicit" }`.
+The rule catalog and every `format` key are in the [Lint & Format guide](https://ttsc.dev/docs/lint).
 
-See [`@ttsc/vscode`](https://github.com/samchon/ttsc/tree/master/packages/vscode) for requirements and settings.
+## Graph
 
-### Coding Agents (MCP)
+Your coding agent answers from the compiler, spending roughly 90% fewer tokens.
 
-`@ttsc/graph` gives a coding agent a checker-resolved graph of your project, over MCP.
+`@ttsc/graph` is an MCP server that gives the agent a compiler-resolved graph of your project: what calls what, what a change would touch, and where to start reading. The agent asks the type checker instead of grepping and re-reading files.
 
-It answers what relates to a symbol and what a change affects, straight from the type checker, so the agent stops grepping and re-reading files.
+Register it with your MCP client. For Claude Code, a `.mcp.json` in the project root:
 
 ```bash
 npm install -D ttsc @ttsc/graph typescript
 ```
 
-Point your agent's MCP client at it. For Claude Code:
-
 ```json
 {
   "mcpServers": {
@@ -149,119 +118,32 @@ Point your agent's MCP client at it. For Claude Code:
 }
 ```
 
-On codegraph's own agent-cost benchmark, Claude agents answer reading zero files, cutting tokens by 77% to 86% and tool calls by 94% to 95%. See [`@ttsc/graph`](https://github.com/samchon/ttsc/tree/master/packages/graph) and the [benchmark](https://ttsc.dev/docs/benchmark/graph).
+On the agent-cost benchmark, Claude agents answer reading zero files, cutting tokens by roughly 90% and tool calls by 93% to 96%. The design and per-repository numbers are in the [Code Graph guide](https://ttsc.dev/docs/graph) and the [benchmark](https://ttsc.dev/docs/benchmark/graph).
 
-Your agent picks the tools up from the MCP handshake and uses them on its own. See [Setup](https://ttsc.dev/docs/setup#coding-agents-ttscgraph) for the full walk-through.
+![Median tokens on the shared onboarding question, lower is better](https://ttsc.dev/benchmark/svg/graph-common-codex-gpt-5.6-sol.svg)
 
 ## Plugins
 
-Plugins let libraries add compile-time checks, transforms, and type-driven code generation to normal `ttsc` and `ttsx` runs.
+A plugin hooks the compile to add checks, transforms, or type-driven code generation, all driven by the types the checker has already resolved. It runs on every `ttsc` build and `ttsx` run, with no extra step.
 
-```bash
-# compile
-npx ttsc
-
-# execute
-npx ttsx src/index.ts
-```
-
-### Transform Example
-
-A transform uses TypeScript types to generate JavaScript before runtime.
+[typia](https://typia.io) is the canonical one. Ask it for a validator of any type, and the transform writes the implementation at build time:
 
 ```ts
-import typia, { tags } from "typia";
-import { v4 } from "uuid";
-
-const matched: boolean = typia.is<IMember>({
-  id: v4(),
-  email: "samchon.github@gmail.com",
-  age: 30,
-});
-console.log(matched); // true
-
-interface IMember {
-  id: string & tags.Format<"uuid">;
-  email: string & tags.Format<"email">;
-  age: number &
-    tags.Type<"uint32"> &
-    tags.ExclusiveMinimum<19> &
-    tags.Maximum<100>;
-}
-```
-
-The transform replaces `typia.is<IMember>()` with dedicated JavaScript checks at build time:
-
-```js
 import typia from "typia";
-import * as __typia_transform__isFormatEmail from "typia/lib/internal/_isFormatEmail";
-import * as __typia_transform__isFormatUuid from "typia/lib/internal/_isFormatUuid";
-import * as __typia_transform__isTypeUint32 from "typia/lib/internal/_isTypeUint32";
-import { v4 } from "uuid";
-
-const matched = (() => {
-  const _io0 = (input) =>
-    "string" === typeof input.id &&
-    __typia_transform__isFormatUuid._isFormatUuid(input.id) &&
-    "string" === typeof input.email &&
-    __typia_transform__isFormatEmail._isFormatEmail(input.email) &&
-    "number" === typeof input.age &&
-    __typia_transform__isTypeUint32._isTypeUint32(input.age) &&
-    19 < input.age &&
-    input.age <= 100;
-  return (input) => "object" === typeof input && null !== input && _io0(input);
-})()({
-  id: v4(),
-  email: "samchon.github@gmail.com",
-  age: 30,
-});
-console.log(matched); // true
-```
-
-## Programmatic API
-
-Embed `ttsc` from another Node tool with the `TtscCompiler` class:
-
-```ts
-import { TtscCompiler } from "ttsc";
 
-const compiler = new TtscCompiler({ cwd: "./project" });
-const result = compiler.compile();
-
-if (result.type === "success") {
-  for (const [path, text] of Object.entries(result.output)) {
-    // path is project-relative ("dist/index.js", "dist/index.d.ts", ...)
-    console.log(path, text.length);
-  }
-} else if (result.type === "failure") {
-  for (const d of result.diagnostics) {
-    console.error(`${d.file}:${d.line}:${d.character} ${d.messageText}`);
-  }
-}
+export const isStringArray = typia.createIs<string[]>();
 ```
 
-When one process transforms a project's files repeatedly (a watch server, an editor, a codegen tool), `TtscService` keeps the compiler host warm instead of recompiling per call. It compiles the project once, then answers per-file transform requests, and reflects in-memory edits through `updateFile`:
+No schema, no decorator. The call compiles to a plain function:
 
-```ts
-import { TtscService } from "ttsc";
-
-const service = new TtscService({ cwd: "./project" });
-try {
-  const code = await service.transformFile("src/index.ts");
-  await service.updateFile("src/index.ts", "export const x: number = 2;\n");
-  const next = await service.transformFile("src/index.ts");
-} finally {
-  service.dispose();
-}
+```js
+export const isStringArray = (() => {
+  return (input) =>
+    Array.isArray(input) && input.every((elem) => "string" === typeof elem);
+})();
 ```
 
-`TtscService` runs through the linked-plugin host, so the project must declare at least one transform-stage plugin.
-
-See the [Programmatic API guide](https://ttsc.dev/docs/ttsc/api) for the full lifecycle, plugin overrides, and patterns. For browser embedding, see [`@ttsc/wasm`](https://github.com/samchon/ttsc/tree/master/packages/wasm) and the higher-level [`@ttsc/playground`](https://github.com/samchon/ttsc/tree/master/packages/playground) package.
-
-### List of Plugins
-
-`ttsc` ships a few small utility plugins in this repository.
+Utility plugins shipped in this repository:
 
 - [`@ttsc/banner`](https://github.com/samchon/ttsc/tree/master/packages/banner): adds `@packageDocumentation` JSDoc banners.
 - [`@ttsc/lint`](https://github.com/samchon/ttsc/tree/master/packages/lint): lints and formats TypeScript source.
@@ -271,13 +153,13 @@ See the [Programmatic API guide](https://ttsc.dev/docs/ttsc/api) for the full li
 - [`@ttsc/unplugin`](https://github.com/samchon/ttsc/tree/master/packages/unplugin): runs `ttsc` plugins inside bundlers supported by `unplugin`.
 - [`@ttsc/metro`](https://github.com/samchon/ttsc/tree/master/packages/metro): runs `ttsc` plugins inside Metro for React Native and Expo.
 
-Plugin authors should start from the [`Guide Documents`](https://ttsc.dev/docs).
-
-Ecosystem plugins are listed below; PRs adding `ttsc` plugins are welcome.
+Ecosystem plugins; PRs adding yours are welcome:
 
 - [`nestia`](https://github.com/samchon/nestia): generates NestJS routes, OpenAPI, and SDKs.
 - [`typia`](https://github.com/samchon/typia): generates validators, serializers, and type-driven runtime code.
 
+To write your own, start from [Plugin Development](https://ttsc.dev/docs/development).
+
 ## Sponsors
 
 [![Sponsors](https://raw.githubusercontent.com/samchon/sponsor-images/refs/heads/master/public/circle.svg)](https://github.com/sponsors/samchon)

package/cmd/graphdump/main.go

@@ -50,7 +50,27 @@ func run() int {
 
   g := graph.Build(prog)
   ignored := graph.GitIgnoredFiles(root, g)
-  data, err := graph.MarshalDump(g, root, *tsconfig, ignored, graph.SourceTexts(prog), *pretty)
+  texts := graph.SourceTexts(prog)
+  // The viewer pipeline reduces nodes and edges and never asks whether the build
+  // universe moved or whether the disk still matches, so this tool pays for
+  // neither. It names its producer and digests what the checker read, and it
+  // declares exactly that and no more: a reader learns the universe and the disk
+  // digests are absent, rather than reading an empty universe as "nothing
+  // changed" or an empty diskDigest as "the file could not be read". The shipped
+  // `ttscgraph dump` is the one that proves the whole contract.
+  data, err := graph.MarshalDump(g, root, *tsconfig, ignored, texts, graph.DumpOrigin{
+    Provenance: graph.NewProvenance(
+      root,
+      // No version: this tool is built from the tree on demand and never
+      // stamped, and an invented one would be worse than an absent one.
+      graph.Producer{Tool: "graphdump", Typescript: graph.TypescriptVersion()},
+      []string{graph.CapabilitySourceDigests},
+      nil,
+      nil,
+      texts,
+      nil,
+    ),
+  }, *pretty)
   if err != nil {
     fmt.Fprintf(os.Stderr, "graphdump: %v\n", err)
     return 1

package/cmd/ttsc/api_compile.go

@@ -10,8 +10,6 @@ import (
   "encoding/json"
   "flag"
   "fmt"
-  "path/filepath"
-  "strings"
 
   shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
 
@@ -146,16 +144,8 @@ func toAPICompileDiagnostic(diag driver.Diagnostic) apiCompileDiagnostic {
 // generated file. Files inside cwd use a slash-separated relative path (the
 // API contract). Files outside cwd — rare, e.g. a monorepo output rooted
 // above the project — are returned as an absolute slash path instead.
+// Delegates to the driver so every envelope section (typescript, graph)
+// shares one key implementation and consumers can join sections by key.
 func apiOutputKey(cwd, fileName string) string {
-  if rel, err := filepath.Rel(cwd, fileName); err == nil && !isOutsideRelativePath(rel) {
-    return filepath.ToSlash(rel)
-  }
-  return filepath.ToSlash(fileName)
-}
-
-// isOutsideRelativePath reports whether the result of filepath.Rel points
-// above the base directory (starts with ".."), meaning the file lives outside
-// the project root and cannot safely be expressed as a project-relative path.
-func isOutsideRelativePath(rel string) bool {
-  return rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator))
+  return driver.TransformOutputKey(cwd, fileName)
 }

package/cmd/ttsc/api_transform.go

@@ -20,6 +20,12 @@ type apiTransformResult struct {
   // Program facade, keyed the same way api-compile keys emitted files.
   Diagnostics []apiCompileDiagnostic `json:"diagnostics,omitempty"`
   TypeScript  map[string]string      `json:"typescript"`
+  // Graph is the host-owned reference graph of the loaded program (direct
+  // resolved reference edges, global-scope files, tsconfig extends chain),
+  // keyed like TypeScript. Consumers use it to register every file whose
+  // content can influence a transformed module, so bundler caches invalidate
+  // soundly without per-plugin reporting.
+  Graph *driver.TransformGraph `json:"graph,omitempty"`
 }
 
 // runAPITransform implements the `api-transform` sub-command. It loads the
@@ -63,8 +69,14 @@ func runAPITransform(args []string) int {
     return 2
   }
   typescript := map[string]string{}
+  var graph *driver.TransformGraph
   if prog != nil {
     defer prog.Close()
+    // Compute the reference graph before SourceFiles() runs linked plugin
+    // hooks: those mutate parsed ASTs in place, and the graph must describe
+    // the original source's resolved references — the transform's inputs —
+    // not the mutated output.
+    graph = driver.NewTransformGraph(prog, cwd)
     for _, file := range prog.SourceFiles() {
       typescript[apiOutputKey(cwd, file.FileName())] = file.Text()
     }
@@ -74,6 +86,7 @@ func runAPITransform(args []string) int {
   result := apiTransformResult{
     Diagnostics: make([]apiCompileDiagnostic, 0, len(diags)),
     TypeScript:  typescript,
+    Graph:       graph,
   }
   for _, diag := range diags {
     result.Diagnostics = append(result.Diagnostics, toAPICompileDiagnostic(diag))

package/cmd/ttscgraph/dump.go

@@ -59,6 +59,12 @@ func runDump(args []string) int {
 
   g := graph.Build(prog)
   ignored := graph.GitIgnoredFiles(cwd, g)
+  texts := graph.SourceTexts(prog)
+  origin, err := dumpOrigin(prog, cwd, texts)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttscgraph: %v\n", err)
+    return 1
+  }
   // Stream the document out instead of marshalling it into one byte slice and
   // then copying that slice into a string: on VS Code the dump is 323 MB, so
   // the string conversion alone was a second full copy of it, for nothing. The
@@ -69,7 +75,8 @@ func runDump(args []string) int {
     cwd,
     tsconfig,
     ignored,
-    graph.SourceTexts(prog),
+    texts,
+    origin,
     *prettyFlag,
   ); err != nil {
     fmt.Fprintf(stderr, "ttscgraph: %v\n", err)
@@ -77,3 +84,35 @@ func runDump(args []string) int {
   }
   return 0
 }
+
+// dumpOrigin assembles the one-shot command's snapshot evidence. A dump written
+// to a file outlives the process that made it and is read by tooling that never
+// saw the project, so it carries the same provenance a served snapshot does:
+// without it the file is a pile of facts with no way to tell which program, or
+// which day, they describe.
+func dumpOrigin(prog *driver.Program, cwd string, texts map[string]string) (graph.DumpOrigin, error) {
+  configs, err := parsedConfigs(prog)
+  if err != nil {
+    return graph.DumpOrigin{}, err
+  }
+  configHashes, err := hashFiles(configFiles(configs))
+  if err != nil {
+    return graph.DumpOrigin{}, err
+  }
+  _, diskDigests, err := hashProgramSources(prog)
+  if err != nil {
+    return graph.DumpOrigin{}, err
+  }
+  return graph.DumpOrigin{
+    Provenance: graph.NewProvenance(
+      cwd,
+      serveProducer(),
+      fullSnapshotCapabilities,
+      fileDigests(configHashes),
+      rootFileEntries(projectRootFilesFromConfigs(configs, false)),
+      texts,
+      diskDigests,
+    ),
+    Diagnostics: graph.NewDiagnostics(prog, cwd),
+  }, nil
+}