@ts-ioc-container/bundler 1.5.0 → 2.1.0

package/AGENTS.md

@@ -7,40 +7,56 @@ 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`
-  (both `TicError`).
+- 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)`; every error the
+  bundler raises on purpose is a `TicError` with a stable `code`
+  (`TicConfigError` = `INVALID_CONFIG`, `NamespaceNotFoundError`, `UsageError`,
+  `StaleBundlesError`, …).
+- Internals follow `release-monorepo-semantically` (ADR 0023): `createContainer(io)`
+  in `lib/app.ts` is the composition root; `Application` resolves the controller
+  registered under the command name (`@register('build')`) and runs its
+  `@onDefault(invoke)` action, which parses its own options with
+  `@inject(pipe(commandArgs, parseOptions(spec), validate(SCHEMA)))`. Work lives in
+  services behind tokens (`IBundleBuilderKey`, `ITicConfigServiceKey`, …); pure
+  logic in `lib/features/build/domain/`. A new command is a controller plus a module.
+- The config schema is `BUNDLE_CONFIG_SCHEMA` (zod); `tic.schema.json` is generated
+  from it with `pnpm run generate:schema` — never edit it by hand.