@mnemonica/tactica 0.1.15 → 0.2.0

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Tactica - TypeScript Language Service Plugin for Mnemonica
+ * Tactica - Type definition generator for Mnemonica
  *
  * Generates type definitions for Mnemonica's dynamic nested constructors,
  * enabling TypeScript to understand runtime type hierarchies created through
@@ -10,6 +10,12 @@ export { TopologicaAnalyzer } from './topologica-analyzer';
 export { TypeGraphImpl } from './graph';
 export { TypesGenerator } from './generator';
 export { TypesWriter } from './writer';
-export type { TacticaConfig, TypeNode, TypeGraph, PropertyInfo, AnalyzeResult, AnalyzeError, GeneratedTypes, DefinitionInfo, UsageInfo, DefinitionsJson, UsagesJson, } from './types';
+export { ModuleGraphBuilder } from './module-graph';
+export { LocalScopeWalker } from './scopes';
+export type { ScopeTypeResolver } from './scopes';
+export { CreationGraphBuilder } from './creation-graph';
+export { mergeTacticaPlugins } from './plugins';
+export type { TacticaPlugin, InstrumentationVocabulary } from './plugins';
+export type { TacticaConfig, TypeNode, TypeGraph, PropertyInfo, AnalyzeResult, AnalyzeError, GeneratedTypes, DefinitionInfo, UsageInfo, DefinitionsJson, UsagesJson, InstrumentationKind, InstrumentationScope, InstrumentationPoint, InstrumentationJson, ModuleBindingKind, ModuleImportKind, ModuleBinding, ModuleInfo, CrossModuleUsage, ModuleGraph, ModulesJson, ScopeKind, ScopeInfo, ScopeVariable, ScopeAnalysis, ScopesJson, CreationGraphNode, CreationGraphEdge, CreationAnchor, CreationGraph, } from './types';
 export { main, run, watch, parseArgs } from './cli';
 export declare const VERSION: string;

package/lib/index.js

