puremvc-typescript-graph 0.1.4

package/dist/lib/facade-resolver.js

@@ -0,0 +1,201 @@
+export function resolveFacadeConfigs(data) {
+    if (data.config.facades.length > 0) {
+        return data.config.facades;
+    }
+    const detected = [];
+    for (const [className, role] of data.classRoles) {
+        if (role === 'facade') {
+            detected.push({
+                className,
+                startupNotification: data.config.startupNotification
+            });
+        }
+    }
+    if (detected.length > 0) {
+        return detected;
+    }
+    return [
+        {
+            className: data.config.facadeClassName,
+            startupNotification: data.config.startupNotification
+        }
+    ];
+}
+export function expandStartupTree(root, macroSubCommands) {
+    const tree = new Set([root]);
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.pop();
+        for (const sub of macroSubCommands.get(current) ?? []) {
+            if (!tree.has(sub)) {
+                tree.add(sub);
+                queue.push(sub);
+            }
+        }
+    }
+    return tree;
+}
+function findStartupCommand(data, facade) {
+    const candidates = data.commandRegistrations.filter((reg) => reg.notification === facade.startupNotification);
+    if (candidates.length === 0) {
+        return null;
+    }
+    const fromFacade = candidates.find((reg) => reg.registrar === facade.className);
+    if (fromFacade) {
+        return fromFacade.commandClass;
+    }
+    const withMacro = candidates.find((reg) => data.macroSubCommands.has(reg.commandClass));
+    if (withMacro) {
+        return withMacro.commandClass;
+    }
+    return candidates[0].commandClass;
+}
+function isInStartupTree(registrar, startupTree) {
+    return registrar !== undefined && startupTree.has(registrar);
+}
+function createEmptyUnscoped() {
+    return {
+        commands: new Set(),
+        proxies: new Set(),
+        mediators: new Set(),
+        listeners: new Set()
+    };
+}
+export function buildFacadePartition(data) {
+    const facadeConfigs = resolveFacadeConfigs(data);
+    const facades = new Map();
+    const classToFacade = new Map();
+    const unscoped = createEmptyUnscoped();
+    const commandOwners = new Map();
+    const proxyOwners = new Map();
+    const mediatorOwners = new Map();
+    for (const facadeConfig of facadeConfigs) {
+        const startupCommand = findStartupCommand(data, facadeConfig);
+        const startupTree = startupCommand
+            ? expandStartupTree(startupCommand, data.macroSubCommands)
+            : new Set();
+        if (startupCommand) {
+            startupTree.add(startupCommand);
+        }
+        const scope = {
+            facadeClassName: facadeConfig.className,
+            startupNotification: facadeConfig.startupNotification,
+            startupCommand,
+            startupTree,
+            commands: new Set(),
+            proxies: new Set(),
+            mediators: new Set(),
+            listeners: new Set()
+        };
+        for (const reg of data.commandRegistrations) {
+            if (reg.notification === facadeConfig.startupNotification) {
+                if (reg.commandClass) {
+                    scope.commands.add(reg.commandClass);
+                }
+                continue;
+            }
+            if (isInStartupTree(reg.registrar, startupTree)) {
+                scope.commands.add(reg.commandClass);
+            }
+        }
+        for (const proxy of data.proxies) {
+            const registrar = data.proxyRegistrars.get(proxy);
+            if (isInStartupTree(registrar, startupTree)) {
+                scope.proxies.add(proxy);
+            }
+        }
+        for (const mediator of data.mediators) {
+            const registrar = data.mediatorRegistrars.get(mediator);
+            if (isInStartupTree(registrar, startupTree)) {
+                scope.mediators.add(mediator);
+            }
+        }
+        facades.set(facadeConfig.className, scope);
+        classToFacade.set(facadeConfig.className, facadeConfig.className);
+        for (const command of scope.commands) {
+            classToFacade.set(command, facadeConfig.className);
+        }
+        for (const proxy of scope.proxies) {
+            classToFacade.set(proxy, facadeConfig.className);
+        }
+        for (const mediator of scope.mediators) {
+            classToFacade.set(mediator, facadeConfig.className);
+        }
+        for (const node of startupTree) {
+            classToFacade.set(node, facadeConfig.className);
+        }
+        for (const reg of data.commandRegistrations) {
+            if (scope.commands.has(reg.commandClass)) {
+                commandOwners.set(reg.commandClass, facadeConfig.className);
+            }
+        }
+        for (const proxy of scope.proxies) {
+            proxyOwners.set(proxy, facadeConfig.className);
+        }
+        for (const mediator of scope.mediators) {
+            mediatorOwners.set(mediator, facadeConfig.className);
+        }
+    }
+    for (const reg of data.commandRegistrations) {
+        if (!commandOwners.has(reg.commandClass)) {
+            unscoped.commands.add(reg.commandClass);
+        }
+    }
+    for (const proxy of data.proxies) {
+        if (!proxyOwners.has(proxy)) {
+            unscoped.proxies.add(proxy);
+        }
+    }
+    for (const mediator of data.mediators) {
+        if (!mediatorOwners.has(mediator)) {
+            unscoped.mediators.add(mediator);
+        }
+    }
+    for (const [className, listener] of data.listeners) {
+        const owner = classToFacade.get(className) ??
+            mediatorOwners.get(className) ??
+            commandOwners.get(className) ??
+            proxyOwners.get(className);
+        if (owner) {
+            facades.get(owner)?.listeners.add(className);
+            classToFacade.set(className, owner);
+        }
+        else {
+            unscoped.listeners.add(className);
+        }
+    }
+    return { facades, unscoped, classToFacade };
+}
+export function resolveFacadeForClass(className, partition) {
+    return partition.classToFacade.get(className) ?? null;
+}
+export function getCommandsForNotificationInScope(data, notification, scope) {
+    return data.commandRegistrations.filter((reg) => reg.notification === notification &&
+        (scope.commands.has(reg.commandClass) ||
+            (reg.notification === scope.startupNotification &&
+                reg.commandClass === scope.startupCommand)));
+}
+export function getNotificationsInScope(data, scope) {
+    const all = new Set();
+    for (const reg of data.commandRegistrations) {
+        if (scope.commands.has(reg.commandClass)) {
+            all.add(reg.notification);
+        }
+    }
+    for (const [sender, notifications] of data.sends) {
+        if (resolveFacadeForClass(sender, data.facadePartition) !== scope.facadeClassName) {
+            continue;
+        }
+        for (const notification of notifications) {
+            all.add(notification);
+        }
+    }
+    for (const listener of data.listeners.values()) {
+        if (!scope.listeners.has(listener.className))
+            continue;
+        for (const interest of listener.interests) {
+            all.add(interest);
+        }
+    }
+    return [...all].sort();
+}

