@ts-ioc-container/bundler 1.1.0 → 1.3.0

package/AGENTS.md

@@ -13,8 +13,14 @@ 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, 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.
+  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

package/README.md

@@ -95,14 +95,64 @@ 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"`                                                      |
+| `excludeAliases`   | —       | tsconfig `paths` aliases to drop, e.g. `["services"]` for a `services/*` or `@services/*` alias             |
 
 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.
+
+`excludeAliases` drops classes by the tsconfig `paths` alias their file resolves
+through — handy for excluding a whole namespace without naming its classes:
+
+```json
+"select": {
+  "excludeAliases": ["services"]
+}
+```
+
+An entry matches a `paths` pattern such as `services/*` or `@services/*`; a
+leading `@` and a trailing `/*` may be omitted.
+
+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
+```
+
+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.
+
 ## Including files with a predicate
 
 When globs aren't enough, decide in code which files take part:

package/cjm/ImportPaths.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ImportPaths = void 0;
+exports.normalizeAliasName = normalizeAliasName;
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 const ts = __importStar(require("typescript"));
@@ -92,6 +93,19 @@ class ImportPaths {
     specifier(fromFile, toFile) {
         const target = (0, glob_1.toPosix)(toFile);
         const bare = target.replace(SOURCE_EXTENSION, '');
+        const best = this.bestAlias(target, bare);
+        if (best)
+            return best.spec;
+        const relative = (0, glob_1.toPosix)(node_path_1.default.relative(node_path_1.default.dirname(fromFile), bare));
+        return `${relative.startsWith('.') ? relative : `./${relative}`}${this.extension}`;
+    }
+    aliasName(file) {
+        const target = (0, glob_1.toPosix)(file);
+        const bare = target.replace(SOURCE_EXTENSION, '');
+        const best = this.bestAlias(target, bare);
+        return best && normalizeAliasName(best.pattern);
+    }
+    bestAlias(target, bare) {
         let best;
         for (const { pattern, targets } of this.aliases) {
             for (const aliasTarget of targets) {
@@ -100,10 +114,7 @@ class ImportPaths {
                     best = match;
             }
         }
-        if (best)
-            return best.spec;
-        const relative = (0, glob_1.toPosix)(node_path_1.default.relative(node_path_1.default.dirname(fromFile), bare));
-        return `${relative.startsWith('.') ? relative : `./${relative}`}${this.extension}`;
+        return best;
     }
     aliasTargets(spec) {
         return this.aliases.flatMap(({ pattern, targets }) => {
@@ -121,14 +132,17 @@ class ImportPaths {
         const wildcard = splitWildcard(aliasTarget);
         if (!wildcard) {
             const exact = aliasTarget === file || aliasTarget.replace(SOURCE_EXTENSION, '') === bare;
-            return exact && !splitWildcard(pattern) ? { spec: pattern, score: Infinity } : undefined;
+            return exact && !splitWildcard(pattern) ? { spec: pattern, score: Infinity, pattern } : 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 };
+        return { spec: `${pattern.replace('*', captured)}${this.extension}`, score: prefix.length, pattern };
     }
 }
 exports.ImportPaths = ImportPaths;
+function normalizeAliasName(pattern) {
+    return pattern.replace(/^@/, '').replace(/\/?\*$/, '');
+}

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, warnings: resolved.warnings };
+    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);
@@ -69,10 +76,19 @@ function generate(config, bundle, paths, { include, filterExports }) {
         for (const file of (0, scan_1.listSourceFiles)(dir, namespace.recursive, isExcluded))
             files.add(file);
     }
+    const excludedAliases = new Set((bundle.select.excludeAliases ?? []).map(ImportPaths_1.normalizeAliasName));
+    const isAliasExcluded = (file) => {
+        if (excludedAliases.size === 0)
+            return false;
+        const alias = paths.aliasName(file);
+        return alias !== undefined && excludedAliases.has(alias);
+    };
     const classes = [...files]
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
         .flatMap((file) => (0, scan_1.findClasses)(file, bundle.select))
         .filter((cls) => {
+        if (isAliasExcluded(cls.file))
+            return false;
         if (!filterExports)
             return true;
         const filename = relative(cls.file);
@@ -86,5 +102,31 @@ 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 cls of classes) {
+        for (const token of cls.tokens) {
+            const group = owners.get(token) ?? [];
+            if (!group.some((owner) => owner.className === cls.className))
+                group.push(cls);
+            owners.set(token, group);
+        }
+    }
+    return [...owners]
+        .filter(([, group]) => group.length > 1 && !scopeDisjoint(group))
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([token, group]) => {
+        const names = group.map((cls) => cls.className);
+        return (`${field}: decorator token "${token}" is passed by ${names.join(', ')}; ` +
+            `registration is last-wins, exclude one with select.excludeClasses`);
+    });
+}
+function scopeDisjoint(group) {
+    const [first, ...rest] = group;
+    return first.decoratorCalls.some(({ name, args }) => rest.every((cls) => {
+        const same = cls.decoratorCalls.find((call) => call.name === name);
+        return same !== undefined && same.args.join('\u0000') !== args.join('\u0000');
+    }));
 }

package/cjm/config.js

@@ -38,7 +38,14 @@ 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',
+    'excludeAliases',
+]);
 function toSelector(value, field) {
     if (value === undefined)
         return { export: 'any' };
@@ -47,7 +54,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, excludeAliases } = value;
     if (kind !== undefined && kind !== 'any' && kind !== 'named' && kind !== 'default') {
         return fail(`${field}.export`, '"any", "named" or "default"');
     }
@@ -56,7 +63,23 @@ 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');
+    }
+    if (excludeAliases !== undefined && !(isStringArray(excludeAliases) && excludeAliases.length > 0)) {
+        return fail(`${field}.excludeAliases`, 'a non-empty array of strings');
+    }
+    return {
+        export: kind ?? 'any',
+        decorators,
+        nameGlob: nameGlob === undefined ? undefined : (0, glob_1.globToRegExp)(nameGlob),
+        excludeClasses,
+        excludeNameGlob: excludeNameGlob === undefined ? undefined : (0, glob_1.globToRegExp)(excludeNameGlob),
+        excludeAliases,
+    };
 }
 function toBundle(value, field, dir) {
     if (!isObject(value))

package/cjm/scan.js

@@ -114,6 +114,17 @@ 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 decoratorCallsOf = (node) => (ts.getDecorators(node) ?? []).flatMap((d) => {
+        const name = decoratorName(d, imports);
+        if (!name)
+            return [];
+        const args = ts.isCallExpression(d.expression) ? d.expression.arguments.map((arg) => arg.getText(source)) : [];
+        return [{ name, args }];
+    });
+    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 +133,8 @@ function findClasses(file, selector, text = (0, node_fs_1.readFileSync)(file, 'u
         exportName,
         className: node.name?.text ?? nameFromFile(file),
         decorators: decoratorsOf(node),
+        decoratorCalls: decoratorCallsOf(node),
+        tokens: tokensOf(node),
     }))
         .filter(({ node, exportName, className, decorators }) => {
         if (hasModifier(node, ts.SyntaxKind.AbstractKeyword))
@@ -130,15 +143,23 @@ 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, decoratorCalls, tokens }) => ({
         file,
         exportName,
         localName: exportName === 'default' ? className : exportName,
         className,
         isDefault: exportName === 'default',
         decorators,
+        decoratorCalls,
+        tokens,
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-ioc-container/bundler",
-  "version": "1.1.0",
+  "version": "1.3.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,29 @@
                 "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."
+              },
+              "excludeAliases": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "tsconfig paths aliases to drop after selection, e.g. [\"services\"] for a `services/*` (or `@services/*`) alias. A class whose file resolves through one of these aliases is dropped. Names may omit a leading `@` and a trailing `/*`."
               }
             }
           },

package/typings/ImportPaths.d.ts

@@ -29,9 +29,18 @@ export declare class ImportPaths {
     resolveNamespace(namespace: string, baseDir: string): string;
     /** The specifier `fromFile` imports `toFile` by: its most specific alias, else a relative path. */
     specifier(fromFile: string, toFile: string): string;
