@openload28/unplugin-tt 0.1.0-next.1.0.0.20260828.263

package/README.md

@@ -0,0 +1,86 @@
+# @openload28/unplugin-tt
+
+`.tt`과 `.ttx` 모듈을 번들러에서 그대로 import합니다. 중간 `.ts`/`.tsx` 트리를 만들지 않고,
+번들러가 소스를 직접 읽습니다.
+
+[unplugin](https://github.com/unjs/unplugin) 기반이라 구현은 하나이고 번들러별
+서브패스로 갈라져 나갑니다.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import tt from "@openload28/unplugin-tt/vite";
+
+export default defineConfig({ plugins: [tt()] });
+```
+
+```ts
+// src/main.ts — 평범한 TypeScript
+import { Notice, render } from "./notice.tt";
+```
+
+컴파일러는 [`@openload28/tt-lang`](https://www.npmjs.com/package/@openload28/tt-lang)을 함께
+설치하면 자동으로 찾습니다 (`npm install --save-dev @openload28/tt-lang@next @openload28/unplugin-tt@next`). @openload28/tt-lang이
+없으면 PATH의 `ttc`(`cargo install --path .`)로 폴백합니다.
+
+## 서브패스
+
+| import | 상태 |
+|--------|------|
+| `@openload28/unplugin-tt/vite` | 예제(`tt-interop`)로 검증 |
+| `@openload28/unplugin-tt/esbuild` | 번들·실행 검증 |
+| `@openload28/unplugin-tt/rollup`, `/rolldown`, `/webpack`, `/rspack`, `/farm` | unplugin이 제공하는 어댑터 — 미검증 |
+
+`@openload28/unplugin-tt`를 그대로 import하면 `unplugin` 객체와 `vitePlugin`·
+`esbuildPlugin` 같은 이름들이 나옵니다.
+
+## 동작
+
+| 단계 | 하는 일 |
+|------|---------|
+| `resolveId` | `.tt`/`.ttx` 지정자를 파일 경로로 풀고 각각 `.ts`/`.tsx`를 덧붙인 가상 id를 돌려줍니다. `@tt/std`, `@tt/std/option`, `@tt/std/result`는 각각 가상 모듈 id로 바꿉니다 |
+| `load` | `ttc -p --rewrite-imports off`의 출력을 돌려줍니다. 표준 라이브러리와 파이프 런타임은 모듈별 `ttc --emit-std types|option|result|runtime` 출력을 사용합니다 |
+
+id에 `.ts` 또는 `.tsx`를 붙이는 이유는 **호스트의 TypeScript 처리에 그대로 태우기**
+위해서입니다. 덕분에 플러그인이 변환을 직접 하지 않습니다. 다만 esbuild의
+`load`는 JavaScript만 반환할 수 있어서, 그 경로에는 소스 종류에 맞는 `ts`/`tsx`
+loader를 명시합니다.
+
+`--rewrite-imports off`인 것도 의도입니다. 지정자 재작성은 미리 컴파일하는
+파이프라인을 위한 기능이고, 여기서는 `.tt`이 그대로 남아야 이 플러그인이
+다음 모듈도 잡습니다.
+
+컴파일 에러는 ttc의 진단이 그대로 빌드 에러가 됩니다.
+
+```
+[@openload28/unplugin-tt] src/notice.tt:22:16: match on variant Notice is not exhaustive:
+              missing "Warn" (add the missing arms or a final `_` arm)
+```
+
+## 옵션
+
+| 옵션 | 기본값 | 설명 |
+|------|--------|------|
+| `compiler` | 설치된 `@openload28/tt-lang`의 바이너리, 없으면 `"ttc"` | ttc 실행 파일 경로 |
+| `verify` | `true` | `false`면 `--no-verify`를 넘겨 방출물 자가 검사를 생략합니다 |
+
+타입 선언(`index.d.ts`와 서브패스별 `.d.ts`)을 함께 싣습니다 — 소비자가
+`vite.config.ts`를 타입 검사에 넣어도 `tt()`의 옵션이 그대로 검사됩니다.
+
+## 타입은 별도입니다
+
+번들러 플러그인은 **런타임만** 해결합니다. `.ts` 파일이 `.tt`을 import할 때
+타입 검사와 정의 이동이 동작하려면 사이드카가 필요하고, 그건 ttc가 만듭니다.
+
+```sh
+ttc --types src/        # .tt-types/<이름>.tt.d.ts + .map
+```
+
+CLI에서 `ttc help workflow`를 실행하거나 [VSCode 확장](../../editors/vscode/README.md)을
+참조하세요. 확장은 저장할 때마다 사이드카를 갱신합니다.
+
+## 알려진 제약
+
+- `enforce: "pre"`는 Rollup·esbuild에서 무시됩니다 (unplugin 문서의 지원 훅
+  표). 그 두 곳에서는 플러그인 순서를 직접 앞에 두세요.
+- `resolveId`는 Rspack·Rsbuild에서 최신 버전을 요구합니다.

package/esbuild.d.ts

@@ -0,0 +1,5 @@
+import type { UnpluginInstance } from "unplugin";
+import type { Options } from "./index.js";
+
+declare const plugin: UnpluginInstance<Options | undefined>["esbuild"];
+export default plugin;

package/esbuild.js

@@ -0,0 +1,3 @@
+import unplugin from "./index.js";
+
+export default unplugin.esbuild;

package/farm.d.ts

@@ -0,0 +1,5 @@
+import type { UnpluginInstance } from "unplugin";
+import type { Options } from "./index.js";
+
+declare const plugin: UnpluginInstance<Options | undefined>["farm"];
+export default plugin;

package/farm.js

@@ -0,0 +1,3 @@
+import unplugin from "./index.js";
+
+export default unplugin.farm;

package/index.d.ts

@@ -0,0 +1,21 @@
+import type { UnpluginFactory, UnpluginInstance } from "unplugin";
+
+/** Options accepted by every `@openload28/unplugin-tt` entry. */
+export interface Options {
+  /** Path to the ttc binary (default: the installed `@openload28/tt-lang`, else `"ttc"`). */
+  compiler?: string;
+  /** Run ttc's output self-check (default: true). */
+  verify?: boolean;
+}
+
+export declare const unpluginFactory: UnpluginFactory<Options | undefined>;
+export declare const unplugin: UnpluginInstance<Options | undefined>;
+export default unplugin;
+
+export declare const vitePlugin: UnpluginInstance<Options | undefined>["vite"];
+export declare const rollupPlugin: UnpluginInstance<Options | undefined>["rollup"];
+export declare const rolldownPlugin: UnpluginInstance<Options | undefined>["rolldown"];
+export declare const webpackPlugin: UnpluginInstance<Options | undefined>["webpack"];
+export declare const rspackPlugin: UnpluginInstance<Options | undefined>["rspack"];
+export declare const esbuildPlugin: UnpluginInstance<Options | undefined>["esbuild"];
+export declare const farmPlugin: UnpluginInstance<Options | undefined>["farm"];

package/index.js

@@ -0,0 +1,200 @@
+/* --------------------------------------------------------------------------
+ * @openload28/unplugin-tt — `.tt` modules for every bundler unplugin supports.
+ *
+ * The plugin resolves `.tt` specifiers itself and compiles each file with
+ * `ttc` on the way in, so a project needs no intermediate `.ts` tree: the
+ * bundler reads the sources directly.
+ *
+ * Two deliberate details:
+ *
+ * - `ttc` runs with `--rewrite-imports off`. Rewriting exists for the
+ *   ahead-of-time pipeline (where a `.tt` neighbour has already become a
+ *   `.ts` file); here the specifier must stay `.tt` so this plugin resolves
+ *   it too.
+ * - Module ids get a `.ts` suffix. ttc emits TypeScript, and the host's own
+ *   TypeScript pass keys off the extension — this keeps the plugin out of
+ *   that job entirely. esbuild is told the loader explicitly instead, since
+ *   its `load` hook may only return JavaScript.
+ *
+ * Editor support is separate: `ttc --types` writes the declarations that let
+ * a `.ts` file import `.tt` without the type checker complaining.
+ * ----------------------------------------------------------------------- */
+import { execFile } from "node:child_process";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { promisify } from "node:util";
+
+import { createUnplugin } from "unplugin";
+
+const run = promisify(execFile);
+
+/**
+ * Default compiler: the prebuilt binary from an installed `@openload28/tt-lang` npm
+ * package when present (spawned directly — no per-call node launcher),
+ * otherwise `ttc` from PATH as before.
+ */
+function defaultCompiler() {
+  try {
+    const require = createRequire(import.meta.url);
+    return require("@openload28/tt-lang").binaryPath();
+  } catch {
+    return "ttc";
+  }
+}
+
+/** Virtual suffix for ordinary `.tt` modules. */
+const TS_SUFFIX = ".ts";
+/** Virtual suffix for JSX-bearing `.ttx` modules. */
+const TSX_SUFFIX = ".tsx";
+
+const sourceSuffix = (file) => (file.endsWith(".ttx") ? TSX_SUFFIX : TS_SUFFIX);
+
+const sourceFileOfId = (id) => {
+  if (id.endsWith(`.ttx${TSX_SUFFIX}`)) return id.slice(0, -TSX_SUFFIX.length);
+  if (id.endsWith(`.tt${TS_SUFFIX}`)) return id.slice(0, -TS_SUFFIX.length);
+  return null;
+};
+
+/** The bare specifier tt sources use for the standard library. */
+const STD_MODULES = new Map([
+  ["@tt/std", "types"],
+  ["@tt/std/option", "option"],
+  ["@tt/std/result", "result"],
+  ["@tt/runtime", "runtime"],
+]);
+
+/** Virtual module id for the standard library, per working directory. */
+const stdId = (module) =>
+  path.resolve(process.cwd(), "__tt_std__", `${module}${TS_SUFFIX}`);
+
+const stdModuleOfId = (id) => {
+  for (const module of STD_MODULES.values()) {
+    if (id === stdId(module)) return module;
+  }
+  return null;
+};
+
+const INLINE_MAP =
+  /\n\/\/# sourceMappingURL=data:application\/json;charset=utf-8;base64,([A-Za-z0-9+/=]+)\n?$/;
+
+/**
+ * Splits ttc's inline source map back out of the printed output.
+ *
+ * The map travels inline because stdout carries one stream; a bundler wants
+ * it as a separate object so it can compose it with everything downstream.
+ * Output without a map is returned unchanged.
+ *
+ * @param {string} code
+ * @returns {{ code: string, map: object | null }}
+ */
+function detachInlineSourceMap(code) {
+  const found = INLINE_MAP.exec(code);
+  if (found === null) return { code, map: null };
+  try {
+    const map = JSON.parse(Buffer.from(found[1], "base64").toString("utf8"));
+    return { code: code.slice(0, found.index + 1), map };
+  } catch {
+    // An unreadable map is not a reason to fail the build; the code is
+    // still exactly what ttc produced.
+    return { code, map: null };
+  }
+}
+
+/**
+ * @typedef {object} Options
+ * @property {string} [compiler] Path to the ttc binary (default: the
+ *   installed `@openload28/tt-lang` package's binary, falling back to `"ttc"` on PATH).
+ * @property {boolean} [verify] Run ttc's output self-check (default: true).
+ * @property {boolean} [sourcemap] Ask ttc for a source map and hand it to the
+ *   host, so a stack trace and a debugger point at the `.tt` (default: true).
+ */
+
+/** @type {import("unplugin").UnpluginFactory<Options | undefined>} */
+export const unpluginFactory = (options = {}) => {
+  const compiler = options.compiler ?? defaultCompiler();
+  const verify = options.verify ?? true;
+  const sourcemap = options.sourcemap ?? true;
+
+  return {
+    name: "@openload28/unplugin-tt",
+    // Ahead of the host's own resolution: `.tt` is not an extension it
+    // knows. Rollup and esbuild ignore `enforce`, where plugin order is the
+    // author's responsibility instead.
+    enforce: "pre",
+
+    resolveId(source, importer) {
+      // The standard library has no file: ttc prints it on demand, so it
+      // becomes a virtual module. Nothing lands in the project tree.
+      const stdModule = STD_MODULES.get(source);
+      if (stdModule !== undefined) return stdId(stdModule);
+      if (importer !== undefined && importer !== null) {
+        const importerModule = stdModuleOfId(importer);
+        if (importerModule !== null) {
+          if (source === "./option.js") return stdId("option");
+          if (source === "./result.js") return stdId("result");
+        }
+      }
+      if (!source.endsWith(".tt") && !source.endsWith(".ttx")) return null;
+
+      const file = path.isAbsolute(source)
+        ? source
+        : importer === undefined || importer === null
+          ? null
+          : path.resolve(path.dirname(importer), source);
+      return file === null ? null : `${file}${sourceSuffix(file)}`;
+    },
+
+    async load(id) {
+      const stdModule = stdModuleOfId(id);
+      if (stdModule !== null) {
+        const { stdout } = await run(compiler, ["--emit-std", stdModule, "--no-banner"], {
+          maxBuffer: 16 * 1024 * 1024,
+        });
+        return { code: stdout, map: null };
+      }
+      const file = sourceFileOfId(id);
+      if (file === null) return null;
+
+      const args = ["-p", "--rewrite-imports", "off"];
+      if (!verify) args.push("--no-verify");
+      // ttc prints the map into the output as a data: URL — the one form
+      // that survives a pipe. It is split back out here so the host gets a
+      // real map object and composes it with its own transforms.
+      if (sourcemap) args.push("--source-map", "inline");
+      args.push(file);
+
+      try {
+        const { stdout } = await run(compiler, args, { maxBuffer: 16 * 1024 * 1024 });
+        this.addWatchFile(file);
+        return detachInlineSourceMap(stdout);
+      } catch (error) {
+        // ttc reports `file:line:col: message` on stderr; surface that as
+        // the build error so the host shows the compiler's diagnostic.
+        const detail = String(error.stderr ?? error.message).trim();
+        this.error(detail.replace(/^ttc:\s*/, ""));
+        return null;
+      }
+    },
+
+    esbuild: {
+      // esbuild resolves and loads through its own filters, and its `load`
+      // may only return JavaScript — so narrow the filters to our ids and
+      // name the loader for the TypeScript ttc emits.
+      onResolveFilter: /(\.ttx?|^@tt\/(?:std(?:\/(?:option|result))?|runtime)$|\.\/(?:option|result)\.js$)/,
+      onLoadFilter: /(\.tt\.ts|\.ttx\.tsx|__tt_std__\/(?:types|option|result|runtime)\.ts)$/,
+      loader: (_code, id) => (id.endsWith(TSX_SUFFIX) ? "tsx" : "ts"),
+    },
+  };
+};
+
+export const unplugin = /* #__PURE__ */ createUnplugin(unpluginFactory);
+
+export default unplugin;
+
+export const vitePlugin = unplugin.vite;
+export const rollupPlugin = unplugin.rollup;
+export const rolldownPlugin = unplugin.rolldown;
+export const webpackPlugin = unplugin.webpack;
+export const rspackPlugin = unplugin.rspack;
+export const esbuildPlugin = unplugin.esbuild;
+export const farmPlugin = unplugin.farm;

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@openload28/unplugin-tt",
+  "version": "0.1.0-next.1.0.0.20260828.263",
+  "description": "Compile .tt and .ttx modules with ttc in Vite, Rollup, webpack, Rspack, esbuild and Farm",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./vite": {
+      "types": "./vite.d.ts",
+      "default": "./vite.js"
+    },
+    "./rollup": {
+      "types": "./rollup.d.ts",
+      "default": "./rollup.js"
+    },
+    "./rolldown": {
+      "types": "./rolldown.d.ts",
+      "default": "./rolldown.js"
+    },
+    "./webpack": {
+      "types": "./webpack.d.ts",
+      "default": "./webpack.js"
+    },
+    "./rspack": {
+      "types": "./rspack.d.ts",
+      "default": "./rspack.js"
+    },
+    "./esbuild": {
+      "types": "./esbuild.d.ts",
+      "default": "./esbuild.js"
+    },
+    "./farm": {
+      "types": "./farm.d.ts",
+      "default": "./farm.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "vite.js",
+    "vite.d.ts",
+    "rollup.js",
+    "rollup.d.ts",
+    "rolldown.js",
+    "rolldown.d.ts",
+    "webpack.js",
+    "webpack.d.ts",
+    "rspack.js",
+    "rspack.d.ts",
+    "esbuild.js",
+    "esbuild.d.ts",
+    "farm.js",
+    "farm.d.ts",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/load28/tt",
+    "directory": "integrations/unplugin"
+  },
+  "keywords": [
+    "unplugin",
+    "vite-plugin",
+    "rollup-plugin",
+    "webpack-plugin",
+    "esbuild-plugin",
+    "tt",
+    "typescript"
+  ],
+  "dependencies": {
+    "unplugin": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "types": "./index.d.ts"
+}

package/rolldown.d.ts

@@ -0,0 +1,5 @@
+import type { UnpluginInstance } from "unplugin";
+import type { Options } from "./index.js";
+
+declare const plugin: UnpluginInstance<Options | undefined>["rolldown"];
+export default plugin;

package/rolldown.js

@@ -0,0 +1,3 @@
+import unplugin from "./index.js";
+
+export default unplugin.rolldown;

package/rollup.d.ts

@@ -0,0 +1,5 @@
+import type { UnpluginInstance } from "unplugin";
+import type { Options } from "./index.js";
+
+declare const plugin: UnpluginInstance<Options | undefined>["rollup"];
+export default plugin;

package/rollup.js

@@ -0,0 +1,3 @@
+import unplugin from "./index.js";
+
+export default unplugin.rollup;

package/rspack.d.ts

@@ -0,0 +1,5 @@
+import type { UnpluginInstance } from "unplugin";
+import type { Options } from "./index.js";
+
+declare const plugin: UnpluginInstance<Options | undefined>["rspack"];
+export default plugin;

package/rspack.js

@@ -0,0 +1,3 @@
+import unplugin from "./index.js";
+
+export default unplugin.rspack;

package/vite.d.ts

@@ -0,0 +1,5 @@
+import type { UnpluginInstance } from "unplugin";
+import type { Options } from "./index.js";
+
+declare const plugin: UnpluginInstance<Options | undefined>["vite"];
+export default plugin;

package/vite.js

@@ -0,0 +1,3 @@
+import unplugin from "./index.js";
+
+export default unplugin.vite;

package/webpack.d.ts

@@ -0,0 +1,5 @@
+import type { UnpluginInstance } from "unplugin";
+import type { Options } from "./index.js";
+
+declare const plugin: UnpluginInstance<Options | undefined>["webpack"];
+export default plugin;

package/webpack.js

@@ -0,0 +1,3 @@
+import unplugin from "./index.js";
+
+export default unplugin.webpack;