@ts-ioc-container/bundler 1.4.0 → 2.0.0

package/AGENTS.md

@@ -7,40 +7,45 @@ nothing here runs inside the container, and the core package is not changed by
 it.
 
 - The CLI is `ts-ioc-container`, with `tic` as a shortcut (both `bin` entries,
-  same program). `tic build` reads `tic.config.json` (schema: `tic.schema.json`) and writes one
-  bundle per `bundles[]` entry — a generated class, `export class AppBundle implements IContainerModule`, applied with `container.useModule(new AppBundle())`. `--check` writes nothing and exits 1
-  when an output is stale — run it in CI.
-- A namespace is a folder: relative to the config file, or a tsconfig `paths`
-  alias. Generated imports use the most specific alias, else a relative path.
-- Default selection is every exported, non-abstract class. A module's
-  `select: { export, decorators, nameGlob, excludeClasses, excludeNameGlob, excludeAliases }`
-  narrows it; positive criteria must all hold and then `excludeClasses` (exact
-  names), `excludeNameGlob` (glob) and `excludeAliases` (tsconfig `paths` aliases
-  the file resolves through, e.g. `services` for `@services/*`) drop classes.
+  same program). One config file describes one bundle: `<name>.bundle.json`, or the same in
+  YAML as `<name>.bundle.yaml` / `.yml` (an empty YAML file = all defaults)
+  (schema: `tic.schema.json`), flat — `output`, `name`, `tags`, `extends`,
+  `importExtension`, `files`, `classes`, all optional. `tic build` works on
+  the package it is invoked in (nearest `package.json` up from the working
+  directory; never a workspace root): it builds every `*.bundle.{json,yaml,yml}` there
+  (or the ones named with repeatable `-c`), else — zero config — one bundle
+  from that package's `tsconfig.json` with every default. Each writes one class — `export class AppBundle implements IContainerModule`,
+  applied with `container.useModule(new AppBundle())`. Several bundles (e.g.
+  `production.bundle.json`, `development.bundle.json`) mean several configs.
+  `--check` writes nothing and exits 1 when an output is stale — run it in CI.
+- A config `extends` a tsconfig (default `./tsconfig.json`, may be absent; one
+  named explicitly must exist), like a child tsconfig: what it compiles is the
+  bundle's file set, and its `paths` aliases and module resolution shape the
+  generated imports (most specific alias, else a relative path). `output`
+  defaults to `<root>/<name>.bundle.ts`: root = tsconfig `rootDir`, else the
+  common folder of its files. `name` defaults to the config's stem
+  (`production.bundle.json` → `production`), else `base`; the class is
+  `toClassName(name)` — `ProductionBundle`, `BaseBundle`.
+- Selection has two stages. `files: { paths, include, exclude }` decides by path
+  which files are read and parsed at all. `paths` override the tsconfig's file
+  set with folders (relative to the config, or tsconfig aliases); required when
+  there is no tsconfig. A candidate must match one of `include` (default: all)
+  and none of `exclude` (default: test files, `__tests__/`, `node_modules/`; a
+  non-empty list replaces it, and the build warns if it drops a default). Globs
+  are relative to the config. With file naming conventions, `include` is the
+  speed lever — nothing else is read. Files `tic build` generated are never input.
+- `classes: { export, decorators, name, excludeClasses, excludeName }`
+  then picks classes of the parsed files; default is every exported,
+  non-abstract class decorated with `@register` (`decorators` defaults to
+  `["register"]`; `[]` requires none); positive criteria must all hold and then `excludeClasses` (exact
+  names) and `excludeName` (glob) drop classes.
   Decorators match by name, so composed ones must be listed. The build warns when
   two selected classes pass the same plain-identifier first decorator argument (a
   same-token heuristic), unless a decorator they share has differing arguments
   (scope-gated, e.g. `@perPage('a')` vs `@perPage('b')`).
 - Never edit a `*.bundle.ts` by hand — change the classes or the config and
   rerun `tic build`.