+    /**
+     * The tsconfig `paths` alias `file` is covered by, normalized to its name
+     * (`@app/services/*` -> `app/services`), or `undefined` when no alias covers it.
+     * Used to drop classes by alias (`select.excludeAliases`).
+     */
+    aliasName(file: string): string | undefined;
+    private bestAlias;
     private aliasTargets;
     /** A longer matched target prefix is a more specific alias; an exact file alias beats every wildcard. */
     private matchAlias;
 }
+/** The name of a `paths` alias: `@app/services/*` and `@app/services` both become `app/services`. */
+export declare function normalizeAliasName(pattern: string): string;
 export {};
 //# sourceMappingURL=ImportPaths.d.ts.map

package/typings/build.d.ts

@@ -27,7 +27,11 @@ export interface BuildResult {
     /** Absolute path of the config that was built. */
     config: string;
     outputs: OutputResult[];
-    /** Non-fatal problems found while resolving the config, e.g. an `exclude` that drops a default test glob. */
+    /**
+     * 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[];
 }
 /**

package/typings/config.d.ts

@@ -12,12 +12,28 @@ 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;
+    /**
+     * tsconfig `paths` aliases to drop after selection: a class whose file resolves
+     * through one of these aliases is dropped, e.g. `["services"]` for a `services/*`
+     * (or `@services/*`) alias. Names may omit a leading `@` and a trailing `/*`.
+     */
+    excludeAliases?: 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;
+    excludeAliases?: string[];
 }
 export interface NamespaceConfig {
     /** A folder relative to the config file (`./src/services`) or a tsconfig `paths` alias (`@app/services`). */

package/typings/scan.d.ts

@@ -11,6 +11,21 @@ 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[];
+    /**
+     * Each class decorator's name and the source text of its arguments, e.g.
+     * `perPage` with `["'stations'"]`. Syntax only: lets the token-collision check
+     * tell scope-gated classes (`@perPage('a')` vs `@perPage('b')`) apart.
+     */
+    decoratorCalls: {
+        name: string;
+        args: 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[];