@mnemonica/tactica 0.1.15 → 0.3.0

package/lib/plugins.d.ts

@@ -0,0 +1,44 @@
+import { InstrumentationKind } from './types';
+/**
+ * Tactica plugin: supplies the framework vocabulary the analyzer matches
+ * syntactically. Tactica core is framework-blind — with no plugins loaded
+ * it detects no instrumentation points at all. Framework adapters (e.g. a
+ * server-framework integration package) ship a plugin; projects enable it
+ * through a `.tactica.js` / `tactica.config.js` config file.
+ *
+ * All keys are matched by identifier TEXT only (no import resolution, no
+ * type checker), so a plugin entry fires on any same-named identifier.
+ */
+export interface TacticaPlugin {
+    /** Plugin name, used in verbose logging */
+    name?: string;
+    /** Heritage interface identifier -> kind (`implements X`) */
+    instrumentationInterfaces?: Record<string, InstrumentationKind>;
+    /** Decorator identifier -> kind (`@X(Impl)` on classes/methods) */
+    useDecorators?: Record<string, InstrumentationKind>;
+    /** Provider token identifier -> kind (`{ provide: TOKEN, useClass: X }`) */
+    appTokens?: Record<string, InstrumentationKind>;
+    /**
+     * Enable middleware wiring detection: `consumer.apply(Mw).forRoutes(...)`
+     * inside a `configure()` method. Shape-based (no vocabulary keys), so it
+     * is opt-in per plugin.
+     */
+    middlewareWiring?: boolean;
+}
+/**
+ * The analyzer's merged view of all loaded plugins: one lookup table per
+ * detection channel, plus the middleware-wiring switch.
+ */
+export interface InstrumentationVocabulary {
+    interfaces: Record<string, InstrumentationKind>;
+    useDecorators: Record<string, InstrumentationKind>;
+    appTokens: Record<string, InstrumentationKind>;
+    middlewareWiring: boolean;
+}
+/**
+ * Merge plugins into one vocabulary. Later plugins override earlier ones on
+ * the same identifier key; middlewareWiring is an OR (any plugin enables it).
+ * An empty plugin list yields an empty vocabulary — the analyzer then
+ * collects zero instrumentation points.
+ */
+export declare function mergeTacticaPlugins(plugins: TacticaPlugin[]): InstrumentationVocabulary;

package/lib/plugins.js

