@ts-ioc-container/bundler 0.0.0

package/lib/ImportPaths.ts

@@ -0,0 +1,127 @@
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import * as ts from 'typescript';
+import { NamespaceNotFoundError, TicConfigError } from './errors';
+import { toPosix } from './glob';
+
+interface Alias {
+  pattern: string;
+  /** Absolute, `/`-separated. */
+  targets: string[];
+}
+
+const SOURCE_EXTENSION = /\.(tsx?|mts|cts)$/;
+/** tsconfig "No inputs were found": irrelevant here, the bundler scans its own folders. */
+const NO_INPUTS = 18003;
+
+const isDirectory = (dir: string) => existsSync(dir) && statSync(dir).isDirectory();
+const isRelative = (spec: string) => spec.startsWith('.') || path.isAbsolute(spec);
+
+/** Splits a `paths` pattern at its `*`, if it has one. */
+function splitWildcard(pattern: string): [string, string] | undefined {
+  const star = pattern.indexOf('*');
+  return star === -1 ? undefined : [pattern.slice(0, star), pattern.slice(star + 1)];
+}
+
+/**
+ * Import paths as a project's `tsconfig.json` sees them: resolves namespaces
+ * written as `paths` aliases to folders, and writes imports back in alias form.
+ */
+export class ImportPaths {
+  /**
+   * Reads `paths` (following `extends`) and the extension imports need under the
+   * tsconfig's `moduleResolution`; `importExtension` overrides the latter.
+   *
+   * @throws {TicConfigError} when a required tsconfig is missing or cannot be parsed.
+   */
+  static load(tsconfig: { file: string; required: boolean }, importExtension?: string): ImportPaths {
+    if (!existsSync(tsconfig.file)) {
+      if (tsconfig.required) throw new TicConfigError(`tsconfig not found: ${tsconfig.file}`);
+      return new ImportPaths([], importExtension ?? '');
+    }
+
+    const { config, error } = ts.readConfigFile(tsconfig.file, ts.sys.readFile);
+    const parsed = ts.parseJsonConfigFileContent(config, ts.sys, path.dirname(tsconfig.file), undefined, tsconfig.file);
+    const [fatal] = [error, ...parsed.errors].filter((d): d is ts.Diagnostic => !!d && d.code !== NO_INPUTS);
+    if (fatal) {
+      throw new TicConfigError(`${tsconfig.file}: ${ts.flattenDiagnosticMessageText(fatal.messageText, '\n')}`);
+    }
+
+    const { paths = {}, baseUrl, pathsBasePath, moduleResolution } = parsed.options;
+    // Without baseUrl, paths resolve against the tsconfig that declared them (which `extends` may make another file).
+    const base = baseUrl ?? (typeof pathsBasePath === 'string' ? pathsBasePath : path.dirname(tsconfig.file));
+    const aliases = Object.entries(paths).map(([pattern, targets]) => ({
+      pattern,
+      targets: targets.map((target) => toPosix(path.resolve(base, target))),
+    }));
+    const nodeEsm =
+      moduleResolution === ts.ModuleResolutionKind.Node16 || moduleResolution === ts.ModuleResolutionKind.NodeNext;
+    return new ImportPaths(aliases, importExtension ?? (nodeEsm ? '.js' : ''));
+  }
+
+  constructor(
+    private readonly aliases: Alias[],
+    readonly extension: string,
+  ) {}
+
+  /**
+   * The folder a namespace names: a path relative to `baseDir`, or a `paths` alias.
+   *
+   * @throws {NamespaceNotFoundError} when the namespace is neither an existing folder nor an alias of one.
+   */
+  resolveNamespace(namespace: string, baseDir: string): string {
+    const folder = path.resolve(baseDir, namespace);
+    if (isDirectory(folder)) return folder;
+    if (!isRelative(namespace)) {
+      // `@app` also matches an `@app/*` pattern, naming the alias root itself.
+      const found = [namespace, `${namespace}/`].flatMap((spec) => this.aliasTargets(spec)).find(isDirectory);
+      if (found) return path.normalize(found);
+    }
+    throw new NamespaceNotFoundError(
+      `namespace "${namespace}" is neither a folder relative to ${baseDir} nor a tsconfig paths alias of one`,
+    );
+  }
+
+  /** The specifier `fromFile` imports `toFile` by: its most specific alias, else a relative path. */
+  specifier(fromFile: string, toFile: string): string {
+    const target = toPosix(toFile);
+    const bare = target.replace(SOURCE_EXTENSION, '');
+    let best: { spec: string; score: number } | undefined;
+    for (const { pattern, targets } of this.aliases) {
+      for (const aliasTarget of targets) {
+        const match = this.matchAlias(pattern, aliasTarget, target, bare);
+        if (match && (!best || match.score > best.score)) best = match;
+      }
+    }
+    if (best) return best.spec;
+
+    const relative = toPosix(path.relative(path.dirname(fromFile), bare));
+    return `${relative.startsWith('.') ? relative : `./${relative}`}${this.extension}`;
+  }
+
+  private aliasTargets(spec: string): string[] {
+    return this.aliases.flatMap(({ pattern, targets }) => {
+      const wildcard = splitWildcard(pattern);
+      if (!wildcard) return pattern === spec ? targets : [];
+      const [prefix, suffix] = wildcard;
+      if (!spec.startsWith(prefix) || !spec.endsWith(suffix) || spec.length < prefix.length + suffix.length) return [];
+      const captured = spec.slice(prefix.length, spec.length - suffix.length);
+      return targets.map((target) => target.replace('*', captured));
+    });
+  }
+
+  /** A longer matched target prefix is a more specific alias; an exact file alias beats every wildcard. */
+  private matchAlias(pattern: string, aliasTarget: string, file: string, bare: string) {
+    const wildcard = splitWildcard(aliasTarget);
+    if (!wildcard) {
+      const exact = aliasTarget === file || aliasTarget.replace(SOURCE_EXTENSION, '') === bare;
+      return exact && !splitWildcard(pattern) ? { spec: pattern, score: Infinity } : undefined;
+    }
+    const [prefix, suffix] = wildcard;
+    if (!bare.startsWith(prefix) || !bare.endsWith(suffix) || bare.length < prefix.length + suffix.length) {
+      return undefined;
+    }
+    const captured = bare.slice(prefix.length, bare.length - suffix.length);
+    return { spec: `${pattern.replace('*', captured)}${this.extension}`, score: prefix.length };
+  }
+}

