@densetsuuu/docteur 0.1.1-beta

package/build/src/profiler/reporters/console_reporter.js

@@ -0,0 +1,237 @@
+/*
+|--------------------------------------------------------------------------
+| Console Reporter
+|--------------------------------------------------------------------------
+|
+| Renders profiling results to the terminal using @poppinss/cliui.
+|
+*/
+import { ProfileCollector } from '../collector.js';
+import { symbols } from '../registries/index.js';
+import { colorDuration, createBar, formatDuration, getCategoryIcon, getEffectiveTime, simplifyUrl, ui, } from './format.js';
+export class ConsoleReporter {
+    /**
+     * Renders the complete report to console.
+     */
+    render(context) {
+        const { result, config, cwd } = context;
+        this.#printHeader();
+        this.#printSummary(result);
+        this.#printAppFiles(result, cwd);
+        this.#printSlowestModules(result, config, cwd);
+        if (config.groupByPackage) {
+            this.#printPackageGroups(result, config);
+        }
+        this.#printProviders(result);
+        this.#printRecommendations(result, config);
+        this.#printFooter();
+    }
+    #printHeader() {
+        ui.logger.log('');
+        ui.logger.log(ui.colors.bold(ui.colors.cyan(`  ${symbols.stethoscope} Docteur - Cold Start Analysis`)));
+        ui.logger.log(ui.colors.dim(`  ${symbols.dash}`.repeat(25)));
+        ui.logger.log('');
+    }
+    #printSummary(result) {
+        ui.logger.log(ui.colors.bold(`  ${symbols.chart} Summary`));
+        ui.logger.log('');
+        const table = ui.table();
+        table
+            .row([ui.colors.dim('Total boot time:'), colorDuration(result.totalTime)])
+            .row([
+            ui.colors.dim('Total modules loaded:'),
+            ui.colors.white(result.summary.totalModules.toString()),
+        ])
+            .row([
+            ui.colors.dim('  App modules:'),
+            ui.colors.white(result.summary.userModules.toString()),
+        ])
+            .row([
+            ui.colors.dim('  Node modules:'),
+            ui.colors.white(result.summary.nodeModules.toString()),
+        ])
+            .row([
+            ui.colors.dim('  AdonisJS modules:'),
+            ui.colors.white(result.summary.adonisModules.toString()),
+        ])
+            .row([ui.colors.dim('Module import time:'), colorDuration(result.summary.totalModuleTime)]);
+        if (result.providers.length > 0) {
+            table.row([
+                ui.colors.dim('Provider exec time:'),
+                colorDuration(result.summary.totalProviderTime),
+            ]);
+        }
+        table.render();
+        ui.logger.log('');
+    }
+    #printSlowestModules(result, config, cwd) {
+        const collector = new ProfileCollector(result.modules, result.providers);
+        const filtered = collector.filterModules(config);
+        const slowest = new ProfileCollector(filtered).getTopSlowest(config.topModules);
+        if (slowest.length === 0) {
+            ui.logger.log(ui.colors.dim('  No modules found above the threshold'));
+            return;
+        }
+        const maxTime = slowest[0] ? getEffectiveTime(slowest[0]) : 1;
+        ui.logger.log(ui.colors.bold(`  ${symbols.turtle} Slowest Module Imports (top ${config.topModules})`));
+        ui.logger.log(ui.colors.dim('  Total = with dependencies, Self = file only'));
+        ui.logger.log('');
+        const table = ui.table();
+        table
+            .head([
+            ui.colors.dim('#'),
+            ui.colors.dim('Module'),
+            ui.colors.dim('Total'),
+            ui.colors.dim('Self'),
+            ui.colors.dim(''),
+        ])
+            .columnWidths([6, 45, 11, 11, 30]);
+        slowest.forEach((module, index) => {
+            const simplified = simplifyUrl(module.resolvedUrl, cwd);
+            const totalTime = getEffectiveTime(module);
+            const selfTime = module.loadTime;
+            table.row([
+                ui.colors.dim((index + 1).toString()),
+                simplified.length > 40 ? simplified.slice(-40) : simplified,
+                colorDuration(totalTime),
+                ui.colors.dim(formatDuration(selfTime)),
+                createBar(totalTime, maxTime, 25),
+            ]);
+        });
+        table.render();
+        ui.logger.log('');
+    }
+    #printPackageGroups(result, config) {
+        const collector = new ProfileCollector(result.modules, result.providers);
+        const filtered = collector.filterModules(config);
+        const groups = new ProfileCollector(filtered).groupModulesByPackage();
+        if (groups.length === 0) {
+            return;
+        }
+        const topGroups = groups.slice(0, 10);
+        const maxTime = topGroups[0]?.totalTime || 1;
+        ui.logger.log(ui.colors.bold(`  ${symbols.package} Slowest Packages`));
+        ui.logger.log(ui.colors.dim('  Total import time per npm package'));
+        ui.logger.log('');
+        const table = ui.table();
+        table
+            .head([
+            ui.colors.dim('#'),
+            ui.colors.dim('Package'),
+            ui.colors.dim('Modules'),
+            ui.colors.dim('Total'),
+            ui.colors.dim(''),
+        ])
+            .columnWidths([6, 38, 12, 12, 35]);
+        topGroups.forEach((group, index) => {
+            table.row([
+                ui.colors.dim((index + 1).toString()),
+                group.name.length > 33 ? group.name.slice(0, 33) : group.name,
+                ui.colors.dim(group.modules.length.toString()),
+                colorDuration(group.totalTime),
+                createBar(group.totalTime, maxTime),
+            ]);
+        });
+        table.render();
+        ui.logger.log('');
+    }
+    #printProviders(result) {
+        if (result.providers.length === 0) {
+            return;
+        }
+        const sorted = [...result.providers].sort((a, b) => b.totalTime - a.totalTime);
+        const maxTime = sorted[0]?.totalTime || 1;
+        ui.logger.log(ui.colors.bold(`  ${symbols.lightning} Provider Execution Times`));
+        ui.logger.log(ui.colors.dim('  Time spent in register() and boot() methods'));
+        ui.logger.log('');
+        const table = ui.table();
+        table
+            .head([
+            ui.colors.dim('#'),
+            ui.colors.dim('Provider'),
+            ui.colors.dim('Register'),
+            ui.colors.dim('Boot'),
+            ui.colors.dim('Total'),
+            ui.colors.dim(''),
+        ])
+            .columnWidths([5, 28, 11, 11, 11, 35]);
+        sorted.forEach((provider, index) => {
+            table.row([
+                ui.colors.dim((index + 1).toString()),
+                provider.name.length > 26 ? provider.name.slice(0, 26) : provider.name,
+                colorDuration(provider.registerTime),
+                colorDuration(provider.bootTime),
+                colorDuration(provider.totalTime),
+                createBar(provider.totalTime, maxTime, 30),
+            ]);
+        });
+        table.render();
+        ui.logger.log('');
+    }
+    #printRecommendations(result, config) {
+        const recommendations = [];
+        if (result.totalTime > 2000) {
+            recommendations.push('Total boot time is over 2s. Consider lazy-loading some providers.');
+        }
+        if (result.summary.totalModules > 500) {
+            recommendations.push(`Loading ${result.summary.totalModules} modules. Consider code splitting or lazy imports.`);
+        }
+        const collector = new ProfileCollector(result.modules, result.providers);
+        const filtered = collector.filterModules(config);
+        const verySlowModules = filtered.filter((m) => getEffectiveTime(m) > 100);
+        if (verySlowModules.length > 0) {
+            recommendations.push(`${verySlowModules.length} module(s) took over 100ms to load. Check for heavy initialization code.`);
+        }
+        if (recommendations.length === 0) {
+            ui.logger.log(ui.colors.bold(`  ${symbols.checkmark} `) + ui.colors.green('No major issues detected!'));
+        }
+        else {
+            ui.logger.log(ui.colors.bold(`  ${symbols.lightbulb} Recommendations`));
+            ui.logger.log('');
+            recommendations.forEach((rec) => {
+                ui.logger.log(`  ${ui.colors.yellow(symbols.bullet)} ${rec}`);
+            });
+        }
+        ui.logger.log('');
+    }
+    #printAppFiles(result, cwd) {
+        const groups = result.summary.appFileGroups;
+        if (groups.length === 0) {
+            return;
+        }
+        ui.logger.log(ui.colors.bold(`  ${symbols.folder} App Files by Category`));
+        ui.logger.log('');
+        for (const group of groups) {
+            if (group.files.length === 0)
+                continue;
+            const icon = getCategoryIcon(group.category);
+            const header = `  ${icon} ${group.displayName} (${group.files.length} files, ${formatDuration(group.totalTime)})`;
+            ui.logger.log(ui.colors.bold(ui.colors.white(header)));
+            this.#printAppFileGroup(group, cwd);
+            ui.logger.log('');
+        }
+    }
+    #printAppFileGroup(group, cwd) {
+        const maxTime = group.files[0] ? getEffectiveTime(group.files[0]) : 1;
+        const table = ui.table();
+        table.columnWidths([35, 11, 11, 30]);
+        for (const file of group.files) {
+            const simplified = simplifyUrl(file.resolvedUrl, cwd);
+            const fileName = simplified.split('/').pop() || simplified;
+            const totalTime = getEffectiveTime(file);
+            const selfTime = file.loadTime;
+            table.row([
+                fileName.length > 33 ? fileName.slice(-33) : fileName,
+                colorDuration(totalTime),
+                ui.colors.dim(formatDuration(selfTime)),
+                createBar(totalTime, maxTime, 25),
+            ]);
+        }
+        table.render();
+    }
+    #printFooter() {
+        ui.logger.log(ui.colors.dim(`  ${symbols.dash}`.repeat(25)));
+        ui.logger.log(ui.colors.dim('  Run with --help for more options'));
+        ui.logger.log('');
+    }
+}

