@angular-modernizer/api 0.1.0

package/dist/investigation/stack-trace-parser.js

@@ -0,0 +1,117 @@
+/**
+ * @angular-modernizer/api - Stack Trace Parser
+ *
+ * Parses Node.js/Angular/Zone.js/browser stack traces and maps frames to project source files.
+ *
+ * @remarks
+ * Frames are classified as project files when their resolved path starts with `projectRoot`
+ * and does not pass through `node_modules`. Browser URL frames (http/https) are always
+ * classified as non-project files regardless of origin.
+ *
+ * @example
+ * ```typescript
+ * const parser = new StackTraceParser('/my/project/src');
+ * const frames = parser.parse(error.stack ?? '');
+ * // frames[0].file → '/my/project/src/app/user.service.ts'
+ * // frames[0].isProjectFile → true
+ *
+ * const projectOnly = parser.parseProjectFrames(error.stack ?? '');
+ * ```
+ */
+/**
+ * Regex matching a V8-style "at" frame in the following forms:
+ *
+ * ```
+ * at FunctionName (file:line:col)
+ * at async FunctionName (file:line:col)
+ * at new FunctionName (file:line:col)
+ * at file:line:col
+ * ```
+ */
+const AT_FRAME_WITH_LOCATION = /^\s*at\s+(?:async\s+)?(.+?)\s+\((.+):(\d+):(\d+)\)\s*$/;
+const AT_FRAME_WITHOUT_FUNCTION = /^\s*at\s+((?!async\s|new\s)[^(]+):(\d+):(\d+)\s*$/;
+const HTTP_SCHEME = /^https?:\/\//;
+const NODE_MODULES_SEGMENT = /[/\\]node_modules[/\\]/;
+/**
+ * Parses Node.js/Angular/Zone.js/browser stack traces into structured frames.
+ */
+export class StackTraceParser {
+    projectRoot;
+    /**
+     * @param projectRoot - Absolute path to the project root used to classify
+     *   frames as project files vs. external dependencies.
+     */
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    /**
+     * Parses a raw stack trace string into an array of structured frames.
+     *
+     * @param stackTrace - Raw `Error.stack` string or console-captured stack trace.
+     * @returns All frames found, including non-project frames.
+     */
+    parse(stackTrace) {
+        if (!stackTrace) {
+            return [];
+        }
+        const frames = [];
+        for (const line of stackTrace.split('\n')) {
+            const frame = this.parseLine(line);
+            if (frame !== null) {
+                frames.push(frame);
+            }
+        }
+        return frames;
+    }
+    /**
+     * Parses a stack trace and returns only frames that belong to the project.
+     *
+     * @param stackTrace - Raw `Error.stack` string or console-captured stack trace.
+     * @returns Frames where `isProjectFile` is `true`.
+     */
+    parseProjectFrames(stackTrace) {
+        return this.parse(stackTrace).filter((f) => f.isProjectFile);
+    }
+    parseLine(line) {
+        const withFunc = AT_FRAME_WITH_LOCATION.exec(line);
+        if (withFunc !== null) {
+            const [, functionName, file, lineStr, colStr] = withFunc;
+            return this.buildFrame(this.sanitizeFunctionName(functionName ?? ''), file ?? '', Number(lineStr), Number(colStr));
+        }
+        const withoutFunc = AT_FRAME_WITHOUT_FUNCTION.exec(line);
+        if (withoutFunc !== null) {
+            const [, file, lineStr, colStr] = withoutFunc;
+            return this.buildFrame('<anonymous>', file ?? '', Number(lineStr), Number(colStr));
+        }
+        return null;
+    }
+    buildFrame(functionName, file, line, col) {
+        return {
+            file,
+            line,
+            col,
+            functionName,
+            isProjectFile: this.isProjectFile(file),
+        };
+    }
+    isProjectFile(file) {
+        if (HTTP_SCHEME.test(file)) {
+            return false;
+        }
+        if (NODE_MODULES_SEGMENT.test(file)) {
+            return false;
+        }
+        return file.startsWith(this.projectRoot);
+    }
+    /**
+     * Strips the `async ` prefix that ts-jest/V8 sometimes leaves in function names
+     * when the regex group captures it as part of the name rather than the keyword.
+     */
+    sanitizeFunctionName(name) {
+        return name
+            .replace(/^async\s+/, '')
+            .replace(/^new\s+/, 'new ')
+            .trim();
+    }
+}
+//# sourceMappingURL=stack-trace-parser.js.map

package/dist/investigation/stack-trace-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-trace-parser.js","sourceRoot":"","sources":["../../src/investigation/stack-trace-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAuBH;;;;;;;;;GASG;AACH,MAAM,sBAAsB,GAC1B,wDAAwD,CAAC;AAE3D,MAAM,yBAAyB,GAC7B,mDAAmD,CAAC;AAEtD,MAAM,WAAW,GAAG,cAAc,CAAC;AACnC,MAAM,oBAAoB,GAAG,wBAAwB,CAAC;AAEtD;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAKE;IAJ7B;;;OAGG;IACH,YAA6B,WAAmB;QAAnB,gBAAW,GAAX,WAAW,CAAQ;IAAG,CAAC;IAEpD;;;;;OAKG;IACH,KAAK,CAAC,UAAkB;QACtB,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,MAAM,GAAiB,EAAE,CAAC;QAEhC,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,UAAkB;QACnC,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAC/D,CAAC;IAEO,SAAS,CAAC,IAAY;QAC5B,MAAM,QAAQ,GAAG,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC;YACzD,OAAO,IAAI,CAAC,UAAU,CACpB,IAAI,CAAC,oBAAoB,CAAC,YAAY,IAAI,EAAE,CAAC,EAC7C,IAAI,IAAI,EAAE,EACV,MAAM,CAAC,OAAO,CAAC,EACf,MAAM,CAAC,MAAM,CAAC,CACf,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC;YAC9C,OAAO,IAAI,CAAC,UAAU,CACpB,aAAa,EACb,IAAI,IAAI,EAAE,EACV,MAAM,CAAC,OAAO,CAAC,EACf,MAAM,CAAC,MAAM,CAAC,CACf,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,UAAU,CAChB,YAAoB,EACpB,IAAY,EACZ,IAAY,EACZ,GAAW;QAEX,OAAO;YACL,IAAI;YACJ,IAAI;YACJ,GAAG;YACH,YAAY;YACZ,aAAa,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;SACxC,CAAC;IACJ,CAAC;IAEO,aAAa,CAAC,IAAY;QAChC,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED;;;OAGG;IACK,oBAAoB,CAAC,IAAY;QACvC,OAAO,IAAI;aACR,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;aACxB,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC;aAC1B,IAAI,EAAE,CAAC;IACZ,CAAC;CACF"}

package/dist/investigation/type-resolver.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @angular-modernizer/api - Type Resolver
+ *
+ * Resolves the TypeScript type at a given position (file, line, column)
+ * using the ts-morph language service and type checker.
+ *
+ * @remarks
+ * Useful in bug investigation to understand what type a variable holds
+ * at a specific location — including whether it is nullable, async,
+ * or wraps a generic parameter.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new TypeResolver(project);
+ * const info = resolver.resolveType('/src/app/user.service.ts', 42, 15);
+ * // info.typeString   → 'UserService'
+ * // info.isNullable   → false
+ * // info.isAsync      → false
+ * // info.declaredIn   → '/src/app/user.service.ts'
+ * ```
+ */
+import type { Project } from 'ts-morph';
+/** Resolved type information for a source position. */
+export interface ResolvedTypeInfo {
+    /** Human-readable resolved type string. */
+    typeString: string;
+    /** Generic type parameters extracted from the type string (e.g. `['string']` for `Array<string>`). */
+    genericParams: string[];
+    /** Absolute path of the file where this type is declared. Empty string when not determinable. */
+    declaredIn: string;
+    /** `true` when the type includes `null` or `undefined` in a union. */
+    isNullable: boolean;
+    /** `true` when the type is `Promise<T>` or `Observable<T>`. */
+    isAsync: boolean;
+}
+/**
+ * Resolves TypeScript types at source positions via ts-morph.
+ */
+export declare class TypeResolver {
+    private readonly project;
+    /**
+     * @param project - A ts-morph `Project` instance with source files already added.
+     */
+    constructor(project: Project);
+    /**
+     * Resolves the TypeScript type at the given 1-based position.
+     *
+     * @param file - Absolute path of the source file.
+     * @param line - 1-based line number.
+     * @param column - 1-based column number.
+     * @returns Resolved type information, or a fallback with `typeString: 'unknown'`.
+     */
+    resolveType(file: string, line: number, column: number): ResolvedTypeInfo;
+    private extractGenericParams;
+    private resolveDeclaredIn;
+    private checkNullable;
+    private checkAsync;
+}
+//# sourceMappingURL=type-resolver.d.ts.map

package/dist/investigation/type-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-resolver.d.ts","sourceRoot":"","sources":["../../src/investigation/type-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IAEnB,sGAAsG;IACtG,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB,iGAAiG;IACjG,UAAU,EAAE,MAAM,CAAC;IAEnB,sEAAsE;IACtE,UAAU,EAAE,OAAO,CAAC;IAEpB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;CAClB;AAgBD;;GAEG;AACH,qBAAa,YAAY;IAIX,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC;;OAEG;gBAC0B,OAAO,EAAE,OAAO;IAE7C;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB;IA+BzE,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,iBAAiB;IAoBzB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,UAAU;CAInB"}

package/dist/investigation/type-resolver.js

@@ -0,0 +1,111 @@
+/**
+ * @angular-modernizer/api - Type Resolver
+ *
+ * Resolves the TypeScript type at a given position (file, line, column)
+ * using the ts-morph language service and type checker.
+ *
+ * @remarks
+ * Useful in bug investigation to understand what type a variable holds
+ * at a specific location — including whether it is nullable, async,
+ * or wraps a generic parameter.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new TypeResolver(project);
+ * const info = resolver.resolveType('/src/app/user.service.ts', 42, 15);
+ * // info.typeString   → 'UserService'
+ * // info.isNullable   → false
+ * // info.isAsync      → false
+ * // info.declaredIn   → '/src/app/user.service.ts'
+ * ```
+ */
+const ASYNC_TYPE_NAMES = new Set([
+    'Promise',
+    'Observable',
+    'Subject',
+    'BehaviorSubject',
+]);
+const FALLBACK = {
+    typeString: 'unknown',
+    genericParams: [],
+    declaredIn: '',
+    isNullable: false,
+    isAsync: false,
+};
+/**
+ * Resolves TypeScript types at source positions via ts-morph.
+ */
+export class TypeResolver {
+    project;
+    /**
+     * @param project - A ts-morph `Project` instance with source files already added.
+     */
+    constructor(project) {
+        this.project = project;
+    }
+    /**
+     * Resolves the TypeScript type at the given 1-based position.
+     *
+     * @param file - Absolute path of the source file.
+     * @param line - 1-based line number.
+     * @param column - 1-based column number.
+     * @returns Resolved type information, or a fallback with `typeString: 'unknown'`.
+     */
+    resolveType(file, line, column) {
+        const sourceFile = this.project.getSourceFile(file);
+        if (!sourceFile) {
+            return FALLBACK;
+        }
+        try {
+            const pos = sourceFile.compilerNode.getPositionOfLineAndCharacter(line - 1, column - 1);
+            const node = sourceFile.getDescendantAtPos(pos);
+            if (!node) {
+                return FALLBACK;
+            }
+            const type = this.project.getTypeChecker().getTypeAtLocation(node);
+            const typeString = type.getText(node);
+            const genericParams = this.extractGenericParams(typeString);
+            const declaredIn = this.resolveDeclaredIn(type);
+            const isNullable = this.checkNullable(typeString);
+            const isAsync = this.checkAsync(typeString);
+            return { typeString, genericParams, declaredIn, isNullable, isAsync };
+        }
+        catch {
+            return FALLBACK;
+        }
+    }
+    extractGenericParams(typeString) {
+        const match = /<([^>]+)>/.exec(typeString);
+        if (!match?.[1]) {
+            return [];
+        }
+        return match[1]
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    resolveDeclaredIn(type) {
+        try {
+            const symbol = type.getSymbol();
+            if (!symbol) {
+                return '';
+            }
+            const declarations = symbol.getDeclarations();
+            if (declarations.length === 0) {
+                return '';
+            }
+            return declarations[0]?.getSourceFile().getFilePath() ?? '';
+        }
+        catch {
+            return '';
+        }
+    }
+    checkNullable(typeString) {
+        return typeString.includes('null') || typeString.includes('undefined');
+    }
+    checkAsync(typeString) {
+        const baseName = typeString.split('<')[0]?.trim() ?? '';
+        return ASYNC_TYPE_NAMES.has(baseName);
+    }
+}
+//# sourceMappingURL=type-resolver.js.map

package/dist/investigation/type-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-resolver.js","sourceRoot":"","sources":["../../src/investigation/type-resolver.ts"],"names":[],"mappings":"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"}

package/dist/investigation/usage-finder.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @angular-modernizer/api - Usage Finder
+ *
+ * Finds all references to a symbol (class, method, function, variable, constant)
+ * across a ts-morph Project. Used in bug investigation to determine call paths
+ * and blast radius before proposing a fix.
+ *
+ * @remarks
+ * Uses ts-morph `findReferences()` under the hood. The project must already have
+ * the relevant source files added before calling `findUsages`.
+ *
+ * @example
+ * ```typescript
+ * const finder = new UsageFinder(project);
+ * const usages = finder.findUsages('UserService', { file: '/src/app/user.component.ts' });
+ * // usages[0] → { file, line, col, snippet, usageType: 'read' }
+ * ```
+ */
+import type { Project } from 'ts-morph';
+/** Classification of how a symbol is used at a given location. */
+export type UsageType = 'read' | 'write' | 'call';
+/** A single resolved symbol usage. */
+export interface SymbolUsage {
+    /** Absolute file path containing the usage. */
+    file: string;
+    /** 1-based line number. */
+    line: number;
+    /** 1-based column number. */
+    col: number;
+    /** The source line containing the usage. */
+    snippet: string;
+    /** How the symbol is used at this location. */
+    usageType: UsageType;
+}
+/** Options for narrowing `findUsages` results. */
+export interface FindUsagesOptions {
+    /**
+     * Restrict results to a single source file (absolute path).
+     * When omitted, all files in the project are searched.
+     */
+    file?: string;
+    /**
+     * Restrict results to a specific usage type.
+     * When omitted, all usage types are returned.
+     */
+    usageType?: UsageType;
+}
+/**
+ * Finds all references to named symbols across a ts-morph Project.
+ */
+export declare class UsageFinder {
+    private readonly project;
+    /**
+     * @param project - A ts-morph `Project` instance with source files already added.
+     */
+    constructor(project: Project);
+    /**
+     * Finds all usages of the named symbol across the project.
+     *
+     * @param symbol - The symbol name to search for (class, method, function, variable, constant).
+     * @param options - Optional filters for file scope and usage type.
+     * @returns Array of resolved usages, sorted by file path then line number.
+     */
+    findUsages(symbol: string, options?: FindUsagesOptions): SymbolUsage[];
+    private findSymbolNodes;
+    private classifyUsage;
+    private deduplicate;
+}
+//# sourceMappingURL=usage-finder.d.ts.map

package/dist/investigation/usage-finder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-finder.d.ts","sourceRoot":"","sources":["../../src/investigation/usage-finder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAQ,MAAM,UAAU,CAAC;AAE9C,kEAAkE;AAClE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAElD,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IAEb,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IAEZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAEhB,+CAA+C;IAC/C,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC;;OAEG;gBAC0B,OAAO,EAAE,OAAO;IAE7C;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,WAAW,EAAE;IAqD1E,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,aAAa;IAoCrB,OAAO,CAAC,WAAW;CAWpB"}

package/dist/investigation/usage-finder.js

@@ -0,0 +1,132 @@
+/**
+ * @angular-modernizer/api - Usage Finder
+ *
+ * Finds all references to a symbol (class, method, function, variable, constant)
+ * across a ts-morph Project. Used in bug investigation to determine call paths
+ * and blast radius before proposing a fix.
+ *
+ * @remarks
+ * Uses ts-morph `findReferences()` under the hood. The project must already have
+ * the relevant source files added before calling `findUsages`.
+ *
+ * @example
+ * ```typescript
+ * const finder = new UsageFinder(project);
+ * const usages = finder.findUsages('UserService', { file: '/src/app/user.component.ts' });
+ * // usages[0] → { file, line, col, snippet, usageType: 'read' }
+ * ```
+ */
+/**
+ * Finds all references to named symbols across a ts-morph Project.
+ */
+export class UsageFinder {
+    project;
+    /**
+     * @param project - A ts-morph `Project` instance with source files already added.
+     */
+    constructor(project) {
+        this.project = project;
+    }
+    /**
+     * Finds all usages of the named symbol across the project.
+     *
+     * @param symbol - The symbol name to search for (class, method, function, variable, constant).
+     * @param options - Optional filters for file scope and usage type.
+     * @returns Array of resolved usages, sorted by file path then line number.
+     */
+    findUsages(symbol, options = {}) {
+        const usages = [];
+        const sourceFiles = options.file
+            ? [this.project.getSourceFile(options.file)].filter(Boolean)
+            : this.project.getSourceFiles();
+        for (const sourceFile of sourceFiles) {
+            if (!sourceFile) {
+                continue;
+            }
+            const nodes = this.findSymbolNodes(sourceFile, symbol);
+            for (const node of nodes) {
+                const refs = this.project.getLanguageService().findReferences(node);
+                for (const refSymbol of refs) {
+                    for (const ref of refSymbol.getReferences()) {
+                        const refFile = ref.getSourceFile();
+                        const refFilePath = refFile.getFilePath();
+                        if (options.file && refFilePath !== options.file) {
+                            continue;
+                        }
+                        const pos = ref.getNode().getStart();
+                        const lineAndCol = refFile.getLineAndColumnAtPos(pos);
+                        const lineText = refFile.getFullText().split('\n')[lineAndCol.line - 1] ?? '';
+                        const usageType = this.classifyUsage(ref.getNode());
+                        if (options.usageType && usageType !== options.usageType) {
+                            continue;
+                        }
+                        usages.push({
+                            file: refFilePath,
+                            line: lineAndCol.line,
+                            col: lineAndCol.column,
+                            snippet: lineText.trim(),
+                            usageType,
+                        });
+                    }
+                }
+            }
+        }
+        return this.deduplicate(usages).sort((a, b) => a.file !== b.file ? a.file.localeCompare(b.file) : a.line - b.line);
+    }
+    findSymbolNodes(sourceFile, symbol) {
+        if (!sourceFile) {
+            return [];
+        }
+        const nodes = [];
+        sourceFile.forEachDescendant((node) => {
+            if ('getName' in node &&
+                typeof node.getName === 'function') {
+                if (node.getName() === symbol) {
+                    nodes.push(node);
+                }
+            }
+        });
+        return nodes;
+    }
+    classifyUsage(node) {
+        const parent = node.getParent();
+        if (!parent) {
+            return 'read';
+        }
+        const parentKindName = parent.getKindName();
+        // Call expression: svc.method() or method()
+        if (parentKindName === 'CallExpression') {
+            return 'call';
+        }
+        if (parentKindName === 'PropertyAccessExpression') {
+            const grandParent = parent.getParent();
+            if (grandParent?.getKindName() === 'CallExpression') {
+                return 'call';
+            }
+        }
+        // Assignment: x = value or x += value
+        if (parentKindName === 'BinaryExpression' ||
+            parentKindName === 'VariableDeclaration' ||
+            parentKindName === 'PropertyAssignment') {
+            const parentText = parent.getText();
+            const nodeText = node.getText();
+            const nodePos = parentText.indexOf(nodeText);
+            if (nodePos === 0) {
+                return 'write';
+            }
+        }
+        return 'read';
+    }
+    deduplicate(usages) {
+        const seen = new Set();
+        return usages.filter((u) => {
+            const key = `${u.file}:${u.line}:${u.col}`;
+            if (seen.has(key)) {
+                return false;
+            }
+            seen.add(key);
+            return true;
+        });
+    }
+}
+//# sourceMappingURL=usage-finder.js.map

package/dist/investigation/usage-finder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-finder.js","sourceRoot":"","sources":["../../src/investigation/usage-finder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAwCH;;GAEG;AACH,MAAM,OAAO,WAAW;IAIO;IAH7B;;OAEG;IACH,YAA6B,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;IAAG,CAAC;IAEjD;;;;;;OAMG;IACH,UAAU,CAAC,MAAc,EAAE,UAA6B,EAAE;QACxD,MAAM,MAAM,GAAkB,EAAE,CAAC;QAEjC,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI;YAC9B,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;YAC5D,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;QAElC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;YACrC,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,SAAS;YACX,CAAC;YAED,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YAEvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;gBAEpE,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;oBAC7B,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,aAAa,EAAE,EAAE,CAAC;wBAC5C,MAAM,OAAO,GAAG,GAAG,CAAC,aAAa,EAAE,CAAC;wBACpC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;wBAE1C,IAAI,OAAO,CAAC,IAAI,IAAI,WAAW,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC;4BACjD,SAAS;wBACX,CAAC;wBAED,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC;wBACrC,MAAM,UAAU,GAAG,OAAO,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC;wBACtD,MAAM,QAAQ,GACZ,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;wBAC/D,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;wBAEpD,IAAI,OAAO,CAAC,SAAS,IAAI,SAAS,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC;4BACzD,SAAS;wBACX,CAAC;wBAED,MAAM,CAAC,IAAI,CAAC;4BACV,IAAI,EAAE,WAAW;4BACjB,IAAI,EAAE,UAAU,CAAC,IAAI;4BACrB,GAAG,EAAE,UAAU,CAAC,MAAM;4BACtB,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE;4BACxB,SAAS;yBACV,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAC5C,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CACnE,CAAC;IACJ,CAAC;IAEO,eAAe,CACrB,UAAgD,EAChD,MAAc;QAEd,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,KAAK,GAAW,EAAE,CAAC;QAEzB,UAAU,CAAC,iBAAiB,CAAC,CAAC,IAAI,EAAE,EAAE;YACpC,IACE,SAAS,IAAI,IAAI;gBACjB,OAAQ,IAA8B,CAAC,OAAO,KAAK,UAAU,EAC7D,CAAC;gBACD,IAAK,IAA8B,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;oBACzD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACnB,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,aAAa,CAAC,IAAU;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QAE5C,4CAA4C;QAC5C,IAAI,cAAc,KAAK,gBAAgB,EAAE,CAAC;YACxC,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,cAAc,KAAK,0BAA0B,EAAE,CAAC;YAClD,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;YACvC,IAAI,WAAW,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,CAAC;gBACpD,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAED,sCAAsC;QACtC,IACE,cAAc,KAAK,kBAAkB;YACrC,cAAc,KAAK,qBAAqB;YACxC,cAAc,KAAK,oBAAoB,EACvC,CAAC;YACD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YAChC,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC7C,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;gBAClB,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,WAAW,CAAC,MAAqB;QACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YACzB,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;YAC3C,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClB,OAAO,KAAK,CAAC;YACf,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}