@@ -0,0 +1,27 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeTacticaPlugins = mergeTacticaPlugins;
+/**
+ * Merge plugins into one vocabulary. Later plugins override earlier ones on
+ * the same identifier key; middlewareWiring is an OR (any plugin enables it).
+ * An empty plugin list yields an empty vocabulary — the analyzer then
+ * collects zero instrumentation points.
+ */
+function mergeTacticaPlugins(plugins) {
+    const merged = {
+        interfaces: {},
+        useDecorators: {},
+        appTokens: {},
+        middlewareWiring: false,
+    };
+    for (const plugin of plugins) {
+        Object.assign(merged.interfaces, plugin.instrumentationInterfaces);
+        Object.assign(merged.useDecorators, plugin.useDecorators);
+        Object.assign(merged.appTokens, plugin.appTokens);
+        if (plugin.middlewareWiring) {
+            merged.middlewareWiring = true;
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9wbHVnaW5zLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLFlBQVksQ0FBQzs7QUFnRGIsa0RBZ0JDO0FBdEJEOzs7OztHQUtHO0FBQ0gsU0FBZ0IsbUJBQW1CLENBQUUsT0FBd0I7SUFDNUQsTUFBTSxNQUFNLEdBQThCO1FBQ3pDLFVBQVUsRUFBUyxFQUFFO1FBQ3JCLGFBQWEsRUFBTSxFQUFFO1FBQ3JCLFNBQVMsRUFBVSxFQUFFO1FBQ3JCLGdCQUFnQixFQUFHLEtBQUs7S0FDeEIsQ0FBQztJQUNGLEtBQUssTUFBTSxNQUFNLElBQUksT0FBTyxFQUFFLENBQUM7UUFDOUIsTUFBTSxDQUFDLE1BQU0sQ0FBQyxNQUFNLENBQUMsVUFBVSxFQUFFLE1BQU0sQ0FBQyx5QkFBeUIsQ0FBQyxDQUFDO1FBQ25FLE1BQU0sQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUFDLGFBQWEsRUFBRSxNQUFNLENBQUMsYUFBYSxDQUFDLENBQUM7UUFDMUQsTUFBTSxDQUFDLE1BQU0sQ0FBQyxNQUFNLENBQUMsU0FBUyxFQUFFLE1BQU0sQ0FBQyxTQUFTLENBQUMsQ0FBQztRQUNsRCxJQUFJLE1BQU0sQ0FBQyxnQkFBZ0IsRUFBRSxDQUFDO1lBQzdCLE1BQU0sQ0FBQyxnQkFBZ0IsR0FBRyxJQUFJLENBQUM7UUFDaEMsQ0FBQztJQUNGLENBQUM7SUFDRCxPQUFPLE1BQU0sQ0FBQztBQUNmLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIndXNlIHN0cmljdCc7XG5cbmltcG9ydCB7IEluc3RydW1lbnRhdGlvbktpbmQgfSBmcm9tICcuL3R5cGVzJztcblxuLyoqXG4gKiBUYWN0aWNhIHBsdWdpbjogc3VwcGxpZXMgdGhlIGZyYW1ld29yayB2b2NhYnVsYXJ5IHRoZSBhbmFseXplciBtYXRjaGVzXG4gKiBzeW50YWN0aWNhbGx5LiBUYWN0aWNhIGNvcmUgaXMgZnJhbWV3b3JrLWJsaW5kIOKAlCB3aXRoIG5vIHBsdWdpbnMgbG9hZGVkXG4gKiBpdCBkZXRlY3RzIG5vIGluc3RydW1lbnRhdGlvbiBwb2ludHMgYXQgYWxsLiBGcmFtZXdvcmsgYWRhcHRlcnMgKGUuZy4gYVxuICogc2VydmVyLWZyYW1ld29yayBpbnRlZ3JhdGlvbiBwYWNrYWdlKSBzaGlwIGEgcGx1Z2luOyBwcm9qZWN0cyBlbmFibGUgaXRcbiAqIHRocm91Z2ggYSBgLnRhY3RpY2EuanNgIC8gYHRhY3RpY2EuY29uZmlnLmpzYCBjb25maWcgZmlsZS5cbiAqXG4gKiBBbGwga2V5cyBhcmUgbWF0Y2hlZCBieSBpZGVudGlmaWVyIFRFWFQgb25seSAobm8gaW1wb3J0IHJlc29sdXRpb24sIG5vXG4gKiB0eXBlIGNoZWNrZXIpLCBzbyBhIHBsdWdpbiBlbnRyeSBmaXJlcyBvbiBhbnkgc2FtZS1uYW1lZCBpZGVudGlmaWVyLlxuICovXG5leHBvcnQgaW50ZXJmYWNlIFRhY3RpY2FQbHVnaW4ge1xuXHQvKiogUGx1Z2luIG5hbWUsIHVzZWQgaW4gdmVyYm9zZSBsb2dnaW5nICovXG5cdG5hbWU/OiBzdHJpbmc7XG5cdC8qKiBIZXJpdGFnZSBpbnRlcmZhY2UgaWRlbnRpZmllciAtPiBraW5kIChgaW1wbGVtZW50cyBYYCkgKi9cblx0aW5zdHJ1bWVudGF0aW9uSW50ZXJmYWNlcz86IFJlY29yZDxzdHJpbmcsIEluc3RydW1lbnRhdGlvbktpbmQ+O1xuXHQvKiogRGVjb3JhdG9yIGlkZW50aWZpZXIgLT4ga2luZCAoYEBYKEltcGwpYCBvbiBjbGFzc2VzL21ldGhvZHMpICovXG5cdHVzZURlY29yYXRvcnM/OiBSZWNvcmQ8c3RyaW5nLCBJbnN0cnVtZW50YXRpb25LaW5kPjtcblx0LyoqIFByb3ZpZGVyIHRva2VuIGlkZW50aWZpZXIgLT4ga2luZCAoYHsgcHJvdmlkZTogVE9LRU4sIHVzZUNsYXNzOiBYIH1gKSAqL1xuXHRhcHBUb2tlbnM/OiBSZWNvcmQ8c3RyaW5nLCBJbnN0cnVtZW50YXRpb25LaW5kPjtcblx0LyoqXG5cdCAqIEVuYWJsZSBtaWRkbGV3YXJlIHdpcmluZyBkZXRlY3Rpb246IGBjb25zdW1lci5hcHBseShNdykuZm9yUm91dGVzKC4uLilgXG5cdCAqIGluc2lkZSBhIGBjb25maWd1cmUoKWAgbWV0aG9kLiBTaGFwZS1iYXNlZCAobm8gdm9jYWJ1bGFyeSBrZXlzKSwgc28gaXRcblx0ICogaXMgb3B0LWluIHBlciBwbHVnaW4uXG5cdCAqL1xuXHRtaWRkbGV3YXJlV2lyaW5nPzogYm9vbGVhbjtcbn1cblxuLyoqXG4gKiBUaGUgYW5hbHl6ZXIncyBtZXJnZWQgdmlldyBvZiBhbGwgbG9hZGVkIHBsdWdpbnM6IG9uZSBsb29rdXAgdGFibGUgcGVyXG4gKiBkZXRlY3Rpb24gY2hhbm5lbCwgcGx1cyB0aGUgbWlkZGxld2FyZS13aXJpbmcgc3dpdGNoLlxuICovXG5leHBvcnQgaW50ZXJmYWNlIEluc3RydW1lbnRhdGlvblZvY2FidWxhcnkge1xuXHRpbnRlcmZhY2VzOiBSZWNvcmQ8c3RyaW5nLCBJbnN0cnVtZW50YXRpb25LaW5kPjtcblx0dXNlRGVjb3JhdG9yczogUmVjb3JkPHN0cmluZywgSW5zdHJ1bWVudGF0aW9uS2luZD47XG5cdGFwcFRva2VuczogUmVjb3JkPHN0cmluZywgSW5zdHJ1bWVudGF0aW9uS2luZD47XG5cdG1pZGRsZXdhcmVXaXJpbmc6IGJvb2xlYW47XG59XG5cbi8qKlxuICogTWVyZ2UgcGx1Z2lucyBpbnRvIG9uZSB2b2NhYnVsYXJ5LiBMYXRlciBwbHVnaW5zIG92ZXJyaWRlIGVhcmxpZXIgb25lcyBvblxuICogdGhlIHNhbWUgaWRlbnRpZmllciBrZXk7IG1pZGRsZXdhcmVXaXJpbmcgaXMgYW4gT1IgKGFueSBwbHVnaW4gZW5hYmxlcyBpdCkuXG4gKiBBbiBlbXB0eSBwbHVnaW4gbGlzdCB5aWVsZHMgYW4gZW1wdHkgdm9jYWJ1bGFyeSDigJQgdGhlIGFuYWx5emVyIHRoZW5cbiAqIGNvbGxlY3RzIHplcm8gaW5zdHJ1bWVudGF0aW9uIHBvaW50cy5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIG1lcmdlVGFjdGljYVBsdWdpbnMgKHBsdWdpbnM6IFRhY3RpY2FQbHVnaW5bXSk6IEluc3RydW1lbnRhdGlvblZvY2FidWxhcnkge1xuXHRjb25zdCBtZXJnZWQ6IEluc3RydW1lbnRhdGlvblZvY2FidWxhcnkgPSB7XG5cdFx0aW50ZXJmYWNlcyAgICAgICA6IHt9LFxuXHRcdHVzZURlY29yYXRvcnMgICAgOiB7fSxcblx0XHRhcHBUb2tlbnMgICAgICAgIDoge30sXG5cdFx0bWlkZGxld2FyZVdpcmluZyA6IGZhbHNlLFxuXHR9O1xuXHRmb3IgKGNvbnN0IHBsdWdpbiBvZiBwbHVnaW5zKSB7XG5cdFx0T2JqZWN0LmFzc2lnbihtZXJnZWQuaW50ZXJmYWNlcywgcGx1Z2luLmluc3RydW1lbnRhdGlvbkludGVyZmFjZXMpO1xuXHRcdE9iamVjdC5hc3NpZ24obWVyZ2VkLnVzZURlY29yYXRvcnMsIHBsdWdpbi51c2VEZWNvcmF0b3JzKTtcblx0XHRPYmplY3QuYXNzaWduKG1lcmdlZC5hcHBUb2tlbnMsIHBsdWdpbi5hcHBUb2tlbnMpO1xuXHRcdGlmIChwbHVnaW4ubWlkZGxld2FyZVdpcmluZykge1xuXHRcdFx0bWVyZ2VkLm1pZGRsZXdhcmVXaXJpbmcgPSB0cnVlO1xuXHRcdH1cblx0fVxuXHRyZXR1cm4gbWVyZ2VkO1xufVxuIl19

package/lib/scopes.d.ts

@@ -0,0 +1,113 @@
+import * as ts from 'typescript';
+import { ScopeAnalysis, UsageInfo } from './types';
+/**
+ * Compile-time view over the analyzer's definitions, used to attach mnemonica
+ * type paths to variables. Name-based heuristics only — the no-getTypeChecker()
+ * precedent stays.
+ */
+export interface ScopeTypeResolver {
+    /** Resolve a bare constructor/type name to a mnemonica fullPath (undefined when unknown or ambiguous) */
+    resolveByName(name: string): string | undefined;
+    /** True when the dotted path is a known mnemonica type */
+    hasPath(fullPath: string): boolean;
+}
+/**
+ * Local-scope walker (instrumentation walker plan, Phase 2).
+ *
+ * Tracks function/method/arrow scopes ONLY (decision 5: no block scopes),
+ * plus one synthetic 'module' scope per file — the plan requires module-scope
+ * instance creations to be labeled, not dropped. Variables carry isMutable
+ * (const vs let/var/parameter) and `reassignments`: each reassignment site of
+ * a mutable binding is a flow-termination point (decision 6) — downstream the
+ * walker stops following that binding there.
+ *
+ * Usage: addFile() per source file, then build(resolver) once definitions are
+ * known. findHolderScopeId(location) maps a usage location string to the
+ * innermost scope containing it (usages.json holderScopeId).
+ */
+export declare class LocalScopeWalker {
+    private scopes;
+    private spans;
+    private variables;
+    private pending;
+    /**
+     * Arrow/function-expression node -> name it is bound to (`const f = () => …`,
+     * `{ handler: () => … }`, class properties). Program source files can be
+     * UNBOUND (no node.parent pointers), so binding names travel through this
+     * map instead of parent lookups.
+     */
+    private boundNames;
+    /**
+     * Track one source file. Re-adding the same file replaces its records,
+     * so a walker may safely be reused across passes.
+     */
+    addFile(sourceFile: ts.SourceFile): void;
+    /**
+     * Resolve pending typePaths and return the analysis.
+     */
+    build(resolver?: ScopeTypeResolver): ScopeAnalysis;
+    /**
+     * Map a usage location string ('abs/file.ts:line:col') to the innermost
+     * scope containing it. Module scope is the fallback, so every location
+     * inside a tracked file resolves to some scope.
+     */
+    findHolderScopeId(location: string): string | undefined;
+    /**
+     * Remove every record belonging to one file (re-add support).
+     */
+    private dropFile;
+    /**
+     * Attach holderScopeId to every usage whose location falls inside a
+     * tracked scope. Additive on UsageInfo; usages outside tracked files
+     * are left untouched.
+     */
+    static attachHolderScopeIds(usages: Map<string, UsageInfo[]>, walker: LocalScopeWalker): void;
+    private visitNode;
+    private static scopeKindOf;
+    private hasBody;
+    private enterScope;
+    /**
+     * Decision 8 labeling: functions by name; methods as Class.method;
+     * arrows/functions bound to a variable or property take that name;
+     * anonymous holders are labeled file:line.
+     */
+    private scopeName;
+    private spanOf;
+    /**
+     * Record the name an arrow/function-expression is bound to, without
+     * relying on node.parent (unbound program files): `const f = () => …`,
+     * `{ handler: () => … }`, `class C { run = () => … }`.
+     */
+    private collectBoundName;
+    private collectVariableDeclarationList;
+    private recordVariable;
+    /**
+     * `a.b.c` → ['a', 'b', 'c'] (left-to-right); undefined-safe for
+     * non-identifier roots.
+     */
+    private static unwrapPropertyAccess;
+    /**
+     * `lookup('A.B')`, `App.lookup('A.B')`, `lookup(source, 'A.B')` → the
+     * string-literal path plus the receiver's root identifier when there is
+     * one. Only literal paths are tracked: a computed path is data the static
+     * walker cannot follow, so it is skipped (the analyzer's usage pass still
+     * records the lookup call itself).
+     */
+    private static unwrapLookupCall;
+    /**
+     * Cheap initializer classification for inferredType. Deliberately tiny:
+     * literal kinds and `new X` constructor names; everything else undefined.
+     */
+    private static inferInitializerKind;
+    /**
+     * Reassignment of a let/var/parameter binding: a flow-termination point
+     * (decision 6). Recorded on the variable so the Phase 3 walker stops
+     * following that binding there.
+     */
+    private collectReassignment;
+    /**
+     * Find a variable by name walking the scope chain outward.
+     */
+    private findVariable;
+    private resolveVariableTypePath;
+}