package/build/src/profiler/reporters/format.d.ts

@@ -0,0 +1,62 @@
+import type { AppFileCategory, ModuleTiming } from '../../types.js';
+/**
+ * Shared UI instance for consistent styling
+ */
+export declare const ui: {
+    colors: import("@poppinss/colors/types").Colors;
+    logger: import("@poppinss/cliui").Logger;
+    table: (tableOptions
+    /**
+     * Colors a duration based on how slow it is
+     */
+    ? /**
+     * Colors a duration based on how slow it is
+     */: Partial<import("@poppinss/cliui/types").TableOptions>) => import("@poppinss/cliui").Table;
+    tasks: (tasksOptions?: Partial<import("@poppinss/cliui/types").TaskManagerOptions>) => import("@poppinss/cliui").TaskManager;
+    steps: () => import("@poppinss/cliui").Steps;
+    icons: {
+        tick: string;
+        cross: string;
+        bullet: string;
+        nodejs: string;
+        pointer: string;
+        info: string;
+        warning: string;
+        squareSmallFilled: string;
+        borderVertical: string;
+    };
+    sticker: () => import("@poppinss/cliui").Instructions;
+    instructions: () => import("@poppinss/cliui").Instructions;
+    switchMode(modeToUse: "raw" | "silent" | "normal"): void;
+    useRenderer(rendererToUse: import("@poppinss/cliui/types").RendererContract): void;
+    useColors(colorsToUse: import("@poppinss/colors/types").Colors): void;
+};
+/**
+ * Get icon for a category
+ */
+export declare function getCategoryIcon(category: AppFileCategory): string;
+/**
+ * Gets the effective time for a module.
+ * Uses subtreeTime (total including dependencies) if available,
+ * otherwise falls back to loadTime.
+ */
+export declare function getEffectiveTime(module: ModuleTiming): number;
+/**
+ * Formats a duration in milliseconds for display
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Colors a duration based on how slow it is
+ */
+export declare function colorDuration(ms: number): string;
+/**
+ * Creates a visual bar representing the duration
+ */
+export declare function createBar(ms: number, maxMs: number, width?: number): string;
+/**
+ * Simplifies a module URL for display:
+ * - Strips file:// protocol
+ * - Converts absolute paths to relative (using cwd)
+ * - For node_modules, shows only the package path (handles pnpm store)
+ */
+export declare function simplifyUrl(url: string, cwd: string): string;

