@mnemonica/tactica 0.1.15 → 0.2.0

package/README.md

@@ -134,8 +134,11 @@ Tactica writes everything under the `--output` directory (default `.tactica/`):
 | `index.ts` | default mode | Re-exports everything from `types.ts` and `registry.ts`. |
 | `index.d.ts` | with `--module-augmentation` | Single global-augmentation file (legacy mode). |
 | `definitions.json` | always | One entry per discovered type: `{ name, location, kind: 'define'\|'decorate', parent, strictChain, blockErrors }`. Consumed by `mnemographica`'s Go to Definition. |
-| `usages.json` | always | One entry per type, value is an array of `{ location, kind, code }` records — where each type is instantiated, referenced, accessed, or looked up. Consumed by `mnemographica`'s Find References. |
+| `usages.json` | always | One entry per type, value is an array of `{ location, kind, code, holderScopeId?, constructorText? }` records — where each type is instantiated, referenced, accessed, or looked up. `holderScopeId` points into `scopes.json` (the innermost scope holding the usage); `constructorText` (instantiations only) is the constructor expression text actually used. Consumed by `mnemographica`'s Find References. |
 | `flow.json` | always | Native instance-flow patterns (property reads/writes, method calls, destructuring, returns, spreads, etc.) per type. |
+| `instrumentation.json` | always | v2 envelope. `points`: framework lifecycle crossroads (interceptors, guards, pipes, filters, middleware) detected via **plugin-supplied vocabulary** — heritage declarations, decorator sites, provider-token registrations, `consumer.apply()` wiring. Syntactic only — no dive dependency; with no plugins loaded, `points` is `[]`. `creationGraph`: the inside-out walk from every instantiation site out to the starters — see "Creation graph" below. |
+| `modules.json` | always | Module-scope graph: every module's `exportedBindings`/`importedBindings` (functions, classes, consts, types — not only mnemonica types), project-internal `dependencies`, `builtinSpecifiers` (Node builtins are skipped entirely — both `'path'` and `'node:path'` forms), `unresolvedSpecifiers`, circular-import `cycles`, and cross-module mnemonica-type `edges`. Resolution uses `ts.resolveModuleName` with the project's compilerOptions (tsconfig `paths`, extensionless imports, index files) — no type checker. Bindings resolved into `node_modules` are marked `external: true` and never enter `dependencies`. |
+| `scopes.json` | always | Local-scope graph: function/method/arrow scopes only (no block scopes) plus one module scope per file; variables with `typePath` (mnemonica type when known), `isParameter`, `isMutable`, and `reassignments` — each reassignment of a mutable binding is a flow-termination point. |
 | `eds.json` | when EDS enabled | Execution-flow patterns (`wrap`, `current`, `getFlow`, `attachHooks` lifecycle wiring). Consumed by tools that visualize execution chains. |
 
 ### Default mode (types.ts + registry.ts)
@@ -474,7 +477,7 @@ When inference fails the property's type falls back to `unknown` (or `any` in so
 
 ```ts
 class MnemonicaAnalyzer {
-    constructor(program?: ts.Program);
+    constructor(program?: ts.Program, plugins?: TacticaPlugin[]);
 
     analyzeFile(sourceFile: ts.SourceFile): AnalyzeResult;
     analyzeSource(sourceCode: string, fileName?: string): AnalyzeResult;
@@ -487,6 +490,7 @@ class MnemonicaAnalyzer {
     getUsages():      Map<string, UsageInfo[]>;
     getEDSUsages():   Map<string, EDSInfo[]>;
     getFlowUsages():  Map<string, FlowInfo[]>;
+    getInstrumentationPoints(): InstrumentationPoint[];
 }
 ```
 