-- Files take part when they match no `exclude` glob **and** an
-  `InclusionPredicate` (`({ filename }) => boolean`, filename relative to the
-  config) returns true. The predicate comes from `build({ include })`, else the
-  bundle's `include` file, else a conventional `tic.include.*` next to the
-  config. Predicate files are `require`d once per process — read env vars
-  inside the predicate. README "Recipe: generate per environment" shows the
-  per-environment setup.
-- Right after parsing, an `ExportPredicate` (`FilterPredicate<ExportContext>`:
-  filename, exportName, className, isDefault, decorators, tags) filters class by
-  class, after `select`; found via `build({ filterExports })`, a bundle's
-  `filterExports` file, or `tic.exports.*` next to the config.
-- Prefer `byTags((tags, context) => ...)` (a `TagInclusionPredicate`) over parsing
-  file names: tags are the dot-parts between base name and extension
-  (`Report.production.eu.ts` → `['production', 'eu']`). Usage examples:
-  `__tests__/examples/inclusion-predicates.spec.ts`.
-- For a lean production build, the production entry must import only the
-  production bundle (README "One bundle per environment"); statically importing
-  both bundles ships both.
-- Programmatic API: `build({ config, cwd, check })`, `run(argv, io)`,
-  `loadConfig(file)`; errors are `TicConfigError` / `NamespaceNotFoundError`
+- Unknown config fields are errors, at every level.
+- Programmatic API: `build({ config, cwd, check })` (one config, one output),
+  `findConfigFiles(dir)`, `run(argv, io)`, `loadConfig(file)`; errors are `TicConfigError` / `NamespaceNotFoundError`
   (both `TicError`).

package/README.md

@@ -1,8 +1,8 @@
 # @ts-ioc-container/bundler
 
 **Bundles your dependencies into a single container module.** `tic build` scans