package/lib/bin.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from './cli';
+
+process.exitCode = run(process.argv.slice(2));

package/lib/build.ts

@@ -0,0 +1,157 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_FILE, loadConfig, type ResolvedConfig, type ResolvedBundle } from './config';
+import { emitBundle } from './emit';
+import { globToRegExp, toPosix } from './glob';
+import { ImportPaths } from './ImportPaths';
+import { type ExportPredicate, findConventionalExportPredicate, loadExportPredicate } from './exportPredicate';
+import { fileTags, findConventionalPredicate, type InclusionPredicate, loadInclusionPredicate } from './inclusion';
+import { findClasses, listSourceFiles } from './scan';
+
+export interface BuildOptions {
+  /** Path of `tic.config.json`, relative to `cwd`. Default `tic.config.json`. */
+  config?: string;
+  /** Default `process.cwd()`. */
+  cwd?: string;
+  /** Compare instead of writing: outputs that would change are reported `stale`. */
+  check?: boolean;
+  /** Decides which scanned files take part; overrides every inclusion predicate file. */
+  include?: InclusionPredicate;
+  /** Decides which parsed classes become registrations; overrides every export predicate file. */
+  filterExports?: ExportPredicate;
+}
+
+/** `written` / `unchanged` after a build; `stale` / `unchanged` after a check. */
+export type OutputStatus = 'written' | 'unchanged' | 'stale';
+
+export interface OutputResult {
+  /** Absolute path of the generated file. */
+  file: string;
+  /** Name of the generated class. */
+  bundle: string;
+  status: OutputStatus;
+  registrations: number;
+  content: string;
+}
+
+export interface BuildResult {
+  /** Absolute path of the config that was built. */
+  config: string;
+  outputs: OutputResult[];
+}
+
+/**
+ * Generates one bundle per config entry. Every bundle is generated before any
+ * file is written, so a failing namespace leaves the previous outputs intact.
+ *
+ * @throws {TicConfigError} when the config, the tsconfig or a predicate file it names is missing or invalid.
+ * @throws {NamespaceNotFoundError} when a namespace is neither a folder nor a tsconfig paths alias of one.
+ */
+export function build({
+  config = DEFAULT_CONFIG_FILE,
+  cwd = process.cwd(),
+  check = false,
+  include,
+  filterExports,
+}: BuildOptions = {}): BuildResult {
+  const resolved = loadConfig(path.resolve(cwd, config));
+  const paths = ImportPaths.load(resolved.tsconfig, resolved.importExtension);
+  const includeFor = predicateResolver({
+    override: include,
+    conventional: findConventionalPredicate(resolved.dir),
+    fileOf: (bundle) => bundle.include,
+    load: loadInclusionPredicate,
+  });
+  const filterExportsFor = predicateResolver({
+    override: filterExports,
+    conventional: findConventionalExportPredicate(resolved.dir),
+    fileOf: (bundle) => bundle.filterExports,
+    load: loadExportPredicate,
+  });
+  const generated = resolved.bundles.map((bundle) =>
+    generate(resolved, bundle, paths, { include: includeFor(bundle), filterExports: filterExportsFor(bundle) }),
+  );
+
+  const outputs = generated.map(({ bundle, content, registrations }): OutputResult => {
+    const current = existsSync(bundle.output) ? readFileSync(bundle.output, 'utf8') : undefined;
+    const status: OutputStatus = current === content ? 'unchanged' : check ? 'stale' : 'written';
+    if (status === 'written') {
+      mkdirSync(path.dirname(bundle.output), { recursive: true });
+      writeFileSync(bundle.output, content);
+    }
+    return { file: bundle.output, bundle: bundle.name, status, registrations, content };
+  });
+  return { config: resolved.file, outputs };
+}
+
+/**
+ * Which predicate of one kind a bundle uses: the one passed to `build`, else the bundle's own file,
+ * else the conventional file next to the config, else none. Each file is loaded once, and only when
+ * a bundle needs it.
+ *
+ * @throws {TicConfigError} when a predicate file a bundle needs is missing or does not export a function.
+ */
+function predicateResolver<P>({
+  override,
+  conventional,
+  fileOf,
+  load,
+}: {
+  override?: P;
+  conventional?: string;
+  fileOf: (bundle: ResolvedBundle) => string | undefined;
+  load: (file: string) => P;
+}) {
+  const loaded = new Map<string, P>();
+  return (bundle: ResolvedBundle): P | undefined => {
+    if (override) return override;
+    const file = fileOf(bundle) ?? conventional;
+    if (file === undefined) return undefined;
+    if (!loaded.has(file)) loaded.set(file, load(file));
+    return loaded.get(file);
+  };
+}
+
+/**
+ * @throws {NamespaceNotFoundError} when a namespace is neither a folder nor a tsconfig paths alias of one.
+ */
+function generate(
+  config: ResolvedConfig,
+  bundle: ResolvedBundle,
+  paths: ImportPaths,
+  { include, filterExports }: { include?: InclusionPredicate; filterExports?: ExportPredicate },
+) {
+  const relative = (file: string) => toPosix(path.relative(config.dir, file));
+  const outputs = new Set(config.bundles.map((m) => m.output));
+  const excludes = bundle.exclude.map(globToRegExp);
+  const isExcluded = (file: string) => {
+    if (outputs.has(file)) return true;
+    const filename = relative(file);
+    return excludes.some((glob) => glob.test(filename)) || (include !== undefined && !include({ filename }));
+  };
+
+  const files = new Set<string>();
+  for (const namespace of bundle.namespaces) {
+    const dir = paths.resolveNamespace(namespace.path, config.dir);
+    for (const file of listSourceFiles(dir, namespace.recursive, isExcluded)) files.add(file);
+  }
+
+  const classes = [...files]
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+    .flatMap((file) => findClasses(file, bundle.select))
+    .filter((cls) => {
+      if (!filterExports) return true;
+      const filename = relative(cls.file);
+      const { exportName, className, isDefault, decorators } = cls;
+      return filterExports({ filename, exportName, className, isDefault, decorators, tags: fileTags(filename) });
+    })
+    .map((cls) => ({ ...cls, specifier: paths.specifier(bundle.output, cls.file) }));
+
+  const content = emitBundle({
+    name: bundle.name,
+    configPath: toPosix(path.relative(path.dirname(bundle.output), config.file)),
+    namespaces: bundle.namespaces.map((ns) => ns.path),
+    classes,
+  });
+  return { bundle, content, registrations: classes.length };
+}

