puremvc-typescript-graph 0.1.4

package/dist/lib/graph-config.js

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+function normalizeConstantsGlob(glob) {
+    if (!glob)
+        return [...DEFAULT_CONFIG.constants.glob];
+    return Array.isArray(glob) ? glob : [glob];
+}
+const DEFAULT_CONFIG = {
+    srcDir: 'src',
+    docsDir: 'docs',
+    facadeClassName: 'AppFacade',
+    startupNotification: 'startup',
+    facades: [],
+    images: {
+        enabled: false,
+        format: 'png'
+    },
+    constants: {
+        glob: ['**/*Constants.ts'],
+        exportNames: []
+    }
+};
+function normalizeFacades(raw) {
+    if (raw.facades && raw.facades.length > 0) {
+        return raw.facades.map((facade) => ({
+            className: facade.className,
+            startupNotification: facade.startupNotification
+        }));
+    }
+    return [];
+}
+export function loadConfig(root, configPath) {
+    const resolvedPath = configPath
+        ? isAbsolute(configPath)
+            ? configPath
+            : join(root, configPath)
+        : join(root, 'puremvc-graph.config.json');
+    if (!existsSync(resolvedPath)) {
+        return { ...DEFAULT_CONFIG };
+    }
+    const raw = JSON.parse(readFileSync(resolvedPath, 'utf8'));
+    return {
+        srcDir: raw.srcDir ?? DEFAULT_CONFIG.srcDir,
+        docsDir: raw.docsDir ?? DEFAULT_CONFIG.docsDir,
+        facadeClassName: raw.facadeClassName ?? DEFAULT_CONFIG.facadeClassName,
+        startupNotification: raw.startupNotification ?? DEFAULT_CONFIG.startupNotification,
+        facades: normalizeFacades(raw),
+        images: {
+            enabled: raw.images?.enabled ?? DEFAULT_CONFIG.images.enabled,
+            format: raw.images?.format ?? DEFAULT_CONFIG.images.format
+        },
+        constants: {
+            glob: normalizeConstantsGlob(raw.constants?.glob),
+            exportNames: raw.constants?.exportNames ?? DEFAULT_CONFIG.constants.exportNames
+        }
+    };
+}
+const IMAGE_FORMATS = ['png', 'svg'];
+function isImageFormat(value) {
+    return IMAGE_FORMATS.includes(value);
+}
+export function isHelpRequested(argv) {
+    return argv.includes('--help') || argv.includes('-h');
+}
+export function printCliHelp() {
+    console.log(`Usage: puremvc-graph [options]
+
+Options:
+  --config <path>     Config file path (default: puremvc-graph.config.json)
+  --cwd <path>        Project root directory (default: current directory)
+  --format <fmt>      Image format: png, svg, or png,svg (generates selected formats)
+  --png               Generate PNG images (shortcut for --format png)
+  --svg               Generate SVG images (shortcut for --format svg)
+  --images            Generate images using config images.format
+  -h, --help          Show this help
+
+Config (puremvc-graph.config.json):
+  images.enabled      Generate images on every run (default: false)
+  images.format       Default format when using --images or images.enabled (default: png)
+`);
+}
+function parseImageFormats(argv, configFormat) {
+    const formats = new Set();
+    const formatIndex = argv.indexOf('--format');
+    if (formatIndex !== -1) {
+        const value = argv[formatIndex + 1];
+        if (!value || value.startsWith('-')) {
+            throw new Error('--format requires a value: png, svg, or png,svg');
+        }
+        for (const part of value.split(',')) {
+            const normalized = part.trim().toLowerCase();
+            if (!normalized)
+                continue;
+            if (!isImageFormat(normalized)) {
+                throw new Error(`Invalid image format "${part}". Use png, svg, or png,svg.`);
+            }
+            formats.add(normalized);
+        }
+    }
+    if (argv.includes('--png'))
+        formats.add('png');
+    if (argv.includes('--svg'))
+        formats.add('svg');
+    if (argv.includes('--images') && formats.size === 0)
+        formats.add(configFormat);
+    return [...formats];
+}
+export function parseCliArgs(argv) {
+    const cwdIndex = argv.indexOf('--cwd');
+    const projectRoot = cwdIndex !== -1 && argv[cwdIndex + 1]
+        ? resolve(argv[cwdIndex + 1])
+        : process.cwd();
+    const configIndex = argv.indexOf('--config');
+    const configPath = configIndex !== -1 && argv[configIndex + 1] ? argv[configIndex + 1] : undefined;
+    return { projectRoot, configPath };
+}
+export function resolveImageGeneration(argv, config) {
+    const fromCli = parseImageFormats(argv, config.images.format);
+    if (fromCli.length > 0)
+        return fromCli;
+    if (config.images.enabled)
+        return [config.images.format];
+    return undefined;
+}

