@mnemonica/tactica 0.3.15 → 0.4.1

package/README.md

@@ -41,6 +41,8 @@ npm install --save-dev @mnemonica/tactica
 
 `mnemonica` is a peer dependency (>= 1.0.1).
 
+Tactica bundles its own TypeScript compiler (6.x) as a regular dependency, so it installs and runs regardless of the TypeScript version your project uses — including TypeScript 7, whose npm package no longer exposes the classic compiler API. Your `tsconfig.json` is only ever *parsed* (never emitted), so TS5-era options like `baseUrl` keep working even though TS6 marks them deprecated.
+
 ## Usage
 
 ### CLI
@@ -251,7 +253,7 @@ These usage shapes are recognized and attributed within the existing output cont
 - **`call(entity, Ctor, ...)` / `apply(entity, Ctor, args)`** — the mnemonica construction exports (import-aware: only actual `'mnemonica'` imports or members of a tracked module-object alias match; userland `call`/`apply` never do). The Ctor argument (arg 1) records an `instantiation`, and the result variable binds to the Ctor's type (runtime `InstanceResult<Merge<E, T>>` approximated by T). **Decorated classes resolve as the Ctor** through the same graph tiers — `@decorate() class C` is a known type, so `call(parent, C)` records and binds; an undecorated plain class has no graph entry, so the call binds nothing and records no usage (never a bare name). The free-call `decorate(Class)` form is not tracked (tactica recognizes the `@decorate` decorator syntax only).
 - **`bind(entity, Ctor)`** — records no usage (it constructs nothing); the bound variable binds to the Ctor's type. Invoking the bound function later (`f(...)`, including `await f(...)`) is not followed.
 