@@ -534,6 +538,61 @@ class TypesGenerator {
 }
 ```
 
+### `ModuleGraphBuilder`
+
+Module-scope walker. Tracks every export/import binding of every module —
+generically, not only mnemonica types — and resolves specifiers with
+`ts.resolveModuleName` driven by the program's compilerOptions
+(no `getTypeChecker()`).
+
+```ts
+class ModuleGraphBuilder {
+    constructor(program?: ts.Program, compilerOptions?: ts.CompilerOptions);
+
+    addFile(sourceFile: ts.SourceFile): ModuleInfo;   // call per file (definitions pass)
+    build(definedTypesByFile?: Map<string, string[]>): ModuleGraph;
+}
+```
+
+`ModuleGraph` = `{ modules: Map<absPath, ModuleInfo>, edges: CrossModuleUsage[], cycles: string[][] }`.
+Each `ModuleBinding` carries `{ name, kind: 'function'|'class'|'const'|'type'|'unknown',
+sourceModule (resolved absolute path), importKind?, importAlias?, isReExport, external? }`.
+Node.js builtins (`'path'`, `'node:fs'`, …) are skipped entirely and recorded
+only in the module's `builtinSpecifiers`; bindings resolved into `node_modules`
+carry `external: true` and never enter `dependencies`. Re-export chains
+(barrels, `export * from`) are chased to the origin module when producing
+`edges`; circular imports are recorded in `cycles`, never treated as errors.
+Unused-export detection is internal only — nothing about it is emitted.
+
+### `LocalScopeWalker`
+
+Local-scope walker. Tracks function/method/arrow scopes only (no block
+scopes), plus one synthetic module scope per file. Variables carry
+`isParameter`, `isMutable` (const vs let/var; `this` parameters are
+immutable), and `reassignments` — every reassignment site of a mutable
+binding is a flow-termination point where downstream walking stops.
+
+```ts
+class LocalScopeWalker {
+    addFile(sourceFile: ts.SourceFile): void;         // call per file
+    build(resolver?: ScopeTypeResolver): ScopeAnalysis;
+    findHolderScopeId(location: string): string | undefined;
+
+    static attachHolderScopeIds(usages: Map<string, UsageInfo[]>, walker: LocalScopeWalker): void;
+}
+
+interface ScopeTypeResolver {
+    resolveByName(name: string): string | undefined;  // bare name → mnemonica fullPath
+    hasPath(fullPath: string): boolean;
+}
+```
+
+`ScopeAnalysis` = `{ scopes: Map<scopeId, ScopeInfo>, variables: Map<'scopeId#name', ScopeVariable> }`.
+Scope ids: module scope = file path; function scopes = `file:line:col`.
+Labels: functions by name, methods as `Class.method`, arrows by the binding
+they are assigned to, anonymous holders as `file:line`. Never relies on
+`node.parent` (program files can be unbound).
+
 ### `TypesWriter`
 
 ```ts