package/dist/lib/graph-parser.d.ts

@@ -0,0 +1,35 @@
+import { SourceFile } from 'ts-morph';
+import { ConstantsStore } from './constants-resolver.js';
+import { type FacadePartition } from './facade-resolver.js';
+import type { PureMvcGraphConfig } from './graph-config.js';
+export type ClassRole = 'command' | 'mediator' | 'proxy' | 'facade' | 'other';
+export interface CommandRegistration {
+    notification: string;
+    commandClass: string;
+    registrar?: string;
+}
+export interface ListenerInfo {
+    className: string;
+    role: ClassRole;
+    interests: Set<string>;
+}
+export interface GraphData {
+    constants: ConstantsStore;
+    commandRegistrations: CommandRegistration[];
+    proxies: Set<string>;
+    mediators: Set<string>;
+    proxyRegistrars: Map<string, string>;
+    mediatorRegistrars: Map<string, string>;
+    sends: Map<string, Set<string>>;
+    listeners: Map<string, ListenerInfo>;
+    usesProxy: Map<string, Set<string>>;
+    macroSubCommands: Map<string, string[]>;
+    classRoles: Map<string, ClassRole>;
+    facadePartition: FacadePartition;
+    config: PureMvcGraphConfig;
+}
+export declare function collectGraphData(sourceFiles: SourceFile[], config: PureMvcGraphConfig): GraphData;
+export declare function getCommandsForNotification(data: GraphData, notification: string): CommandRegistration[];
+export declare function getRegisteredCommandClasses(data: GraphData): string[];
+export declare function getListenerRoleLabel(role: ClassRole): string;
+export declare function getAllNotifications(data: GraphData): string[];

package/dist/lib/graph-parser.js