-Two boundaries stay deliberate: bindings surface only for references lexically AFTER the binding statement (a binding made inside a constructor body is not yet visible to that same handler's property extraction), and the mechanism distinction (`new` vs fork vs call) is not carried in the outputs — fork/clone/merge record as plain `instantiation` entries, byte-indistinguishable from `new`, until the deferred mechanism-kind contract revision lands. Consumers counting constructions should expect fork sites among them.
+Three boundaries stay deliberate: bindings surface only for references lexically AFTER the binding statement (a binding made inside a constructor body is not yet visible to that same handler's property extraction); a construction nested inside a class or function body of the initializer does not bind the outer variable (`const X = define('X', class { m = new Map() })` binds X to the defined type, never to `Map` — scope boundaries are not crossed); and the mechanism distinction (`new` vs fork vs call) is not carried in the outputs — fork/clone/merge record as plain `instantiation` entries, byte-indistinguishable from `new`, until the deferred mechanism-kind contract revision lands. Consumers counting constructions should expect fork sites among them.
 
 ### Builder pattern on the imported module object
 
@@ -359,7 +361,7 @@ 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.
+Once `.tactica/registry.ts` is part of your `tsc` compilation, `AppCollection.lookup('UserType')` and `AppCollection.lookup('UserType.AdminType')` are fully typed. Constructor-relative lookups resolve too: a variable bound to `AppCollection.lookup('UserType')` resolves `.lookup('AdminType')` relative-first (the type's own subtypes, then the collection root) — the same law as for default-collection types.
 
 Custom collections also support `decorate()` for root types:
 
@@ -473,7 +475,7 @@ The analyzer infers property types from constructor bodies and class members. Su
 | `this.x = []` / `new Array()` | `Array<…>` |
 | `this.x = {}` | `object` |
 | `this.x = new Date()` | `Date` |
-| `this.x = new Map()` / `new Set()` | `Map<…>` / `Set<…>` |
+| `this.x = new Map()` / `new Set()` | `Map<unknown, unknown>` / `Set<unknown>` — a bare generic is never emitted (TS2314); explicit arguments survive: `new Map<string, number>()` → `Map<string, number>` |
 | `this.x = Date.now()` | `number` |
 | `this.x = parseInt(…)` / `parseFloat(…)` | `number` |
 | `this.x = String(…)` / `Number(…)` / `Boolean(…)` | `string` / `number` / `boolean` |
@@ -907,7 +909,7 @@ Deliberate approximations (name-based, no type checker): namespace imports count
 1. **Parse** — load `tsconfig.json`, build a `ts.Program`, walk each source file's AST.
 2. **Detect** — find `define()` and `@decorate()` calls, plus `lookup` lookups, `new` expressions, and EDS / flow patterns.
 3. **Graph** — build a Trie of types in `TypeGraphImpl`, with parent links via the chain of `.define()` calls and `@decorate(Parent)` references.
-4. **Generate** — emit `types.ts`, `registry.ts`, `index.ts` (default mode) or `index.d.ts` (legacy mode), plus `definitions.json`, `usages.json` (with `holderScopeId`), `flow.json`, `instrumentation.json`, `modules.json`, `scopes.json`, `hierarchy.json`/`hierarchy.txt`, and optionally `eds.json`.
+4. **Generate** — emit `types.ts`, `registry.ts`, `index.ts` (default mode) or `index.d.ts` (legacy mode), plus `definitions.json`, `usages.json` (with `holderScopeId`), `flow.json`, `instrumentation.json`, `modules.json`, `scopes.json`, `hierarchy.json`/`hierarchy.txt`, `collections.json`, and optionally `eds.json`.
 5. **Write** — files land in the output directory (default `.tactica/`).
 
 ```

package/lib/analyzer.d.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { AnalyzeResult, DefinitionInfo, UsageInfo, EDSInfo, FlowInfo, InstrumentationPoint, ResolutionError } from './types';
+import { AnalyzeResult, DefinitionInfo, UsageInfo, EDSInfo, FlowInfo, InstrumentationPoint, ResolutionError, CollectionManifestEntry } from './types';
 import { TypeGraphImpl } from './graph';
 import { TacticaPlugin } from './plugins';
 /**
@@ -73,6 +73,14 @@ export declare class MnemonicaAnalyzer {
      * Get collected definitions
      */
     getDefinitions(): Map<string, DefinitionInfo>;
+    /**
+     * The collections.json manifest: one entry per minted collection, in
+     * minting order, preceded by the default-collection entry whenever
+     * default-collection types exist. The default entry has no id/location
+     * (there is no call site — unprefixed fullPaths are its identity) and
+     * its registry interface is the global TypeRegistry.
+     */
+    getCollectionsManifest(): CollectionManifestEntry[];
     /**
      * Get collected usages
      */
@@ -251,6 +259,14 @@ export declare class MnemonicaAnalyzer {
      */
     private expandReferencedTypeDeclaration;
     private expandReferencedTypeDeclarationInner;
+    /**
+     * Emitted instance-type alias for a graph node — the name types.ts /
+     * registry.ts actually declare. Option B collection types carry their
+     * registry interface prefix; collection types WITHOUT a registry
+     * interface are never emitted, so no valid alias exists for them
+     * (undefined — callers degrade to `unknown`, never a bare name).
+     */
+    private getEmittedInstanceTypeName;
     /**
      * Resolve a simple (non-qualified) type reference: import-aware
      * declaration expansion first, then the InstanceType<typeof X> pattern,
@@ -403,9 +419,14 @@ export declare class MnemonicaAnalyzer {
      */
     private extractRegistryInterfaceName;
     /**
-     * Get the registry interface name for a collection id.
+     * Stamp a node with its collection's emission info: the Option B registry
+     * interface name and the collection's home file — the module the generated
+     * augmentation must target (the interface is confirmed declared there).
+     * A type's own sourceFile is NOT the target: multi-file collections define
+     * types across many modules while the interface lives at the
+     * createTypesCollection() call site.
      */
-    private getRegistryInterfaceName;
+    private applyCollectionEmissionInfo;
     /**
      * Check if an expression is a createTypesCollection() call.
      * Handles: