fix: erase type-only imports in plain .ts files

.changeset/erase-type-imports.md

@@ -0,0 +1,7 @@
+---
+"@maastrich/hashup": patch
+---
+
+Erase type-only imports in `.ts` / `.mts` / `.cts` files before import extraction. Previously only `.tsx` / `.jsx` went through esbuild, so `import type { X } from "pkg/types"` in a plain `.ts` file was walked like a value import — and, when the specifier had no runtime module (a types-only package export), counted as unresolved. All TypeScript now goes through esbuild with `verbatimModuleSyntax` semantics: `import type` / `export type` / `import { type X }` vanish, every value import (unused or side-effect) is kept.
+
+Hashes of entries whose `.ts` graph contained type-only edges to real files change, since those files no longer contribute.

docs/guide/how-it-works.md

@@ -5,7 +5,8 @@
 1. **Resolve the entry file** against `baseDir` (defaults to `process.cwd()`).
 2. **Walk the import graph** starting at the entry. Each file is parsed with
    [`es-module-lexer`](https://github.com/guybedford/es-module-lexer) to extract
-   its static imports, plus a small dedicated parser for
+   its static imports (TypeScript and JSX are lowered with esbuild first,
+   which erases type-only imports), plus a small dedicated parser for
    `import.meta.glob(...)` calls. `?query` / `#fragment` suffixes are
    stripped, bare specifiers are mapped through the nearest
    `tsconfig.json` (`paths` / `baseUrl`, following `extends`), and the
@@ -37,6 +38,10 @@ It does **not** depend on:
 
 ## What Is Not Included
 
+- Type-only imports (`import type`, `export type`, `import { type X }`) in
+  any TypeScript file — esbuild erases them before extraction, so they are
+  neither walked nor reported as unresolved. Value imports are always kept,
+  even when unused (`verbatimModuleSyntax` semantics).
 - Dynamic imports and `import.meta.glob` calls whose argument is not a
   string literal (these are reported in `result.unresolved`).
 - Files outside the reachable import graph, unless passed via `extras`.

docs/guide/usage.md

@@ -197,8 +197,11 @@ The resolver handles the common web/Node module formats:
 - JavaScript: `.js`, `.jsx`, `.mjs`, `.cjs`
 - JSON: `.json`
 
-Type-only imports (`import type { ... }`) are not included in the hash because
-they are erased at compile time and do not affect runtime behavior.
+Type-only imports (`import type { ... }`, `export type { ... }`,
+`import { type X }`) are not included in the hash — every TypeScript file is
+lowered with esbuild before extraction, which erases them. They are not
+reported as unresolved either, even when the specifier has no runtime
+module (a types-only package export).
 
 Files of other types reached through an import (`.json`, `.yml?raw`,
 `.svg?url`, `import.meta.glob` matches) are hashed by content but not

src/lib/preprocess.ts

@@ -1,24 +1,36 @@
-import { transform } from "esbuild";
+import { transform, type Loader } from "esbuild";
 
+const LOADERS: Record<string, Loader> = {
+  ".ts": "ts",
+  ".mts": "ts",
+  ".cts": "ts",
+  ".tsx": "tsx",
+  ".jsx": "jsx",
+};
+
+/**
+ * Lower TypeScript / JSX to plain ESM before import extraction.
+ *
+ * es-module-lexer does not understand TypeScript, so `import type` and
+ * `export type` would otherwise surface as real imports — edges that do
+ * not exist at runtime (and often resolve to nothing, e.g. a types-only
+ * package export). esbuild erases them. `verbatimModuleSyntax` keeps
+ * every *value* import, even unused ones, so a side-effect import is
+ * never dropped from the graph.
+ *
+ * On any transform error the raw source is returned and the lexer gets
+ * its chance; a parse failure there is reported by the caller.
+ */
 export async function preprocess(content: string, extension: string): Promise<string> {
+  const loader = LOADERS[extension];
+  if (loader === undefined) return content;
   try {
-    switch (extension) {
-      case ".jsx":
-      case ".tsx": {
-        const result = await transform(content, {
-          define: {},
-          format: "esm",
-          loader: extension === ".jsx" ? "jsx" : "tsx",
-        });
-        if (!result) {
-          return content;
-        }
-        return result.code;
-      }
-      default: {
-        return content;
-      }
-    }
+    const result = await transform(content, {
+      loader,
+      format: "esm",
+      tsconfigRaw: { compilerOptions: { verbatimModuleSyntax: true } },
+    });
+    return result.code;
   } catch {
     return content;
   }

tests/examples.test.ts

@@ -14,7 +14,8 @@ describe("hashup with example files", () => {
     // Should include dependencies
     expect(result.files.some((f) => f.includes("math"))).toBe(true);
     expect(result.files.some((f) => f.includes("helpers"))).toBe(true);
-    expect(result.files.some((f) => f.includes("user"))).toBe(true);
+    // `import type { User }` is erased before extraction — compile-time only
+    expect(result.files.some((f) => f.includes("user"))).toBe(false);
   });
 
   test("should hash JavaScript files", async () => {
@@ -105,7 +106,7 @@ describe("hashup with example files", () => {
     const result = await hashup("./examples/src/index.ts");
 
     expect(result.hash).toMatchInlineSnapshot(
-      `"ed1c4758b6b759306f2b44feee0bbc2d06291ae490d97367043ab188ce670770"`,
+      `"7159cc21c362448218a62500c883524aa9708e2d8bbf2c900525c62ee8a5309f"`,
     );
   });
 });

tests/fixtures/type-only-imports/entry.ts

@@ -0,0 +1,8 @@
+import type { Recipe } from "@types-only/pkg/types";
+import type { Local } from "./local-types";
+import { type Inline, value } from "./value";
+import "./side-effect";
+import unused from "./unused";
+export type { Reexported } from "./reexported-types";
+
+export const all: [Recipe | Local | Inline | undefined, string] = [undefined, value];

tests/fixtures/type-only-imports/local-types.ts

@@ -0,0 +1 @@
+export type Local = string;

tests/fixtures/type-only-imports/reexported-types.ts

@@ -0,0 +1 @@
+export type Reexported = boolean;

tests/fixtures/type-only-imports/side-effect.ts

@@ -0,0 +1 @@
+globalThis.__sideEffect = true;

tests/fixtures/type-only-imports/unused.ts

@@ -0,0 +1 @@
+export default "unused";

tests/fixtures/type-only-imports/value.ts

@@ -0,0 +1,2 @@
+export type Inline = number;
+export const value = "v";

tests/type-only-imports.test.ts

@@ -0,0 +1,43 @@
+import { resolve } from "node:path";
+import { describe, expect, test } from "vite-plus/test";
+import { extractImports, hashup } from "../src/index.js";
+
+const ENTRY = resolve("tests/fixtures/type-only-imports/entry.ts");
+const has = (files: string[], suffix: string) => files.some((f) => f.endsWith(suffix));
+
+describe("type-only imports in .ts files", () => {
+  test("import type / export type are erased before import extraction", async () => {
+    const imports = await extractImports(
+      "x.ts",
+      [
+        'import type { A } from "./a";',
+        'import { type B, b } from "./b";',
+        'export type { C } from "./c";',
+        'import "./d";',
+        'import e from "./e";',
+        "void b;",
+      ].join("\n"),
+    );
+    expect(imports).toEqual(["./b", "./d", "./e"]);
+  });
+
+  test("same for .mts and .cts", async () => {
+    const src = 'import type { A } from "./a";\nimport { b } from "./b";\nvoid b;';
+    expect(await extractImports("x.mts", src)).toEqual(["./b"]);
+    expect(await extractImports("x.cts", src)).toEqual(["./b"]);
+  });
+
+  test("unresolvable type-only specifier is neither walked nor reported", async () => {
+    const result = await hashup(ENTRY);
+    expect(result.unresolved).toEqual([]);
+    expect(has(result.files, "local-types.ts")).toBe(false);
+    expect(has(result.files, "reexported-types.ts")).toBe(false);
+  });
+
+  test("value imports survive, including unused and side-effect ones", async () => {
+    const result = await hashup(ENTRY);
+    expect(has(result.files, "value.ts")).toBe(true);
+    expect(has(result.files, "side-effect.ts")).toBe(true);
+    expect(has(result.files, "unused.ts")).toBe(true);
+  });
+});

tsconfig.json

@@ -23,6 +23,7 @@
     "tests/fixtures/import-meta-glob",
     "tests/fixtures/query-imports",
     "tests/fixtures/unresolved-report",
-    "tests/fixtures/tsconfig-paths"
+    "tests/fixtures/tsconfig-paths",
+    "tests/fixtures/type-only-imports"
   ]
 }

vite.config.ts

@@ -38,6 +38,7 @@ export default defineConfig({
       "tests/fixtures/query-imports",
       "tests/fixtures/unresolved-report",
       "tests/fixtures/tsconfig-paths",
+      "tests/fixtures/type-only-imports",
     ],
     env: { node: true, es2024: true },
     globals: { NodeJS: "readonly" },