@ttsc/unplugin 0.12.3 → 0.13.0

package/lib/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}
+{"version":3,"file":"index.mjs","sources":["../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;;;AAQG;;;;"}

package/lib/next.d.ts

@@ -1,8 +1,37 @@
 import type { TtscUnpluginOptions } from "./core/options";
+/**
+ * Minimal structural type for a Next.js configuration object.
+ *
+ * Only the `webpack` field is used by this adapter; all other Next.js options
+ * are forwarded as-is through the spread operator.
+ */
 export type NextLikeConfig = Record<string, unknown> & {
+    /**
+     * Optional existing webpack customisation hook. When the caller has already
+     * defined one, `next()` will chain through to it after injecting the ttsc
+     * webpack plugin.
+     */
     webpack?: (config: WebpackLikeConfig, options: unknown) => WebpackLikeConfig;
 };
+/**
+ * Minimal structural type for a webpack configuration object as seen by the
+ * Next.js `webpack` hook callback.
+ */
 export type WebpackLikeConfig = Record<string, unknown> & {
+    /** The webpack plugin array; initialised to `[]` by this adapter if absent. */
     plugins?: unknown[];
 };
+/**
+ * Wrap a Next.js config object so that the ttsc webpack plugin is injected into
+ * every webpack build Next.js performs.
+ *
+ * The adapter uses `unshift` to ensure the ttsc plugin runs before any other
+ * plugins in the array (unplugin `enforce: "pre"` semantics). An existing
+ * `nextConfig.webpack` hook is preserved and called after the plugin is
+ * injected.
+ *
+ * @param nextConfig - The caller's existing Next.js config (spread into the
+ *   returned object unchanged, except for `webpack`).
+ * @param options - Ttsc plugin options forwarded to the webpack adapter.
+ */
 export default function next(nextConfig?: NextLikeConfig, options?: TtscUnpluginOptions): NextLikeConfig;

package/lib/next.js

@@ -4,11 +4,25 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var webpack = require('./webpack.js');
 
+/**
+ * Wrap a Next.js config object so that the ttsc webpack plugin is injected into
+ * every webpack build Next.js performs.
+ *
+ * The adapter uses `unshift` to ensure the ttsc plugin runs before any other
+ * plugins in the array (unplugin `enforce: "pre"` semantics). An existing
+ * `nextConfig.webpack` hook is preserved and called after the plugin is
+ * injected.
+ *
+ * @param nextConfig - The caller's existing Next.js config (spread into the
+ *   returned object unchanged, except for `webpack`).
+ * @param options - Ttsc plugin options forwarded to the webpack adapter.
+ */
 function next(nextConfig = {}, options) {
     return {
         ...nextConfig,
         webpack(config, webpackOptions) {
             config.plugins = Array.isArray(config.plugins) ? config.plugins : [];
+            // Prepend so ttsc runs before any user-added plugins.
             config.plugins.unshift(webpack.default(options));
             if (typeof nextConfig.webpack === "function") {
                 return nextConfig.webpack(config, webpackOptions);

package/lib/next.js.map

@@ -1 +1 @@
-{"version":3,"file":"next.js","sources":["../src/next.ts"],"sourcesContent":[null],"names":["webpack"],"mappings":";;;;;;AAWc,SAAU,IAAI,CAC1B,UAAA,GAA6B,EAAE,EAC/B,OAA6B,EAAA;IAE7B,OAAO;AACL,QAAA,GAAG,UAAU;QACb,OAAO,CAAC,MAAyB,EAAE,cAAuB,EAAA;YACxD,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,GAAG,EAAE;YACpE,MAAM,CAAC,OAAO,CAAC,OAAO,CAACA,eAAO,CAAC,OAAO,CAAC,CAAC;AACxC,YAAA,IAAI,OAAO,UAAU,CAAC,OAAO,KAAK,UAAU,EAAE;gBAC5C,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC;YACnD;AACA,YAAA,OAAO,MAAM;QACf,CAAC;KACF;AACH;;;;"}
+{"version":3,"file":"next.js","sources":["../src/next.ts"],"sourcesContent":[null],"names":["webpack"],"mappings":";;;;;;AA2BA;;;;;;;;;;;;AAYG;AACW,SAAU,IAAI,CAC1B,UAAA,GAA6B,EAAE,EAC/B,OAA6B,EAAA;IAE7B,OAAO;AACL,QAAA,GAAG,UAAU;QACb,OAAO,CAAC,MAAyB,EAAE,cAAuB,EAAA;YACxD,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,GAAG,EAAE;;YAEpE,MAAM,CAAC,OAAO,CAAC,OAAO,CAACA,eAAO,CAAC,OAAO,CAAC,CAAC;AACxC,YAAA,IAAI,OAAO,UAAU,CAAC,OAAO,KAAK,UAAU,EAAE;gBAC5C,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC;YACnD;AACA,YAAA,OAAO,MAAM;QACf,CAAC;KACF;AACH;;;;"}

package/lib/next.mjs

@@ -1,10 +1,24 @@
 import webpack from './webpack.mjs';
 
+/**
+ * Wrap a Next.js config object so that the ttsc webpack plugin is injected into
+ * every webpack build Next.js performs.
+ *
+ * The adapter uses `unshift` to ensure the ttsc plugin runs before any other
+ * plugins in the array (unplugin `enforce: "pre"` semantics). An existing
+ * `nextConfig.webpack` hook is preserved and called after the plugin is
+ * injected.
+ *
+ * @param nextConfig - The caller's existing Next.js config (spread into the
+ *   returned object unchanged, except for `webpack`).
+ * @param options - Ttsc plugin options forwarded to the webpack adapter.
+ */
 function next(nextConfig = {}, options) {
     return {
         ...nextConfig,
         webpack(config, webpackOptions) {
             config.plugins = Array.isArray(config.plugins) ? config.plugins : [];
+            // Prepend so ttsc runs before any user-added plugins.
             config.plugins.unshift(webpack(options));
             if (typeof nextConfig.webpack === "function") {
                 return nextConfig.webpack(config, webpackOptions);

package/lib/next.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"next.mjs","sources":["../src/next.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAWc,SAAU,IAAI,CAC1B,UAAA,GAA6B,EAAE,EAC/B,OAA6B,EAAA;IAE7B,OAAO;AACL,QAAA,GAAG,UAAU;QACb,OAAO,CAAC,MAAyB,EAAE,cAAuB,EAAA;YACxD,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,GAAG,EAAE;YACpE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACxC,YAAA,IAAI,OAAO,UAAU,CAAC,OAAO,KAAK,UAAU,EAAE;gBAC5C,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC;YACnD;AACA,YAAA,OAAO,MAAM;QACf,CAAC;KACF;AACH;;;;"}
+{"version":3,"file":"next.mjs","sources":["../src/next.ts"],"sourcesContent":[null],"names":[],"mappings":";;AA2BA;;;;;;;;;;;;AAYG;AACW,SAAU,IAAI,CAC1B,UAAA,GAA6B,EAAE,EAC/B,OAA6B,EAAA;IAE7B,OAAO;AACL,QAAA,GAAG,UAAU;QACb,OAAO,CAAC,MAAyB,EAAE,cAAuB,EAAA;YACxD,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,GAAG,EAAE;;YAEpE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACxC,YAAA,IAAI,OAAO,UAAU,CAAC,OAAO,KAAK,UAAU,EAAE;gBAC5C,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC;YACnD;AACA,YAAA,OAAO,MAAM;QACf,CAAC;KACF;AACH;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/unplugin",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "Bundler adapters for ttsc plugins.",
   "main": "lib/index.js",
   "module": "lib/index.mjs",
@@ -89,7 +89,7 @@
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
     "@types/node": "^25.3.0",
-    "@typescript/native-preview": "7.0.0-dev.20260518.1",
+    "@typescript/native-preview": "7.0.0-dev.20260522.1",
     "esbuild": "^0.25.12",
     "rimraf": "^6.1.2",
     "rollup": "^4.60.3",
@@ -99,7 +99,7 @@
     "tslib": "^2.8.1",
     "typescript": "^6.0.3",
     "vite": "^7.1.12",
-    "ttsc": "0.12.3"
+    "ttsc": "0.13.0"
   },
   "repository": {
     "type": "git",

package/src/api.ts

@@ -1 +1,8 @@
+/**
+ * Public API surface for `@ttsc/unplugin`.
+ *
+ * Re-exports everything from `core/index` so consumers can access the unified
+ * `unplugin` instance, the transform helpers, and the option types from the
+ * `@ttsc/unplugin/api` entry point without importing directly from `core/`.
+ */
 export * from "./core/index";

package/src/bun.ts

@@ -2,22 +2,51 @@ import fs from "node:fs/promises";
 import type { UnpluginContextMeta } from "unplugin";
 
 import { unplugin } from "./api";
+import { sourceFilePattern } from "./core/index";
 import type { TtscUnpluginOptions } from "./core/options";
 
+/**
+ * Minimal subset of the Bun plugin API consumed by this adapter.
+ *
+ * Bun does not yet ship TypeScript types for its bundler plugin interface, so
+ * we define the subset we need here. This keeps the adapter free of a Bun
+ * runtime dependency while remaining type-safe.
+ */
 export interface BunLikePlugin {
+  /** Plugin identifier shown in Bun bundler output. */
   name: string;
+  /** Called by Bun when the plugin is registered. */
   setup(build: BunLikeBuild): void | Promise<void>;
 }
 
+/**
+ * Minimal subset of the Bun `BuildConfig` plugin build object.
+ *
+ * Only the `onLoad` hook is used; other hooks are not needed for a
+ * source-to-source transform.
+ */
 export interface BunLikeBuild {
+  /**
+   * Register a loader callback for files matching `filter`.
+   *
+   * The callback receives the absolute file path and must return the
+   * transformed file contents.
+   */
   onLoad(
     options: { filter: RegExp },
     loader: (args: { path: string }) => Promise<{ contents: string }>,
   ): void;
 }
 
-const sourceFilePattern = /\.[cm]?tsx?$/;
-
+/**
+ * Create a ttsc plugin for Bun's bundler.
+ *
+ * Bun does not implement the unplugin protocol, so this adapter instantiates
+ * the raw unplugin transform and wires it to Bun's `onLoad` hook manually. The
+ * adapter reads each matching file from disk and forwards the content to the
+ * ttsc transform; if the transform returns no changes the original source is
+ * passed through unchanged.
+ */
 export default function bun(options?: TtscUnpluginOptions): BunLikePlugin {
   return {
     name: "ttsc-unplugin",
@@ -29,6 +58,7 @@ export default function bun(options?: TtscUnpluginOptions): BunLikePlugin {
           typeof raw.transform === "function"
             ? await raw.transform.call({} as never, source, args.path)
             : undefined;
+        // Unpack both shorthand string and object result shapes.
         if (typeof result === "string") {
           return { contents: result };
         }

package/src/core/index.ts

@@ -11,10 +11,30 @@ import {
 } from "./transform";
 
 const name = "ttsc-unplugin";
-const sourceFilePattern = /\.[cm]?tsx?$/;
+/**
+ * Matches any TypeScript or JavaScript source extension (.ts, .tsx, .mts, .cts,
+ * etc.). Shared with the Bun adapter (`bun.ts`) so the filter is defined once
+ * and both adapters stay in sync.
+ */
+export const sourceFilePattern = /\.[cm]?tsx?$/;
+/** Matches any path segment that is a `node_modules` directory (cross-platform). */
 const nodeModulesPattern = /(?:^|[/\\])node_modules(?:[/\\]|$)/;
+/**
+ * Matches virtual module ids — Rollup/Vite use a leading NUL byte (`\0`) as
+ * convention.
+ */
 const virtualModulePattern = /\0/;
 
+/**
+ * Unplugin factory that wires the ttsc transform pipeline into any supported
+ * bundler (Vite, Rollup, Rolldown, webpack, Rspack, esbuild, Farm).
+ *
+ * The factory resolves raw options once, creates a per-build transform cache,
+ * and captures Vite alias configuration via the `vite.configResolved` hook so
+ * that path aliases are forwarded to the generated tsconfig overlay. The cache
+ * is cleared on every `buildStart` to avoid stale results across watch-mode
+ * rebuilds.
+ */
 const unpluginFactory: UnpluginFactory<
   TtscUnpluginOptions | undefined,
   false
@@ -63,6 +83,13 @@ export { createTtscTransformCache, resolveOptions, transformTtsc, unplugin };
 
 export default unplugin;
 
+/**
+ * Returns `true` when the module id refers to a real TypeScript/JavaScript
+ * source file that should be processed by the ttsc transform.
+ *
+ * Excluded ids: virtual modules (NUL prefix), `.d.ts` declaration files, and
+ * anything inside `node_modules`.
+ */
 function isTransformTarget(id: string): boolean {
   return (
     sourceFilePattern.test(id) &&

package/src/core/options.ts

@@ -1,7 +1,9 @@
 import type { ITtscProjectPluginConfig } from "ttsc";
 
+/** Raw compiler-options overlay supplied by the caller as a plain JSON value. */
 export type TtscUnpluginCompilerOptionsJson = Record<string, unknown>;
 
+/** Options accepted by the `@ttsc/unplugin` bundler adapter. */
 export interface TtscUnpluginOptions {
   /**
    * Project config used by the bundler adapter.
@@ -29,9 +31,22 @@ export interface TtscUnpluginOptions {
   plugins?: readonly ITtscProjectPluginConfig[] | false;
 }
 
+/**
+ * Fully-resolved plugin options with all defaults applied.
+ *
+ * Produced by {@link resolveOptions}; consumed internally by the transform
+ * pipeline. Every field is present and normalised — callers should not
+ * construct this type directly.
+ */
 export interface ResolvedTtscUnpluginOptions {
+  /** Compiler-options overlay applied on top of the discovered tsconfig. */
   compilerOptions: TtscUnpluginCompilerOptionsJson;
+  /**
+   * Resolved plugin list; mirrors the semantics of
+   * {@link TtscUnpluginOptions.plugins}.
+   */
   plugins?: readonly ITtscProjectPluginConfig[] | false;
+  /** Resolved path to the project tsconfig, or `undefined` to auto-discover. */
   project?: string;
 }
 
@@ -41,6 +56,13 @@ const defaultOptions: ResolvedTtscUnpluginOptions = {
   project: undefined,
 };
 
+/**
+ * Normalise raw user-supplied options into {@link ResolvedTtscUnpluginOptions}.
+ *
+ * Merges provided values with defaults. The `plugins` field uses an explicit
+ * `"plugins" in options` presence check rather than a falsy guard so that
+ * `plugins: false` (disable all plugins) is preserved as-is.
+ */
 export function resolveOptions(
   options: TtscUnpluginOptions = {},
 ): ResolvedTtscUnpluginOptions {

package/src/core/transform.ts

@@ -11,31 +11,86 @@ import type { TransformResult } from "unplugin";
 
 import type { ResolvedTtscUnpluginOptions } from "./options";
 
+/**
+ * The normalised transform result type that this module produces.
+ *
+ * Excludes the shorthand `string`, `null`, and `undefined` variants of
+ * unplugin's `TransformResult` so callers always receive an object or
+ * `undefined`.
+ */
 export type TtscTransformResult = Exclude<
   TransformResult,
   string | null | undefined
 >;
 
+/**
+ * Normalised alias entry used when building the `paths` overlay for the
+ * generated tsconfig. Derived from either a Vite array alias or a webpack/
+ * Rspack object alias.
+ */
 export interface TtscTransformAlias {
+  /** The alias key (module specifier prefix). */
   find: string;
+  /** Absolute or cwd-relative path that the alias points to. */
   replacement: string;
 }
 
+/**
+ * A single entry in the per-build transform cache.
+ *
+ * Stores the full compiler result together with SHA-256 hashes of every input
+ * file. On subsequent transforms the cached entry is validated by comparing
+ * fresh hashes against {@link inputHashes}; a mismatch triggers a full
+ * re-transform of the project.
+ */
 export interface TtscCachedProjectTransform {
+  /**
+   * SHA-256 hash of each project-relative input path at the time of the
+   * transform.
+   */
   inputHashes: Record<string, string>;
+  /** Absolute path to the directory that owns the tsconfig. */
   projectRoot: string;
+  /** Raw compiler output returned by {@link TtscCompiler.transform}. */
   result: ITtscCompilerTransformation;
 }
 
+/**
+ * Keyed by a stable JSON string that encodes the tsconfig path, compiler
+ * options overlay, plugin list, and alias paths. The value is a `Promise` so
+ * concurrent transforms for the same project share a single in-flight
+ * compilation rather than spawning multiple `TtscCompiler` instances.
+ */
 export type TtscTransformCache = Map<
   string,
   Promise<TtscCachedProjectTransform>
 >;
 
+/** Create an empty transform cache for a single build session. */
 export function createTtscTransformCache(): TtscTransformCache {
   return new Map();
 }
 
+/**
+ * Apply the ttsc plugin transform to a single source file.
+ *
+ * The function is intentionally project-scoped: it compiles the entire tsconfig
+ * project in one shot and extracts the result for `id`. Subsequent calls for
+ * sibling files in the same project reuse the cached result as long as none of
+ * the project's input files have changed (verified by comparing SHA-256
+ * hashes).
+ *
+ * Returns `undefined` when no transform is needed (declaration files, virtual
+ * modules, disabled plugins, or source unchanged after transform).
+ *
+ * @param id - Bundler module id (may carry a query string or virtual prefix).
+ * @param source - Current file content supplied by the bundler.
+ * @param options - Resolved plugin options.
+ * @param aliases - Raw bundler alias configuration (Vite array or webpack
+ *   object).
+ * @param cache - Optional per-build cache; cleared by the caller on
+ *   `buildStart`.
+ */
 export async function transformTtsc(
   id: string,
   source: string,
@@ -100,21 +155,44 @@ export async function transformTtsc(
   return createTransformResult(source, code);
 }
 
+/**
+ * Strip a query string or hash fragment from a bundler module id.
+ *
+ * Vite appends query parameters (e.g. `?raw`, `?url`, `?inline`) to
+ * differentiate import variants of the same file. We must strip them before
+ * using the id as a file-system path.
+ */
 export function stripQuery(id: string): string {
   const query = id.search(/[?#]/);
   return query === -1 ? id : id.slice(0, query);
 }
 
+/**
+ * Returns `true` for TypeScript declaration files (`.d.ts`, `.d.mts`,
+ * `.d.cts`).
+ */
 export function isDeclarationFile(id: string): boolean {
   return id.endsWith(".d.ts") || id.endsWith(".d.mts") || id.endsWith(".d.cts");
 }
 
+/**
+ * Returns `true` when the caller has explicitly opted out of all plugins. An
+ * empty array is treated as disabled so we don't invoke the compiler for a
+ * no-op transform.
+ */
 function pluginsAreDisabled(
   plugins: ResolvedTtscUnpluginOptions["plugins"],
 ): boolean {
   return plugins === false || (Array.isArray(plugins) && plugins.length === 0);
 }
 
+/**
+ * Build the unplugin transform result, or `undefined` when the transform
+ * produced no changes.
+ *
+ * Returning `undefined` instead of `{ code: source }` lets the bundler skip the
+ * unnecessary module update and preserves the original source map.
+ */
 export function createTransformResult(
   source: string,
   code: string,
@@ -136,6 +214,16 @@ function matchesCachedSource(
   return sameHashes(cached.inputHashes, currentHashes);
 }
 
+/**
+ * Build the complete input-hash snapshot stored alongside a fresh compiler
+ * result.
+ *
+ * Combines filesystem hashes for every file in the project directory with
+ * hashes for each emitted TypeScript output key (the compiler may have read
+ * files not visible via the directory walk). The in-memory source for the file
+ * that triggered the build is overlaid last to capture unsaved editor content
+ * correctly.
+ */
 function collectInputHashes(props: {
   currentFile: string;
   currentSource: string;
@@ -154,6 +242,7 @@ function collectInputHashes(props: {
       }
     }
   }
+  // Overlay the in-memory source so unsaved edits invalidate the cache.
   hashes[toProjectKey(props.projectRoot, props.currentFile)] = hashText(
     props.currentSource,
   );
@@ -175,6 +264,14 @@ function collectProjectInputHashes(
   return hashes;
 }
 
+/**
+ * Enumerate every regular file under `root`, skipping well-known output and
+ * tooling directories (see {@link isIgnoredProjectDirectory}).
+ *
+ * Uses an iterative DFS instead of `fs.readdirSync` recursion to avoid
+ * unbounded call-stack depth on deep project trees. The result is sorted so
+ * that hash comparisons are deterministic across OS-level directory orderings.
+ */
 function listProjectInputFiles(root: string): string[] {
   const out: string[] = [];
   const stack = [root];
@@ -311,16 +408,30 @@ function createTransformTsconfig(props: {
   };
 }
 
+/**
+ * Resolve all relative paths inside `compilerOptions` against `tsconfigDir`.
+ *
+ * The generated tsconfig lives in a system temp directory, so any relative path
+ * (e.g. `"outDir": "../dist"`) that was meaningful relative to the original
+ * tsconfig must be converted to an absolute path before writing the generated
+ * file. Otherwise TypeScript-Go resolves it against the temp dir.
+ *
+ * Also inserts a synthetic `baseUrl` equal to `tsconfigDir` when `paths` is
+ * provided but `baseUrl` is absent — TypeScript requires `baseUrl` alongside
+ * `paths` when the latter contains non-absolute targets.
+ */
 function normalizeCompilerOptionsForGeneratedTsconfig(
   compilerOptions: Record<string, unknown>,
   tsconfigDir: string,
 ): Record<string, unknown> {
   const output = { ...compilerOptions };
+  // Scalar path fields: resolve each against the original tsconfig directory.
   for (const key of ["baseUrl", "declarationDir", "outDir", "rootDir"]) {
     if (typeof output[key] === "string") {
       output[key] = path.resolve(tsconfigDir, output[key]);
     }
   }
+  // Array path fields: resolve each element individually.
   for (const key of ["rootDirs", "typeRoots"]) {
     if (Array.isArray(output[key])) {
       output[key] = output[key].map((entry) =>
@@ -473,6 +584,14 @@ function createTransformCacheKey(props: {
   });
 }
 
+/**
+ * JSON-serialise `value` with object keys sorted alphabetically.
+ *
+ * Standard `JSON.stringify` does not guarantee key ordering, so two
+ * semantically identical option objects could produce different strings and
+ * cause unnecessary cache misses. Sorting keys makes the cache key stable
+ * regardless of the order properties were added to the options object.
+ */
 function stableStringify(value: unknown): string {
   if (Array.isArray(value)) {
     return `[${value.map(stableStringify).join(",")}]`;
@@ -508,6 +627,15 @@ function isAlias(value: unknown): value is TtscTransformAlias {
   );
 }
 
+/**
+ * Extract the transformed source for a single file from the compiler result.
+ *
+ * Throws on compiler exception or hard failure so the bundler surfaces the
+ * error to the user. On success, tries a fast exact-match lookup by
+ * project-relative key first, then falls back to a resolve-based scan for the
+ * rare case where the key in `result.typescript` uses an absolute or
+ * differently-cased path.
+ */
 function selectTransformedSource(props: {
   file: string;
   projectRoot: string;
@@ -520,11 +648,13 @@ function selectTransformedSource(props: {
     throw new Error(formatDiagnostics(props.result.diagnostics));
   }
 
+  // Fast path: the compiler key matches the normalised project-relative path.
   const key = toProjectKey(props.projectRoot, props.file);
   const direct = props.result.typescript[key];
   if (direct !== undefined) {
     return direct;
   }
+  // Slow path: resolve each candidate to an absolute path for comparison.
   for (const [candidate, source] of Object.entries(props.result.typescript)) {
     if (path.resolve(props.projectRoot, candidate) === props.file) {
       return source;
@@ -533,6 +663,13 @@ function selectTransformedSource(props: {
   throw new Error(`ttsc transform did not return output for ${props.file}`);
 }
 
+/**
+ * Forward non-fatal plugin diagnostics to stderr.
+ *
+ * A `success` result may still carry warnings or informational messages from
+ * plugins. These are surfaced via stderr rather than throwing so the build
+ * continues. Failures and exceptions are handled by the caller.
+ */
 function reportSuccessDiagnostics(result: ITtscCompilerTransformation): void {
   if (result.type !== "success" || result.diagnostics === undefined) {
     return;
@@ -543,6 +680,14 @@ function reportSuccessDiagnostics(result: ITtscCompilerTransformation): void {
   }
 }
 
+/**
+ * Format a compiler diagnostic list into a human-readable string.
+ *
+ * Produces `"file: line:col: message"` entries joined by newlines, matching the
+ * output style of `tsc`. When the list is empty (e.g. a failure with no
+ * attached diagnostics) returns a generic fallback message so the thrown
+ * `Error` is never empty.
+ */
 function formatDiagnostics(diagnostics: ITtscCompilerDiagnostic[]): string {
   if (diagnostics.length === 0) {
     return "ttsc transform failed";
@@ -577,6 +722,16 @@ function formatUnknownError(error: unknown): string {
   return String(error);
 }
 
+/**
+ * Locate the tsconfig that should govern the transform for `file`.
+ *
+ * If `tsconfig` is supplied it is returned as-is (absolute) or resolved from
+ * `process.cwd()` (relative). Otherwise the function walks ancestor directories
+ * starting at `file`'s directory, returning the first `tsconfig.json` found.
+ * Falls back to `<cwd>/tsconfig.json` when no ancestor contains one — the
+ * compiler will error if that file does not exist, which is the correct
+ * behavior for a mis-configured project.
+ */
 function resolveTsconfig(file: string, tsconfig?: string): string {
   if (tsconfig !== undefined) {
     return path.isAbsolute(tsconfig)
@@ -591,6 +746,7 @@ function resolveTsconfig(file: string, tsconfig?: string): string {
       return candidate;
     }
     const parent = path.dirname(current);
+    // Reached filesystem root — stop walking.
     if (parent === current) {
       break;
     }

package/src/index.ts

@@ -1,3 +1,12 @@
+/**
+ * @ttsc/unplugin — bundler-agnostic ttsc plugin adapter.
+ *
+ * Re-exports the unified `unplugin` instance that carries named bundler
+ * adapters (`.vite`, `.rollup`, `.rolldown`, `.webpack`, `.rspack`, `.esbuild`,
+ * `.farm`) as well as the raw factory for custom integrations. Per-bundler
+ * entry points (`@ttsc/unplugin/vite`, `/webpack`, …) each re-export the
+ * matching adapter directly to keep bundler-specific builds lean.
+ */
 import unplugin from "./core/index";
 
 export type { TtscUnpluginOptions } from "./core/options";

package/src/next.ts

@@ -1,14 +1,43 @@
 import type { TtscUnpluginOptions } from "./core/options";
 import webpack from "./webpack";
 
+/**
+ * Minimal structural type for a Next.js configuration object.
+ *
+ * Only the `webpack` field is used by this adapter; all other Next.js options
+ * are forwarded as-is through the spread operator.
+ */
 export type NextLikeConfig = Record<string, unknown> & {
+  /**
+   * Optional existing webpack customisation hook. When the caller has already
+   * defined one, `next()` will chain through to it after injecting the ttsc
+   * webpack plugin.
+   */
   webpack?: (config: WebpackLikeConfig, options: unknown) => WebpackLikeConfig;
 };
 
+/**
+ * Minimal structural type for a webpack configuration object as seen by the
+ * Next.js `webpack` hook callback.
+ */
 export type WebpackLikeConfig = Record<string, unknown> & {
+  /** The webpack plugin array; initialised to `[]` by this adapter if absent. */
   plugins?: unknown[];
 };
 
+/**
+ * Wrap a Next.js config object so that the ttsc webpack plugin is injected into
+ * every webpack build Next.js performs.
+ *
+ * The adapter uses `unshift` to ensure the ttsc plugin runs before any other
+ * plugins in the array (unplugin `enforce: "pre"` semantics). An existing
+ * `nextConfig.webpack` hook is preserved and called after the plugin is
+ * injected.
+ *
+ * @param nextConfig - The caller's existing Next.js config (spread into the
+ *   returned object unchanged, except for `webpack`).
+ * @param options - Ttsc plugin options forwarded to the webpack adapter.
+ */
 export default function next(
   nextConfig: NextLikeConfig = {},
   options?: TtscUnpluginOptions,
@@ -17,6 +46,7 @@ export default function next(
     ...nextConfig,
     webpack(config: WebpackLikeConfig, webpackOptions: unknown) {
       config.plugins = Array.isArray(config.plugins) ? config.plugins : [];
+      // Prepend so ttsc runs before any user-added plugins.
       config.plugins.unshift(webpack(options));
       if (typeof nextConfig.webpack === "function") {
         return nextConfig.webpack(config, webpackOptions);