@ts-ioc-container/bundler 1.0.0 → 1.2.0

package/AGENTS.md

@@ -13,8 +13,11 @@ it.
 - 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 }` narrows it; a class must meet every
-  criterion set. Decorators match by name, so composed ones must be listed.
+  `select: { export, decorators, nameGlob, excludeClasses, excludeNameGlob }`
+  narrows it; positive criteria must all hold and then `excludeClasses` (exact
+  names) and `excludeNameGlob` (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).
 - 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

package/README.md

@@ -56,9 +56,32 @@ below use the shortcut.
 | `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"]
+    }
+  ]
+}
+```
+
+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.
+
 ## Selecting classes
 
 By default every exported, non-abstract class of a scanned file is registered.
@@ -72,14 +95,46 @@ By default every exported, non-abstract class of a scanned file is registered.
 }
 ```
 
-| 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`) |
+| 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"`                                                      |
 
 Abstract and non-exported classes are never registered.
 
+### Excluding a single class
+
+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:
+
+```json
+"select": {
+  "decorators": ["repository", "service"],
+  "excludeClasses": ["MockDashboardRepository"],
+  "excludeNameGlob": "*Fake"
+}
+```
+
+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.
+
+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:
+
+```text
+tic: warning: bundles[0]: decorator token "IDashboardRepositoryToken" is passed by
+HttpDashboardRepository, MockDashboardRepository; registration is last-wins,
+exclude one with select.excludeClasses
+```
+
 ## Including files with a predicate
 
 When globs aren't enough, decide in code which files take part:

package/cjm/build.js

@@ -28,7 +28,10 @@ function build({ config = config_1.DEFAULT_CONFIG_FILE, cwd = process.cwd(), che
         fileOf: (bundle) => bundle.filterExports,
         load: exportPredicate_1.loadExportPredicate,
     });
-    const generated = resolved.bundles.map((bundle) => generate(resolved, bundle, paths, { include: includeFor(bundle), filterExports: filterExportsFor(bundle) }));
+    const generated = resolved.bundles.map((bundle, i) => generate(resolved, bundle, `bundles[${i}]`, paths, {
+        include: includeFor(bundle),
+        filterExports: filterExportsFor(bundle),
+    }));
     const outputs = generated.map(({ bundle, content, registrations }) => {
         const current = (0, node_fs_1.existsSync)(bundle.output) ? (0, node_fs_1.readFileSync)(bundle.output, 'utf8') : undefined;
         const status = current === content ? 'unchanged' : check ? 'stale' : 'written';
@@ -38,7 +41,11 @@ function build({ config = config_1.DEFAULT_CONFIG_FILE, cwd = process.cwd(), che
         }
         return { file: bundle.output, bundle: bundle.name, status, registrations, content };
     });
-    return { config: resolved.file, outputs };
+    return {
+        config: resolved.file,
+        outputs,
+        warnings: [...resolved.warnings, ...generated.flatMap((g) => g.warnings)],
+    };
 }
 function predicateResolver({ override, conventional, fileOf, load, }) {
     const loaded = new Map();
@@ -53,7 +60,7 @@ function predicateResolver({ override, conventional, fileOf, load, }) {
         return loaded.get(file);
     };
 }
-function generate(config, bundle, paths, { include, filterExports }) {
+function generate(config, bundle, field, paths, { include, filterExports }) {
     const relative = (file) => (0, glob_1.toPosix)(node_path_1.default.relative(config.dir, file));
     const outputs = new Set(config.bundles.map((m) => m.output));
     const excludes = bundle.exclude.map(glob_1.globToRegExp);
@@ -86,5 +93,21 @@ function generate(config, bundle, paths, { include, filterExports }) {
         namespaces: bundle.namespaces.map((ns) => ns.path),
         classes,
     });
-    return { bundle, content, registrations: classes.length };
+    return { bundle, content, registrations: classes.length, warnings: tokenCollisions(classes, field) };
+}
+function tokenCollisions(classes, field) {
+    const owners = new Map();
+    for (const { className, tokens } of classes) {
+        for (const token of tokens) {
+            const names = owners.get(token) ?? [];
+            if (!names.includes(className))
+                names.push(className);
+            owners.set(token, names);
+        }
+    }
+    return [...owners]
+        .filter(([, names]) => names.length > 1)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([token, names]) => `${field}: decorator token "${token}" is passed by ${names.join(', ')}; ` +
+        `registration is last-wins, exclude one with select.excludeClasses`);
 }

