@mnemonica/tactica 0.4.1 → 0.4.3

package/README.md

@@ -171,7 +171,23 @@ declare module 'mnemonica' {
 
 **Recommended for new projects.** Explicit imports, better tree-shaking, no global namespace pollution.
 
-**Instance-type inheritance.** Nested instance types flatten the WHOLE ancestor chain: each nested type is `ProtoFlat<ParentInstance, Self>` (mnemonica's `ProtoFlat` keeps every parent key except the ones `Self` overrides), and the parent instance type is itself a `ProtoFlat` over its own parent — so the ROOT's own constructor-arg fields (`uuid` in `PaymentRoot`) are directly present on every descendant instance type, at any depth, alongside intermediate ancestors' fields. If a root field appears missing on a nested type, the usual cause is a stale `.tactica` — regenerate; the composition itself is transitive by construction.
+**Async constructors.** When the construct handler is an `async function` (or async arrow), `new` resolves to a Promise at runtime, so the emitted constructor shapes resolve to `Promise<InstanceType>`: the subtype property on the parent emits `{ new (…): Promise<X>; (…): Promise<X> }` (both twins) and the registry entry emits `new (…) => Promise<X>`. The instance type `X` itself is unchanged, so `await new` yields `X`. Async CLASSES (a class constructor returning a Promise) are not detected — the syntactic shape carries no reliable signal without a type checker — and stay typed as the plain instance type; type them yourself in userland if you need `Promise<X>` there.
+
+**Avoid arrow handlers — use the ESLint plugin.** Construct handlers must be regular functions or classes so the instance can be substituted as `this`. Core rejects sync arrows at `define()` time, but async arrows cannot be detected at runtime and never receive the instance — the failure surfaces far from the cause. The early guard is [`eslint-plugin-no-arrow-this`](https://www.npmjs.com/package/eslint-plugin-no-arrow-this), which flags `this` inside arrow functions before the code runs:
+
+```javascript
+plugins: ['eslint-plugin-no-arrow-this'],
+rules: {
+	// default: warn on `this` inside ANY arrow function
+	'no-arrow-this/no-arrow-this': 'warn',
+	// or restrict to the global/window capture case:
+	// 'no-arrow-this/no-arrow-this': ['warn', { onlyGlobals: true }],
+},
+```
+
+Recommended in every mnemonica project.
+
+**Instance-type inheritance.** Nested instance types flatten the WHOLE ancestor chain: each nested type is `ProtoFlat<ParentInstance, Self>` (mnemonica's `ProtoFlat` keeps every parent key except the ones `Self` overrides), and the parent instance type is itself a `ProtoFlat` over its own parent — so the ROOT's own constructor-arg fields (`serial` in `WidgetRoot`) are directly present on every descendant instance type, at any depth, alongside intermediate ancestors' fields. If a root field appears missing on a nested type, the usual cause is a stale `.tactica` — regenerate; the composition itself is transitive by construction.
 
 ### Legacy global-augmentation mode (`--module-augmentation`)
 
@@ -394,8 +410,8 @@ class Configurable {
 Decorate-class instances need a cast to the generated instance type to access nested constructors at the type level:
 
 ```ts
-const order = new Order() as Order_AugmentedOrder; // … or whatever your generated alias is
-const sub   = new order.AugmentedOrder();
+const gadget = new Gadget() as Gadget_EnhancedGadget; // … or whatever your generated alias is
+const sub   = new gadget.EnhancedGadget();
 ```
 
 ### `Object.assign(this, data)` pattern
@@ -920,8 +936,8 @@ Type Hierarchy (Trie)
 │       ├── properties: { role: string }
 │       └── SuperAdminType
 │           └── properties: { permissions: string[] }
-└── OrderType
-    └── properties: { items: Item[] }
+└── JobType
+    └── properties: { tasks: Task[] }
 ```
 
 ## Known Limitations

package/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: mnemonica-tactica
+description: |
+  Static type generator for mnemonica projects. Use when a project uses
+  mnemonica and needs typed lookup(), TypeRegistry augmentation, or
+  generated instance types; when `define()`/`lazy()`/`@decorate()` calls
+  should become visible to TypeScript; or when the user mentions tactica,
+  .tactica output, types.ts / registry.ts generation, or type-safe
+  mnemonica navigation.
+metadata:
+  tags: [mnemonica, typescript, codegen, type-system, ast, nodejs]
+---
+
+# tactica — usage skill for agents
+
+tactica reads TypeScript/JavaScript source that uses mnemonica and
+generates the types TypeScript cannot infer from runtime calls:
+`.tactica/types.ts` (instance types), `.tactica/registry.ts` (module
+augmentation of mnemonica's `TypeRegistry`), plus JSON metadata
+(definitions, usages, hierarchy, scopes, modules, flow, instrumentation)
+consumed by editor extensions and other tools.
+
+## When to use
+
+- The project depends on `mnemonica` and calls `define()`, `lazy()`, or
+  uses `@decorate()`
+- Code calls `lookup('Some.Type')` and you want the result typed
+- A constructor or subtype type-errors and the fix belongs upstream
+  (regenerate `.tactica` before reaching for a cast)
+
+## How to run
+
+```bash
+npx tactica                     # nearest tsconfig, writes .tactica/
+npx tactica -p tsconfig.json    # explicit project
+npx tactica --esm               # NodeNext ESM: .js import extensions
+npx tactica -w                  # watch mode
+```
+
+The generated `types.ts` + `registry.ts` are imported by application
+code; the JSON files are consumed by tooling (graph views, go-to
+definition). Custom types collections are tracked too — with a
+user-declared registry interface (Option B) they emit their own
+augmented interface instead of the global `TypeRegistry`.
+
+## What it types
+
+- One `export type` per discovered type, named by dotted path with `_`
+  separators; nested types are `ProtoFlat<Parent, Self>`, so ancestor
+  fields are present on descendants by construction.
+- Every parent instance type carries its subtype constructors:
+  `Child: { new (args): Child; (args): Child }` — the construct form
+  and the chain-tip call form.
+- `registry.ts` augments mnemonica's `TypeRegistry` so the free
+  `lookup('Parent.Child')` returns the typed constructor.
+
+## Async constructors
+
+When a construct handler is an `async function` (or async arrow),
+tactica emits `Promise<X>` for both constructor shapes — the subtype
+property and the registry entry — because `new` resolves to a Promise
+at runtime. The instance type `X` itself is unchanged, so
+`await new` yields `X`.
+
+Async **classes** (a class constructor returning a Promise) are NOT
+detected — the syntactic shape carries no reliable signal without a
+type checker — and stay typed as the plain instance type. Type them in
+userland when `Promise<X>` is needed there.
+
+## Avoid arrow handlers — use the ESLint plugin
+
+mnemonica construct handlers must be regular functions or classes so the
+instance can be substituted as `this`:
+
+- Sync arrow handlers are rejected by mnemonica core at `define()` time
+  with a readable error.
+- Async arrow handlers **cannot be detected at runtime** — they look
+  identical to `async function` — and they never receive the instance:
+  `this` inside an arrow is the outer lexical `this`, so fields land on
+  the wrong object and the construction fails later, far from the cause.
+
+The early guard is the ESLint plugin `eslint-plugin-no-arrow-this`,
+which flags `this` inside arrow functions before the code runs:
+
+```javascript
+// eslint.config.js (flat) or .eslintrc
+plugins: ['eslint-plugin-no-arrow-this'],
+rules: {
+  // default: warn on `this` inside ANY arrow function
+  'no-arrow-this/no-arrow-this': 'warn',
+  // or restrict to the global/window capture case:
+  // 'no-arrow-this/no-arrow-this': ['warn', { onlyGlobals: true }],
+},
+```
+
+Recommended in every mnemonica project, especially where handlers are
+written by contributors who have not internalized the rule.
+
+## Example
+
+```typescript
+import { mnemonica } from 'mnemonica';
+
+export const App = mnemonica
+	.define('Widget', function (this: Widget, data: { id: string }) {
+		this.id = data.id;
+	})
+	.define('Gadget', async function (this: Gadget, data: { serial: number }) {
+		this.serial = await register(data.serial);
+		return this;
+	});
+```
+
+After `npx tactica`, `lookup('App.Gadget')` is typed
+`new (data: { serial: number }) => Promise<Gadget>` — a forgotten
+`await` is now a type error at the call site instead of a silent
+`undefined` at runtime.

package/lib/analyzer.d.ts

@@ -665,6 +665,14 @@ export declare class MnemonicaAnalyzer {
      * returned by the lazy getter.
      */
     private extractConstructorExpression;
+    /**
+     * Detect an async constructor handler: the async modifier on a
+     * function expression or arrow. Async CLASSES (a class constructor
+     * returning a Promise) are deliberately NOT detected — the syntactic
+     * class shape gives no reliable signal without a type checker, and the
+     * owner decided they are typed by the user in userland.
+     */
+    private isAsyncConstructHandler;
     /**
      * Extract properties from constructor function
      */
@@ -925,6 +933,11 @@ export declare class MnemonicaAnalyzer {
             * Get type name from expression (identifier or property access)
             */
     private getTypeNameFromExpression;
+    /**
+     * The one candidate whose parent type is defined in `fileName`, or
+     * undefined when none or several qualify.
+     */
+    private subtypeOwnedByFile;
     /**
             * Resolve full type path from property access
             */