🌂 feat: Require Namespace Cleanup for Long Type Imports

[lia-by-librechat]

Summary

Long type-only import lists expand to one symbol per line under Prettier. The existing import sorter now automatically converts eligible long named type imports into collision-free namespace imports and updates references using TypeScript symbols. Compaction is required for safe candidates, not an opt-in mode: the staged-file cleanup hook fixes them, and the existing changed-file import check rejects them when cleanup has not run.

npm run sort-imports -- path/to/file.ts
npm run sort-imports:check -- path/to/file.ts

Run Prettier on affected files afterward, as with the existing sorter. --check uses the same transformation without writing. Runtime imports, short type imports, and unsafe candidates remain unchanged. This PR does not bulk-migrate application source; enforcement applies to staged or changed source files through the existing scoped pipeline.

How it works

The cutoff comes from .prettierrc's printWidth. The converter binds only the current file, without resolving modules or loading a workspace project. It qualifies references by symbol identity, preserves imported aliases and shadowed locals, and chooses a namespace unused across all scopes. Default aliases, re-exported bindings, unsupported uses, commented import clauses, ambiguous declarations, and malformed files are conservatively skipped. Existing sort-imports-ignore markers still apply. Compiler-host paths are normalized for Windows.

-import type {
-  Message,
-  Conversation,
-  AgentConfiguration,
-  AgentPermission,
-  AgentCapability,
-} from './models';
+import type * as t from './models';

-type Row = Message;
+type Row = t.Message;

lint-staged
  sort-imports        # compacts eligible type imports and sorts
  prettier --write
  eslint

Static Checks
  sort-imports --check # fails on eligible imports left unconverted

No new CI invocation or opt-in flag is needed for enforcement: the hook and Static Checks already call this script. TypeScript becomes an explicit root development dependency at its already-locked version. The compiler loads lazily for files with named type imports. The Static Checks workflow also runs the focused tooling regressions, typechecking, and formatting when this tooling changes.

Type of change

• Feature
• Tests / tooling / CI

Testing

Tested environments/configuration: Node.js 24.16.0, TypeScript 5.9.3, and Prettier 3.6.2.

Automated tests:

• node --test scripts/imports/compact.test.mts: all 16 tests passed. Covers aliases, before/after type resolution, synthetic defaults, Windows paths, shadowing, collisions, comments, JSDoc, conservative exclusions, formatter compatibility, default CLI cleanup, the actual pre-commit sorter command, Static Checks import rejection/acceptance, check-only behavior, and idempotence.
• npx --no-install tsc --noEmit --project scripts/imports/tsconfig.json: passed.
• Targeted ESLint, Prettier, and scoped import-sort checks: passed. The sorter only targets application source roots, so import ordering in the script files is not enforced by it.
• The Static Checks import gate is exercised by the regression test: it rejects eligible imports, does not write, and passes after default cleanup. Package-manifest validation is run separately.

The local circular-dependency check and the upstream design-rule build/suppression gates require application workspace dependencies and tsdown, which are absent from the isolated tooling installation. Full application tests, full workspace typechecks, application builds, and Lighthouse were not run locally. The corresponding applicable lanes run in GitHub CI.

Screenshots / recordings

No user-facing change.

Risk / compatibility

This changes the required style for long type-only imports on files processed by cleanup. It does not change runtime imports or runtime evaluation order. Unsupported patterns are skipped rather than rewritten unsafely. Untouched files are not rejected by the changed-file CI gate, avoiding an unrelated repository-wide migration. A whole-tree sort-imports:check intentionally reports existing eligible imports that have not been cleaned.

Checklist

• I reviewed my own changes
• Relevant tests have been added or updated
• User-facing or complex behavior is documented where necessary
• Required dependency changes have been merged/published: existing locked compiler, no version change
• Required documentation PR: N/A

Verification status

Pushed head: c32c248102074b54633ccebec7fe061e3a572a89, targeting dev. All 16 focused tests, tooling no-emit TypeScript compilation, touched-file lint/formatting, package-manifest validation, and resolved workflow validation passed locally. Exact-head CI passed the import-tooling tests/typecheck/Prettier step and changed-file import check, plus workspace typechecks, builds, backend unit tests, circular dependency detection, the design-rule regression sweep, and Lighthouse. As of 2026-10-01 12:35 UTC, no CI failures are reported; the overall Static Checks job, Playwright E2E lanes, API runtime smoke, and Ubuntu frontend test shards remain pending.

