@mnemonica/tactica 0.1.3 → 0.1.5

package/README.md

@@ -221,7 +221,124 @@ const AdminType = UserType.define('AdminType', function (this: { role: string })
 
 Chained calls (`define('A').define('B')`) and nested calls via variable references (`const A = define('A', …); A.define('B', …)`) are both supported.
 
-### `@decorate()` decorator
+### Builder pattern on the imported module object
+
+The analyzer also recognizes the chainable `mnemonica` module object and aliases of it:
+
+```ts
+import { mnemonica } from 'mnemonica';
+
+const App = mnemonica
+    .define('UserType', function (this: { name: string }) {
+        this.name = '';
+    })
+    .define('AdminType', function (this: { role: string }) {
+        this.role = 'admin';
+    });
+
+// Builder .lookup() results are followed
+App.lookup('UserType').define('GuestType', function (this: { token: string }) {
+    this.token = '';
+});
+```
+
+It also recognizes the explicit-source APIs:
+
+```ts
+import { define, lookup } from 'mnemonica';
+
+const AdminType = define(UserType, 'AdminType', function (this: { role: string }) {
+    this.role = 'admin';
+});
+
+const AdminCtor = lookup(App, 'UserType.AdminType');
+```
+
+### Custom collections via `createTypesCollection()`
+
+Types defined on a collection created with `createTypesCollection()` are tracked by the analyzer. By default they are **not** emitted in `.tactica/types.ts` and are **not** added to the global `mnemonica.TypeRegistry` augmentation because they live in an isolated runtime collection. Use the collection variable directly in your own code to get typed constructors.
+
+All common import styles are recognized:
+
+```ts
+import { createTypesCollection } from 'mnemonica';
+
+const AppCollection = createTypesCollection();
+
+AppCollection.define('UserType', function (this: { name: string }) {
+    this.name = '';
+});
+```
+
+```ts
+import { mnemonica } from 'mnemonica';
+
+const AppCollection = mnemonica.createTypesCollection();
+```
+
+```ts
+import * as mnemonica from 'mnemonica';
+
+const AppCollection = mnemonica.createTypesCollection();
+```
+
+```ts
+import { createTypesCollection as ctc } from 'mnemonica';
+
+const AppCollection = ctc();
+```
+
+Subtypes defined from a collection type inherit the same collection membership:
+
+```ts
+const UserType = AppCollection.define('UserType', function (this: { name: string }) {
+    this.name = '';
+});
+
+UserType.define('AdminType', function (this: { role: string }) {
+    this.role = 'admin';
+});
+```
+
+Two independent collections may define root types with the same name without colliding in the analyzer graph.
+
+#### Option B — user-provided registry interface
+
+To get fully typed `.lookup()` and `.decorate()` for a custom collection, export an empty interface and pass it to `createTypesCollection<Registry>()`:
+
+```ts
+import { createTypesCollection } from 'mnemonica';
+
+export interface AppCollectionRegistry {}
+
+const AppCollection = createTypesCollection<AppCollectionRegistry>();
+
+const UserType = AppCollection.define('UserType', function (this: { name: string }) {
+    this.name = '';
+});
+
+UserType.define('AdminType', function (this: { role: string }) {
+    this.role = 'admin';
+});
+```
+
+Tactica then emits:
+
+- Prefixed instance types in `.tactica/types.ts`, e.g. `AppCollectionRegistry_UserType` and `AppCollectionRegistry_UserType_AdminType`.
+- A `declare module '<relative path to this file>'` block in `.tactica/registry.ts` that augments `AppCollectionRegistry` with `'UserType'` and `'UserType.AdminType'` entries.
+
+Once `.tactica/registry.ts` is part of your `tsc` compilation, `AppCollection.lookup('UserType')` and `AppCollection.lookup('UserType.AdminType')` are fully typed.
+
+Custom collections also support `decorate()` for root types:
+
+```ts
+@AppCollection.decorate()
+class UserType {
+    name: string = '';
+}
+```
+
+Decorated root types are included in the same per-collection augmentation.
 
 ```ts
 @decorate()
@@ -387,7 +504,7 @@ class TypeGraphImpl implements TypeGraph {
     *bfs(): Generator<TypeNode>;
     *dfs(node?: TypeNode): Generator<TypeNode>;
 
-    static createNode(name, parent, sourceFile, line, column): TypeNode;
+    static createNode(name, parent, sourceFile, line, column, collectionId?): TypeNode;
 }
 ```
 
@@ -523,6 +640,10 @@ Mnemonica accepts the `exposeInstanceMethods` option at runtime, but tactica's `
 
 The analyzer does not use `ts.Program.getTypeChecker()` for resolution, so cross-file type references in unusual shapes may resolve to `unknown`.
 
+### Custom collection name conflicts
+
+Custom collection types are isolated in the analyzer by their collection identity, so two collections may both define a root type with the same name (e.g., both defining `'User'`) without overwriting each other. Because custom-collection types are not emitted in `.tactica/types.ts`, they also do not conflict in generated output.
+
 ## Troubleshooting
 
 **Generated types are missing properties** — make sure the constructor function has either an explicit `this:` type annotation, or that the data parameter has an inline / aliased type (`{ id: string }` or `Foo` where `type Foo = { id: string }`). Property inference walks one level of indirection.

package/lib/analyzer.d.ts

@@ -13,6 +13,11 @@ export declare class MnemonicaAnalyzer {
     private flowUsages;
     private typeAliases;
     private variableToTypeMap;
+    private moduleObjectVariables;
+    private createTypesCollectionVariables;
+    private collectionVariables;
+    private collectionInfo;
+    private collectionCounter;
     constructor(program?: ts.Program);
     /**
      * Reset usage-related state for a fresh pass.
@@ -60,10 +65,57 @@ export declare class MnemonicaAnalyzer {
      * Visit a node in the AST
      */
     private visitNode;
+    /**
+     * Track imports from 'mnemonica' so aliases of the module object and
+     * createTypesCollection are recognized without relying on the type checker.
+     */
+    private trackImports;
+    /**
+     * Track aliases of the mnemonica module object, e.g.:
+     *   const m = mnemonica;
+     *   const App = m;
+     */
+    private trackModuleObjectAliases;
+    /**
+     * Track custom collection variables, e.g.:
+     *   const MyCollection = createTypesCollection();
+     *   const Other = MyCollection;
+     *
+     * Also detects Option B user-provided registry interfaces:
+     *   export interface MyCollectionRegistry {}
+     *   const MyCollection = createTypesCollection<MyCollectionRegistry>();
+     */
+    private trackCollectionAliases;
+    /**
+     * Extract the registry interface name from createTypesCollection<Registry>()
+     * when the interface is declared in the same source file.
+     */
+    private extractRegistryInterfaceName;
+    /**
+     * Get the registry interface name for a collection id.
+     */
+    private getRegistryInterfaceName;
+    /**
+     * Check if an expression is a createTypesCollection() call.
+     * Handles:
+     *   createTypesCollection()
+     *   ctc() // aliased import
+     *   mnemonica.createTypesCollection() // module object method
+     *   m.createTypesCollection() // aliased module object
+     */
+    private isCreateTypesCollectionCall;
+    /**
+     * Generate a unique collection identifier.
+     */
+    private nextCollectionId;
     /**
      * Check if a node is a define() call
      */
     private isDefineCall;
+    /**
+     * Check if a node is a lazy() call
+     */
+    private isLazyCall;
     /**
         * Extract config options from an object literal
         */
@@ -76,10 +128,52 @@ export declare class MnemonicaAnalyzer {
         * Check if a node is a @decorate() decorator
         */
     private isDecorateDecorator;
+    /**
+     * Mark a call expression as processed and return whether it already was.
+     */
+    private markProcessed;
     /**
      * Process a define() call
      */
     private processDefineCall;
+    /**
+     * Process a lazy() call
+     */
+    private processLazyCall;
+    /**
+     * Extract lazy() call arguments into a normalized shape.
+     * Handles named/unnamed and explicit-source forms, both as free calls
+     * and as method calls.
+     */
+    private extractLazyCallArgs;
+    /**
+     * Unwrap the constructor returned by a lazy getter.
+     * Supports:
+     *   () => class Name {}
+     *   () => function Name() {}
+     *   () => { return class Name {}; }
+     *   function () { return function Name() {}; }
+     */
+    private unwrapLazyGetter;
+    /**
+     * Extract a constructor name from a class expression, class declaration,
+     * or named function expression.
+     */
+    private extractConstructorName;
+    /**
+     * Extract the type name from either a define() or lazy() call.
+     */
+    private extractMnemonicaTypeName;
+    /**
+     * Extract the full lazy() call context: type name, parent type, and collection.
+     * Handles direct calls, property-access calls, chained calls, and the
+     * explicit-source form `lazy(source, 'TypeName', getter)`.
+     */
+    private extractLazyContext;
+    /**
+     * Extract config options from lazy() call
+     */
+    private extractLazyConfig;
     /**
         * Track variable assignments that capture define() results
         * e.g., const User = define('UserEntity', ...) maps "User" -> "UserEntity"
@@ -101,15 +195,46 @@ export declare class MnemonicaAnalyzer {
      */
     private processDecorateDecorator;
     /**
-     * Extract type name from define() call arguments
+     * Extract type name from define() call arguments.
+     * Handles:
+     *   define('TypeName', handler)
+     *   define(source, 'TypeName', handler)   // explicit-source form
+     *   define(function TypeName() {})
+     *   define(() => class TypeName {})
      */
     private extractTypeName;
     /**
-     * Find parent type node for nested define calls
+     * Extract the full define() call context: type name, parent type, and collection.
+     * Handles direct calls, property-access calls, chained calls, and the
+     * explicit-source form `define(source, 'TypeName', handler)`.
+     */
+    private extractDefineContext;
+    /**
+     * Prefix a dotted type path with a collection identifier so custom-collection
+     * types do not collide with default-collection types in the graph.
+     */
+    private prefixCollectionPath;
+    /**
+     * Resolve a define() source identifier to either a parent type, a collection,
+     * or the default (module object) collection.
+     */
+    private resolveDefineSource;
+    /**
+     * Check if a call expression is a lookup() call.
      */
-    private findParentType;
+    private isLookupCall;
     /**
-        * Find a parent type by its name, searching in the graph
+     * Resolve a lookup() call to a dotted type path (best effort).
+     * Handles:
+     *   lookup('User')
+     *   lookup(source, 'User')
+     *   App.lookup('User')
+     *   collection.lookup('User.Admin')
+     */
+    private resolveLookupPath;
+    /**
+        * Find a parent type by its name, searching in the graph.
+        * When collectionId is provided, only types from that collection are considered.
         */
     private findParentTypeByName;
     /**
@@ -118,14 +243,29 @@ export declare class MnemonicaAnalyzer {
         * and direct class/type names.
         */
     private findParentTypeByIdentifier;
+    /**
+     * Get the leftmost identifier of a property-access chain.
+     * For `App.define('User').define('Admin')` this returns the `App` identifier.
+     */
+    private getRootIdentifier;
     /**
         * Get property chain from nested access
         */
     private getPropertyChain;
+    /**
+     * Determine the constructor expression for either a define() or lazy() call.
+     * For define() this is the construct handler; for lazy() it is the value
+     * returned by the lazy getter.
+     */
+    private extractConstructorExpression;
     /**
      * Extract properties from constructor function
      */
     private extractProperties;
+    /**
+     * Extract properties from a constructor expression (function, arrow, or class).
+     */
+    private extractPropertiesFromConstructor;
     /**
      * Build a type map from all parameters with inline object type annotations
      * Returns a map of "paramName.propertyName" -> type
@@ -184,16 +324,16 @@ export declare class MnemonicaAnalyzer {
      */
     private inferTypeFromInitializer;
     /**
-        * Collect usage information for type references
-        */
+            * Collect usage information for type references
+            */
     private collectUsage;
     /**
-        * Get function name from expression (identifier or property access)
-        */
+            * Get function name from expression (identifier or property access)
+            */
     private getFunctionName;
     /**
-        * Add a usage to the collection
-        */
+            * Add a usage to the collection
+            */
     private addUsage;
     /**
      * Collect EDS (Execution Data Storage) usage information
@@ -257,26 +397,30 @@ export declare class MnemonicaAnalyzer {
             */
     private getTypeNameFromExpression;
     /**
-        * Resolve full type path from property access
-        */
+            * Resolve full type path from property access
+            */
     private resolveTypePath;
     /**
-         * Check if a name looks like a type (starts with uppercase)
-         */
+             * Check if a name looks like a type (starts with uppercase)
+             */
     private isLikelyTypeName;
     /**
-         * Resolve a constructor parameter type, expanding inline object literals
-         * and type aliases where possible.
-         */
+             * Resolve a constructor parameter type, expanding inline object literals
+             * and type aliases where possible.
+             */
     private resolveConstructorParamType;
     /**
-         * Extract constructor parameters from a class-like node.
-         */
+             * Extract constructor parameters from a class-like node.
+             */
     private extractClassConstructorParams;
     /**
-         * Extract constructor parameters from define() call
-         * This is used for TypeRegistry constructor signatures
-         * Preserves parameter names and expands object types to their structure
-         */
+             * Extract constructor parameters from define() call
+             * This is used for TypeRegistry constructor signatures
+             * Preserves parameter names and expands object types to their structure
+             */
     private extractConstructorParams;
+    /**
+             * Extract constructor parameters from a constructor expression.
+             */
+    private extractConstructorParamsFromConstructor;
 }