@mnemonica/tactica 0.3.5 → 0.3.8

package/README.md

@@ -464,16 +464,19 @@ The analyzer infers property types from constructor bodies and class members. Su
 | `this.x = a + b` (where `a, b: number`) | `number` |
 | `` this.x = `${a} ${b}` `` | `string` |
 | `this.x = data.field` | type of `data.field` from the parameter annotation |
+| `this.x = data.field` where `data: SomeNamedType` (alias/interface/class) | type of the field from the resolved declaration — import-aware, inherited members included; a bare `this.x = data` keeps the full expanded shape |
 | `this.x = data.field \|\| []` | type of the fallback expression |
 | `this.x = data.field ? a : b` | type of the truthy branch |
 | `Object.assign(this, data)` | all fields of `data`'s type annotation |
 | async / sync constructor functions | same rules |
 
+An existing annotation always beats a weaker inference: `unknown` (and `unknown`-bearing guesses like `Array<unknown>`) never overwrites a known type — `Record<string, unknown>` IS a known type — and an overwrite never drops an optionality modifier.
+
 When inference fails the property's type falls back to `unknown` (or `any` in some Topologica paths) — safe, and you can refine manually.
 
 ### Referenced types in constructor signatures
 
-A constructor parameter that references a named type (`record: SharedShape`) resolves **through the importing file's own import statements** — relative and tsconfig-paths imports are followed to the declaration (chasing re-export barrels), and imported classes/interfaces/type aliases with extractable fields are expanded inline. An import is never shadowed by a same-named declaration elsewhere in the program. A reference that resolves not at all (a ghost name, declared nowhere) emits `unknown` — generated `.tactica/types.ts` carries no import statements of its own, so a bare unresolvable name is never emitted. A reference that resolves *ambiguously* — several of your project's files declare the name and no import chooses between them — is **fatal** like the mnemonica-graph identity law below: tactica prints the reference site and every declaration site, exits non-zero, and writes no output. An import anchoring the reference is never ambiguity (the import wins, duplicate declarations or not), and package-declared same-named types never count — a user-local declaration always wins over a node_modules `.d.ts`. Two same-named interfaces in one file are legal TypeScript merging, not ambiguity (see Known Limitations for the last-wins caveat).
+A constructor parameter that references a named type (`record: SharedShape`) resolves **through the importing file's own import statements** — relative and tsconfig-paths imports are followed to the declaration (chasing re-export barrels), and imported classes/interfaces/type aliases with extractable fields are expanded inline, **inherited members included**: `extends` chains are walked (depth-bounded, cycle-guarded) and parent fields merge with the declaration's own fields overriding on name clash. A field typed by a `typeof` query over a module-level const array (`status?: typeof statusList[number]`) expands to the element literal union (`status?: 'active' | 'closed'`); any other `typeof` source degrades that field to `unknown` — a bare `typeof name` is never emitted, since the generated file has no imports to resolve it against. An import is never shadowed by a same-named declaration elsewhere in the program. A reference that resolves not at all (a ghost name, declared nowhere) emits `unknown` — generated `.tactica/types.ts` carries no import statements of its own, so a bare unresolvable name is never emitted. A reference that resolves *ambiguously* — several of your project's files declare the name and no import chooses between them — is **fatal** like the mnemonica-graph identity law below: tactica prints the reference site and every declaration site, exits non-zero, and writes no output. An import anchoring the reference is never ambiguity (the import wins, duplicate declarations or not), and package-declared same-named types never count — a user-local declaration always wins over a node_modules `.d.ts`. Two same-named interfaces in one file are legal TypeScript merging, not ambiguity (see Known Limitations for the last-wins caveat).
 
 **Ambiguous plain-TypeScript reference — fails, and how to fix it.** Two plain interfaces named `SharedShape` exist in different files, and a third file references a bare `SharedShape` with nothing anchoring it:
 
@@ -939,6 +942,8 @@ Mnemonica accepts the `exposeInstanceMethods` option at runtime, but tactica's `
 
 The analyzer does not use `ts.Program.getTypeChecker()` for resolution. Plain TypeScript references in constructor signatures resolve through the importing file's import statements first, then its local declarations, and only then a unique same-named declaration across the scanned files — so a reference whose name is genuinely absent (or lives behind unresolvable specifiers) resolves to `unknown`, while a name several of your own files declare with no import to disambiguate fails hard (see above). References to mnemonica graph types follow the path-aware lookup law described above and fail hard instead of degrading to `unknown`.
 