package/dist/lib/factory-resolver.d.ts

@@ -0,0 +1,4 @@
+import { type Expression } from 'ts-morph';
+export declare function collectClassNames(sourceFiles: import('ts-morph').SourceFile[]): Set<string>;
+export declare function resolveFactoryClass(expr: Expression | undefined, classNames: Set<string>, depth?: number): string | null;
+export declare function resolveProxyReference(arg: Expression | undefined): string | null;

package/dist/lib/factory-resolver.js

@@ -0,0 +1,61 @@
+import { Node } from 'ts-morph';
+export function collectClassNames(sourceFiles) {
+    const names = new Set();
+    for (const file of sourceFiles) {
+        for (const cls of file.getClasses()) {
+            const name = cls.getName();
+            if (name)
+                names.add(name);
+        }
+    }
+    return names;
+}
+export function resolveFactoryClass(expr, classNames, depth = 0) {
+    if (!expr || depth > 5)
+        return null;
+    const fromFactory = extractClassFromFactory(expr);
+    if (fromFactory)
+        return fromFactory;
+    if (Node.isIdentifier(expr)) {
+        const name = expr.getText();
+        if (classNames.has(name))
+            return name;
+        const decl = expr.getSymbol()?.getValueDeclaration();
+        if (decl && Node.isVariableDeclaration(decl)) {
+            return resolveFactoryClass(decl.getInitializer(), classNames, depth + 1);
+        }
+    }
+    return null;
+}
+function extractClassFromFactory(expr) {
+    if (Node.isNewExpression(expr)) {
+        return expr.getExpression().getText();
+    }
+    if (Node.isParenthesizedExpression(expr)) {
+        return extractClassFromFactory(expr.getExpression());
+    }
+    if (Node.isArrowFunction(expr) || Node.isFunctionExpression(expr)) {
+        const body = expr.getBody();
+        if (!body)
+            return null;
+        if (Node.isNewExpression(body)) {
+            return body.getExpression().getText();
+        }
+        if (Node.isBlock(body)) {
+            for (const stmt of body.getStatements()) {
+                if (!Node.isReturnStatement(stmt))
+                    continue;
+                const retExpr = stmt.getExpression();
+                if (retExpr && Node.isNewExpression(retExpr)) {
+                    return retExpr.getExpression().getText();
+                }
+            }
+        }
+    }
+    return null;
+}
+export function resolveProxyReference(arg) {
+    if (!arg)
+        return null;
+    return arg.getText().replace(/\.NAME$/, '');
+}

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

