@nexus-ioc/graph-analyzer 0.1.0

package/dist/visualize/graph-analyzer.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphAnalyzer = void 0;
+const generator_1 = require("./generator");
+const html_generator_1 = require("./html-generator");
+const json_formatter_1 = require("./json-formatter");
+/**
+ * Main analyzer class for dependency injection graphs
+ *
+ * Analyzes Nexus IoC dependency graphs and generates JSON and/or PNG outputs.
+ *
+ * @example
+ * ```typescript
+ * const analyzer = new GraphAnalyzer(modulesGraph, 'src/main.ts', {
+ *   outputFormat: 'json',
+ *   jsonOutputPath: './output/graph.json'
+ * });
+ *
+ * const output = analyzer.parse();
+ * console.log(`Found ${output.metadata.totalProviders} providers`);
+ * ```
+ */
+class GraphAnalyzer {
+    /**
+     * Create a new GraphAnalyzer instance
+     *
+     * @param graph - Map of module names to parsed modules
+     * @param entryPoint - Path to application entry point file
+     * @param options - Configuration options for output generation
+     */
+    constructor(graph, entryPoint, options = {}) {
+        this.graph = graph;
+        this.entryPoint = entryPoint;
+        this.options = options;
+    }
+    /**
+     * Parse the dependency graph and generate output based on configured format
+     *
+     * @returns GraphOutput object if format is 'json', 'html', or 'both', void if format is 'png'
+     *
+     * @example
+     * ```typescript
+     * // Generate JSON only
+     * const output = analyzer.parse();
+     *
+     * // Generate PNG only
+     * analyzer.parse(); // Returns void
+     *
+     * // Generate HTML only
+     * analyzer.parse(); // Returns void
+     *
+     * // Generate both JSON and PNG
+     * const output = analyzer.parse(); // Returns GraphOutput and creates PNG
+     * ```
+     */
+    parse() {
+        const format = this.options.outputFormat || "both";
+        if (format === "json") {
+            return this.generateJson();
+        }
+        if (format === "png") {
+            this.generatePng();
+            return;
+        }
+        if (format === "html") {
+            this.generateHtml();
+            return;
+        }
+        if (format === "both") {
+            const output = this.generateJson();
+            this.generatePng();
+            return output;
+        }
+    }
+    /**
+     * Generate JSON output of the dependency graph
+     *
+     * Creates a structured JSON representation of all modules, providers, and dependencies.
+     * Optionally writes the output to a file if jsonOutputPath or outputPath is configured.
+     *
+     * @returns GraphOutput object containing modules, providers, and metadata
+     *
+     * @example
+     * ```typescript
+     * const output = analyzer.generateJson();
+     * console.log(`Total modules: ${output.metadata.totalModules}`);
+     * console.log(`Total providers: ${output.metadata.totalProviders}`);
+     * ```
+     */
+    generateJson() {
+        const formatter = new json_formatter_1.JsonFormatter(this.graph, this.entryPoint, this.options.checkCircular || false, this.options.checkUnused || false, this.options.checkDepth || false, this.options.deepModuleThreshold || 5, this.options.checkScope || false);
+        const output = formatter.format();
+        // Write to file if path is specified
+        if (this.options.jsonOutputPath || this.options.outputPath) {
+            const fs = require("node:fs");
+            const pathModule = require("node:path");
+            const path = this.options.jsonOutputPath ||
+                this.options.outputPath ||
+                "./graph.json";
+            // Ensure directory exists
+            const dir = pathModule.dirname(path);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(path, JSON.stringify(output, null, 2));
+            console.log(`JSON output written to: ${path}`);
+        }
+        return output;
+    }
+    /**
+     * Generate PNG visualization of the dependency graph using Graphviz
+     *
+     * Creates a visual graph representation showing modules as nodes and dependencies as edges.
+     * Requires Graphviz to be installed on the system.
+     *
+     * @throws Error if Graphviz is not installed or graph generation fails
+     *
+     * @example
+     * ```typescript
+     * analyzer.generatePng();
+     * // Creates graph.png in the configured output path
+     * ```
+     */
+    generatePng() {
+        const entryModule = this.graph.get("entry");
+        if (!entryModule || !entryModule.name) {
+            throw new Error("Empty entry module");
+        }
+        // biome-ignore lint/suspicious/noExplicitAny: Legacy format for GraphGenerator
+        const json = {};
+        const modules = [entryModule.name];
+        const visited = new Set(); // Track visited modules to prevent infinite loops
+        for (const module of modules) {
+            // Skip if already visited to prevent circular dependency infinite loops
+            if (visited.has(module)) {
+                continue;
+            }
+            visited.add(module);
+            const parseNsModule = this.graph.get(module);
+            if (!parseNsModule) {
+                continue;
+            }
+            json[module] = {
+                name: module,
+                imports: parseNsModule.imports,
+                exports: parseNsModule.exports,
+                isGlobal: parseNsModule.isGlobal,
+                providers: parseNsModule.providers.map((provider) => ({
+                    token: provider.token,
+                    value: provider.value,
+                    inject: provider.inject,
+                    scope: provider.scope,
+                    type: provider.type,
+                    dependencies: provider.dependencies,
+                })),
+                dependencies: parseNsModule.deps,
+            };
+            // Only add imports that haven't been visited yet
+            for (const imp of parseNsModule.imports) {
+                if (!visited.has(imp)) {
+                    modules.push(imp);
+                }
+            }
+        }
+        const pngPath = this.options.pngOutputPath || this.options.outputPath || "./graph.png";
+        const graphGenerator = new generator_1.GraphGenerator(json, pngPath);
+        graphGenerator.scan();
+        console.log(`PNG output written to: ${pngPath}`);
+    }
+    /**
+     * Generate interactive HTML visualization of the dependency graph
+     *
+     * Creates an interactive HTML page with a graph visualization using Cytoscape.js.
+     * The HTML includes zoom/pan controls, node details, search functionality, and
+     * clickable file paths that open in your IDE.
+     *
+     * @example
+     * ```typescript
+     * analyzer.generateHtml();
+     * // Creates graph.html in the configured output path
+     * ```
+     */
+    generateHtml() {
+        const htmlPath = this.options.htmlOutputPath || this.options.outputPath || "./graph.html";
+        const htmlGenerator = new html_generator_1.HtmlGenerator(this.graph, this.entryPoint, this.options.htmlOptions || {});
+        const html = htmlGenerator.generate();
+        const fs = require("node:fs");
+        const path = require("node:path");
+        // Ensure directory exists
+        const dir = path.dirname(htmlPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(htmlPath, html);
+        console.log(`HTML output written to: ${htmlPath}`);
+    }
+}
+exports.GraphAnalyzer = GraphAnalyzer;
+//# sourceMappingURL=graph-analyzer.js.map

package/dist/visualize/graph-analyzer.js.map

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

package/dist/visualize/html-generator.d.ts

@@ -0,0 +1,71 @@
+import type { ParseEntryFile } from "../parser/parse-entry-file";
+import type { ParseNsModule } from "../parser/parse-ns-module";
+/**
+ * Options for HTML generation
+ */
+export interface HtmlGeneratorOptions {
+    /** IDE protocol for clickable file links (default: 'vscode') */
+    ideProtocol?: "vscode" | "webstorm" | "idea" | "custom";
+    /** Custom IDE URL template (e.g., 'vscode://file/{path}:{line}:{column}') */
+    customIdeUrl?: string;
+    /** Title for the HTML page (default: 'Dependency Graph') */
+    title?: string;
+    /** Whether to use dark theme (default: false) */
+    darkTheme?: boolean;
+}
+/**
+ * Generates interactive HTML visualizations of dependency graphs
+ *
+ * Creates a self-contained HTML file with an interactive graph using Cytoscape.js.
+ * The graph includes modules and providers with clickable nodes, zoom/pan capabilities,
+ * and detailed information panels.
+ *
+ * @example
+ * ```typescript
+ * const generator = new HtmlGenerator(modulesGraph, 'src/main.ts', {
+ *   ideProtocol: 'vscode',
+ *   title: 'My App Dependencies',
+ *   darkTheme: true
+ * });
+ *
+ * const html = generator.generate();
+ * fs.writeFileSync('graph.html', html);
+ * ```
+ */
+export declare class HtmlGenerator {
+    readonly graph: Map<string, ParseNsModule | ParseEntryFile>;
+    private readonly entryPoint;
+    private readonly options;
+    private readonly formatter;
+    constructor(graph: Map<string, ParseNsModule | ParseEntryFile>, entryPoint: string, options?: HtmlGeneratorOptions);
+    /**
+     * Generate the complete HTML document
+     *
+     * @returns Complete HTML string ready to be written to a file
+     */
+    generate(): string;
+    /**
+     * Convert GraphOutput to Cytoscape.js format with compound nodes
+     */
+    private convertToCytoscapeFormat;
+    /**
+     * Get IDE URL for a file path
+     */
+    private getIdeUrl;
+    /**
+     * Generate warning section for providers with missing @Inject decorators
+     */
+    private generateMissingDecoratorsWarning;
+    /**
+     * Generate the complete HTML template
+     */
+    private generateHtmlTemplate;
+    /**
+     * Generate CSS styles
+     */
+    private generateStyles;
+    /**
+     * Generate JavaScript code
+     */
+    private generateScript;
+}