@@ -0,0 +1,226 @@
+import { SyntaxKind } from 'ts-morph';
+import { ConstantsStore } from './constants-resolver.js';
+import { buildFacadePartition } from './facade-resolver.js';
+import { collectClassNames, resolveFactoryClass, resolveProxyReference } from './factory-resolver.js';
+function getEnclosingClassName(node) {
+    const cls = node.getFirstAncestorByKind(SyntaxKind.ClassDeclaration);
+    return cls?.getName() ?? null;
+}
+function inferClassRole(classDecl) {
+    const extendsExpr = classDecl.getExtends()?.getText() ?? '';
+    if (/Mediator/.test(extendsExpr))
+        return 'mediator';
+    if (/Proxy/.test(extendsExpr))
+        return 'proxy';
+    if (/SimpleCommand|MacroCommand/.test(extendsExpr))
+        return 'command';
+    if (/Facade/.test(extendsExpr))
+        return 'facade';
+    return 'other';
+}
+function buildClassRoles(sourceFiles) {
+    const roles = new Map();
+    for (const file of sourceFiles) {
+        for (const cls of file.getClasses()) {
+            const name = cls.getName();
+            if (name)
+                roles.set(name, inferClassRole(cls));
+        }
+    }
+    return roles;
+}
+function parseRegisterCommands(sourceFiles, constants, classNames, registrations) {
+    for (const file of sourceFiles) {
+        for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            if (!call.getExpression().getText().endsWith('registerCommand'))
+                continue;
+            const args = call.getArguments();
+            if (args.length < 2)
+                continue;
+            const notification = constants.resolve(args[0]);
+            const commandClass = resolveFactoryClass(args[1], classNames);
+            const registrar = getEnclosingClassName(call) ?? undefined;
+            if (notification && commandClass) {
+                registrations.push({ notification, commandClass, registrar });
+            }
+        }
+    }
+}
+function parseMacroSubCommands(sourceFiles, classNames, macroSubCommands) {
+    for (const file of sourceFiles) {
+        for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            if (call.getExpression().getText() !== 'this.addSubCommand')
+                continue;
+            const className = getEnclosingClassName(call);
+            const subCommand = resolveFactoryClass(call.getArguments()[0], classNames);
+            if (!className || !subCommand)
+                continue;
+            const existing = macroSubCommands.get(className) ?? [];
+            existing.push(subCommand);
+            macroSubCommands.set(className, existing);
+        }
+    }
+}
+function parseRegistrations(sourceFiles, classNames, proxies, mediators, proxyRegistrars, mediatorRegistrars) {
+    for (const file of sourceFiles) {
+        for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            const expr = call.getExpression().getText();
+            const arg = call.getArguments()[0];
+            const registrar = getEnclosingClassName(call);
+            if (expr.endsWith('registerProxy')) {
+                const proxyClass = resolveFactoryClass(arg, classNames);
+                if (proxyClass) {
+                    proxies.add(proxyClass);
+                    if (registrar)
+                        proxyRegistrars.set(proxyClass, registrar);
+                }
+            }
+            if (expr.endsWith('registerMediator')) {
+                const mediatorClass = resolveFactoryClass(arg, classNames);
+                if (mediatorClass) {
+                    mediators.add(mediatorClass);
+                    if (registrar)
+                        mediatorRegistrars.set(mediatorClass, registrar);
+                }
+            }
+        }
+    }
+}
+function parseSendNotifications(sourceFiles, constants, sends) {
+    for (const file of sourceFiles) {
+        for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            if (!call.getExpression().getText().endsWith('sendNotification'))
+                continue;
+            const className = getEnclosingClassName(call);
+            const notification = constants.resolve(call.getArguments()[0]);
+            if (!className || !notification)
+                continue;
+            const existing = sends.get(className) ?? new Set();
+            existing.add(notification);
+            sends.set(className, existing);
+        }
+    }
+}
+function parseListeners(sourceFiles, constants, classRoles, listeners) {
+    for (const file of sourceFiles) {
+        for (const method of file.getDescendantsOfKind(SyntaxKind.MethodDeclaration)) {
+            if (method.getName() !== 'listNotificationInterests')
+                continue;
+            const classDecl = method.getParentIfKind(SyntaxKind.ClassDeclaration);
+            const className = classDecl?.getName();
+            if (!className)
+                continue;
+            const interests = new Set();
+            for (const ret of method.getDescendantsOfKind(SyntaxKind.ReturnStatement)) {
+                const expr = ret.getExpression();
+                if (!expr)
+                    continue;
+                for (const name of constants.resolveArray(expr, classDecl)) {
+                    interests.add(name);
+                }
+            }
+            if (interests.size > 0) {
+                listeners.set(className, {
+                    className,
+                    role: classRoles.get(className) ?? 'other',
+                    interests
+                });
+            }
+        }
+    }
+}
+function parseUsesProxy(sourceFiles, usesProxy) {
+    for (const file of sourceFiles) {
+        for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            if (!call.getExpression().getText().endsWith('retrieveProxy'))
+                continue;
+            const className = getEnclosingClassName(call);
+            const proxyName = resolveProxyReference(call.getArguments()[0]);
+            if (!className || !proxyName)
+                continue;
+            const existing = usesProxy.get(className) ?? new Set();
+            existing.add(proxyName);
+            usesProxy.set(className, existing);
+        }
+    }
+}
+export function collectGraphData(sourceFiles, config) {
+    const constants = new ConstantsStore();
+    constants.parseFromSourceFiles(sourceFiles, config);
+    const classNames = collectClassNames(sourceFiles);
+    const classRoles = buildClassRoles(sourceFiles);
+    const commandRegistrations = [];
+    const proxies = new Set();
+    const mediators = new Set();
+    const proxyRegistrars = new Map();
+    const mediatorRegistrars = new Map();
+    const sends = new Map();
+    const listeners = new Map();
+    const usesProxy = new Map();
+    const macroSubCommands = new Map();
+    parseRegisterCommands(sourceFiles, constants, classNames, commandRegistrations);
+    parseMacroSubCommands(sourceFiles, classNames, macroSubCommands);
+    parseRegistrations(sourceFiles, classNames, proxies, mediators, proxyRegistrars, mediatorRegistrars);
+    parseSendNotifications(sourceFiles, constants, sends);
+    parseListeners(sourceFiles, constants, classRoles, listeners);
+    parseUsesProxy(sourceFiles, usesProxy);
+    const partialData = {
+        constants,
+        commandRegistrations,
+        proxies,
+        mediators,
+        proxyRegistrars,
+        mediatorRegistrars,
+        sends,
+        listeners,
+        usesProxy,
+        macroSubCommands,
+        classRoles,
+        facadePartition: {
+            facades: new Map(),
+            unscoped: {
+                commands: new Set(),
+                proxies: new Set(),
+                mediators: new Set(),
+                listeners: new Set()
+            },
+            classToFacade: new Map()
+        },
+        config
+    };
+    partialData.facadePartition = buildFacadePartition(partialData);
+    return partialData;
+}
+export function getCommandsForNotification(data, notification) {
+    return data.commandRegistrations.filter((r) => r.notification === notification);
+}
+export function getRegisteredCommandClasses(data) {
+    return [...new Set(data.commandRegistrations.map((r) => r.commandClass))];
+}
+export function getListenerRoleLabel(role) {
+    switch (role) {
+        case 'mediator':
+            return 'Mediator';
+        case 'command':
+            return 'Command (observer)';
+        case 'proxy':
+            return 'Proxy (observer)';
+        default:
+            return 'Observer';
+    }
+}
+export function getAllNotifications(data) {
+    const all = new Set();
+    for (const reg of data.commandRegistrations) {
+        all.add(reg.notification);
+    }
+    for (const interests of [...data.sends.values()].flatMap((s) => [...s])) {
+        all.add(interests);
+    }
+    for (const listener of data.listeners.values()) {
+        for (const interest of listener.interests) {
+            all.add(interest);
+        }
+    }
+    return [...all].sort();
+}

