@angular-modernizer/api 0.1.0

package/dist/investigation/call-graph-builder.js

@@ -0,0 +1,196 @@
+/**
+ * @angular-modernizer/api - Call Graph Builder
+ *
+ * Builds a call graph for a named method or function within a ts-morph Project.
+ * Supports traversal upward (callers) and downward (callees) with configurable depth.
+ *
+ * @remarks
+ * Used in bug investigation to understand how an error propagates through the
+ * codebase. Combine with `find-usages` to trace the full call path from the
+ * entry point to the failing code.
+ *
+ * @example
+ * ```typescript
+ * const builder = new CallGraphBuilder(project);
+ * const graph = builder.buildCallGraph('getUser', '/src/app/user.service.ts', {
+ *   direction: 'both',
+ *   depth: 2,
+ * });
+ * // graph.callers → who calls getUser
+ * // graph.callees → what getUser calls
+ * ```
+ */
+import { SyntaxKind } from 'ts-morph';
+/**
+ * Builds caller/callee graphs for methods and functions across a ts-morph Project.
+ */
+export class CallGraphBuilder {
+    project;
+    /**
+     * @param project - A ts-morph `Project` instance with source files already added.
+     */
+    constructor(project) {
+        this.project = project;
+    }
+    /**
+     * Builds a call graph rooted at the named method or function.
+     *
+     * @param method - Name of the method or function to analyse.
+     * @param file - Absolute path of the source file containing the method.
+     * @param options - Traversal direction and depth. Defaults to `both` / depth `2`.
+     * @returns A `CallGraphResult` with the target and its caller/callee trees.
+     */
+    buildCallGraph(method, file, options = {}) {
+        const direction = options.direction ?? 'both';
+        const depth = options.depth ?? 2;
+        const target = this.resolveTarget(method, file);
+        if (!target) {
+            return { target: null, callers: [], callees: [] };
+        }
+        const targetInfo = {
+            name: method,
+            file,
+            line: target.getStartLineNumber(),
+        };
+        const callers = direction === 'down'
+            ? []
+            : this.buildCallers(target, depth, new Set([`${file}:${method}`]));
+        const callees = direction === 'up'
+            ? []
+            : this.buildCallees(target, depth, new Set([`${file}:${method}`]));
+        return { target: targetInfo, callers, callees };
+    }
+    resolveTarget(name, file) {
+        const sourceFile = this.project.getSourceFile(file);
+        if (!sourceFile) {
+            return null;
+        }
+        // Search class methods
+        for (const cls of sourceFile.getClasses()) {
+            const method = cls.getMethod(name);
+            if (method) {
+                return method;
+            }
+        }
+        // Search top-level functions
+        const fn = sourceFile.getFunction(name);
+        if (fn) {
+            return fn;
+        }
+        return null;
+    }
+    buildCallees(callable, depth, visited) {
+        if (depth <= 0) {
+            return [];
+        }
+        const callees = [];
+        const body = callable.getBody();
+        if (!body) {
+            return [];
+        }
+        body.forEachDescendant((node) => {
+            if (node.getKind() !== SyntaxKind.CallExpression) {
+                return;
+            }
+            const callExpr = node.asKindOrThrow(SyntaxKind.CallExpression);
+            const expr = callExpr.getExpression();
+            const calleeName = this.extractCallName(expr.getText());
+            if (!calleeName) {
+                return;
+            }
+            const targetDecl = this.findDeclarationInProject(calleeName);
+            if (!targetDecl) {
+                return;
+            }
+            const targetFile = targetDecl.getSourceFile().getFilePath();
+            const key = `${targetFile}:${calleeName}`;
+            if (visited.has(key)) {
+                return;
+            }
+            visited.add(key);
+            const children = this.buildCallees(targetDecl, depth - 1, new Set(visited));
+            callees.push({
+                name: calleeName,
+                file: targetFile,
+                line: targetDecl.getStartLineNumber(),
+                children,
+            });
+        });
+        return this.deduplicateNodes(callees);
+    }
+    buildCallers(callable, depth, visited) {
+        if (depth <= 0) {
+            return [];
+        }
+        const callers = [];
+        const name = callable.getName();
+        if (!name) {
+            return [];
+        }
+        const refs = this.project.getLanguageService().findReferences(callable);
+        for (const refSymbol of refs) {
+            for (const ref of refSymbol.getReferences()) {
+                if (ref.isDefinition()) {
+                    continue;
+                }
+                const refNode = ref.getNode();
+                const parentMethod = refNode.getFirstAncestor((n) => n.getKind() === SyntaxKind.MethodDeclaration ||
+                    n.getKind() === SyntaxKind.FunctionDeclaration);
+                if (!parentMethod) {
+                    continue;
+                }
+                const callerName = parentMethod.getName();
+                if (!callerName) {
+                    continue;
+                }
+                const callerFile = parentMethod.getSourceFile().getFilePath();
+                const key = `${callerFile}:${callerName}`;
+                if (visited.has(key)) {
+                    continue;
+                }
+                visited.add(key);
+                const children = this.buildCallers(parentMethod, depth - 1, new Set(visited));
+                callers.push({
+                    name: callerName,
+                    file: callerFile,
+                    line: parentMethod.getStartLineNumber(),
+                    children,
+                });
+            }
+        }
+        return this.deduplicateNodes(callers);
+    }
+    findDeclarationInProject(name) {
+        for (const sourceFile of this.project.getSourceFiles()) {
+            for (const cls of sourceFile.getClasses()) {
+                const method = cls.getMethod(name);
+                if (method) {
+                    return method;
+                }
+            }
+            const fn = sourceFile.getFunction(name);
+            if (fn) {
+                return fn;
+            }
+        }
+        return null;
+    }
+    extractCallName(exprText) {
+        // svc.method() → method, method() → method
+        const parts = exprText.split('.');
+        const last = parts.at(-1);
+        return last && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(last) ? last : null;
+    }
+    deduplicateNodes(nodes) {
+        const seen = new Set();
+        return nodes.filter((n) => {
+            const key = `${n.file}:${n.name}`;
+            if (seen.has(key)) {
+                return false;
+            }
+            seen.add(key);
+            return true;
+        });
+    }
+}
+//# sourceMappingURL=call-graph-builder.js.map