package/lib/cli.ts

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { build, type OutputStatus } from './build';
+import { TicError } from './errors';
+
+export interface CliIo {
+  cwd: string;
+  stdout: (line: string) => void;
+  stderr: (line: string) => void;
+}
+
+const USAGE = [
+  'Usage: ts-ioc-container <command> [options]',
+  '       tic is a shortcut for ts-ioc-container',
+  '',
+  'Commands:',
+  '  ts-ioc-container build [--config <path>] [--check]   generate the bundles described by tic.config.json',
+  '',
+  'Options:',
+  '  -c, --config <path>   config file (default: tic.config.json)',
+  '  --check               write nothing; exit 1 when a generated bundle is out of date',
+  '  -h, --help            show this help',
+  '  -v, --version         show the version',
+].join('\n');
+
+const VERB: Record<OutputStatus, string> = { written: 'wrote', unchanged: 'unchanged', stale: 'stale' };
+
+const plural = (n: number) => `${n} registration${n === 1 ? '' : 's'}`;
+
+function version(): string {
+  return JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
+}
+
+class UsageError extends TicError {}
+
+/**
+ * @throws {UsageError} when an option is unknown or `--config` has no value.
+ */
+function parseBuildArgs(args: string[]) {
+  const options: { config?: string; check: boolean } = { check: false };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--check') options.check = true;
+    else if (arg === '--config' || arg === '-c') {
+      options.config = args[++i];
+      if (!options.config) throw new UsageError(`${arg} needs a path`);
+    } else if (arg.startsWith('--config=')) options.config = arg.slice('--config='.length);
+    else throw new UsageError(`unknown option "${arg}"`);
+  }
+  return options;
+}
+
+/** Runs the `tic` CLI and returns its exit code; output goes through `io`. */
+export function run(
+  argv: string[],
+  io: CliIo = { cwd: process.cwd(), stdout: console.log, stderr: console.error },
+): number {
+  const [command, ...rest] = argv;
+  if (command === '--help' || command === '-h' || command === 'help') {
+    io.stdout(USAGE);
+    return 0;
+  }
+  if (command === '--version' || command === '-v') {
+    io.stdout(version());
+    return 0;
+  }
+  try {
+    if (command !== 'build') {
+      io.stderr(command ? `tic: unknown command "${command}"` : USAGE);
+      return 1;
+    }
+    const { config, check } = parseBuildArgs(rest);
+    const { outputs } = build({ config, check, cwd: io.cwd });
+    for (const { status, file, registrations } of outputs) {
+      io.stdout(`${VERB[status].padEnd(10)}${path.relative(io.cwd, file)} (${plural(registrations)})`);
+    }
+    const stale = outputs.filter((o) => o.status === 'stale').length;
+    if (stale > 0) {
+      io.stderr(`tic: ${stale} generated bundle${stale === 1 ? ' is' : 's are'} out of date — run \`tic build\``);
+      return 1;
+    }
+    return 0;
+  } catch (e) {
+    if (!(e instanceof TicError)) throw e;
+    io.stderr(`tic: ${e.message}`);
+    return 1;
+  }
+}