package/cjm/cli.js

@@ -62,7 +62,9 @@ function run(argv, io = { cwd: process.cwd(), stdout: console.log, stderr: conso
             return 1;
         }
         const { config, check } = parseBuildArgs(rest);
-        const { outputs } = (0, build_1.build)({ config, check, cwd: io.cwd });
+        const { outputs, warnings } = (0, build_1.build)({ config, check, cwd: io.cwd });
+        for (const warning of warnings)
+            io.stderr(`tic: warning: ${warning}`);
         for (const { status, file, registrations } of outputs) {
             io.stdout(`${VERB[status].padEnd(10)}${node_path_1.default.relative(io.cwd, file)} (${plural(registrations)})`);
         }

package/cjm/config.js

@@ -38,7 +38,7 @@ function toNamespace(value, field) {
         return fail(`${field}.recursive`, 'a boolean');
     return { path: value.path, recursive: value.recursive ?? true };
 }
-const SELECTOR_FIELDS = new Set(['export', 'decorators', 'nameGlob']);
+const SELECTOR_FIELDS = new Set(['export', 'decorators', 'nameGlob', 'excludeClasses', 'excludeNameGlob']);
 function toSelector(value, field) {
     if (value === undefined)
         return { export: 'any' };
@@ -47,7 +47,7 @@ function toSelector(value, field) {
     const unknown = Object.keys(value).find((key) => !SELECTOR_FIELDS.has(key));
     if (unknown)
         throw new errors_1.TicConfigError(`${field}.${unknown}: unknown field`);
-    const { export: kind, decorators, nameGlob } = value;
+    const { export: kind, decorators, nameGlob, excludeClasses, excludeNameGlob } = value;
     if (kind !== undefined && kind !== 'any' && kind !== 'named' && kind !== 'default') {
         return fail(`${field}.export`, '"any", "named" or "default"');
     }
@@ -56,12 +56,24 @@ function toSelector(value, field) {
     }
     if (nameGlob !== undefined && !isNonEmptyString(nameGlob))
         return fail(`${field}.nameGlob`, 'a non-empty string');
-    return { export: kind ?? 'any', decorators, nameGlob: nameGlob === undefined ? undefined : (0, glob_1.globToRegExp)(nameGlob) };
+    if (excludeClasses !== undefined && !(isStringArray(excludeClasses) && excludeClasses.length > 0)) {
+        return fail(`${field}.excludeClasses`, 'a non-empty array of strings');
+    }
+    if (excludeNameGlob !== undefined && !isNonEmptyString(excludeNameGlob)) {
+        return fail(`${field}.excludeNameGlob`, 'a non-empty string');
+    }
+    return {
+        export: kind ?? 'any',
+        decorators,
+        nameGlob: nameGlob === undefined ? undefined : (0, glob_1.globToRegExp)(nameGlob),
+        excludeClasses,
+        excludeNameGlob: excludeNameGlob === undefined ? undefined : (0, glob_1.globToRegExp)(excludeNameGlob),
+    };
 }
 function toBundle(value, field, dir) {
     if (!isObject(value))
         return fail(field, 'an object');
-    const { output, name, namespaces, select, exclude, include, filterExports } = value;
+    const { output, name, namespaces, select, exclude, additionalExclude, include, filterExports } = value;
     if (!isNonEmptyString(output))
         return fail(`${field}.output`, 'a non-empty string');
     if (name !== undefined && !isIdentifier(name))
@@ -70,6 +82,9 @@ function toBundle(value, field, dir) {
         return fail(`${field}.namespaces`, 'a non-empty array');
     if (exclude !== undefined && !isStringArray(exclude))
         return fail(`${field}.exclude`, 'an array of strings');
+    if (additionalExclude !== undefined && !isStringArray(additionalExclude)) {
+        return fail(`${field}.additionalExclude`, 'an array of strings');
+    }
     if (include !== undefined && !isNonEmptyString(include))
         return fail(`${field}.include`, 'a non-empty string');
     if (filterExports !== undefined && !isNonEmptyString(filterExports)) {
@@ -80,11 +95,25 @@ function toBundle(value, field, dir) {
         name: name ?? exports.DEFAULT_BUNDLE_NAME,
         namespaces: namespaces.map((ns, i) => toNamespace(ns, `${field}.namespaces[${i}]`)),
         select: toSelector(select, `${field}.select`),
-        exclude: exclude ?? exports.DEFAULT_EXCLUDE,
+        exclude: [...(exclude ?? exports.DEFAULT_EXCLUDE), ...(additionalExclude ?? [])],
         include: include === undefined ? undefined : node_path_1.default.resolve(dir, include),
         filterExports: filterExports === undefined ? undefined : node_path_1.default.resolve(dir, filterExports),
     };
 }
+function excludeWarnings(value, field) {
+    if (!isObject(value))
+        return [];
+    const exclude = value.exclude;
+    if (!isStringArray(exclude) || exclude.length === 0)
+        return [];
+    const missing = exports.DEFAULT_EXCLUDE.filter((glob) => !exclude.includes(glob));
+    if (missing.length === 0)
+        return [];
+    return [
+        `${field}.exclude replaces the default excludes and omits ${missing.map((glob) => `"${glob}"`).join(', ')}; ` +
+            `add them back or use ${field}.additionalExclude`,
+    ];
+}
 function resolveConfig(content, file) {
     const dir = node_path_1.default.dirname(file);
     if (!isObject(content))
@@ -102,6 +131,7 @@ function resolveConfig(content, file) {
         tsconfig: { file: node_path_1.default.resolve(dir, tsconfig ?? 'tsconfig.json'), required: tsconfig !== undefined },
         importExtension,
         bundles: bundles.map((m, i) => toBundle(m, `bundles[${i}]`, dir)),
+        warnings: bundles.flatMap((m, i) => excludeWarnings(m, `bundles[${i}]`)),
     };
 }
 function loadConfig(file) {

package/cjm/scan.js

@@ -114,6 +114,10 @@ function findClasses(file, selector, text = (0, node_fs_1.readFileSync)(file, 'u
         }
     }
     const decoratorsOf = (node) => (ts.getDecorators(node) ?? []).map((d) => decoratorName(d, imports)).filter((n) => !!n);
+    const tokensOf = (node) => (ts.getDecorators(node) ?? [])
+        .map((d) => (ts.isCallExpression(d.expression) ? d.expression.arguments[0] : undefined))
+        .filter((arg) => !!arg && ts.isIdentifier(arg))
+        .map((arg) => arg.text);
     return exported
         .map(({ node, local, exportName }) => ({ node: node ?? (local ? classes.get(local) : undefined), exportName }))
         .filter((e) => !!e.node)
@@ -122,6 +126,7 @@ function findClasses(file, selector, text = (0, node_fs_1.readFileSync)(file, 'u
         exportName,
         className: node.name?.text ?? nameFromFile(file),
         decorators: decoratorsOf(node),
+        tokens: tokensOf(node),
     }))
         .filter(({ node, exportName, className, decorators }) => {
         if (hasModifier(node, ts.SyntaxKind.AbstractKeyword))
@@ -130,15 +135,22 @@ function findClasses(file, selector, text = (0, node_fs_1.readFileSync)(file, 'u
             return false;
         if (selector.decorators && !selector.decorators.some((name) => decorators.includes(name)))
             return false;
-        return !selector.nameGlob || selector.nameGlob.test(className);
+        if (selector.nameGlob && !selector.nameGlob.test(className))
+            return false;
+        if (selector.excludeClasses?.includes(className))
+            return false;
+        if (selector.excludeNameGlob?.test(className))
+            return false;
+        return true;
     })
         .sort((a, b) => a.node.pos - b.node.pos)
-        .map(({ exportName, className, decorators }) => ({
+        .map(({ exportName, className, decorators, tokens }) => ({
         file,
         exportName,
         localName: exportName === 'default' ? className : exportName,
         className,
         isDefault: exportName === 'default',
         decorators,
+        tokens,
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-ioc-container/bundler",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Bundles your dependencies into a single container module for ts-ioc-container: the `tic` CLI scans folders (by path or tsconfig alias) and generates one typed bundle that registers every class — `container.useModule(new AppBundle())`.",
   "publishConfig": {
     "access": "public",

package/tic.schema.json

@@ -99,6 +99,20 @@
                 "type": "string",
                 "minLength": 1,
                 "description": "Glob the class name must match, e.g. \"*Service\". An anonymous default export is named after its file."
+              },
+              "excludeClasses": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "Class names to drop after selection, e.g. one test double sitting next to the real registration in the same file."
+              },
+              "excludeNameGlob": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Glob the class name must NOT match, e.g. \"*Mock\". An anonymous default export is named after its file."
               }
             }
           },
@@ -115,7 +129,14 @@
               "**/__tests__/**",
               "**/node_modules/**"
             ],
-            "description": "Globs, relative to this file, of files never scanned. Replaces the default when given."
+            "description": "Globs, relative to this file, of files never scanned. Replaces the default when given; prefer additionalExclude to add one exclusion without restating the defaults. A non-empty list that omits a default glob makes `tic build` warn."
+          },
+          "additionalExclude": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Globs, relative to this file, of files never scanned, added on top of `exclude` (or the default excludes when `exclude` is omitted)."
           },
           "include": {
             "type": "string",

package/typings/build.d.ts

@@ -27,6 +27,12 @@ export interface BuildResult {
     /** Absolute path of the config that was built. */
     config: string;
     outputs: OutputResult[];
+    /**
+     * Non-fatal problems found while building, e.g. an `exclude` that drops a default
+     * test glob or two selected classes passing the same decorator token. Each warning
+     * names the bundle field it belongs to.
+     */
+    warnings: string[];
 }
 /**
  * Generates one bundle per config entry. Every bundle is generated before any

package/typings/config.d.ts

@@ -12,12 +12,21 @@ export interface ClassSelector {
     decorators?: string[];
     /** A glob the class name must match, e.g. `*Service`. An anonymous default export is named after its file. */
     nameGlob?: string;
+    /**
+     * Class names to drop after selection, e.g. one test double sitting next to the
+     * real registration in the same file. Unlike `filterExports` this needs no file.
+     */
+    excludeClasses?: string[];
+    /** A glob the class name must NOT match, e.g. `*Mock`. An anonymous default export is named after its file. */
+    excludeNameGlob?: string;
 }
-/** A {@link ClassSelector} with its defaults filled in and its `nameGlob` compiled. */
+/** A {@link ClassSelector} with its defaults filled in and its globs compiled. */
 export interface ResolvedSelector {
     export: ExportKind;
     decorators?: string[];
     nameGlob?: RegExp;
+    excludeClasses?: string[];
+    excludeNameGlob?: RegExp;
 }
 export interface NamespaceConfig {
     /** A folder relative to the config file (`./src/services`) or a tsconfig `paths` alias (`@app/services`). */
@@ -35,6 +44,12 @@ export interface BundleConfig {
     select?: ClassSelector;
     /** Globs, relative to the config file, of files never scanned. Replaces {@link DEFAULT_EXCLUDE} when given. */
     exclude?: string[];
+    /**
+     * Globs, relative to the config file, of files never scanned, added on top of
+     * `exclude` (or {@link DEFAULT_EXCLUDE} when `exclude` is omitted). Use this to
+     * add one exclusion without restating the defaults.
+     */
+    additionalExclude?: string[];
     /**
      * A file exporting an `InclusionPredicate`, relative to the config file. Overrides the
      * conventional `tic.include.*` next to the config.
@@ -68,12 +83,15 @@ export interface ResolvedConfig {
     };
     importExtension?: string;
     bundles: ResolvedBundle[];
+    /** Non-fatal problems found while resolving, e.g. an `exclude` that drops a default test glob. */
+    warnings: string[];
 }
 export interface ResolvedBundle {
     output: string;
     name: string;
     namespaces: Required<NamespaceConfig>[];
     select: ResolvedSelector;
+    /** The effective list: the configured `exclude` (or the defaults) followed by `additionalExclude`. */
     exclude: string[];
     /** Absolute path of the bundle's own predicate file, when it names one. */
     include?: string;

package/typings/scan.d.ts

@@ -11,6 +11,12 @@ export interface DiscoveredClass {
     isDefault: boolean;
     /** Names of the class's decorators, renamed imports resolved. */
     decorators: string[];
+    /**
+     * Plain-identifier first arguments of the class's decorators, e.g. the token in
+     * `@repository(Token)`; an empty array when a decorator takes none. Syntax only:
+     * used to warn when two classes pass the same identifier.
+     */
+    tokens: string[];
 }
 /** Source files of `dir`, sorted by path so the generated output is stable across machines. */
 export declare function listSourceFiles(dir: string, recursive: boolean, isExcluded: (file: string) => boolean): string[];