-your folders — by path or tsconfig alias — and generates one typed bundle that
-registers every class in them, ready for
+what your tsconfig compiles — or the folders you name, by path or tsconfig alias —
+and generates one typed bundle that registers every class in them, ready for
 [`ts-ioc-container`](https://www.npmjs.com/package/ts-ioc-container):
 
 ```ts
@@ -14,9 +14,8 @@ Adding a service means writing the class — no hand-maintained list of
 TypeScript, generated at build time, so it type-checks, bundles and tree-shakes
 like code you wrote yourself.
 
-In TypeScript a namespace is an import path, so folders are named the way
-imports are: relative to the config file (`./src/services`) or through a
-`tsconfig.json` `paths` alias (`@app/services`).
+A bundle is configured like a tsconfig that `extends` yours: by default it
+takes the files your tsconfig compiles, and narrows or overrides them.
 
 ## Install
 
@@ -30,347 +29,225 @@ below use the shortcut.
 
 `typescript` (>= 5) is a peer dependency.
 
-## Configure
+## Zero config
 
-`tic.config.json`, next to your `tsconfig.json`:
+With a `tsconfig.json`, there is nothing to configure:
 
-```json
-{
-  "$schema": "./node_modules/@ts-ioc-container/bundler/tic.schema.json",
-  "bundles": [
-    {
-      "output": "src/di/app.bundle.ts",
-      "name": "AppBundle",
-      "namespaces": ["@app/services", { "path": "./src/infra", "recursive": false }]
-    }
-  ]
-}
+```bash
+tic build
 ```
 
-| Field                        | Default                                   | Meaning                                                                                      |
-| ---------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `tsconfig`                   | `tsconfig.json` (may be absent)           | Source of `paths` aliases and of the import extension                                        |
-| `importExtension`            | `.js` under node16/nodenext, else none    | Extension of generated imports                                                               |
-| `bundles[].output`           | —                                         | The bundle file (convention: `*.bundle.ts`)                                                  |
-| `bundles[].name`             | `Bundle`                                  | Name of the generated class, an `IContainerModule`                                           |
-| `bundles[].namespaces`       | —                                         | Folders to scan; `{ path, recursive }` to stop at the folder itself                          |
-| `bundles[].select`           | every exported class                      | Which classes of a file are registered — see [Selecting classes](#selecting-classes)          |
-| `bundles[].exclude`          | test files, `__tests__/`, `node_modules/` | Globs (relative to the config) never scanned; replaces the default                           |
-| `bundles[].additionalExclude`| —                                         | Globs never scanned, added on top of `exclude` (or the defaults) — see [Excluding files](#excluding-files) |
-| `bundles[].filterExports`    | `tic.exports.*` next to the config        | File exporting an `ExportPredicate` — see [Filtering classes](#filtering-classes-after-parsing) |
-| `bundles[].include`          | `tic.include.*` next to the config        | File exporting an `InclusionPredicate` — see [Including files](#including-files-with-a-predicate) |
-
-## Excluding files
-
-By default test files, `__tests__/` and `node_modules/` are never scanned. To
-add one exclusion without restating those defaults, use `additionalExclude`:
-
-```json
-{
-  "bundles": [
-    {
-      "output": "src/di/app.bundle.ts",
-      "namespaces": ["@app/services"],
-      "additionalExclude": ["frontend/api/generated/**", "**/Mock*.ts"]
-    }
-  ]
-}
+```text
+wrote     src/base.bundle.ts (12 registrations)
 ```
 
-A non-empty `exclude` replaces the defaults; if it omits a default glob the
-build warns, since test classes usually carry the same `@register` decorators as
-production ones. `exclude: []` deliberately scans everything, including tests —
-combine it with `include` when only some tests should join.
+The bundle registers every exported class decorated with `@register` among the
+files your `tsconfig.json` compiles, test files excluded, and lands at the root
+of those sources — `rootDir`, else their common folder (`src/`), so `tsc`
+compiles it too. It exports `BaseBundle`:
 
-## Selecting classes
-
-By default every exported, non-abstract class of a scanned file is registered.
-`select` narrows that; a class must meet every criterion that is set:
+```ts
+import { BaseBundle } from './base.bundle';
 
-```json
-"select": {
-  "export": "named",
-  "decorators": ["register", "repository"],
-  "nameGlob": "*Service"
-}
+const container = new Container().useModule(new BaseBundle());
 ```
 
-| Criterion          | Default | Meaning                                                                                                     |
-| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------- |
-| `export`           | `any`   | `any`, `named` or `default` — which exports count                                                           |
-| `decorators`       | —       | The class must carry one of these, by name — also renamed imports and `@ioc.register()`; list composed ones |
-| `nameGlob`         | —       | Glob on the class name; an anonymous default export is named after its file (`user-service.ts` → `UserService`) |
-| `excludeClasses`   | —       | Class names to drop, e.g. `["MockDashboardRepository"]`                                                     |
-| `excludeNameGlob`  | —       | Glob the class name must **not** match, e.g. `"*Mock"`                                                      |
-| `excludeAliases`   | —       | tsconfig `paths` aliases to drop, e.g. `["services"]` for a `services/*` or `@services/*` alias             |
+`tic build` works on the package it is invoked in: it walks up from the working
+directory to the nearest `package.json` — the project root, or in a monorepo
+the package — and uses the `tsconfig.json` there. It never falls back to a
+workspace root's tsconfig.
 
-Abstract and non-exported classes are never registered.
-
-### Excluding a single class
+## Configure
 
-When a real implementation and a test-only stand-in are both decorated and both
-bind the same token, registration is last-wins and the stand-in silently wins. A
-`tic.exports.*` predicate works, but forces a hand-maintained name list in code;
-`excludeClasses` and `excludeNameGlob` drop a class right in the config:
+To change a default, add a config file next to your `tsconfig.json`. One config
+file describes one bundle and is named `<name>.bundle.json` — `app.bundle.json`:
 
 ```json
-"select": {
-  "decorators": ["repository", "service"],
-  "excludeClasses": ["MockDashboardRepository"],
-  "excludeNameGlob": "*Fake"
+{
+  "$schema": "./node_modules/@ts-ioc-container/bundler/tic.schema.json",
+  "output": "src/di/app.bundle.ts"
 }
 ```
 
-Both apply after every other criterion, so they can be combined with
-`decorators` and `nameGlob` freely. Reach for `filterExports` when the rule
-needs more than the class name.
-
-`excludeAliases` drops classes by the tsconfig `paths` alias their file resolves
-through — handy for excluding a whole namespace without naming its classes:
+or, in YAML, `<name>.bundle.yaml` / `<name>.bundle.yml` — same fields, same schema:
 
-```json
-"select": {
-  "excludeAliases": ["services"]
-}
+```yaml
+# yaml-language-server: $schema=./node_modules/@ts-ioc-container/bundler/tic.schema.json
+output: src/di/app.bundle.ts
+files:
+  include: ['**/*.service.ts']
 ```
 
-An entry matches a `paths` pattern such as `services/*` or `@services/*`; a
-leading `@` and a trailing `/*` may be omitted.
+An empty YAML file is a bundle with every setting at its default. Describing
+one bundle in two formats (`app.bundle.json` and `app.bundle.yaml`) is an error.
 
-As a safety net, the build warns when two selected classes pass the same
-plain-identifier first argument to a decorator — usually the binding token, as in
-`@repository(IDashboardRepositoryToken)`. The check is syntactic (aliased imports
-are not resolved), so it can only be a heuristic:
+Every field is optional; `{}` is the zero-config bundle.
 
-```text
-tic: warning: bundles[0]: decorator token "IDashboardRepositoryToken" is passed by
-HttpDashboardRepository, MockDashboardRepository; registration is last-wins,
-exclude one with select.excludeClasses
-```
+| Field             | Default                                | Meaning                                                                                       |
+| ----------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `output`          | `<root>/<name>.bundle.ts`              | The bundle file; `<root>` as in [Zero config](#zero-config). Required without a tsconfig     |
+| `name`            | the config's stem, else `base`         | The bundle's name (`production.bundle.json` → `production`): names the default output and the class, `ProductionBundle` |
+| `tags`            | `[]`                                   | Tags associated with the bundle                                                               |
+| `extends`         | `./tsconfig.json` (may be absent)      | The tsconfig to build on: its file set, `paths` aliases and import extension; one named here must exist |
+| `importExtension` | `.js` under node16/nodenext, else none | Extension of generated imports                                                                |
+| `files`           | what the tsconfig compiles, no tests   | Which files are parsed — see [Selecting files](#selecting-files)                              |
+| `classes`         | exported classes with `@register`      | Which classes of a parsed file are registered — see [Selecting classes](#selecting-classes)   |
 
-Classes that are scope-gated are not last-wins, so they do not warn: when the
-colliding classes share a decorator called with different arguments, e.g.
-`@perPage('stations')` vs `@perPage('sessions')`, each scope registers its own
-class and nothing is lost.
+An unknown field is an error, so a misspelled or removed option never goes
+unnoticed.
 
-## Including files with a predicate
+## Several bundles
 
-When globs aren't enough, decide in code which files take part:
+Need more than one bundle — per environment, per app? Add a config per bundle.
+`tic build` builds every `*.bundle.json`, `*.bundle.yaml` and `*.bundle.yml` at
+the package root:
 
-```ts
-type InclusionPredicate = (context: { filename: string }) => boolean;
+```text
+production.bundle.json    → src/di/production.bundle.ts
+development.bundle.json   → src/di/development.bundle.ts
+test.bundle.json          → src/di/test.bundle.ts
 ```
 
-`filename` is the path relative to the config file, `/`-separated
-(`src/services/Logger.ts`). A file takes part only when it matches no `exclude`
-glob **and** the predicate returns `true`.
-
-By convention there is nothing to configure: put a `tic.include.ts` (or `.cjs`,
-`.js`, `.mjs`, `.cts`, `.mts`) next to `tic.config.json` and its default export
-applies to every bundle.
+Each one can extend its own tsconfig and select its own files:
 
-```ts
-// tic.include.ts
-import type { InclusionPredicate } from '@ts-ioc-container/bundler';
-
-const include: InclusionPredicate = ({ filename }) => !filename.includes('/legacy/');
-export default include;
+```jsonc
+// production.bundle.json
+{
+  "extends": "./tsconfig.production.json",
+  "files": { "exclude": ["**/*.development.ts", "**/*.test.ts", "**/*.spec.ts", "**/__tests__/**", "**/node_modules/**"] }
+}
 ```
 
-| Where the predicate comes from       | Applies to    | Wins over                      |
-| ------------------------------------ | ------------- | ------------------------------ |
-| `build({ include })` (programmatic)  | every bundle  | everything                     |
-| `bundles[].include: "./path/file"`   | that bundle   | the conventional file          |
-| `tic.include.*` next to the config   | every bundle  | — (used when nothing is named) |
+It writes `src/production.bundle.ts`, exporting `ProductionBundle`.
 
-Predicate files are loaded synchronously with `require`: `.cjs` / `.js`
-everywhere, `.mjs` on Node 22.12+, `.ts` on Node versions that strip types
-(22.18+, 23.6+). Like any `require`d module a file is loaded **once per
-process**, so read environment variables inside the predicate, not at the top
-of the file.
+A bundle generated by one config is never registered by another, even when it
+sits in a folder the other scans.
 
-### Tags: `TagInclusionPredicate`
+## Selection in two stages
 
-A file's **tags** are the dot-separated parts of its name between the base name
-and the extension — `StripeGateway.production.ts` → `['production']`,
-`Report.production.eu.ts` → `['production', 'eu']`, `Shared.ts` → `[]`. Write
-a predicate over them and wrap it with `byTags`:
+A bundle picks its registrations in two stages:
 
-```ts
-type TagInclusionPredicate = (tags: string[], context: { filename: string }) => boolean;
-```
+1. **`files`** — decided by path alone, before anything is read. Only files that
+   pass are parsed.
+2. **`classes`** — decided per class, on the files stage 1 let through.
 
-```ts
-// tic.include.ts
-import { byTags } from '@ts-ioc-container/bundler';
+Parsing is where the time goes, so when your project names files by convention
+(`user.service.ts`, `user.repository.ts`), say so in `files.include` and the
+bundler never reads anything else:
 
-export default byTags((tags) => !tags.includes('manual')); // Scheduler.manual.ts is never generated
-```
-
-`byTags` returns an ordinary `InclusionPredicate`, so it goes anywhere one
-does. `fileTags(filename)` is exported too. More examples — folders, name
-conventions, environments, environment × region — run as tests in
-[`__tests__/examples/inclusion-predicates.spec.ts`](__tests__/examples/inclusion-predicates.spec.ts).
-
-## Filtering classes after parsing
-
-`include` decides on whole files before they are read. To decide class by
-class, right after a file is parsed, use an `ExportPredicate`. It runs on every
-exported, non-abstract class that passes `select`:
-
-```ts
-type FilterPredicate<Target> = (value: Target) => boolean;
-type ExportPredicate = FilterPredicate<ExportContext>;
-
-interface ExportContext {
-  filename: string;     // relative to the config: 'src/Mailer.ts'
-  exportName: string;   // 'default' for a default export
-  className: string;    // an anonymous default export is named after its file
-  isDefault: boolean;
-  decorators: string[]; // renamed imports resolved: `register as reg` -> 'register'
-  tags: string[];       // file-name tags, as byTags reads them
+```json
+{
+  "output": "src/di/app.bundle.ts",
+  "files": {
+    "paths": ["@app/services"],
+    "include": ["**/*.service.ts", "**/*.repository.ts"]
+  },
+  "classes": { "decorators": ["register"] }
 }
 ```
 
-```ts
-// tic.exports.ts, next to tic.config.json: picked up by convention
-import type { ExportPredicate } from '@ts-ioc-container/bundler';
-
-const filterExports: ExportPredicate = ({ exportName }) => !/(Stub|Mock|Fake)$/.test(exportName);
-export default filterExports;
-```
-
-It is found and loaded like an inclusion predicate: `build({ filterExports })`,
-else the bundle's `filterExports` file, else a `tic.exports.*` next to the
-config. Examples (test doubles sharing a file, decorator combinations, tags
-with class names) run as tests in
-[`__tests__/examples/inclusion-predicates.spec.ts`](__tests__/examples/inclusion-predicates.spec.ts).
-
-## Recipe: generate per environment
-
-Keep environment-specific implementations side by side, named by convention:
-`*.production.ts` joins only production, `*.development.ts` only development,
-and every other file is shared.
-
-```text
-src/services/
-├── Shared.ts                        → every environment
-├── StripeGateway.production.ts      → production only
-└── FakeGateway.development.ts       → development only
-```
-
-One helper turns the convention into a predicate — the environment tags a file
-carries must all be the wanted one, and a file without any is shared:
+## Selecting files
 
-```js
-// tic/for-env.cjs
-const { byTags } = require('@ts-ioc-container/bundler');
-const ENVS = ['development', 'production', 'test'];
+The candidates are the files the extended tsconfig compiles (its `files` /
+`include` / `exclude`, following its own `extends`). `paths` overrides that set
+the way a child tsconfig's `include` overrides its parent's: the bundle then scans
+those folders instead — relative to the config file (`./src/services`) or tsconfig
+`paths` aliases (`@app/services`), recursively unless an entry says
+`{ "path": "...", "recursive": false }`. Without a tsconfig, `paths` is required.
 
-module.exports = (env) => byTags((tags) => tags.filter((tag) => ENVS.includes(tag)).every((tag) => tag === env));
-```
+A candidate is parsed when it matches **one of** `include` and **none of**
+`exclude`. Globs are relative to the config file and `/`-separated; `**` spans
+folders.
 
-### A. One bundle per environment (recommended)
+| Rule      | Default                                   | Meaning                                                    |
+| --------- | ----------------------------------------- | ---------------------------------------------------------- |
+| `paths`   | what the tsconfig compiles                | Folders to scan instead                                    |
+| `include` | every source file                         | Globs a file must match one of, e.g. `"**/*.service.ts"`   |
+| `exclude` | test files, `__tests__/`, `node_modules/` | Globs of files never read; replaces the default when given |
 
-Every environment gets its own bundle, and both are committed. The files don't
-depend on who ran `tic build`, so `tic build --check` stays stable in CI.
+A non-empty `exclude` replaces the defaults, so restate the ones you still want:
 
 ```json
-{
-  "bundles": [
-    {
-      "output": "src/di/app.production.bundle.ts",
-      "name": "AppBundle",
-      "namespaces": ["@app/services"],
-      "include": "./tic/production.cjs"
-    },
-    {
-      "output": "src/di/app.development.bundle.ts",
-      "name": "AppBundle",
-      "namespaces": ["@app/services"],
-      "include": "./tic/development.cjs"
-    }
+"files": {
+  "exclude": [
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    "**/*.spec.tsx",
+    "**/*.test.tsx",
+    "**/__tests__/**",
+    "**/node_modules/**",
+    "frontend/api/generated/**"
   ]
 }
 ```
 
-```js
-// tic/production.cjs
-module.exports = require('./for-env.cjs')('production');
-// tic/development.cjs
-module.exports = require('./for-env.cjs')('development');
-```
-
-To keep development code out of the production build, the production entry
-point must import **only** the production bundle — a bundler includes what is
-imported, and a registration keeps its class alive, so nothing can be dropped
-after the fact. Give each environment its own entry:
+If it omits a default glob the build warns, since test classes usually carry
+the same `@register` decorators as production ones. `"exclude": []` deliberately
+parses everything, including tests. Giving only `include` keeps the default
+`exclude`, so `**/*.service.ts` still skips `user.service.spec.ts`.
 
-```ts
-// src/main.production.ts — production build entry
-import { Container } from 'ts-ioc-container';
-import { AppBundle } from './di/app.production.bundle';
-
-export const container = new Container().useModule(new AppBundle());
-```
+## Selecting classes
 
-```ts
-// src/main.development.ts — development entry
-import { Container } from 'ts-ioc-container';
-import { AppBundle } from './di/app.development.bundle';
+By default every exported, non-abstract class of a parsed file that carries
+`@register` is registered. `classes` changes that; a class must meet every
+criterion that is set:
 
-export const container = new Container().useModule(new AppBundle());
+```json
+"classes": {
+  "export": "named",
+  "decorators": ["register", "repository"],
+  "name": "*Service"
+}
 ```
 
-With a single entry, pick the bundle with a dynamic `import()`: the bundler
-splits each into its own chunk and only the chosen one is loaded — the other
-chunk is still emitted, just never fetched.
-
-```ts
-const { AppBundle } =
-  process.env.NODE_ENV === 'production'
-    ? await import('./di/app.production.bundle')
-    : await import('./di/app.development.bundle');
-```
+| Criterion          | Default | Meaning                                                                                                     |
+| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `export`           | `any`   | `any`, `named` or `default` — which exports count                                                           |
+| `decorators`       | `["register"]` | The class must carry one of these, by name — also renamed imports and `@ioc.register()`; list composed ones. `[]` requires none |
+| `name`         | —       | Glob the class name must match, e.g. `"*Service"`; an anonymous default export is named after its file (`user-service.ts` → `UserService`) |
+| `excludeClasses`   | —       | Class names to drop, e.g. `["MockDashboardRepository"]`                                                     |
+| `excludeName`  | —       | Glob the class name must **not** match, e.g. `"*Mock"`                                                      |
 
-| How the app picks the bundle                                     | Development classes in the production build |
-| ---------------------------------------------------------------- | ------------------------------------------- |
-| One entry per environment, importing its own bundle              | ✅ none                                     |
-| Recipe B below — only the production bundle exists at build time | ✅ none                                     |
-| Dynamic `import()` of the bundle                                 | ⚠️ emitted as a separate chunk, never loaded |
-| Static imports of both bundles plus a runtime condition          | ❌ both bundles, in full                    |
+Abstract and non-exported classes are never registered.
 
-Don't rely on the bundler dropping a statically imported bundle behind
-`process.env.NODE_ENV === 'production'`: the classes it imports run decorators
-at load time, which bundlers treat as side effects and keep.
+### Excluding a single class
 
-### B. One output, environment chosen when `tic build` runs
+When a real implementation and a test-only stand-in are both decorated and both
+bind the same token, registration is last-wins and the stand-in silently wins.
+`excludeClasses` and `excludeName` drop a class right in the config:
 
-The smallest production build: only the production bundle ever exists while it
-is built. For pipelines that generate at deploy time instead of committing the
-output:
+```json
+"classes": {
+  "decorators": ["repository", "service"],
+  "excludeClasses": ["MockDashboardRepository"],
+  "excludeName": "*Fake"
+}
+```
 
-```js
-// tic.include.cjs — picked up by convention
-const forEnv = require('./tic/for-env.cjs');
+Both apply after every other criterion, so they can be combined with
+`decorators` and `name` freely.
 
-// Read TIC_ENV per call: the file is loaded once per process.
-module.exports = (context) => forEnv(process.env.TIC_ENV ?? 'development')(context);
-```
+As a safety net, the build warns when two selected classes pass the same
+plain-identifier first argument to a decorator — usually the binding token, as in
+`@repository(IDashboardRepositoryToken)`. The check is syntactic (aliased imports
+are not resolved), so it can only be a heuristic:
 
-```bash
-TIC_ENV=production tic build
+```text
+tic: warning: app.bundle.json: decorator token "IDashboardRepositoryToken" is passed by
+HttpDashboardRepository, MockDashboardRepository; registration is last-wins,
+exclude one with classes.excludeClasses
 ```
 
-The output now depends on `TIC_ENV`. Either don't commit it (generate it in
-every pipeline), or run `tic build --check` with the same `TIC_ENV` it was
-generated with.
+Classes that are scope-gated are not last-wins, so they do not warn: when the
+colliding classes share a decorator called with different arguments, e.g.
+`@perPage('stations')` vs `@perPage('sessions')`, each scope registers its own
+class and nothing is lost.
 
 ## Build
 
 ```bash
-tic build                 # tic.config.json in the working directory
-tic build -c path/to/tic.config.json
+tic build                 # every *.bundle.{json,yaml,yml} of this package, else its tsconfig.json
+tic build -c app.bundle.json -c admin/admin.bundle.json   # only these
 tic build --check         # CI: write nothing, exit 1 if a bundle is out of date
 ```
 
@@ -378,8 +255,8 @@ The output is plain TypeScript over the public `ts-ioc-container` API:
 
 ```ts
 // src/di/app.bundle.ts
-// Generated by `tic build` from ../../tic.config.json. Do not edit by hand.
-// Namespaces: @app/services, @app/infra
+// Generated by `tic build` from ../../app.bundle.json. Do not edit by hand.
+// Paths: @app/services, @app/infra
 import { type IContainer, type IContainerModule, type IRegistration, Registration } from 'ts-ioc-container';
 import { MemoryLogger } from '@app/infra/logging/MemoryLogger';
 import { Greeter } from '@app/services/Greeter';