@mnemonica/tactica 0.4.7 → 0.4.9

package/README.md

@@ -131,6 +131,8 @@ You should commit `.tactica/` if you want type information to flow through CI wi
 
 EDS tracking is **auto-enabled** when `@mnemonica/dive` is present in `package.json` dependencies; otherwise it is off. `--eds` / `--no-eds` override the auto-detection.
 
+Analyzer errors (for example the unnamed `lazy()` form, which the runtime rejects with `TYPENAME_MUST_BE_A_STRING`) never abort the run: the offending call is skipped, each error prints once as a `tactica: <file>:<line>:<column> <message>` warning on stderr (not `--verbose`-gated), and the exit code stays 0.
+
 ## Generated Files
 
 Tactica writes everything under the `--output` directory (default `.tactica/`). All file paths inside the JSON files are emitted **project-relative** (anchored at the tsconfig directory) so the output is portable across machines; consumers resolve them against the directory holding `.tactica`. Earlier versions emitted absolute paths, so consumers should accept both.
@@ -256,7 +258,7 @@ Chained calls (`define('A').define('B')`) and nested calls via variable referenc
 ### `lazy()` definitions
 
 ```ts
-const AdminType = UserType.lazy(() => class AdminType {
+const AdminType = UserType.lazy('AdminType', () => class AdminType {
     role: string;
     constructor (role: string) {
         this.role = role;
@@ -264,7 +266,7 @@ const AdminType = UserType.lazy(() => class AdminType {
 });
 ```
 
-All forms are recognized: free `lazy('Name', getter)`, method `Type.lazy(...)`, and chained `define('A').lazy('B', getter)`. The getter is followed, and the returned constructor is analyzed like a direct `define()` handler — properties and constructor parameters are extracted and emitted in `types.ts` / `registry.ts` like any other type.
+The name is required — the runtime throws `TYPENAME_MUST_BE_A_STRING` for the unnamed forms (`lazy(getter)`, `Type.lazy(getter)`, `lazy(source, getter)`), so tactica reports them as analyzer errors naming the call site and generates no type for them. The named forms are all recognized: free `lazy('Name', getter)`, method `Type.lazy('Name', getter)`, chained `define('A').lazy('B', getter)`, and explicit-source `lazy(source, 'Name', getter)`. The getter is followed, and the returned constructor is analyzed like a direct `define()` handler — properties and constructor parameters are extracted and emitted in `types.ts` / `registry.ts` like any other type.
 
 ### Construction shapes beyond plain `new`
 
@@ -859,7 +861,8 @@ interface TacticaPlugin {
     appTokens?: Record<string, InstrumentationKind>;
     // factory calls inside listed decorators' args: factory method name ->
     // kind + which factory-call argument holds the target class (default 0)
-    decoratorArgFactories?: Record<string, { kind: InstrumentationKind; targetArg?: number }>;
+    // + whether the factory constructs that target (instantiation)
+    decoratorArgFactories?: Record<string, { kind: InstrumentationKind; targetArg?: number; instantiation?: boolean }>;
     // opt in to shape-based `consumer.apply(Mw).forRoutes(...)` detection
     middlewareWiring?: boolean;
 }
@@ -869,7 +872,7 @@ Programmatic callers pass plugins directly: `new MnemonicaAnalyzer(program, plug
 
 - **Heritage** — `class X implements <plugin-listed interface>` (matched by interface identifier name). Bare declarations carry scope `module` (attachment statically unknown).
 - **Decorator sites** — plugin-listed decorators on classes, methods, or method parameters, including inline instances (`@Register(new Impl(…))`). One point per referenced class; scope is `controller:<Name>` or `method:<Class>.<method>` (parameter-decorated sites take the enclosing method's scope — the attachment is the handler, not the argument name).
-- **Decorator-arg factories** — a `CallExpression` argument of the form `<anything>.<factory>(…)` inside a listed decorator's args (class, method, or parameter position), e.g. `@UsePipes(mvp.forType(Dto))` and the parameter form `@Body(mvp.forType(Entity, Dto))`: when `<factory>` is plugin-listed, a point of the configured `kind` is emitted with the class in `targetArg` (default 0) as the target. Factory calls whose method name is not listed are ignored, as are listed factories whose configured position is not an identifier. Points resolve `location`/`code` to the target's declaration and dedupe exactly like other decorator sites.
+- **Decorator-arg factories** — a `CallExpression` argument of the form `<anything>.<factory>(…)` inside a listed decorator's args (class, method, or parameter position), e.g. `@UsePipes(mvp.forType(Dto))` and the parameter form `@Body(mvp.forType(Entity, Dto))`: when `<factory>` is plugin-listed, a point of the configured `kind` is emitted with the class in `targetArg` (default 0) as the target. Factory calls whose method name is not listed are ignored, as are listed factories whose configured position is not an identifier. Points resolve `location`/`code` to the target's declaration and dedupe exactly like other decorator sites. With `instantiation: true` the plugin declares that the factory constructs its target on the caller's behalf (a pipe running `new Target(body)` per request): when the target argument resolves to a defined type — a `lookup()` alias, a type name, or a type path — the factory call is also recorded in `usages.json` and `flow.json` as an `instantiation` of that type, `constructorText` being the argument text.
 - **Global providers** — `{ provide: <plugin-listed token>, useClass: X }` object literals → scope `global`. `useExisting`/`useFactory` without `useClass` are skipped.
 - **Middleware wiring** — `consumer.apply(Mw).forRoutes(...)` inside a class's `configure()` method → scope `module`, targets from `forRoutes` arguments when statically readable. Requires `middlewareWiring: true` from any loaded plugin.
 

package/lib/analyzer.d.ts

@@ -477,7 +477,9 @@ export declare class MnemonicaAnalyzer {
     /**
      * Extract lazy() call arguments into a normalized shape.
      * Handles named/unnamed and explicit-source forms, both as free calls
-     * and as method calls.
+     * and as method calls. The unnamed shapes return `name: undefined` —
+     * processLazyCall rejects them with an analyzer error (the runtime
+     * requires the name), so no type is generated for them.
      */
     private extractLazyCallArgs;
     /**
@@ -577,6 +579,13 @@ export declare class MnemonicaAnalyzer {
      * chain resolution for property accesses).
      */
     private resolveConstructionFnTypePath;
+    /**
+     * Resolve an expression passed where a constructor is expected (the
+     * Ctor of call/apply/bind, a plugin factory's constructed target) to a
+     * defined type's fullPath: value scope for identifiers, chain
+     * resolution for property accesses.
+     */
+    private resolveCtorArgTypePath;
     /**
      * instance.fork(...) / instance.clone(...) on a tracked variable —
      * runtime returns `this`, so the result carries the source type.
@@ -986,6 +995,14 @@ export declare class MnemonicaAnalyzer {
      * referenced class identifier.
      */
     private collectInstrumentationDecorator;
+    /**
+     * A plugin-listed decorator-arg factory with `instantiation: true`
+     * (`@Body(mvp.forType(Entity, Dto))`) constructs the type at its
+     * target argument later, at runtime: record the factory call as that
+     * type's `instantiation` usage and flow, the same as call/apply. A
+     * target that resolves to no defined type records nothing.
+     */
+    private recordFactoryConstruction;
     /**
      * Detect global registrations: object literals shaped like
      * `{ provide: <plugin-listed token>, useClass: X }`.