feat: import grouping

[todor-a]

Closes #493.

---

Transparency note: This PR was prepared with AI assistance (Claude).

---

Adds ESLint-import/order-style import grouping to dprint-plugin-typescript: classify import declarations, reorder across the import block to match a user-declared group order, and insert exactly one blank line between groups.

Configuration

Four new keys under module.*:

{
  "module.importGroups": [
    { "match": "builtin" },
    { "match": "external" },
    { "match": "parent" },
    { "match": ["sibling", "index"] }
  ],
  "module.typeImports": "separate",       // or "interleave"
  "module.builtinsRuntime": "node"        // or "deno" | "bun" | "none"
}

Empty module.importGroups (default) disables the feature; output is byte-identical to the previous release.

match forms

• String: one of builtin | external | parent | sibling | index | type | unknown
• Array: union of strings / pattern objects, merged into one group (no blank line between)
• Pattern object: { "pattern": "<glob>" } matched against the literal import source

First-match-wins across the list.

Built-in categories per runtime

Runtime	builtin match
node (default)	node:* prefix or hardcoded Node 22 LTS core list
deno	node:* prefix only
bun	node:*, bun:*, or Node core list
none	nothing

What works

• Reorder across groups + blank line between groups
• Pattern globs (@app/**, etc.)
• unknown catch-all (implicit at end, or explicit anywhere)
• Type-only imports: "separate" (default, own category) or "interleave"
• Side-effect imports (import "./polyfill") act as barriers — preserve position; imports either side grouped independently
• Per-import leading comments travel with the import on reorder
• Detached file-header comments (license, // @ts-check, etc.) pinned to file start
• Honors existing module.sortImportDeclarations for within-group order
• Honors existing importDeclaration.sortNamedImports for specifier sort
• Idempotent (verified via format_twice: true in the existing spec harness)

Tests

16 new spec files under tests/specs/declarations/import/ImportGroups_*.txt covering: basic reorder, sort variants, type-imports both modes, all four runtimes, pattern matchers + first-match-wins, side-effect barriers, header comments, multi-chunk barriers, import attributes (with { type: "json" }), .d.ts files + nested declare module, knob interactions, implicit/explicit unknown.

Plus unit tests covering classifier, partition, resolved-config compile, and diagnostics.

Full suite: 666 specs pass (660 pre-existing untouched + 16 new files / 14 sub-tests), 61 lib tests pass. Feature-off output byte-identical to baseline.

Known limitations (documented in README)

• // dprint-ignore on an import currently reorders like any other; barrier handling is a follow-up.
• CommonJS require(...), dynamic import(), TS import = require() not reordered.
• No module-resolver / tsconfig-paths consultation — raw source string only.
• Descending sort not supported.
• Imports inside nested declare module "..." bodies not classified.

ESLint import/order migration

ESLint	dprint
groups	module.importGroups (strings; nested arrays merge)
pathGroups	{ "pattern": "..." } entries placed positionally
newlines-between: "always"	Default when feature enabled
newlines-between: "never"/"ignore"	Empty module.importGroups
alphabetize.order: "asc"	Existing module.sortImportDeclarations
alphabetize.order: "desc"	Not supported

[LinusU]

Huge thanks for working on this! 🙌

I've tried it out on one of our codebases which has 302 TypeScript files. It didn't want to change anything! 🎉

Here is my config:

  "plugins": [
    "https://locousercontent.com/rhSXZADUEDZdBirieW5rdHdoHCfc0TyMUQoCGA4NGC4YKVm11ojTer5kN9R9XyYK/original.wasm"
  ],
  "typescript": {
    "module.importGroups": [
      { "match": "builtin" },
      { "match": "external" },
      { "match": "parent" },
      { "match": ["sibling", "index"] }
    ],
    "module.typeImports": "interleave",
    "module.builtinsRuntime": "node"
  }

And this is the Biome config that we used before:

"organizeImports": {
  "level": "on",
  "options": {
    "groups": [
      [":NODE:", ":BUN:"],
      ":BLANK_LINE:",
      [":URL:", ":PACKAGE_WITH_PROTOCOL:", ":PACKAGE:", ":ALIAS:"],
      ":BLANK_LINE:",
      "../**",
      ":BLANK_LINE:",
      "./**"
    ]
  }
}

(":URL:", ":PACKAGE_WITH_PROTOCOL:", and ":ALIAS:" are not used in our repo)

I built the WASM file from commit a8c550e, and the resulting SHA-384 hash is rhSXZADUEDZdBirieW5rdHdoHCfc0TyMUQoCGA4NGC4YKVm11ojTer5kN9R9XyYK, using Rust 1.90.0 (but not sure if builds are reproducable in this repo)

[todor-a]

@dsherret if I had to pick one PR that I would love to get merged, it would be this one. 😅 thanks!

[dimofeev]

I hope to have that approved soon! Thanks for this, @todor-a.

[todor-a]

hey, @dsherret. i see you are updating this repo, saw the new site as well, looks awesome.

i was wondering if we can go through with this pr? thanks a lot!