Independent source review at this exact head reported no supported defects. Its verification remains incomplete: reviewer workspace capacity prevented local checks, and its available tools could not inspect individual Actions steps. The author independently confirmed those focused CI steps passed, but that does not make the reviewer verification complete. No further same-head review retry is pending. Earlier findings R1 (P2, synthetic default aliases) and R2 (P2, compiler-host path normalization) were fixed in c9a9312397b8b1fb54269d147b799b503f3f5c3c and remain present; no findings are rejected or open.

[lia-by-librechat]

Review head 3d2eaf2: adds an opt-in compact-type-import mode to the scoped sorter, symbol-aware reference updates, conservative exclusions, and focused tests/typechecking in Static Checks. Runtime imports and default cleanup behavior are unchanged.

[lia-by-librechat]

Review head c9a9312: preserves synthetic default aliases, normalizes Windows compiler-host paths, and adds type-resolution and cross-platform filename regressions. All 16 focused tests, tooling no-emit compilation, and touched-file lint passed locally. The prior head's two P2 review findings are fixed here.

[lia-by-librechat]

Final verification for head c9a9312:

• Independent review: complete, no new findings at this exact head.
• Finding ledger: R1 (P2), Preserve synthetic default aliases, fixed in c9a9312. R2 (P2), Normalize compiler-host filenames, fixed in the same commit. No rejected or open findings.
• Local verification: all 16 focused tests, tooling no-emit TypeScript compilation, touched-file ESLint and Prettier, lockfile dry run, and available Static Checks passed. Read-only corpus smoke covered 2,448 type-import files; converted outputs were syntactically valid, idempotent, and identical for Windows paths.
• All applicable GitHub CI checks passed, including Static Checks, builds, unit tests, workspace typechecks, circular dependency checks, runtime smoke, and Lighthouse. No pending or failed checks.
• Full application tests, full workspace typechecks, builds, Lighthouse, and circular dependency checks were not run locally; the corresponding CI checks passed.
• Title verification: 🌂 had 0 prior occurrences (0 subject-leading) in 5,643 indexed LibreChat commits through 2026-09-30 15:01:32 UTC. The nightly corpus is a floor; the sentinel check passed.

[lia-by-librechat]

Review head 007f889: safe type-import compaction now runs during normal cleanup and normal --check. The existing pre-commit sorter automatically fixes eligible staged files, and Static Checks rejects eligible imports in changed source files. Runtime imports and conservative safety exclusions remain unchanged. All 16 focused tests, tooling typecheck, touched-file lint/formatting, and available local Static Checks passed. Title rarity rechecked: 🌂 has 0 prior uses (0 subject-leading) in 5,750 indexed LibreChat commits through 2026-09-30 22:35:22 UTC; sentinel passed.

[lia-by-librechat]

Review head c32c248: normal cleanup and check mode require safe type-import compaction. The current-dev workflow conflict is resolved while retaining its design-rule build/suppression gates and the new import-tooling tests. All 16 focused tests, tooling no-emit compilation, touched-file lint/formatting, and resolved-workflow YAML validation passed. Runtime imports and safety exclusions remain unchanged; no bulk application migration is included.

[lia-by-librechat]

Required-cleanup handoff for head c32c248:

• Normal cleanup and the staged-file sorter automatically compact eligible long type-only imports. Normal --check and changed-file CI reject safe candidates left unconverted. No opt-in flag or bulk migration is needed.
• Local checks passed: all 16 focused tests, tooling tsc --noEmit, touched-file ESLint and Prettier, package-manifest validation, and workflow validation. Runtime imports and conservative exclusions remain intact.
• Exact-head CI independently checked by the author: import-tooling tests/typecheck/Prettier and changed-file import enforcement passed. No CI failures as of 2026-10-01 12:35 UTC. Overall Static Checks, E2E lanes, API runtime smoke, and Ubuntu frontend test shards remain pending.
• Independent source review reported no supported defects, but verification is incomplete because reviewer workspace capacity and available GitHub tools prevented local checks and inspection of individual Actions steps. This is not a clean, fully verified independent review.
• Finding ledger: R1 (P2, preserve synthetic default aliases) and R2 (P2, normalize compiler-host filenames) fixed in c9a9312 and retained. No rejected or open findings.
• Not run locally: full application suites, full workspace typechecks, application builds, Lighthouse, circular dependency detection, and upstream design-rule build/suppression gates. Applicable CI lanes cover them; pending lanes are named above.