package/lib/config.ts

@@ -0,0 +1,206 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { TicConfigError } from './errors';
+import { globToRegExp } from './glob';
+
+/** Which exports of a file count: both kinds, only named exports, or only the default export. */
+export type ExportKind = 'any' | 'named' | 'default';
+
+/**
+ * How the bundler picks target classes out of a file. A class is selected when
+ * it is exported, not abstract, and meets every criterion set here; an empty
+ * rule selects every exported class.
+ */
+export interface ClassSelector {
+  /** Default `any`. */
+  export?: ExportKind;
+  /** The class must carry one of these decorators, recognised by name (`register`, or a composed one). */
+  decorators?: string[];
+  /** A glob the class name must match, e.g. `*Service`. An anonymous default export is named after its file. */
+  nameGlob?: string;
+}
+
+/** A {@link ClassSelector} with its defaults filled in and its `nameGlob` compiled. */
+export interface ResolvedSelector {
+  export: ExportKind;
+  decorators?: string[];
+  nameGlob?: RegExp;
+}
+
+export interface NamespaceConfig {
+  /** A folder relative to the config file (`./src/services`) or a tsconfig `paths` alias (`@app/services`). */
+  path: string;
+  /** Scan sub-folders too. Default `true`. */
+  recursive?: boolean;
+}
+
+export interface BundleConfig {
+  /** The generated file, relative to the config file. */
+  output: string;
+  /** Name of the generated class, an `IContainerModule`. Default `Bundle`. */
+  name?: string;
+  namespaces: (string | NamespaceConfig)[];
+  /** Which classes of a scanned file are registered. Default: every exported class. */
+  select?: ClassSelector;
+  /** Globs, relative to the config file, of files never scanned. Replaces {@link DEFAULT_EXCLUDE} when given. */
+  exclude?: string[];
+  /**
+   * A file exporting an `InclusionPredicate`, relative to the config file. Overrides the
+   * conventional `tic.include.*` next to the config.
+   */
+  include?: string;
+  /**
+   * A file exporting an `ExportPredicate`, relative to the config file. Overrides the
+   * conventional `tic.exports.*` next to the config.
+   */
+  filterExports?: string;
+}
+
+/** The shape of `tic.config.json`. */
+export interface TicConfig {
+  $schema?: string;
+  /** Relative to the config file. Default `tsconfig.json`, which may be absent. */
+  tsconfig?: string;
+  /** Extension of generated imports. Inferred from the tsconfig's `moduleResolution` when omitted. */
+  importExtension?: string;
+  bundles: BundleConfig[];
+}
+
+export const DEFAULT_CONFIG_FILE = 'tic.config.json';
+export const DEFAULT_BUNDLE_NAME = 'Bundle';
+export const DEFAULT_EXCLUDE = [
+  '**/*.spec.ts',
+  '**/*.test.ts',
+  '**/*.spec.tsx',
+  '**/*.test.tsx',
+  '**/__tests__/**',
+  '**/node_modules/**',
+];
+
+/** A config whose defaults are filled in and whose paths are absolute. */
+export interface ResolvedConfig {
+  file: string;
+  dir: string;
+  tsconfig: { file: string; required: boolean };
+  importExtension?: string;
+  bundles: ResolvedBundle[];
+}
+
+export interface ResolvedBundle {
+  output: string;
+  name: string;
+  namespaces: Required<NamespaceConfig>[];
+  select: ResolvedSelector;
+  exclude: string[];
+  /** Absolute path of the bundle's own predicate file, when it names one. */
+  include?: string;
+  /** Absolute path of the bundle's own export predicate file, when it names one. */
+  filterExports?: string;
+}
+
+type Json = Record<string, unknown>;
+
+const isObject = (value: unknown): value is Json =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+const isNonEmptyString = (value: unknown): value is string => typeof value === 'string' && value.length > 0;
+const isStringArray = (value: unknown): value is string[] => Array.isArray(value) && value.every(isNonEmptyString);
+const isIdentifier = (value: unknown): value is string => typeof value === 'string' && /^[A-Za-z_$][\w$]*$/.test(value);
+
+const fail = (field: string, expected: string): never => {
+  throw new TicConfigError(`${field}: expected ${expected}`);
+};
+
+/**
+ * @throws {TicConfigError} when a namespace entry is neither a non-empty string nor an object with a `path`.
+ */
+function toNamespace(value: unknown, field: string): Required<NamespaceConfig> {
+  if (isNonEmptyString(value)) return { path: value, recursive: true };
+  if (!isObject(value)) return fail(field, 'a string or an object with "path"');
+  if (!isNonEmptyString(value.path)) return fail(`${field}.path`, 'a non-empty string');
+  if (value.recursive !== undefined && typeof value.recursive !== 'boolean')
+    return fail(`${field}.recursive`, 'a boolean');
+  return { path: value.path, recursive: value.recursive ?? true };
+}
+
+const SELECTOR_FIELDS = new Set(['export', 'decorators', 'nameGlob']);
+
+/**
+ * @throws {TicConfigError} when the rule is not an object, has an unknown field, or a field has the wrong type.
+ */
+function toSelector(value: unknown, field: string): ResolvedSelector {
+  if (value === undefined) return { export: 'any' };
+  if (!isObject(value)) return fail(field, 'an object');
+  const unknown = Object.keys(value).find((key) => !SELECTOR_FIELDS.has(key));
+  if (unknown) throw new TicConfigError(`${field}.${unknown}: unknown field`);
+  const { export: kind, decorators, nameGlob } = value;
+  if (kind !== undefined && kind !== 'any' && kind !== 'named' && kind !== 'default') {
+    return fail(`${field}.export`, '"any", "named" or "default"');
+  }
+  if (decorators !== undefined && !(isStringArray(decorators) && decorators.length > 0)) {
+    return fail(`${field}.decorators`, 'a non-empty array of strings');
+  }
+  if (nameGlob !== undefined && !isNonEmptyString(nameGlob)) return fail(`${field}.nameGlob`, 'a non-empty string');
+  return { export: kind ?? 'any', decorators, nameGlob: nameGlob === undefined ? undefined : globToRegExp(nameGlob) };
+}
+
+/**
+ * @throws {TicConfigError} when a bundle field is missing or has the wrong type.
+ */
+function toBundle(value: unknown, field: string, dir: string): ResolvedBundle {
+  if (!isObject(value)) return fail(field, 'an object');
+  const { output, name, namespaces, select, exclude, include, filterExports } = value;
+  if (!isNonEmptyString(output)) return fail(`${field}.output`, 'a non-empty string');
+  if (name !== undefined && !isIdentifier(name)) return fail(`${field}.name`, 'a valid identifier');
+  if (!Array.isArray(namespaces) || namespaces.length === 0) return fail(`${field}.namespaces`, 'a non-empty array');
+  if (exclude !== undefined && !isStringArray(exclude)) return fail(`${field}.exclude`, 'an array of strings');
+  if (include !== undefined && !isNonEmptyString(include)) return fail(`${field}.include`, 'a non-empty string');
+  if (filterExports !== undefined && !isNonEmptyString(filterExports)) {
+    return fail(`${field}.filterExports`, 'a non-empty string');
+  }
+  return {
+    output: path.resolve(dir, output),
+    name: name ?? DEFAULT_BUNDLE_NAME,
+    namespaces: namespaces.map((ns, i) => toNamespace(ns, `${field}.namespaces[${i}]`)),
+    select: toSelector(select, `${field}.select`),
+    exclude: exclude ?? DEFAULT_EXCLUDE,
+    include: include === undefined ? undefined : path.resolve(dir, include),
+    filterExports: filterExports === undefined ? undefined : path.resolve(dir, filterExports),
+  };
+}
+
+/**
+ * Validates parsed `tic.config.json` content and resolves its paths against `file`'s directory.
+ *
+ * @throws {TicConfigError} when the content does not match the config shape; the message names the field.
+ */
+export function resolveConfig(content: unknown, file: string): ResolvedConfig {
+  const dir = path.dirname(file);
+  if (!isObject(content)) return fail('config', 'a JSON object');
+  const { tsconfig, importExtension, bundles } = content;
+  if (tsconfig !== undefined && !isNonEmptyString(tsconfig)) return fail('tsconfig', 'a non-empty string');
+  if (importExtension !== undefined && typeof importExtension !== 'string') return fail('importExtension', 'a string');
+  if (!Array.isArray(bundles) || bundles.length === 0) return fail('bundles', 'a non-empty array');
+  return {
+    file,
+    dir,
+    tsconfig: { file: path.resolve(dir, tsconfig ?? 'tsconfig.json'), required: tsconfig !== undefined },
+    importExtension,
+    bundles: bundles.map((m, i) => toBundle(m, `bundles[${i}]`, dir)),
+  };
+}
+
+/**
+ * Reads and validates a `tic.config.json`.
+ *
+ * @throws {TicConfigError} when the file is missing, is not valid JSON, or does not match the config shape.
+ */
+export function loadConfig(file: string): ResolvedConfig {
+  if (!existsSync(file)) throw new TicConfigError(`config file not found: ${file}`);
+  let content: unknown;
+  try {
+    content = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    throw new TicConfigError(`${file} is not valid JSON: ${(e as Error).message}`);
+  }
+  return resolveConfig(content, file);
+}

