feat: import grouping (#493)

[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