package/build/src/profiler/reporters/format.js

@@ -0,0 +1,84 @@
+/*
+|--------------------------------------------------------------------------
+| Formatting Utilities
+|--------------------------------------------------------------------------
+|
+| Shared formatting functions for report rendering.
+|
+*/
+import { cliui } from '@poppinss/cliui';
+import { categories, symbols } from '../registries/index.js';
+/**
+ * Shared UI instance for consistent styling
+ */
+export const ui = cliui();
+/**
+ * Get icon for a category
+ */
+export function getCategoryIcon(category) {
+    return categories[category].icon;
+}
+/**
+ * Gets the effective time for a module.
+ * Uses subtreeTime (total including dependencies) if available,
+ * otherwise falls back to loadTime.
+ */
+export function getEffectiveTime(module) {
+    return module.subtreeTime ?? module.loadTime;
+}
+/**
+ * Formats a duration in milliseconds for display
+ */
+export function formatDuration(ms) {
+    if (ms >= 1000) {
+        return `${(ms / 1000).toFixed(2)}s`;
+    }
+    return `${ms.toFixed(2)}ms`;
+}
+/**
+ * Colors a duration based on how slow it is
+ */
+export function colorDuration(ms) {
+    const formatted = formatDuration(ms);
+    if (ms >= 100)
+        return ui.colors.red(formatted);
+    if (ms >= 50)
+        return ui.colors.yellow(formatted);
+    if (ms >= 10)
+        return ui.colors.cyan(formatted);
+    return ui.colors.green(formatted);
+}
+/**
+ * Creates a visual bar representing the duration
+ */
+export function createBar(ms, maxMs, width = 30) {
+    const ratio = Math.min(ms / maxMs, 1);
+    const filled = Math.round(ratio * width);
+    const bar = symbols.barFull.repeat(filled) + symbols.barEmpty.repeat(width - filled);
+    if (ms >= 100)
+        return ui.colors.red(bar);
+    if (ms >= 50)
+        return ui.colors.yellow(bar);
+    if (ms >= 10)
+        return ui.colors.cyan(bar);
+    return ui.colors.green(bar);
+}
+/**
+ * Simplifies a module URL for display:
+ * - Strips file:// protocol
+ * - Converts absolute paths to relative (using cwd)
+ * - For node_modules, shows only the package path (handles pnpm store)
+ */
+export function simplifyUrl(url, cwd) {
+    const withoutProtocol = url.replace(/^file:\/\//, '');
+    // Use lastIndexOf to handle pnpm store paths like:
+    // .pnpm/@pkg@version/node_modules/@scope/pkg/index.js
+    const nodeModulesIndex = withoutProtocol.lastIndexOf('node_modules/');
+    if (nodeModulesIndex !== -1) {
+        return withoutProtocol.slice(nodeModulesIndex + 'node_modules/'.length);
+    }
+    if (withoutProtocol.startsWith(cwd)) {
+        return '.' + withoutProtocol.slice(cwd.length);
+    }
+    return withoutProtocol;
+}

package/build/src/profiler/reporters/tui_reporter.d.ts

@@ -0,0 +1,8 @@
+import type { Reporter, ReportContext } from './base_reporter.js';
+export declare class TuiReporter implements Reporter {
+    /**
+     * Renders an interactive TUI report using the XRay explorer.
+     * Enters alternate screen buffer for a clean experience.
+     */
+    render(context: ReportContext): Promise<void>;
+}

package/build/src/profiler/reporters/tui_reporter.js

@@ -0,0 +1,32 @@
+/*
+|--------------------------------------------------------------------------
+| TUI Reporter
+|--------------------------------------------------------------------------
+|
+| Interactive terminal UI reporter using Ink.
+| Renders an explorable dependency tree view.
+|
+*/
+import React from 'react';
+import { render } from 'ink';
+import { XRayApp } from '../../xray/components/XRayApp.js';
+export class TuiReporter {
+    /**
+     * Renders an interactive TUI report using the XRay explorer.
+     * Enters alternate screen buffer for a clean experience.
+     */
+    async render(context) {
+        const { result, cwd } = context;
+        // Enter alternate screen buffer
+        process.stdout.write('\x1b[?1049h');
+        process.stdout.write('\x1b[H');
+        try {
+            const { waitUntilExit } = render(React.createElement(XRayApp, { result, cwd }));
+            await waitUntilExit();
+        }
+        finally {
+            // Exit alternate screen buffer
+            process.stdout.write('\x1b[?1049l');
+        }
+    }
+}

package/build/src/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Timing information for a single module import
+ */
+export interface ModuleTiming {
+    /**
+     * The original import specifier (e.g., '@adonisjs/core', './app/services/user.js')
+     */
+    specifier: string;
+    /**
+     * The fully resolved URL of the module
+     */
+    resolvedUrl: string;
+    /**
+     * Time in milliseconds to load the module (file read + parse)
+     */
+    loadTime: number;
+    /**
+     * The URL of the parent module that imported this one
+     */
+    parentUrl?: string;
+    /**
+     * Total time including all transitive dependencies.
+     * This represents the actual impact of importing this module.
+     */
+    subtreeTime?: number;
+}
+/**
+ * Timing information for an AdonisJS provider
+ */
+export interface ProviderTiming {
+    /**
+     * Name of the provider class
+     */
+    name: string;
+    /**
+     * Time in milliseconds for the register phase
+     */
+    registerTime: number;
+    /**
+     * Time in milliseconds for the boot phase
+     */
+    bootTime: number;
+    /**
+     * Time in milliseconds for the start phase
+     */
+    startTime: number;
+    /**
+     * Time in milliseconds for the ready phase
+     */
+    readyTime: number;
+    /**
+     * Time in milliseconds for the shutdown phase
+     */
+    shutdownTime: number;
+    /**
+     * Total time (register + boot + start + ready)
+     */
+    totalTime: number;
+}
+/**
+ * Complete profiling results
+ */
+export interface ProfileResult {
+    /**
+     * Total cold start time in milliseconds
+     */
+    totalTime: number;
+    /**
+     * All module timing data
+     */
+    modules: ModuleTiming[];
+    /**
+     * Provider timing data
+     */
+    providers: ProviderTiming[];
+    /**
+     * Summary statistics
+     */
+    summary: ProfileSummary;
+}
+/**
+ * App file category types
+ */
+export type AppFileCategory = 'controller' | 'service' | 'model' | 'middleware' | 'validator' | 'exception' | 'event' | 'listener' | 'mailer' | 'policy' | 'command' | 'provider' | 'config' | 'start' | 'other';
+/**
+ * Grouped app files by category
+ */
+export interface AppFileGroup {
+    /**
+     * Category name (e.g., 'controller', 'service')
+     */
+    category: AppFileCategory;
+    /**
+     * Display name for the category
+     */
+    displayName: string;
+    /**
+     * Files in this category
+     */
+    files: ModuleTiming[];
+    /**
+     * Total load time for all files in this category
+     */
+    totalTime: number;
+}
+/**
+ * Summary statistics for the profile
+ */
+export interface ProfileSummary {
+    /**
+     * Total number of modules loaded
+     */
+    totalModules: number;
+    /**
+     * Number of user modules (from the app directory)
+     */
+    userModules: number;
+    /**
+     * Number of node_modules dependencies
+     */
+    nodeModules: number;
+    /**
+     * Number of AdonisJS core modules
+     */
+    adonisModules: number;
+    /**
+     * Total time spent loading modules
+     */
+    totalModuleTime: number;
+    /**
+     * Total time spent in provider lifecycle
+     */
+    totalProviderTime: number;
+    /**
+     * App files grouped by category
+     */
+    appFileGroups: AppFileGroup[];
+}
+/**
+ * Configuration options for Docteur
+ */
+export interface DocteurConfig {
+    /**
+     * Number of slowest modules to display in the report
+     * @default 20
+     */
+    topModules: number;
+    /**
+     * Only show modules that took longer than this threshold (in ms)
+     * @default 1
+     */
+    threshold: number;
+    /**
+     * Include node_modules in the analysis
+     * @default true
+     */
+    includeNodeModules: boolean;
+    /**
+     * Group modules by package name
+     * @default true
+     */
+    groupByPackage: boolean;
+}
+/**
+ * Resolved configuration with defaults applied
+ */
+export type ResolvedConfig = Required<DocteurConfig>;

package/build/src/types.js

@@ -0,0 +1,9 @@
+/*
+|--------------------------------------------------------------------------
+| Docteur Types
+|--------------------------------------------------------------------------
+|
+| Type definitions for the Docteur profiler package.
+|
+*/
+export {};

package/build/src/xray/components/ListView.d.ts

@@ -0,0 +1,9 @@
+import type { DependencyTree, ModuleNode } from '../tree.js';
+interface Props {
+    tree: DependencyTree;
+    onSelect: (node: ModuleNode) => void;
+    onSwitchToProviders: () => void;
+    hasProviders: boolean;
+}
+export declare function ListView({ tree, onSelect, onSwitchToProviders, hasProviders }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/build/src/xray/components/ListView.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import SelectInput from 'ink-select-input';
+import { formatDuration, getEffectiveTime, getFileIcon, getTimeColor, isDependency, } from '../tree.js';
+import { symbols } from '../../profiler/registries/index.js';
+function ItemComponent({ isSelected = false, label, timeStr, timeColor, fileIcon, displayName, }) {
+    // Spacer
+    if (!label) {
+        return _jsx(Text, { children: " " });
+    }
+    // Switch button
+    if (label.includes('Switch') || label.includes('Tab')) {
+        return (_jsx(Text, { color: isSelected ? 'blue' : 'cyan', bold: isSelected, children: label }));
+    }
+    if (isSelected) {
+        return (_jsxs(Text, { color: "blue", bold: true, children: [timeStr, " ", fileIcon, " ", displayName] }));
+    }
+    return (_jsxs(Text, { children: [_jsx(Text, { color: timeColor, children: timeStr }), " ", fileIcon, " ", displayName] }));
+}
+export function ListView({ tree, onSelect, onSwitchToProviders, hasProviders }) {
+    // Only show app files, not node_modules
+    const appModules = tree.sortedByTime.filter((node) => !isDependency(node.timing.resolvedUrl));
+    const moduleItems = appModules.slice(0, 30).map((node, index) => {
+        const time = getEffectiveTime(node.timing);
+        const name = node.displayName.length > 45 ? '...' + node.displayName.slice(-42) : node.displayName;
+        const url = node.timing.resolvedUrl;
+        return {
+            key: `${index}-${url}`,
+            label: name,
+            value: node,
+            timeStr: formatDuration(time).padStart(10),
+            timeColor: getTimeColor(time),
+            fileIcon: getFileIcon(url),
+            displayName: name,
+        };
+    });
+    const items = hasProviders
+        ? [
+            ...moduleItems,
+            {
+                key: 'spacer',
+                label: '',
+                value: 'switch',
+                timeStr: '',
+                timeColor: 'green',
+                fileIcon: '',
+                displayName: '',
+            },
+            {
+                key: 'switch',
+                label: `${symbols.lightning} Switch to Providers (Tab)`,
+                value: 'switch',
+                timeStr: '',
+                timeColor: 'green',
+                fileIcon: '',
+                displayName: '',
+            },
+        ]
+        : moduleItems;
+    const handleSelect = (item) => {
+        if (item.value === 'switch') {
+            onSwitchToProviders();
+        }
+        else {
+            onSelect(item.value);
+        }
+    };
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { marginBottom: 1, children: _jsxs(Text, { bold: true, color: "cyan", children: [' ', '\ue234', " Docteur X-Ray - Module Explorer"] }) }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { dimColor: true, children: " Use arrows to navigate, Enter to inspect, Tab to switch views" }) }), _jsx(Box, { flexDirection: "column", children: _jsx(SelectInput, { items: items, onSelect: handleSelect, itemComponent: ItemComponent }) })] }));
+}

package/build/src/xray/components/ModuleView.d.ts

@@ -0,0 +1,9 @@
+import type { DependencyTree, ModuleNode } from '../tree.js';
+interface Props {
+    node: ModuleNode;
+    tree: DependencyTree;
+    onNavigate: (node: ModuleNode) => void;
+    onBack: () => void;
+}
+export declare function ModuleView({ node, tree: _tree, onNavigate, onBack }: Props): import("react/jsx-runtime").JSX.Element;
+export {};