package/lib/emit.ts

@@ -0,0 +1,47 @@
+import { renderProtocol } from './render';
+import type { DiscoveredClass } from './scan';
+
+export interface EmitInput {
+  /** Name of the generated class. */
+  name: string;
+  /** Shown in the header: where the output came from. */
+  configPath: string;
+  namespaces: string[];
+  classes: (DiscoveredClass & { specifier: string })[];
+}
+
+const RUNTIME_IMPORTS = ['IContainer', 'IContainerModule', 'IRegistration', 'Registration'];
+
+/**
+ * Renders the generated bundle — static imports, `registrations`, and the bundle applying them —
+ * from its protocol, `protocols/Bundle.ts.hbs`. This function only prepares the data: unique local
+ * names, and one import per file in file order.
+ */
+export function emitBundle({ name, configPath, namespaces, classes }: EmitInput): string {
+  const taken = new Set([...RUNTIME_IMPORTS, 'registrations', name]);
+  const uniqueName = (wanted: string) => {
+    let candidate = wanted;
+    for (let n = 2; taken.has(candidate); n++) candidate = `${wanted}_${n}`;
+    taken.add(candidate);
+    return candidate;
+  };
+
+  // One import statement per file, in file order.
+  const byFile = new Map<string, { specifier: string; defaultName?: string; named: string[] }>();
+  const bindings = classes.map((cls) => {
+    const binding = uniqueName(cls.localName);
+    const entry = byFile.get(cls.file) ?? { specifier: cls.specifier, named: [] };
+    byFile.set(cls.file, entry);
+    if (cls.exportName === 'default') entry.defaultName = binding;
+    else entry.named.push(binding === cls.exportName ? binding : `${cls.exportName} as ${binding}`);
+    return binding;
+  });
+
+  return renderProtocol('Bundle.ts.hbs', {
+    configPath,
+    namespaces,
+    name,
+    imports: [...byFile.values()],
+    registrations: bindings,
+  });
+}

package/lib/errors.ts

@@ -0,0 +1,14 @@
+/** Base class of every error the bundler raises on purpose; the CLI prints its message without a stack. */
+export class TicError extends Error {
+  name = 'TicError';
+}
+
+/** The config file is missing, is not JSON, or does not match the `tic.config.json` shape. */
+export class TicConfigError extends TicError {
+  name = 'TicConfigError';
+}
+
+/** A namespace is neither an existing folder nor a `tsconfig.json` `paths` alias of one. */
+export class NamespaceNotFoundError extends TicError {
+  name = 'NamespaceNotFoundError';
+}