package/dist/investigation/call-graph-builder.js.map

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

package/dist/investigation/codebase-searcher.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @angular-modernizer/api - Codebase Searcher
+ *
+ * Searches across all source files in a ts-morph Project using three modes:
+ * - `text`    — literal string search (case-sensitive substring)
+ * - `pattern` — regular-expression search
+ * - `symbol`  — TypeScript declaration search (class, function, interface,
+ *               enum, type alias, variable)
+ *
+ * @remarks
+ * The project must already have the relevant source files added before calling
+ * `search`. For `symbol` mode only top-level named declarations are indexed;
+ * local variables and anonymous expressions are not returned.
+ *
+ * @example
+ * ```typescript
+ * const searcher = new CodebaseSearcher(project);
+ *
+ * // Text search
+ * const hits = searcher.search('TODO:', { mode: 'text' });
+ *
+ * // Regex search
+ * const selectors = searcher.search('selector:\\s*["\']([^"\']+)["\']', { mode: 'pattern' });
+ *
+ * // Symbol search
+ * const classes = searcher.search('UserService', { mode: 'symbol' });
+ * ```
+ */
+import type { Project } from 'ts-morph';
+/** The kind of named declaration returned in symbol-mode results. */
+export type SymbolKind = 'class' | 'function' | 'interface' | 'enum' | 'typeAlias' | 'variable';
+/** A single search result. */
+export interface SearchResult {
+    /** Absolute file path. */
+    file: string;
+    /** 1-based line number of the match. */
+    line: number;
+    /** 1-based column of the match start. */
+    col: number;
+    /** The source line (trimmed) containing the match. */
+    snippet: string;
+    /**
+     * Set in `symbol` mode to classify the declaration type.
+     * Absent in `text` and `pattern` modes.
+     */
+    symbolKind?: SymbolKind;
+}
+/** Options for `CodebaseSearcher.search()`. */
+export interface SearchOptions {
+    /**
+     * - `text`    — literal substring match
+     * - `pattern` — regular expression match
+     * - `symbol`  — TypeScript named declaration lookup
+     */
+    mode: 'text' | 'pattern' | 'symbol';
+    /**
+     * Optional glob pattern (minimatch) to restrict which files are searched.
+     * E.g. `'**\/*.service.ts'`. When omitted all project source files are
+     * searched.
+     */
+    include?: string;
+    /**
+     * Maximum number of results to return. When omitted all matches are
+     * returned.
+     */
+    maxResults?: number;
+}
+/**
+ * Searches source files in a ts-morph `Project` by text, regex, or symbol
+ * name.
+ */
+export declare class CodebaseSearcher {
+    private readonly project;
+    constructor(project: Project);
+    /**
+     * Search for `query` across all (filtered) source files.
+     *
+     * @param query - The text, regex pattern, or symbol name to find.
+     * @param options - Search mode and optional file filter / result limit.
+     * @returns Array of `SearchResult` objects ordered by file then line.
+     *
+     * @example
+     * ```typescript
+     * searcher.search('UserService', { mode: 'symbol' });
+     * searcher.search('TODO', { mode: 'text', include: 'src/**\/*.ts' });
+     * ```
+     */
+    search(query: string, options: SearchOptions): SearchResult[];
+    /**
+     * Text or pattern search: splits each file into lines and tests each line.
+     */
+    private searchText;
+    /**
+     * Symbol search: finds top-level named declarations whose name equals
+     * `query`.
+     */
+    private searchSymbols;
+}
+//# sourceMappingURL=codebase-searcher.d.ts.map