@@ -548,6 +607,9 @@ class TypesWriter {
     writeUsagesFile     (map: Map<string, UsageInfo[]>):    string; // → outputDir/usages.json
     writeEDSFile        (map: Map<string, EDSInfo[]>):      string; // → outputDir/eds.json
     writeFlowFile       (map: Map<string, FlowInfo[]>):     string; // → outputDir/flow.json
+    writeInstrumentationFile(points: InstrumentationPoint[], creationGraph?: CreationGraph): string; // → outputDir/instrumentation.json
+    writeModulesFile      (graph: ModuleGraph):             string; // → outputDir/modules.json
+    writeScopesFile       (analysis: ScopeAnalysis):        string; // → outputDir/scopes.json
 
     write(generated: GeneratedTypes): string; // legacy alias for writeTypesFile
     clean(): void;
@@ -557,7 +619,7 @@ class TypesWriter {
 
 ### Types
 
-`TacticaConfig`, `TypeNode`, `TypeGraph`, `PropertyInfo`, `ConstructorParamInfo`, `AnalyzeResult`, `AnalyzeError`, `GeneratedTypes`, `DefinitionInfo`, `UsageInfo`, `UsagesJson`, `DefinitionsJson`, `EDSInfo`, `EDSJson`, `EDSKind`, `FlowInfo`, `FlowJson`, `FlowKind` — all exported from `@mnemonica/tactica`. See [`src/types.ts`](src/types.ts) for the full schema.
+`TacticaConfig`, `TypeNode`, `TypeGraph`, `PropertyInfo`, `ConstructorParamInfo`, `AnalyzeResult`, `AnalyzeError`, `GeneratedTypes`, `DefinitionInfo`, `UsageInfo`, `UsagesJson`, `DefinitionsJson`, `EDSInfo`, `EDSJson`, `EDSKind`, `FlowInfo`, `FlowJson`, `FlowKind`, `InstrumentationKind`, `InstrumentationScope`, `InstrumentationPoint`, `InstrumentationJson`, `ModuleBindingKind`, `ModuleImportKind`, `ModuleBinding`, `ModuleInfo`, `CrossModuleUsage`, `ModuleGraph`, `ModulesJson`, `ScopeKind`, `ScopeInfo`, `ScopeVariable`, `ScopeAnalysis`, `ScopesJson`, `CreationGraphNode`, `CreationGraphEdge`, `CreationAnchor`, `CreationGraph`, `TacticaPlugin`, `InstrumentationVocabulary` — all exported from `@mnemonica/tactica`. See [`src/types.ts`](src/types.ts) for the full schema. The `mergeTacticaPlugins(plugins)` helper merges plugin vocabulary the same way the analyzer does.
 
 ## EDS (Execution Data Storage) Tracking
 
@@ -567,7 +629,7 @@ When enabled, tactica detects execution-flow patterns alongside type definitions
 |---|---|---|
 | `wrap(fn)`, `wrapConstructorArg(fn, parent)`, `upgradeConstructorArg(arg, inst)`, `wrapInstanceMethods(obj)` | `wrap` | Wrap a function / constructor argument / instance methods for context propagation and tracing (`@mnemonica/dive`) |
 | `current()`, `getErrorInstance(err)`, `getFlow(target?)` | `contextConsume` | Read the current context, the error-pinned instance, or the recorded flow (`@mnemonica/dive`) |
-| `attachHooks(collection)` | `hookAttach` | Wire a TypesCollection to dive's lifecycle tracing (`@mnemonica/nestjs`) |
+| `attachHooks(collection)` | `hookAttach` | Wire a TypesCollection to dive's lifecycle tracing (`@mnemonica/otel`) |
 
 `eds.json` structure:
 
@@ -588,12 +650,110 @@ When enabled, tactica detects execution-flow patterns alongside type definitions
 }
 ```
 
+`wrap` entries additionally carry graph-join fields (all optional, additive):
+
+- `label` — the label string literal of `wrap(fn, …, 'label')` when statically visible.
+- `callbackScopeId` — the scopeId (scopes.json) of the wrapped callback's own scope; the callback is what the wrapper runs, so graph consumers join on it first.
+- `instanceArg` — the identifier passed as the instance/context argument (`user` in `wrap(fn, user)`), when it is one.
+- `scopeId` — the scopeId of the scope holding the wrap call site (fallback join).
+- `wrapsTypePath` — the mnemonica fullPath of the instance argument, resolved through the scope-variable chain (innermost binding wins; an untyped local shadows a typed outer one rather than being guessed).
+- `via` — the location of the enclosing wrap site when the call is nested inside another wrapped body (or returns a function): the wrappers-graph generation chain is built from it.
+
+## Instrumentation Points
+
+Tactica statically detects framework lifecycle crossroads — interceptors, guards, pipes, exception filters, middleware — purely syntactically (no type checker), and always emits `.tactica/instrumentation.json`. **Tactica core ships no framework vocabulary**: detection is driven entirely by plugins, so with no plugins loaded `points` is `[]`. Framework adapters ship a plugin; projects enable it through a `.tactica.js` (or `tactica.config.js`) config file next to `tsconfig.json`:
+
+```js
+// .tactica.js
+module.exports = {
+    plugins: [ '@mnemonica/example-adapter/tactica' ],
+};
+```
+
+Plugin entries are module specifiers (required relative to the config file) or inline plugin objects. A plugin is a plain object:
+
+```ts
+interface TacticaPlugin {
+    name?: string;
+    // `implements X` heritage matches: interface identifier -> kind
+    instrumentationInterfaces?: Record<string, InstrumentationKind>;
+    // `@X(Impl)` decorator sites: decorator identifier -> kind
+    useDecorators?: Record<string, InstrumentationKind>;
+    // `{ provide: TOKEN, useClass: Impl }` registrations: token identifier -> kind
+    appTokens?: Record<string, InstrumentationKind>;
+    // opt in to shape-based `consumer.apply(Mw).forRoutes(...)` detection
+    middlewareWiring?: boolean;
+}
+```
+
+Programmatic callers pass plugins directly: `new MnemonicaAnalyzer(program, plugins)` or `run({ …, plugins })`; config-file plugins append after programmatic ones, and later plugins override earlier ones on the same identifier key. Detection covers:
+
+- **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 or methods, including inline instances (`@Register(new Impl(…))`). One point per referenced class; scope is `controller:<Name>` or `method:<Class>.<method>`.
+- **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.
+
+When a referenced class is declared in the analyzed project, the point's `location`/`code` resolve to the class declaration; external classes keep the registration site. Points are deduped by `(kind, className, location, scope)` with `targets` merged — a class seen via both heritage and a decorator yields separate entries per scope, with the bare declaration carrying scope `module`.
+
+`instrumentation.json` structure (v2):
+
+```json
+{
+    "version": 2,
+    "generatedAt": "2026-09-04T…",
+    "points": [
+        {
+            "kind": "pipe",
+            "className": "PayloadPipe",
+            "location": "/project/src/user.controller.ts:49:2",
+            "code": "@RegisterPipe(new PayloadPipe({ transform: true }))",
+            "scope": "method:UserController.createUser",
+            "targets": ["UserController"]
+        }
+    ],
+    "creationGraph": {
+        "nodes": [
+            {
+                "scopeId": "/project/src/main.ts",
+                "name": "/project/src/main.ts",
+                "kind": "module",
+                "filePath": "/project/src/main.ts",
+                "location": "/project/src/main.ts:1:1",
+                "starter": true
+            }
+        ],
+        "edges": [
+            { "caller": "/project/src/main.ts", "callee": "/project/src/user.service.ts:26:2" }
+        ],
+        "anchors": [
+            {
+                "location": "/project/src/user.service.ts:29:24",
+                "holderScopeId": "/project/src/user.service.ts:26:2",
+                "typePath": "UserEntity.UserResponse",
+                "constructorText": "user.UserResponse",
+                "variable": "userResponse"
+            }
+        ]
+    }
+}
+```
+
+## Creation graph (inside-out walk)
+
+The `creationGraph` key is the third phase of the instrumentation walker: it starts at the certain points — every `usages.json` `instantiation` entry (each carries a `holderScopeId` into `scopes.json`) — and walks **outward**: who invokes or references the holder function, crossing files through `modules.json` (re-export barrels chased to the origin module), until no callers remain. Terminals are the **starters** (application entry points); the walk never assumes a linear type Trie (mnemonica `strictChain: false` permits cycles and out-of-order construction), so traversal is cycle-guarded and every anchor records the constructor expression actually used.
+
+- **Nodes** are scopes (`module` / `function` / `method` / `arrow`), labeled like `scopes.json`; `starter: true` marks nodes with no discovered callers.
+- **Edges** point `caller → callee`, where the callee is closer to the creation site.
+- **Anchors** pin each creation site to its holder scope: `typePath`, the `constructorText` used, `rooted: true` for module-scope creations (a legitimate root or a developer error — labeled, not policed), and a `variable`/`terminatedAt` pair from a documented heuristic: the variable declared in the holder scope on the same line as the creation (typePath must match when known), with `terminatedAt` being that variable's first reassignment site — the flow-termination point where the walk stops following the binding.
+
+Deliberate approximations (name-based, no type checker): namespace imports count any reference to the alias once the namespace's module exposes the holder's export; method holders bind to their **class** name (that is what callers reference); any non-declaration identifier counts as a reference. Export wiring alone (`export { f }`, `export default f`) is not a caller — an importer's usage creates the edge.
+
 ## How It Works
 
 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`, `flow.json`, 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`, and optionally `eds.json`.
 5. **Write** — files land in the output directory (default `.tactica/`).
 
 ```

package/lib/analyzer.d.ts

@@ -1,8 +1,13 @@
 import * as ts from 'typescript';
-import { AnalyzeResult, DefinitionInfo, UsageInfo, EDSInfo, FlowInfo } from './types';
+import { AnalyzeResult, DefinitionInfo, UsageInfo, EDSInfo, FlowInfo, InstrumentationPoint } from './types';
 import { TypeGraphImpl } from './graph';
+import { TacticaPlugin } from './plugins';
 /**
  * AST Analyzer for finding Mnemonica define() and decorate() calls
+ *
+ * Framework-blind by construction: instrumentation detection vocabulary
+ * (interface names, decorator names, provider tokens, middleware wiring)
+ * comes entirely from plugins — with none loaded, zero points are collected.
  */
 export declare class MnemonicaAnalyzer {
     private errors;
@@ -22,7 +27,10 @@ export declare class MnemonicaAnalyzer {
     private collectionVariables;
     private collectionInfo;
     private collectionCounter;
-    constructor(program?: ts.Program);
+    private instrumentationClassDecls;
+    private instrumentationSites;
+    private instrumentationVocabulary;
+    constructor(program?: ts.Program, plugins?: TacticaPlugin[]);
     /**
      * Reset usage-related state for a fresh pass.
      * Call before the usage-collection pass to avoid duplicates from definition pass.
@@ -56,6 +64,17 @@ export declare class MnemonicaAnalyzer {
      * Get collected flow usages
      */
     getFlowUsages(): Map<string, FlowInfo[]>;
+    /**
+     * Get collected instrumentation points.
+     * Registration sites referencing a class declared in the same project
+     * resolve to the class declaration's location/code; external classes
+     * (e.g., a framework-builtin implementation from node_modules) keep
+     * the registration site.
+     * Deduped by kind+className+location+scope with targets merged — a
+     * class detected by heritage AND by a decorator site yields separate
+     * entries with distinct scopes (see InstrumentationPoint in types.ts).
+     */
+    getInstrumentationPoints(): InstrumentationPoint[];
     /**
      * Add a topologica type to the analyzer for usage tracking.
      * This allows the analyzer to recognize topologica types when collecting usages.
@@ -462,4 +481,42 @@ export declare class MnemonicaAnalyzer {
              * Extract constructor parameters from a constructor expression.
              */
     private extractConstructorParamsFromConstructor;
+    /**
+     * Collect framework instrumentation points. Purely syntactic: heritage
+     * clauses, decorator application sites, provider-token object literals
+     * and consumer.apply().forRoutes() wiring. The vocabulary comes from
+     * plugins; identifier text is matched as-is — no import resolution,
+     * the type checker stays unused.
+     */
+    private collectInstrumentation;
+    /**
+     * Record a named class declaration for instrumentation site resolution
+     * and detect heritage-based kinds (`implements <plugin interface>`)
+     */
+    private collectInstrumentationClass;
+    /**
+     * Detect decorator application sites: plugin-listed decorators applied
+     * with class arguments on a class or one of its methods. One site per
+     * referenced class identifier.
+     */
+    private collectInstrumentationDecorator;
+    /**
+     * Detect global registrations: object literals shaped like
+     * `{ provide: <plugin-listed token>, useClass: X }`.
+     * useExisting/useFactory without a useClass identifier are not
+     * statically obvious — skipped rather than guessed.
+     */
+    private collectInstrumentationProvider;
+    /**
+     * Detect middleware wiring: `consumer.apply(Mw1, Mw2).forRoutes(...)`
+     * inside a class's configure() method. Targets come from forRoutes
+     * arguments when statically readable (string routes or controller
+     * identifiers), else []. Shape-based, so a plugin must opt in via
+     * `middlewareWiring: true`.
+     */
+    private collectInstrumentationMiddleware;
+    /**
+     * Walk up the parent chain looking for an enclosing configure() method
+     */
+    private isInsideConfigureMethod;
 }