+Two expansion boundaries stay name-based and deliberate: **heritage** — `extends` chains are walked through the same import-aware machinery (depth-capped, cycle-guarded), but bases that resolve to an external/node_modules declaration or to a non-identifier expression (mixin calls like `extends mixin(X)`) are not followed — their inherited fields simply stay absent, same as before the walk existed. And **`typeof` fields** — only module-level const arrays with statically visible literal elements expand to the literal union (cross-file only when the const is imported by the declaring file); every other `typeof` source degrades the field to `unknown`.
+
 ### Same-file interface merging is last-wins
 
 Two same-named interfaces in ONE module are legal TypeScript declaration merging, and tactica does not treat them as ambiguity (the fatal class is same-named declarations across several files, unanchored by an import). Resolution keeps a single declaration per name per file, and it is the last one — members from earlier declarations are not combined:

package/lib/analyzer.d.ts

@@ -37,6 +37,7 @@ export declare class MnemonicaAnalyzer {
     private referencedTypeNamespaces;
     private referencedTypeNamespaceStars;
     private referencedTypeResolutionCache;
+    private referencedTypeConstArrays;
     private referencedTypeCompilerOptions;
     private currentReferencedTypeFile;
     private expandingReferencedAliases;
@@ -117,6 +118,40 @@ export declare class MnemonicaAnalyzer {
      * interface) for the file currently being visited.
      */
     private trackReferencedTypeDeclaration;
+    /**
+     * Record consts initialized with an array literal (optionally wrapped in
+     * `as const` / `satisfies`), so a `typeof statusList[number]` field type
+     * expands to the element literal union — the generated file carries no
+     * imports, so emitting the bare `typeof statusList` query would be an
+     * unresolvable name downstream. First binding wins: a nested shadow
+     * must not replace the module-level const the typeof refers to.
+     */
+    private trackReferencedTypeConstArray;
+    /**
+     * Find the array literal behind a module const referenced through
+     * `typeof`: the declaring file's own consts first (the F13 case is a
+     * NON-exported const in the same module as the expanded class), then —
+     * when the file imports the name — the imported module's consts.
+     * External modules are never analyzed, so those yield nothing.
+     */
+    private findReferencedConstArray;
+    /**
+     * Element literal types of a tracked const array: every element must be
+     * a plain literal (optionally wrapped in `as const` / `satisfies`) —
+     * string, numeric, boolean, or null. Spreads, identifiers, and nested
+     * arrays mean the union is not statically visible and yield undefined,
+     * so the caller degrades the field to `unknown` rather than guessing.
+     */
+    private literalTypesOfArray;
+    /**
+     * Emit-type for `typeof name` when `name` is a tracked const array: the
+     * union of its element literal types (`'active' | 'closed'`). Every
+     * other typeof source — non-array consts, functions, classes, names not
+     * tracked at all — yields undefined, so the caller degrades the field
+     * to `unknown`: a bare `typeof name` emitted into types.ts has no
+     * import to resolve against downstream.
+     */
+    private typeOfConstArrayUnion;
     /**
      * Record the importing file's named/namespace/default import bindings so
      * referenced-type names resolve through the file's own import statements
@@ -162,8 +197,28 @@ export declare class MnemonicaAnalyzer {
     /**
      * Properties of a referenced class/interface/alias-of-literal declaration,
      * shared by `this:`-parameter expansion and inline type emission.
+     * Inherited members are included: the extends chain is walked
+     * (depth-capped, cycle-guarded) and parent fields merge first, the
+     * declaration's own fields overriding on name clash.
      */
     private referencedDeclarationProperties;
+    private referencedDeclarationPropertiesInner;
+    /**
+     * Property signatures of interface/alias type-literal members, into
+     * the given map.
+     */
+    private collectTypeElementProperties;
+    /**
+     * Resolve the heritage clause of a class (`extends Base`) or interface
+     * (`extends A, B`) to referenced-type declarations through the SAME
+     * import-aware machinery as plain references (the declaring file's own
+     * imports first, then its locals, then the unique program-wide
+     * declaration). Unresolvable or external bases yield nothing — their
+     * inherited fields simply stay absent, same as before this walk
+     * existed. Mixin calls (`extends mixin(X)`) and namespace access are
+     * not followed.
+     */
+    private resolveHeritageDeclarations;
     /**
      * Expand a referenced-type declaration to a self-contained type string
      * for emission into generated files: type aliases through inferType,