package/dist/investigation/codebase-searcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase-searcher.d.ts","sourceRoot":"","sources":["../../src/investigation/codebase-searcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,qEAAqE;AACrE,MAAM,MAAM,UAAU,GAClB,OAAO,GACP,UAAU,GACV,WAAW,GACX,MAAM,GACN,WAAW,GACX,UAAU,CAAC;AAEf,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;IAEZ,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;IAEpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAeD;;;GAGG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,OAAO;IAE7C;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,YAAY,EAAE;IAoB7D;;OAEG;IACH,OAAO,CAAC,UAAU;IAqClB;;;OAGG;IACH,OAAO,CAAC,aAAa;CAwGtB"}

package/dist/investigation/codebase-searcher.js

@@ -0,0 +1,201 @@
+/**
+ * @angular-modernizer/api - Codebase Searcher
+ *
+ * Searches across all source files in a ts-morph Project using three modes:
+ * - `text`    — literal string search (case-sensitive substring)
+ * - `pattern` — regular-expression search
+ * - `symbol`  — TypeScript declaration search (class, function, interface,
+ *               enum, type alias, variable)
+ *
+ * @remarks
+ * The project must already have the relevant source files added before calling
+ * `search`. For `symbol` mode only top-level named declarations are indexed;
+ * local variables and anonymous expressions are not returned.
+ *
+ * @example
+ * ```typescript
+ * const searcher = new CodebaseSearcher(project);
+ *
+ * // Text search
+ * const hits = searcher.search('TODO:', { mode: 'text' });
+ *
+ * // Regex search
+ * const selectors = searcher.search('selector:\\s*["\']([^"\']+)["\']', { mode: 'pattern' });
+ *
+ * // Symbol search
+ * const classes = searcher.search('UserService', { mode: 'symbol' });
+ * ```
+ */
+/**
+ * Converts a glob pattern (`**\/*.service.ts`) to a RegExp and tests `filePath`.
+ * Supports `**` (any path segments) and `*` (single segment wildcard).
+ */
+function matchesGlob(filePath, pattern) {
+    const escaped = pattern
+        .replaceAll(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replaceAll('**', '\u0000')
+        .replaceAll('*', '[^/]*')
+        .replaceAll('\u0000', '.*');
+    return new RegExp(`(^|/)${escaped}$`).test(filePath);
+}
+/**
+ * Searches source files in a ts-morph `Project` by text, regex, or symbol
+ * name.
+ */
+export class CodebaseSearcher {
+    project;
+    constructor(project) {
+        this.project = project;
+    }
+    /**
+     * Search for `query` across all (filtered) source files.
+     *
+     * @param query - The text, regex pattern, or symbol name to find.
+     * @param options - Search mode and optional file filter / result limit.
+     * @returns Array of `SearchResult` objects ordered by file then line.
+     *
+     * @example
+     * ```typescript
+     * searcher.search('UserService', { mode: 'symbol' });
+     * searcher.search('TODO', { mode: 'text', include: 'src/**\/*.ts' });
+     * ```
+     */
+    search(query, options) {
+        const sourceFiles = this.project
+            .getSourceFiles()
+            .filter((sf) => options.include === undefined ||
+            matchesGlob(sf.getFilePath(), options.include));
+        const results = options.mode === 'symbol'
+            ? this.searchSymbols(query, sourceFiles)
+            : this.searchText(query, options.mode, sourceFiles);
+        if (options.maxResults !== undefined) {
+            return results.slice(0, options.maxResults);
+        }
+        return results;
+    }
+    /**
+     * Text or pattern search: splits each file into lines and tests each line.
+     */
+    searchText(query, mode, sourceFiles) {
+        const results = [];
+        const regex = mode === 'pattern' ? new RegExp(query) : null;
+        for (const sf of sourceFiles) {
+            const filePath = sf.getFilePath();
+            const lines = sf.getFullText().split('\n');
+            lines.forEach((lineText, index) => {
+                const matched = regex === null ? lineText.includes(query) : regex.test(lineText);
+                if (!matched) {
+                    return;
+                }
+                const col = regex === null
+                    ? lineText.indexOf(query) + 1
+                    : lineText.search(regex) + 1;
+                results.push({
+                    file: filePath,
+                    line: index + 1,
+                    col,
+                    snippet: lineText.trim(),
+                });
+            });
+        }
+        return results;
+    }
+    /**
+     * Symbol search: finds top-level named declarations whose name equals
+     * `query`.
+     */
+    searchSymbols(query, sourceFiles) {
+        const results = [];
+        for (const sf of sourceFiles) {
+            const filePath = sf.getFilePath();
+            // Classes
+            for (const decl of sf.getClasses()) {
+                if (decl.getName() === query) {
+                    const pos = decl.getNameNode()?.getStart() ?? decl.getStart();
+                    const { line, column } = sf.getLineAndColumnAtPos(pos);
+                    results.push({
+                        file: filePath,
+                        line,
+                        col: column,
+                        snippet: (decl.getText().split('\n')[0] ?? '').trim(),
+                        symbolKind: 'class',
+                    });
+                }
+            }
+            // Functions
+            for (const decl of sf.getFunctions()) {
+                if (decl.getName() === query) {
+                    const pos = decl.getNameNode()?.getStart() ?? decl.getStart();
+                    const { line, column } = sf.getLineAndColumnAtPos(pos);
+                    results.push({
+                        file: filePath,
+                        line,
+                        col: column,
+                        snippet: (decl.getText().split('\n')[0] ?? '').trim(),
+                        symbolKind: 'function',
+                    });
+                }
+            }
+            // Interfaces
+            for (const decl of sf.getInterfaces()) {
+                if (decl.getName() === query) {
+                    const pos = decl.getNameNode().getStart();
+                    const { line, column } = sf.getLineAndColumnAtPos(pos);
+                    results.push({
+                        file: filePath,
+                        line,
+                        col: column,
+                        snippet: (decl.getText().split('\n')[0] ?? '').trim(),
+                        symbolKind: 'interface',
+                    });
+                }
+            }
+            // Enums
+            for (const decl of sf.getEnums()) {
+                if (decl.getName() === query) {
+                    const pos = decl.getNameNode().getStart();
+                    const { line, column } = sf.getLineAndColumnAtPos(pos);
+                    results.push({
+                        file: filePath,
+                        line,
+                        col: column,
+                        snippet: (decl.getText().split('\n')[0] ?? '').trim(),
+                        symbolKind: 'enum',
+                    });
+                }
+            }
+            // Type aliases
+            for (const decl of sf.getTypeAliases()) {
+                if (decl.getName() === query) {
+                    const pos = decl.getNameNode().getStart();
+                    const { line, column } = sf.getLineAndColumnAtPos(pos);
+                    results.push({
+                        file: filePath,
+                        line,
+                        col: column,
+                        snippet: (decl.getText().split('\n')[0] ?? '').trim(),
+                        symbolKind: 'typeAlias',
+                    });
+                }
+            }
+            // Variables (top-level const/let/var declarations)
+            for (const varStmt of sf.getVariableStatements()) {
+                for (const decl of varStmt.getDeclarations()) {
+                    if (decl.getName() === query) {
+                        const pos = decl.getNameNode().getStart();
+                        const { line, column } = sf.getLineAndColumnAtPos(pos);
+                        results.push({
+                            file: filePath,
+                            line,
+                            col: column,
+                            snippet: (varStmt.getText().split('\n')[0] ?? '').trim(),
+                            symbolKind: 'variable',
+                        });
+                    }
+                }
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=codebase-searcher.js.map

package/dist/investigation/codebase-searcher.js.map

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

package/dist/investigation/stack-trace-parser.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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 ?? '');
+ * ```
+ */
+/** A single resolved stack frame. */
+export interface StackFrame {
+    /** Absolute file path. For browser URL frames, the raw URL string. */
+    file: string;
+    /** 1-based line number. */
+    line: number;
+    /** 1-based column number. */
+    col: number;
+    /** Function or method name. `'<anonymous>'` when not present. */
+    functionName: string;
+    /**
+     * `true` when the frame's path starts with `projectRoot`
+     * and does not pass through `node_modules`.
+     */
+    isProjectFile: boolean;
+}
+/**
+ * Parses Node.js/Angular/Zone.js/browser stack traces into structured frames.
+ */
+export declare class StackTraceParser {
+    private readonly projectRoot;
+    /**
+     * @param projectRoot - Absolute path to the project root used to classify
+     *   frames as project files vs. external dependencies.
+     */
+    constructor(projectRoot: string);
+    /**
+     * 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: string): StackFrame[];
+    /**
+     * 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: string): StackFrame[];
+    private parseLine;
+    private buildFrame;
+    private isProjectFile;
+    /**
+     * 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.
+     */
+    private sanitizeFunctionName;
+}
+//# sourceMappingURL=stack-trace-parser.d.ts.map

package/dist/investigation/stack-trace-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-trace-parser.d.ts","sourceRoot":"","sources":["../../src/investigation/stack-trace-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IAEb,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IAEZ,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;CACxB;AAqBD;;GAEG;AACH,qBAAa,gBAAgB;IAKf,OAAO,CAAC,QAAQ,CAAC,WAAW;IAJxC;;;OAGG;gBAC0B,WAAW,EAAE,MAAM;IAEhD;;;;;OAKG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,EAAE;IAiBvC;;;;;OAKG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,EAAE;IAIpD,OAAO,CAAC,SAAS;IA0BjB,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,aAAa;IAUrB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;CAM7B"}