@@ -33,10 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.parseArgs = exports.watch = exports.run = exports.main = exports.TypesWriter = exports.TypesGenerator = exports.TypeGraphImpl = exports.TopologicaAnalyzer = exports.MnemonicaAnalyzer = void 0;
+exports.VERSION = exports.parseArgs = exports.watch = exports.run = exports.main = exports.mergeTacticaPlugins = exports.CreationGraphBuilder = exports.LocalScopeWalker = exports.ModuleGraphBuilder = exports.TypesWriter = exports.TypesGenerator = exports.TypeGraphImpl = exports.TopologicaAnalyzer = exports.MnemonicaAnalyzer = void 0;
 const pkg = __importStar(require("../package.json"));
 /**
- * Tactica - TypeScript Language Service Plugin for Mnemonica
+ * Tactica - Type definition generator for Mnemonica
  *
  * Generates type definitions for Mnemonica's dynamic nested constructors,
  * enabling TypeScript to understand runtime type hierarchies created through
@@ -52,6 +52,14 @@ var generator_1 = require("./generator");
 Object.defineProperty(exports, "TypesGenerator", { enumerable: true, get: function () { return generator_1.TypesGenerator; } });
 var writer_1 = require("./writer");
 Object.defineProperty(exports, "TypesWriter", { enumerable: true, get: function () { return writer_1.TypesWriter; } });
+var module_graph_1 = require("./module-graph");
+Object.defineProperty(exports, "ModuleGraphBuilder", { enumerable: true, get: function () { return module_graph_1.ModuleGraphBuilder; } });
+var scopes_1 = require("./scopes");
+Object.defineProperty(exports, "LocalScopeWalker", { enumerable: true, get: function () { return scopes_1.LocalScopeWalker; } });
+var creation_graph_1 = require("./creation-graph");
+Object.defineProperty(exports, "CreationGraphBuilder", { enumerable: true, get: function () { return creation_graph_1.CreationGraphBuilder; } });
+var plugins_1 = require("./plugins");
+Object.defineProperty(exports, "mergeTacticaPlugins", { enumerable: true, get: function () { return plugins_1.mergeTacticaPlugins; } });
 // CLI entry point
 var cli_1 = require("./cli");
 Object.defineProperty(exports, "main", { enumerable: true, get: function () { return cli_1.main; } });
@@ -60,4 +68,4 @@ Object.defineProperty(exports, "watch", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "parseArgs", { enumerable: true, get: function () { return cli_1.parseArgs; } });
 // Version from package.json
 exports.VERSION = pkg.version;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsWUFBWSxDQUFDOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFFYixxREFBdUM7QUFFdkM7Ozs7OztHQU1HO0FBRUgsdUNBQStDO0FBQXRDLDZHQUFBLGlCQUFpQixPQUFBO0FBQzFCLDZEQUEyRDtBQUFsRCx5SEFBQSxrQkFBa0IsT0FBQTtBQUMzQixpQ0FBd0M7QUFBL0Isc0dBQUEsYUFBYSxPQUFBO0FBQ3RCLHlDQUE2QztBQUFwQywyR0FBQSxjQUFjLE9BQUE7QUFDdkIsbUNBQXVDO0FBQTlCLHFHQUFBLFdBQVcsT0FBQTtBQWlCcEIsa0JBQWtCO0FBQ2xCLDZCQUVlO0FBRGQsMkZBQUEsSUFBSSxPQUFBO0FBQUUsMEZBQUEsR0FBRyxPQUFBO0FBQUUsNEZBQUEsS0FBSyxPQUFBO0FBQUUsZ0dBQUEsU0FBUyxPQUFBO0FBRzVCLDRCQUE0QjtBQUNmLFFBQUEsT0FBTyxHQUFHLEdBQUcsQ0FBQyxPQUFPLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIndXNlIHN0cmljdCc7XG5cbmltcG9ydCAqIGFzIHBrZyBmcm9tICcuLi9wYWNrYWdlLmpzb24nO1xuXG4vKipcbiAqIFRhY3RpY2EgLSBUeXBlU2NyaXB0IExhbmd1YWdlIFNlcnZpY2UgUGx1Z2luIGZvciBNbmVtb25pY2FcbiAqXG4gKiBHZW5lcmF0ZXMgdHlwZSBkZWZpbml0aW9ucyBmb3IgTW5lbW9uaWNhJ3MgZHluYW1pYyBuZXN0ZWQgY29uc3RydWN0b3JzLFxuICogZW5hYmxpbmcgVHlwZVNjcmlwdCB0byB1bmRlcnN0YW5kIHJ1bnRpbWUgdHlwZSBoaWVyYXJjaGllcyBjcmVhdGVkIHRocm91Z2hcbiAqIGRlZmluZSgpIGFuZCBkZWNvcmF0ZSgpIGNhbGxzLlxuICovXG5cbmV4cG9ydCB7IE1uZW1vbmljYUFuYWx5emVyIH0gZnJvbSAnLi9hbmFseXplcic7XG5leHBvcnQgeyBUb3BvbG9naWNhQW5hbHl6ZXIgfSBmcm9tICcuL3RvcG9sb2dpY2EtYW5hbHl6ZXInO1xuZXhwb3J0IHsgVHlwZUdyYXBoSW1wbCB9IGZyb20gJy4vZ3JhcGgnO1xuZXhwb3J0IHsgVHlwZXNHZW5lcmF0b3IgfSBmcm9tICcuL2dlbmVyYXRvcic7XG5leHBvcnQgeyBUeXBlc1dyaXRlciB9IGZyb20gJy4vd3JpdGVyJztcblxuXG5leHBvcnQgdHlwZSB7XG5cdFRhY3RpY2FDb25maWcsXG5cdFR5cGVOb2RlLFxuXHRUeXBlR3JhcGgsXG5cdFByb3BlcnR5SW5mbyxcblx0QW5hbHl6ZVJlc3VsdCxcblx0QW5hbHl6ZUVycm9yLFxuXHRHZW5lcmF0ZWRUeXBlcyxcblx0RGVmaW5pdGlvbkluZm8sXG5cdFVzYWdlSW5mbyxcblx0RGVmaW5pdGlvbnNKc29uLFxuXHRVc2FnZXNKc29uLFxufSBmcm9tICcuL3R5cGVzJztcblxuLy8gQ0xJIGVudHJ5IHBvaW50XG5leHBvcnQge1xuXHRtYWluLCBydW4sIHdhdGNoLCBwYXJzZUFyZ3MgXG59IGZyb20gJy4vY2xpJztcblxuLy8gVmVyc2lvbiBmcm9tIHBhY2thZ2UuanNvblxuZXhwb3J0IGNvbnN0IFZFUlNJT04gPSBwa2cudmVyc2lvbjtcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsWUFBWSxDQUFDOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFFYixxREFBdUM7QUFFdkM7Ozs7OztHQU1HO0FBRUgsdUNBQStDO0FBQXRDLDZHQUFBLGlCQUFpQixPQUFBO0FBQzFCLDZEQUEyRDtBQUFsRCx5SEFBQSxrQkFBa0IsT0FBQTtBQUMzQixpQ0FBd0M7QUFBL0Isc0dBQUEsYUFBYSxPQUFBO0FBQ3RCLHlDQUE2QztBQUFwQywyR0FBQSxjQUFjLE9BQUE7QUFDdkIsbUNBQXVDO0FBQTlCLHFHQUFBLFdBQVcsT0FBQTtBQUNwQiwrQ0FBb0Q7QUFBM0Msa0hBQUEsa0JBQWtCLE9BQUE7QUFDM0IsbUNBQTRDO0FBQW5DLDBHQUFBLGdCQUFnQixPQUFBO0FBRXpCLG1EQUF3RDtBQUEvQyxzSEFBQSxvQkFBb0IsT0FBQTtBQUM3QixxQ0FBZ0Q7QUFBdkMsOEdBQUEsbUJBQW1CLE9BQUE7QUF3QzVCLGtCQUFrQjtBQUNsQiw2QkFFZTtBQURkLDJGQUFBLElBQUksT0FBQTtBQUFFLDBGQUFBLEdBQUcsT0FBQTtBQUFFLDRGQUFBLEtBQUssT0FBQTtBQUFFLGdHQUFBLFNBQVMsT0FBQTtBQUc1Qiw0QkFBNEI7QUFDZixRQUFBLE9BQU8sR0FBRyxHQUFHLENBQUMsT0FBTyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiJ3VzZSBzdHJpY3QnO1xuXG5pbXBvcnQgKiBhcyBwa2cgZnJvbSAnLi4vcGFja2FnZS5qc29uJztcblxuLyoqXG4gKiBUYWN0aWNhIC0gVHlwZSBkZWZpbml0aW9uIGdlbmVyYXRvciBmb3IgTW5lbW9uaWNhXG4gKlxuICogR2VuZXJhdGVzIHR5cGUgZGVmaW5pdGlvbnMgZm9yIE1uZW1vbmljYSdzIGR5bmFtaWMgbmVzdGVkIGNvbnN0cnVjdG9ycyxcbiAqIGVuYWJsaW5nIFR5cGVTY3JpcHQgdG8gdW5kZXJzdGFuZCBydW50aW1lIHR5cGUgaGllcmFyY2hpZXMgY3JlYXRlZCB0aHJvdWdoXG4gKiBkZWZpbmUoKSBhbmQgZGVjb3JhdGUoKSBjYWxscy5cbiAqL1xuXG5leHBvcnQgeyBNbmVtb25pY2FBbmFseXplciB9IGZyb20gJy4vYW5hbHl6ZXInO1xuZXhwb3J0IHsgVG9wb2xvZ2ljYUFuYWx5emVyIH0gZnJvbSAnLi90b3BvbG9naWNhLWFuYWx5emVyJztcbmV4cG9ydCB7IFR5cGVHcmFwaEltcGwgfSBmcm9tICcuL2dyYXBoJztcbmV4cG9ydCB7IFR5cGVzR2VuZXJhdG9yIH0gZnJvbSAnLi9nZW5lcmF0b3InO1xuZXhwb3J0IHsgVHlwZXNXcml0ZXIgfSBmcm9tICcuL3dyaXRlcic7XG5leHBvcnQgeyBNb2R1bGVHcmFwaEJ1aWxkZXIgfSBmcm9tICcuL21vZHVsZS1ncmFwaCc7XG5leHBvcnQgeyBMb2NhbFNjb3BlV2Fsa2VyIH0gZnJvbSAnLi9zY29wZXMnO1xuZXhwb3J0IHR5cGUgeyBTY29wZVR5cGVSZXNvbHZlciB9IGZyb20gJy4vc2NvcGVzJztcbmV4cG9ydCB7IENyZWF0aW9uR3JhcGhCdWlsZGVyIH0gZnJvbSAnLi9jcmVhdGlvbi1ncmFwaCc7XG5leHBvcnQgeyBtZXJnZVRhY3RpY2FQbHVnaW5zIH0gZnJvbSAnLi9wbHVnaW5zJztcbmV4cG9ydCB0eXBlIHtcblx0VGFjdGljYVBsdWdpbiwgSW5zdHJ1bWVudGF0aW9uVm9jYWJ1bGFyeVxufSBmcm9tICcuL3BsdWdpbnMnO1xuXG5cbmV4cG9ydCB0eXBlIHtcblx0VGFjdGljYUNvbmZpZyxcblx0VHlwZU5vZGUsXG5cdFR5cGVHcmFwaCxcblx0UHJvcGVydHlJbmZvLFxuXHRBbmFseXplUmVzdWx0LFxuXHRBbmFseXplRXJyb3IsXG5cdEdlbmVyYXRlZFR5cGVzLFxuXHREZWZpbml0aW9uSW5mbyxcblx0VXNhZ2VJbmZvLFxuXHREZWZpbml0aW9uc0pzb24sXG5cdFVzYWdlc0pzb24sXG5cdEluc3RydW1lbnRhdGlvbktpbmQsXG5cdEluc3RydW1lbnRhdGlvblNjb3BlLFxuXHRJbnN0cnVtZW50YXRpb25Qb2ludCxcblx0SW5zdHJ1bWVudGF0aW9uSnNvbixcblx0TW9kdWxlQmluZGluZ0tpbmQsXG5cdE1vZHVsZUltcG9ydEtpbmQsXG5cdE1vZHVsZUJpbmRpbmcsXG5cdE1vZHVsZUluZm8sXG5cdENyb3NzTW9kdWxlVXNhZ2UsXG5cdE1vZHVsZUdyYXBoLFxuXHRNb2R1bGVzSnNvbixcblx0U2NvcGVLaW5kLFxuXHRTY29wZUluZm8sXG5cdFNjb3BlVmFyaWFibGUsXG5cdFNjb3BlQW5hbHlzaXMsXG5cdFNjb3Blc0pzb24sXG5cdENyZWF0aW9uR3JhcGhOb2RlLFxuXHRDcmVhdGlvbkdyYXBoRWRnZSxcblx0Q3JlYXRpb25BbmNob3IsXG5cdENyZWF0aW9uR3JhcGgsXG59IGZyb20gJy4vdHlwZXMnO1xuXG4vLyBDTEkgZW50cnkgcG9pbnRcbmV4cG9ydCB7XG5cdG1haW4sIHJ1biwgd2F0Y2gsIHBhcnNlQXJncyBcbn0gZnJvbSAnLi9jbGknO1xuXG4vLyBWZXJzaW9uIGZyb20gcGFja2FnZS5qc29uXG5leHBvcnQgY29uc3QgVkVSU0lPTiA9IHBrZy52ZXJzaW9uO1xuIl19

package/lib/module-graph.d.ts

@@ -0,0 +1,109 @@
+import * as ts from 'typescript';
+import { ModuleGraph, ModuleInfo } from './types';
+/**
+ * Module-scope walker (instrumentation walker plan, Phase 1).
+ *
+ * Builds the cross-file module graph: every export/import binding (functions,
+ * classes, consts, types — not only mnemonica types), resolved with
+ * `ts.resolveModuleName` driven by the program's compilerOptions (tsconfig
+ * `paths`, extensionless imports, index files). This is module resolution,
+ * NOT the type checker — the no-`getTypeChecker()` precedent stays intact.
+ *
+ * Usage: addFile() per source file during the definitions pass, then
+ * build(definedTypesByFile) once definitions are known.
+ */
+export declare class ModuleGraphBuilder {
+    private compilerOptions;
+    private modules;
+    private localDecls;
+    private importSites;
+    private resolutionCache;
+    constructor(program?: ts.Program, compilerOptions?: ts.CompilerOptions);
+    /**
+     * Track one source file. Re-adding the same file replaces its record,
+     * so a builder may safely be reused across passes.
+     */
+    addFile(sourceFile: ts.SourceFile): ModuleInfo;
+    /**
+     * Resolve all specifiers, backfill binding kinds from origin modules,
+     * derive dependencies, cross-module mnemonica-type edges, and cycles.
+     * `definedTypesByFile` maps absolute file path -> mnemonica type fullPaths
+     * defined there (from the analyzer's definitions).
+     */
+    build(definedTypesByFile?: Map<string, string[]>): ModuleGraph;
+    /**
+     * Resolve a specifier to an absolute file path via ts.resolveModuleName
+     * with the program's compilerOptions. Returns undefined on failure.
+     */
+    private resolveModule;
+    /**
+     * True for Node.js builtins in both bare and `node:`-prefixed forms
+     * ('path', 'node:path', 'fs/promises', 'node:fs/promises', …).
+     */
+    private static isBuiltinSpecifier;
+    /**
+     * Record a builtin import on the module (honesty marker) and skip it
+     * entirely: no bindings, no site, no dependency, no edge.
+     * Returns true when the specifier was a builtin (caller must return early).
+     */
+    private static skipBuiltin;
+    /**
+     * Chase a binding to the module that actually declares it, following
+     * re-export chains (barrels). Cycle-guarded. Returns undefined when the
+     * origin is external or the chain loops.
+     */
+    private resolveOrigin;
+    /**
+     * Match a binding against a module's defined mnemonica types.
+     * Returns the matched fullPath, or undefined when the binding is not a
+     * mnemonica type of that module.
+     */
+    private matchDefinedType;
+    /**
+     * Three-color DFS over project-internal dependencies. Cycles are recorded
+     * (mnemonica strictChain:false permits non-linear construction), never
+     * treated as errors.
+     */
+    private detectCycles;
+    /**
+     * Rotation-independent cycle key: smallest path first.
+     */
+    private static cycleKey;
+    /**
+     * Pass 1: record every named top-level declaration's kind.
+     */
+    private collectLocalDecl;
+    /**
+     * Classify a variable declaration: arrow/function initializers are
+     * 'function' (holder functions the walker follows), class expressions
+     * are 'class', everything else is 'const'.
+     */
+    private static variableKind;
+    /**
+     * Pass 2: imports, exports, requires, exported declarations.
+     */
+    private processStatement;
+    private processImport;
+    private processExportDeclaration;
+    /**
+     * `import foo = require('./y')`
+     */
+    private processImportEquals;
+    /**
+     * `export default <expression>`
+     */
+    private processExportAssignment;
+    /**
+     * `export function/class/const/interface/type …` declarations.
+     */
+    private processMaybeExportedDecl;
+    /**
+     * CommonJS `const x = require('./y')` (JS sources with allowJs).
+     */
+    private processRequireCall;
+    /**
+     * Format a node's position as file.ts:Line:Col (1-based), matching the
+     * location format of the other .tactica outputs.
+     */
+    private locationOf;
+}