typescript-barrel-split

Answer 1

The split is a two-part operation: (A) the oversized file becomes a directory with an exact-API barrel, (B) the original file path becomes a shim that forwards to the barrel. Importers are never touched.

Why the shim is mandatory

Under moduleResolution: "bundler" (and node16/nodenext), the .js suffix maps to a file, not a directory. import { x } from "./big.js" resolves to big.ts via .js→.ts substitution; it does not fall back to big/index.ts. Delete big.ts and every .js-suffixed importer dies with TS2307. (Extensionless ./big does fall back to the dir index in bundler mode, but that doesn't save the .js importers.) Since big.ts and big/index.ts are distinct filesystem paths, they coexist — and because file lookup precedes dir-index lookup, even extensionless importers hit the shim.

Recipe (verified, zero importer changes)

1. Move the body into a directory. Split into impl.ts / sub.ts / etc. as the 900+L file dictates.

2. Re-root relative imports. Paths that pointed at siblings gain ../; paths to co-moved modules stay ./:

// src/big/impl.ts  (moved from src/big.ts)
import { resolvePixel } from "../pixel-resolver.js";   // was "./pixel-resolver.js"
import { helper } from "./sub.js";                     // co-moved, unchanged

3. Build the index barrel preserving the exact public API. Prefer an explicit re-export list over chained export * (avoids ambiguous-star drops), and forward types separately:

// src/big/index.ts
export { PIXEL_SCALE, area, resolve } from "./impl.js";
export { default } from "./impl.js";                            // default — see trap below
export { resolvePixel as aliasResolver } from "../pixel-resolver.js"; // alias re-export, re-rooted
export type { Pixel, PixelKind } from "./impl.js";

4. Replace the original file with the shim.

Named-only module (the canonical 1-liner):

// src/big.ts
export * from "./big/index.js";

Module with a default export — export * never forwards default, so add one line:

// src/big.ts
export * from "./big/index.js";
export { default } from "./big/index.js";

Traps discovered while verifying

• TS1192 / default: a star-only shim compiles fine until an importer does import def from "./big.js" → "Module has no default export". The second line is mandatory when the original had a default.
• TS2614: you cannot write export { defaultMeta as default } from "./impl.js" — the local name of a default export is not itself an exported name. It must be export { default } from.
• Ambiguous export *: if two sub-modules star-export the same name, the name is silently dropped. Explicit barrel lists eliminate the risk, which is what "preserve exact public API" demands.

Answer 2

Target structure — split git.service.ts (512L) into a 5-file module dir, keeping the original import path working via a 1-line star shim:

src/services/
  git.service.ts            ← REPLACED by 1-line shim (keeps original path live)
  git.service/
    types.ts                ← 9 interfaces (moved verbatim, no imports)
    errors.ts               ← enhanceGitError (pure helper, private)
    events.ts               ← publishEvent (private, explicit eventBus param)
    core.ts                 ← GitService class + let-singleton + factories (LF-059: at END)
    index.ts                ← parent barrel: named re-exports, full 13/13 surface

1. git.service/types.ts — 9 interfaces (private-helper-free, type-only module):

export interface GitEventBus      { publish(channel: string, payload: unknown): void; }
export interface GitServiceOptions { cwd: string; gitPath?: string; eventBus: GitEventBus; }
export interface GitExecOptions   { cwd?: string; timeoutMs?: number; env?: NodeJS.ProcessEnv; }
export interface GitBranchInfo    { name: string; current: boolean; upstream?: string; ahead?: number; behind?: number; }
export interface GitStatusEntry   { path: string; status: 'added'|'modified'|'deleted'|'untracked'|'renamed'; staged: boolean; }
export interface GitLogEntry      { hash: string; author: string; date: string; message: string; }
export interface GitRemoteInfo    { name: string; url: string; pushUrl?: string; }
export interface GitTagInfo       { name: string; commitHash: string; annotated: boolean; }
export interface GitDiffSummary   { filesChanged: number; insertions: number; deletions: number; }

2. git.service/errors.ts — enhanceGitError (pure: zero module-scope deps, only args):

import type { GitExecOptions } from './types.js';
export interface GitEnhancedError extends Error { command?: string; exitCode?: number; stderr?: string; }
export function enhanceGitError(error: unknown, command: string, stderr?: string): GitEnhancedError {
  const e = (error instanceof Error ? error : new Error(String(error))) as GitEnhancedError;
  e.command = command; e.stderr = stderr; return e;
}

3. git.service/events.ts — publishEvent with explicit eventBus param (only dep is the type):

import type { GitEventBus } from './types.js';
export function publishEvent(eventBus: GitEventBus, eventName: string, payload: unknown): void {
  eventBus.publish(`git:${eventName}`, payload);
}

4. git.service/core.ts — class + singleton + factories; LF-059 order; import shift:

import { eventBus } from '../event-bus.js';          // ← shifted: ./event-bus.js → ../event-bus.js (only import change)
import { enhanceGitError } from './errors.js';
import { publishEvent } from './events.js';
import type { GitServiceOptions, GitExecOptions, GitBranchInfo, /* ...all 9 */ } from './types.js';

// --- private helpers that stay in core (runGit, parsers) ---

// --- LF-059: class whole + let-singleton + factories at END of core.ts ---
export class GitService {
  constructor(private readonly options: GitServiceOptions) {}
  async getBranches(): Promise<GitBranchInfo[]> { /* ... */ }
  // ...
  private runGit(args: string[], opts?: GitExecOptions) {
    try { /* ... */ } catch (err) { throw enhanceGitError(err, args.join(' ')); }
  }
  protected emit(name: string, payload: unknown) { publishEvent(this.options.eventBus, name, payload); }
}

let gitServiceInstance: GitService | null = null;      // let-singleton

export function createGitService(options: GitServiceOptions): GitService { return new GitService(options); }
export function getGitService(): GitService {
  gitServiceInstance ??= createGitService({ cwd: process.cwd(), eventBus });
  return gitServiceInstance;
}
export function resetGitService(): void { gitServiceInstance = null; }

5. git.service/index.ts — parent barrel, named re-exports of all 13 (9 types + class + 3 fns):

export type {
  GitEventBus, GitServiceOptions, GitExecOptions, GitBranchInfo, GitStatusEntry,
  GitLogEntry, GitRemoteInfo, GitTagInfo, GitDiffSummary,
} from './types.js';
export { GitService, createGitService, getGitService, resetGitService } from './core.js';
// errors.ts / events.ts are private helpers — intentionally NOT re-exported

6. git.service.ts — 1-line star shim (named-only surface; API has no default export, so star parity is exact):

export * from './git.service/index.js';

Importer compatibility: tests keep import { GitService, getGitService, ... } from './git.service.js' — TS resolves ./git.service.js → shim git.service.ts → ./git.service/index.js barrel; compiled JS mirrors the same chain (git.service.js → git.service/index.js). The only relative-path shift anywhere is ./event-bus.js → ../event-bus.js inside core.ts. Zero importer changes.