@@ -0,0 +1,23 @@
+import { type FacadeScope } from './facade-resolver.js';
+import { type GraphData } from './graph-parser.js';
+export declare function facadeFileSlug(facadeClassName: string): string;
+export interface FacadeDiagramFiles {
+    slug: string;
+    label: string;
+    startupMermaid: string;
+    runtimeMermaid: string;
+}
+export declare function buildStartupMermaidForScope(data: GraphData, scope: FacadeScope): string;
+export declare function buildRuntimeMermaidForScope(data: GraphData, scope: FacadeScope): string;
+export declare function buildUnscopedStartupMermaid(data: GraphData): string | null;
+export declare function buildUnscopedRuntimeMermaid(data: GraphData): string | null;
+export declare function buildFacadeDiagramFiles(data: GraphData): FacadeDiagramFiles[];
+export declare function buildMarkdown(data: GraphData): string;
+export declare function buildStats(data: GraphData): {
+    notifications: number;
+    commandRegistrations: number;
+    proxies: number;
+    mediators: number;
+    listeners: number;
+    facades: number;
+};

package/dist/lib/graph-builder.js

@@ -0,0 +1,301 @@
+import { getCommandsForNotificationInScope, getNotificationsInScope, resolveFacadeForClass } from './facade-resolver.js';
+import { getListenerRoleLabel } from './graph-parser.js';
+function safeId(name) {
+    return name.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+export function facadeFileSlug(facadeClassName) {
+    return facadeClassName.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+function wrapMermaid(kind, edges, emptyLabel) {
+    if (edges.length === 0) {
+        return `flowchart ${kind}\n  empty["${emptyLabel}"]`;
+    }
+    const direction = kind === 'TB' ? 'TB' : 'LR';
+    return [`flowchart ${kind}`, `  direction ${direction}`, ...edges].join('\n');
+}
+export function buildStartupMermaidForScope(data, scope) {
+    return wrapMermaid('TB', buildStartupEdgesForScope(data, scope), 'No startup wiring detected');
+}
+export function buildRuntimeMermaidForScope(data, scope) {
+    return wrapMermaid('LR', buildRuntimeEdgesForScope(data, scope), 'No runtime flow detected');
+}
+export function buildUnscopedStartupMermaid(data) {
+    const edges = buildUnscopedStartupEdges(data);
+    if (edges.length === 0)
+        return null;
+    return wrapMermaid('TB', edges, 'No unscoped startup wiring');
+}
+export function buildUnscopedRuntimeMermaid(data) {
+    const edges = buildUnscopedRuntimeEdges(data);
+    if (edges.length === 0)
+        return null;
+    return wrapMermaid('LR', edges, 'No unscoped runtime flow');
+}
+export function buildFacadeDiagramFiles(data) {
+    return [...data.facadePartition.facades.values()].map((scope) => ({
+        slug: facadeFileSlug(scope.facadeClassName),
+        label: scope.facadeClassName,
+        startupMermaid: buildStartupMermaidForScope(data, scope),
+        runtimeMermaid: buildRuntimeMermaidForScope(data, scope)
+    }));
+}
+function buildStartupEdgesForScope(data, scope) {
+    const edges = [];
+    for (const [macro, subs] of data.macroSubCommands) {
+        if (!scope.startupTree.has(macro))
+            continue;
+        for (const sub of subs) {
+            if (scope.startupTree.has(sub)) {
+                edges.push(`    ${safeId(macro)} --> ${safeId(sub)}`);
+            }
+        }
+    }
+    const startupCommand = scope.startupCommand ?? scope.startupTree.values().next().value ?? 'StartupCommand';
+    edges.push(`    ${safeId(scope.facadeClassName)} -->|${scope.startupNotification}| ${safeId(startupCommand)}`);
+    for (const reg of data.commandRegistrations) {
+        if (reg.notification === scope.startupNotification)
+            continue;
+        if (!scope.commands.has(reg.commandClass))
+            continue;
+        const from = reg.registrar ? safeId(reg.registrar) : safeId(startupCommand);
+        edges.push(`    ${from} -->|${reg.notification}| ${safeId(reg.commandClass)}`);
+    }
+    for (const proxy of scope.proxies) {
+        const registrar = data.proxyRegistrars.get(proxy);
+        const from = registrar ? safeId(registrar) : safeId(startupCommand);
+        edges.push(`    ${from} -->|registerProxy| ${safeId(proxy)}`);
+    }
+    for (const mediator of scope.mediators) {
+        const registrar = data.mediatorRegistrars.get(mediator);
+        const from = registrar ? safeId(registrar) : safeId(startupCommand);
+        edges.push(`    ${from} -->|registerMediator| ${safeId(mediator)}`);
+    }
+    return edges;
+}
+function buildUnscopedStartupEdges(data) {
+    const edges = [];
+    const { unscoped } = data.facadePartition;
+    for (const reg of data.commandRegistrations) {
+        if (!unscoped.commands.has(reg.commandClass))
+            continue;
+        const from = reg.registrar ? safeId(reg.registrar) : 'unscoped_registrar';
+        edges.push(`    ${from} -->|${reg.notification}| ${safeId(reg.commandClass)}`);
+    }
+    for (const proxy of unscoped.proxies) {
+        const registrar = data.proxyRegistrars.get(proxy);
+        const from = registrar ? safeId(registrar) : 'unscoped_registrar';
+        edges.push(`    ${from} -->|registerProxy| ${safeId(proxy)}`);
+    }
+    for (const mediator of unscoped.mediators) {
+        const registrar = data.mediatorRegistrars.get(mediator);
+        const from = registrar ? safeId(registrar) : 'unscoped_registrar';
+        edges.push(`    ${from} -->|registerMediator| ${safeId(mediator)}`);
+    }
+    return edges;
+}
+function buildRuntimeEdgesForScope(data, scope) {
+    const edges = [];
+    for (const [sender, notifications] of data.sends) {
+        if (resolveFacadeForClass(sender, data.facadePartition) !== scope.facadeClassName) {
+            continue;
+        }
+        for (const notification of notifications) {
+            const commands = getCommandsForNotificationInScope(data, notification, scope);
+            for (const reg of commands) {
+                edges.push(`    ${safeId(sender)} -->|"${notification}"| ${safeId(reg.commandClass)}`);
+                const proxies = data.usesProxy.get(reg.commandClass);
+                if (proxies) {
+                    for (const proxy of proxies) {
+                        if (scope.proxies.has(proxy)) {
+                            edges.push(`    ${safeId(reg.commandClass)} --> ${safeId(proxy)}`);
+                        }
+                    }
+                }
+            }
+            for (const listener of data.listeners.values()) {
+                if (!scope.listeners.has(listener.className))
+                    continue;
+                if (!listener.interests.has(notification))
+                    continue;
+                edges.push(`    ${safeId(sender)} -->|"${notification}"| ${safeId(listener.className)}`);
+            }
+        }
+    }
+    return edges;
+}
+function buildUnscopedRuntimeEdges(data) {
+    const edges = [];
+    const { unscoped } = data.facadePartition;
+    for (const [sender, notifications] of data.sends) {
+        if (resolveFacadeForClass(sender, data.facadePartition))
+            continue;
+        for (const notification of notifications) {
+            for (const reg of data.commandRegistrations) {
+                if (reg.notification !== notification)
+                    continue;
+                if (!unscoped.commands.has(reg.commandClass))
+                    continue;
+                edges.push(`    ${safeId(sender)} -->|"${notification}"| ${safeId(reg.commandClass)}`);
+            }
+            for (const listener of data.listeners.values()) {
+                if (!unscoped.listeners.has(listener.className))
+                    continue;
+                if (!listener.interests.has(notification))
+                    continue;
+                edges.push(`    ${safeId(sender)} -->|"${notification}"| ${safeId(listener.className)}`);
+            }
+        }
+    }
+    return edges;
+}
+function formatCommandHandler(data, commandClass, scope) {
+    const proxies = data.usesProxy.get(commandClass);
+    if (!proxies || proxies.size === 0)
+        return commandClass;
+    const scopedProxies = [...proxies].filter((proxy) => scope.proxies.has(proxy));
+    if (scopedProxies.length === 0)
+        return commandClass;
+    return `${commandClass} → ${scopedProxies.join(', ')}`;
+}
+function buildNotificationTableForScope(data, scope) {
+    const rows = [
+        '| Notification | Senders | Handlers |',
+        '| --- | --- | --- |'
+    ];
+    for (const notification of getNotificationsInScope(data, scope)) {
+        const senders = [...data.sends.entries()]
+            .filter(([name, set]) => set.has(notification) &&
+            resolveFacadeForClass(name, data.facadePartition) === scope.facadeClassName)
+            .map(([name]) => name);
+        const handlers = [];
+        const seenHandlers = new Set();
+        for (const reg of getCommandsForNotificationInScope(data, notification, scope)) {
+            const label = formatCommandHandler(data, reg.commandClass, scope);
+            if (!seenHandlers.has(label)) {
+                seenHandlers.add(label);
+                handlers.push(`Command: ${label}`);
+            }
+        }
+        for (const listener of data.listeners.values()) {
+            if (!scope.listeners.has(listener.className))
+                continue;
+            if (!listener.interests.has(notification))
+                continue;
+            const label = `${getListenerRoleLabel(listener.role)}: ${listener.className}`;
+            if (!seenHandlers.has(label)) {
+                seenHandlers.add(label);
+                handlers.push(label);
+            }
+        }
+        rows.push(`| \`${notification}\` | ${senders.map((s) => `\`${s}\``).join(', ') || '-'} | ${handlers.map((h) => `\`${h}\``).join(', ') || '-'} |`);
+    }
+    return rows.join('\n');
+}
+function buildFacadeOverviewTable(data) {
+    const rows = [
+        '| Facade | Startup | Commands | Proxies | Mediators | Observers |',
+        '| --- | --- | --- | --- | --- | --- |'
+    ];
+    for (const scope of data.facadePartition.facades.values()) {
+        rows.push(`| \`${scope.facadeClassName}\` | \`${scope.startupNotification}\` | ${scope.commands.size} | ${scope.proxies.size} | ${scope.mediators.size} | ${scope.listeners.size} |`);
+    }
+    const { unscoped } = data.facadePartition;
+    const unscopedTotal = unscoped.commands.size +
+        unscoped.proxies.size +
+        unscoped.mediators.size +
+        unscoped.listeners.size;
+    if (unscopedTotal > 0) {
+        rows.push(`| Unscoped | - | ${unscoped.commands.size} | ${unscoped.proxies.size} | ${unscoped.mediators.size} | ${unscoped.listeners.size} |`);
+    }
+    return rows.join('\n');
+}
+function buildComponentsTableForScope(scope) {
+    return `| Role | Classes |
+| --- | --- |
+| Command | ${[...scope.commands].map((c) => `\`${c}\``).join(', ') || '-'} |
+| Proxy | ${[...scope.proxies].map((p) => `\`${p}\``).join(', ') || '-'} |
+| Mediator | ${[...scope.mediators].map((m) => `\`${m}\``).join(', ') || '-'} |
+| Observer | ${[...scope.listeners].map((l) => `\`${l}\``).join(', ') || '-'} |`;
+}
+function buildUnscopedSection(data) {
+    const { unscoped } = data.facadePartition;
+    const total = unscoped.commands.size +
+        unscoped.proxies.size +
+        unscoped.mediators.size +
+        unscoped.listeners.size;
+    if (total === 0)
+        return '';
+    return `## Unscoped Components
+
+Components that could not be assigned to a Facade startup tree.
+
+| Role | Classes |
+| --- | --- |
+| Command | ${[...unscoped.commands].map((c) => `\`${c}\``).join(', ') || '-'} |
+| Proxy | ${[...unscoped.proxies].map((p) => `\`${p}\``).join(', ') || '-'} |
+| Mediator | ${[...unscoped.mediators].map((m) => `\`${m}\``).join(', ') || '-'} |
+| Observer | ${[...unscoped.listeners].map((l) => `\`${l}\``).join(', ') || '-'} |
+`;
+}
+function buildFacadeSections(data) {
+    const sections = [];
+    for (const scope of data.facadePartition.facades.values()) {
+        const slug = facadeFileSlug(scope.facadeClassName);
+        sections.push(`## ${scope.facadeClassName}
+
+| Diagram | File |
+| --- | --- |
+| Startup | [startup.mmd](${slug}/startup.mmd) |
+| Runtime | [runtime.mmd](${slug}/runtime.mmd) |
+
+### Notification Map
+
+${buildNotificationTableForScope(data, scope)}
+
+### Components
+
+${buildComponentsTableForScope(scope)}
+`);
+    }
+    return sections.join('\n');
+}
+function buildUnscopedFilesSection(data) {
+    const { unscoped } = data.facadePartition;
+    const hasStartup = unscoped.commands.size > 0 || unscoped.proxies.size > 0 || unscoped.mediators.size > 0;
+    const hasRuntime = unscoped.listeners.size > 0 || unscoped.commands.size > 0;
+    if (!hasStartup && !hasRuntime)
+        return '';
+    const rows = ['| Diagram | File |', '| --- | --- |'];
+    if (hasStartup)
+        rows.push('| Startup | [startup.mmd](unscoped/startup.mmd) |');
+    if (hasRuntime)
+        rows.push('| Runtime | [runtime.mmd](unscoped/runtime.mmd) |');
+    return `## Unscoped
+
+${rows.join('\n')}
+
+${buildUnscopedSection(data)}`;
+}
+export function buildMarkdown(data) {
+    const generatedAt = new Date().toISOString();
+    return `# PureMVC Architecture Graph
+
+> Auto-generated by \`npx puremvc-ts-graph\` at ${generatedAt}
+
+## Facades Overview
+
+${buildFacadeOverviewTable(data)}
+
+${buildFacadeSections(data)}
+${buildUnscopedFilesSection(data)}`;
+}
+export function buildStats(data) {
+    return {
+        notifications: data.constants.propertyCount,
+        commandRegistrations: data.commandRegistrations.length,
+        proxies: data.proxies.size,
+        mediators: data.mediators.size,
+        listeners: data.listeners.size,
+        facades: data.facadePartition.facades.size
+    };
+}

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

@@ -0,0 +1,31 @@
+export interface FacadeConfig {
+    className: string;
+    startupNotification: string;
+}
+export type ImageFormat = 'png' | 'svg';
+export interface ImageConfig {
+    enabled: boolean;
+    format: ImageFormat;
+}
+export interface PureMvcGraphConfig {
+    srcDir: string;
+    docsDir: string;
+    facadeClassName: string;
+    startupNotification: string;
+    facades: FacadeConfig[];
+    images: ImageConfig;
+    constants: {
+        glob: string[];
+        exportNames: string[];
+    };
+}
+export interface CliOptions {
+    projectRoot: string;
+    configPath?: string;
+    imageFormat?: ImageFormat;
+}
+export declare function loadConfig(root: string, configPath?: string): PureMvcGraphConfig;
+export declare function isHelpRequested(argv: string[]): boolean;
+export declare function printCliHelp(): void;
+export declare function parseCliArgs(argv: string[]): CliOptions;
+export declare function resolveImageGeneration(argv: string[], config: PureMvcGraphConfig): ImageFormat[] | undefined;