package/dist/lib/image-generator.d.ts

@@ -0,0 +1,8 @@
+import type { ImageFormat } from './graph-config.js';
+export interface ImageGenerationResult {
+    generated: string[];
+    failed: string[];
+}
+export declare function mmdcAvailable(): boolean;
+export declare function getMmdcInstallHint(): string;
+export declare function generateImages(mmdPaths: string[], format: ImageFormat): ImageGenerationResult;

package/dist/lib/image-generator.js

@@ -0,0 +1,56 @@
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const require = createRequire(fileURLToPath(import.meta.url));
+function resolveMmdcPath() {
+    try {
+        const entryPath = require.resolve('@mermaid-js/mermaid-cli');
+        return join(dirname(entryPath), 'cli.js');
+    }
+    catch {
+        return null;
+    }
+}
+function runMmdc(inputPath, outputPath, format) {
+    const mmdcPath = resolveMmdcPath();
+    if (!mmdcPath) {
+        return false;
+    }
+    const result = spawnSync(process.execPath, [mmdcPath, '-i', inputPath, '-o', outputPath, '-e', format], { stdio: 'pipe', encoding: 'utf8' });
+    if (result.status !== 0) {
+        const stderr = result.stderr?.trim();
+        if (stderr) {
+            console.error(stderr);
+        }
+        return false;
+    }
+    return true;
+}
+export function mmdcAvailable() {
+    return resolveMmdcPath() !== null;
+}
+export function getMmdcInstallHint() {
+    return 'Install @mermaid-js/mermaid-cli: npm install -D @mermaid-js/mermaid-cli';
+}
+export function generateImages(mmdPaths, format) {
+    const generated = [];
+    const failed = [];
+    if (!mmdcAvailable()) {
+        console.error(getMmdcInstallHint());
+        return { generated, failed: mmdPaths.map((p) => replaceExtension(p, format)) };
+    }
+    for (const mmdPath of mmdPaths) {
+        const outputPath = resolve(replaceExtension(mmdPath, format));
+        if (runMmdc(resolve(mmdPath), outputPath, format)) {
+            generated.push(outputPath);
+        }
+        else {
+            failed.push(outputPath);
+        }
+    }
+    return { generated, failed };
+}
+function replaceExtension(filePath, format) {
+    return filePath.replace(/\.mmd$/i, `.${format}`);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "puremvc-typescript-graph",
+    "version": "0.1.4",
+    "description": "CLI tool that scans PureMVC TypeScript code and auto-generates Mermaid diagrams of notification flows and startup wiring (Command, Proxy, Mediator).",
+    "type": "module",
+    "bin": {
+        "puremvc-graph": "dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "puremvc-graph.config.example.json"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "puremvc",
+        "typescript",
+        "mermaid",
+        "diagram",
+        "architecture",
+        "cli"
+    ],
+    "license": "MIT",
+    "author": "vizyman <viz.anything@gmail.com>",
+    "homepage": "https://github.com/puremvc/puremvc-typescript-graph#readme",
+    "bugs": {
+        "url": "https://github.com/puremvc/puremvc-typescript-graph/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/puremvc/puremvc-typescript-graph.git"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "dependencies": {
+        "ts-morph": "^25.0.0"
+    },
+    "optionalDependencies": {
+        "@mermaid-js/mermaid-cli": "^11.4.0"
+    },
+    "devDependencies": {
+        "@mermaid-js/mermaid-cli": "^11.4.0",
+        "@types/node": "^22.0.0",
+        "typescript": "^5.7.0"
+    }
+}

package/puremvc-graph.config.example.json

@@ -0,0 +1,25 @@
+{
+  "srcDir": "src",
+  "docsDir": "docs",
+  "facades": [
+    {
+      "className": "AppFacade",
+      "startupNotification": "startup"
+    },
+    {
+      "className": "TodoModuleFacade",
+      "startupNotification": "moduleStartup"
+    }
+  ],
+  "images": {
+    "enabled": false,
+    "format": "png"
+  },
+  "constants": {
+    "glob": [
+      "**/*Constants.ts",
+      "**/notifications.ts"
+    ],
+    "exportNames": ["AppConstants", "TodoConstants"]
+  }
+}