@densetsuuu/docteur 0.1.1-beta

package/build/src/profiler/loader.js

@@ -0,0 +1,111 @@
+/*
+|--------------------------------------------------------------------------
+| Profiler Loader
+|--------------------------------------------------------------------------
+|
+| Registers ESM hooks for module timing and subscribes to AdonisJS
+| tracing channels for provider lifecycle timing.
+|
+*/
+import { tracingChannels } from '@adonisjs/application';
+import { register } from 'node:module';
+import { performance } from 'node:perf_hooks';
+import { MessageChannel } from 'node:worker_threads';
+// Module timing data from hooks
+const parents = new Map();
+const loadTimes = new Map();
+// Provider timing data
+const providerPhases = new Map();
+const providerStarts = new Map();
+const asyncCalls = new Set();
+// Set up message channel for hooks
+const { port1, port2 } = new MessageChannel();
+port1.unref?.();
+port1.on('message', (msg) => {
+    if (msg.type !== 'batch' || !msg.messages)
+        return;
+    for (const m of msg.messages) {
+        if (m.type === 'parent')
+            parents.set(m.child, m.parent);
+        else if (m.type === 'timing')
+            loadTimes.set(m.url, m.loadTime);
+    }
+});
+register('./hooks.js', {
+    parentURL: import.meta.url,
+    data: { port: port2 },
+    transferList: [port2],
+});
+// Subscribe to provider lifecycle phases
+// For async methods: start -> end -> asyncStart -> asyncEnd (we wait for asyncEnd)
+// For sync methods: start -> end (we record on end, but defer to check if async fires)
+function subscribePhase(channel, phase) {
+    const getName = (msg) => msg.provider.constructor.name;
+    channel.subscribe({
+        start(msg) {
+            providerStarts.set(`${getName(msg)}:${phase}`, performance.now());
+        },
+        end(msg) {
+            const name = getName(msg);
+            const key = `${name}:${phase}`;
+            const endTime = performance.now();
+            // Defer to check if this becomes async (asyncStart fires before our setTimeout)
+            setTimeout(() => {
+                if (asyncCalls.has(key))
+                    return;
+                const start = providerStarts.get(key);
+                if (start !== undefined) {
+                    const phases = providerPhases.get(name) || {};
+                    phases[phase] = endTime - start;
+                    providerPhases.set(name, phases);
+                    providerStarts.delete(key);
+                }
+            }, 0);
+        },
+        asyncStart(msg) {
+            asyncCalls.add(`${getName(msg)}:${phase}`);
+        },
+        asyncEnd(msg) {
+            const name = getName(msg);
+            const key = `${name}:${phase}`;
+            const start = providerStarts.get(key);
+            if (start !== undefined) {
+                const phases = providerPhases.get(name) || {};
+                phases[phase] = performance.now() - start;
+                providerPhases.set(name, phases);
+                providerStarts.delete(key);
+            }
+            asyncCalls.delete(key);
+        },
+        error() { },
+    });
+}
+subscribePhase(tracingChannels.providerRegister, 'register');
+subscribePhase(tracingChannels.providerBoot, 'boot');
+subscribePhase(tracingChannels.providerStart, 'start');
+subscribePhase(tracingChannels.providerReady, 'ready');
+subscribePhase(tracingChannels.providerShutdown, 'shutdown');
+// Send results to parent process when requested
+if (process.send) {
+    process.on('message', (msg) => {
+        if (msg.type !== 'getResults')
+            return;
+        const providers = [...providerPhases.entries()].map(([name, t]) => ({
+            name,
+            registerTime: t.register || 0,
+            bootTime: t.boot || 0,
+            startTime: t.start || 0,
+            readyTime: t.ready || 0,
+            shutdownTime: t.shutdown || 0,
+            totalTime: (t.register || 0) + (t.boot || 0) + (t.start || 0) + (t.ready || 0),
+        }));
+        process.send({
+            type: 'results',
+            data: {
+                loadTimes: Object.fromEntries(loadTimes),
+                parents: Object.fromEntries(parents),
+                providers,
+            },
+        });
+    });
+}

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

@@ -0,0 +1,9 @@
+import type { ProfileResult } from '../types.js';
+export interface ProfileOptions {
+    entryPoint?: string;
+    suppressOutput?: boolean;
+}
+export declare function findLoaderPath(): string;
+export declare function findEntryPoint(cwd: string, entry?: string): string;
+export declare function isAdonisProject(cwd: string): boolean;
+export declare function profile(cwd: string, options?: ProfileOptions): Promise<ProfileResult>;

package/build/src/profiler/profiler.js

@@ -0,0 +1,117 @@
+/*
+|--------------------------------------------------------------------------
+| Core Profiler
+|--------------------------------------------------------------------------
+|
+| Standalone profiler that doesn't depend on AdonisJS Ace framework.
+| Used by both the CLI and the ace commands.
+|
+*/
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { ProfileCollector } from './collector.js';
+import { simplifyUrl } from './reporters/format.js';
+const TIMEOUT_MS = 30_000;
+export function findLoaderPath() {
+    return fileURLToPath(import.meta.resolve('@densetsuuu/docteur/profiler/loader'));
+}
+export function findEntryPoint(cwd, entry) {
+    const entryPath = join(cwd, entry || 'bin/server.ts');
+    if (!existsSync(entryPath)) {
+        throw new Error(`Entry point not found: ${entryPath}`);
+    }
+    return entryPath;
+}
+export function isAdonisProject(cwd) {
+    return existsSync(join(cwd, 'adonisrc.ts')) || existsSync(join(cwd, '.adonisrc.ts'));
+}
+export async function profile(cwd, options = {}) {
+    const loaderPath = findLoaderPath();
+    const entryPoint = findEntryPoint(cwd, options.entryPoint);
+    const state = await runProfiledProcess(loaderPath, entryPoint, cwd, options);
+    return buildResults(state, cwd);
+}
+function runProfiledProcess(loaderPath, entryPoint, cwd, options) {
+    const suppressOutput = options.suppressOutput ?? false;
+    return new Promise((resolve, reject) => {
+        const state = {
+            providers: [],
+            loadTimes: new Map(),
+            parents: new Map(),
+            done: false,
+        };
+        const child = fork(entryPoint, [], {
+            cwd,
+            stdio: ['pipe', 'pipe', 'pipe', 'ipc'],
+            execArgv: ['--import', loaderPath, '--import', '@poppinss/ts-exec', '--no-warnings'],
+            env: { ...process.env, DOCTEUR_PROFILING: 'true' },
+        });
+        const timeout = setTimeout(() => {
+            child.kill('SIGKILL');
+            reject(new Error(`Profiling timed out after ${TIMEOUT_MS / 1000} seconds`));
+        }, TIMEOUT_MS);
+        const complete = () => {
+            if (state.done)
+                return;
+            state.done = true;
+            clearTimeout(timeout);
+            child.kill('SIGTERM');
+            const forceKill = setTimeout(() => child.kill('SIGKILL'), 500);
+            child.once('exit', () => {
+                clearTimeout(forceKill);
+                resolve(state);
+            });
+        };
+        child.stdout?.on('data', (data) => {
+            const output = data.toString();
+            if (!suppressOutput)
+                process.stdout.write(output);
+            if (output.includes('started HTTP server')) {
+                child.send({ type: 'getResults' });
+            }
+        });
+        child.stderr?.on('data', (data) => {
+            if (!suppressOutput)
+                process.stderr.write(data);
+        });
+        child.on('message', (message) => {
+            const msg = message;
+            if (msg.isAdonisJS === true && msg.environment === 'web' && msg.duration) {
+                state.bootDuration = msg.duration;
+                return;
+            }
+            if (msg.type === 'results') {
+                const data = msg.data;
+                state.loadTimes = new Map(Object.entries(data.loadTimes));
+                state.parents = new Map(Object.entries(data.parents || {}));
+                state.providers = data.providers || [];
+                complete();
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+        child.on('exit', (code) => {
+            if (code !== null && code !== 0 && code !== 137 && code !== 143 && !state.done) {
+                clearTimeout(timeout);
+                reject(new Error(`Process exited with code ${code}`));
+            }
+        });
+    });
+}
+function buildResults(state, cwd) {
+    const modules = [...state.loadTimes].map(([url, loadTime]) => ({
+        specifier: simplifyUrl(url, cwd),
+        resolvedUrl: url,
+        loadTime,
+        parentUrl: state.parents.get(url),
+    }));
+    const collector = new ProfileCollector(modules, state.providers);
+    const bootTimeMs = state.bootDuration
+        ? state.bootDuration[0] * 1000 + state.bootDuration[1] / 1_000_000
+        : 0;
+    return collector.collectResults(bootTimeMs);
+}

package/build/src/profiler/registries/categories.d.ts

@@ -0,0 +1,7 @@
+import type { AppFileCategory } from '../../types.js';
+export interface CategoryDefinition {
+    displayName: string;
+    icon: string;
+    patterns: string[];
+}
+export declare const categories: Record<AppFileCategory, CategoryDefinition>;

package/build/src/profiler/registries/categories.js

@@ -0,0 +1,87 @@
+/*
+|--------------------------------------------------------------------------
+| App File Categories Registry
+|--------------------------------------------------------------------------
+|
+| Defines how app files are categorized based on path patterns,
+| along with display names and icons for each category.
+|
+*/
+import { symbols } from './symbols.js';
+export const categories = {
+    controller: {
+        displayName: 'Controllers',
+        icon: symbols.controller,
+        patterns: ['/controllers/', '_controller.'],
+    },
+    service: {
+        displayName: 'Services',
+        icon: symbols.service,
+        patterns: ['/services/', '_service.'],
+    },
+    model: {
+        displayName: 'Models',
+        icon: symbols.model,
+        patterns: ['/models/', '/model/'],
+    },
+    middleware: {
+        displayName: 'Middleware',
+        icon: symbols.middleware,
+        patterns: ['/middleware/', '_middleware.'],
+    },
+    validator: {
+        displayName: 'Validators',
+        icon: symbols.validator,
+        patterns: ['/validators/', '_validator.'],
+    },
+    exception: {
+        displayName: 'Exceptions',
+        icon: symbols.exception,
+        patterns: ['/exceptions/', '_exception.'],
+    },
+    event: {
+        displayName: 'Events',
+        icon: symbols.event,
+        patterns: ['/events/', '_event.'],
+    },
+    listener: {
+        displayName: 'Listeners',
+        icon: symbols.listener,
+        patterns: ['/listeners/', '_listener.'],
+    },
+    mailer: {
+        displayName: 'Mailers',
+        icon: symbols.mailer,
+        patterns: ['/mailers/', '_mailer.'],
+    },
+    policy: {
+        displayName: 'Policies',
+        icon: symbols.policy,
+        patterns: ['/policies/', '_policy.'],
+    },
+    command: {
+        displayName: 'Commands',
+        icon: symbols.command,
+        patterns: ['/commands/', '_command.'],
+    },
+    provider: {
+        displayName: 'Providers',
+        icon: symbols.provider,
+        patterns: ['/providers/', '_provider.'],
+    },
+    config: {
+        displayName: 'Config',
+        icon: symbols.config,
+        patterns: ['/config/'],
+    },
+    start: {
+        displayName: 'Start Files',
+        icon: symbols.start,
+        patterns: ['/start/'],
+    },
+    other: {
+        displayName: 'Other',
+        icon: symbols.file,
+        patterns: [],
+    },
+};

package/build/src/profiler/registries/index.d.ts

@@ -0,0 +1,2 @@
+export { categories, type CategoryDefinition } from './categories.js';
+export { symbols, fileIcons, type SymbolKey } from './symbols.js';

package/build/src/profiler/registries/index.js

@@ -0,0 +1,2 @@
+export { categories } from './categories.js';
+export { symbols, fileIcons } from './symbols.js';

package/build/src/profiler/registries/symbols.d.ts

@@ -0,0 +1,42 @@
+export declare const symbols: {
+    readonly controller: "🎮";
+    readonly service: "⚙️";
+    readonly model: "📦";
+    readonly middleware: "🔗";
+    readonly validator: "✅";
+    readonly exception: "💥";
+    readonly event: "📡";
+    readonly listener: "👂";
+    readonly mailer: "📧";
+    readonly policy: "🔐";
+    readonly command: "⌨️";
+    readonly provider: "🔌";
+    readonly config: "⚙️";
+    readonly start: "🚀";
+    readonly file: "📄";
+    readonly folder: "📁";
+    readonly checkmark: "✅";
+    readonly cross: "❌";
+    readonly warning: "⚠️";
+    readonly info: "ℹ️";
+    readonly lightning: "⚡";
+    readonly turtle: "🐢";
+    readonly package: "📦";
+    readonly chart: "📊";
+    readonly lightbulb: "💡";
+    readonly stethoscope: "🩺";
+    readonly barFull: "█";
+    readonly barEmpty: "░";
+    readonly barMedium: "▒";
+    readonly barLight: "▓";
+    readonly dash: "─";
+    readonly bullet: "•";
+    readonly arrow: "→";
+    readonly arrowLeft: "←";
+    readonly arrowUp: "↑";
+    readonly arrowDown: "↓";
+    readonly sourcePackage: "";
+    readonly sourceHome: "";
+};
+export declare const fileIcons: Record<string, string>;
+export type SymbolKey = keyof typeof symbols;

package/build/src/profiler/registries/symbols.js

@@ -0,0 +1,71 @@
+/*
+|--------------------------------------------------------------------------
+| Unicode Symbols Registry
+|--------------------------------------------------------------------------
+|
+| Centralized registry of Unicode symbols used throughout the UI.
+| Access via: symbols.controller, symbols.checkmark, etc.
+|
+*/
+export const symbols = {
+    // App file categories
+    controller: '\uD83C\uDFAE', // 🎮
+    service: '\u2699\uFE0F', // ⚙️
+    model: '\uD83D\uDCE6', // 📦
+    middleware: '\uD83D\uDD17', // 🔗
+    validator: '\u2705', // ✅
+    exception: '\uD83D\uDCA5', // 💥
+    event: '\uD83D\uDCE1', // 📡
+    listener: '\uD83D\uDC42', // 👂
+    mailer: '\uD83D\uDCE7', // 📧
+    policy: '\uD83D\uDD10', // 🔐
+    command: '\u2328\uFE0F', // ⌨️
+    provider: '\uD83D\uDD0C', // 🔌
+    config: '\u2699\uFE0F', // ⚙️
+    start: '\uD83D\uDE80', // 🚀
+    file: '\uD83D\uDCC4', // 📄
+    folder: '\uD83D\uDCC1', // 📁
+    // Status & UI
+    checkmark: '\u2705', // ✅
+    cross: '\u274C', // ❌
+    warning: '\u26A0\uFE0F', // ⚠️
+    info: '\u2139\uFE0F', // ℹ️
+    lightning: '\u26A1', // ⚡
+    turtle: '\uD83D\uDC22', // 🐢
+    package: '\uD83D\uDCE6', // 📦
+    chart: '\uD83D\uDCCA', // 📊
+    lightbulb: '\uD83D\uDCA1', // 💡
+    stethoscope: '\uD83E\uDE7A', // 🩺
+    // Bars (for progress indicators)
+    barFull: '\u2588', // █
+    barEmpty: '\u2591', // ░
+    barMedium: '\u2592', // ▒
+    barLight: '\u2593', // ▓
+    // Misc
+    dash: '\u2500', // ─
+    bullet: '\u2022', // •
+    arrow: '\u2192', // →
+    arrowLeft: '\u2190', // ←
+    arrowUp: '\u2191', // ↑
+    arrowDown: '\u2193', // ↓
+    // Nerd Font source icons (for TUI)
+    sourcePackage: '\uf487',
+    sourceHome: '\uf015',
+};
+// Nerd Font file icons by extension
+export const fileIcons = {
+    ts: '\ue628',
+    tsx: '\ue628',
+    js: '\ue781',
+    jsx: '\ue781',
+    mjs: '\ue718',
+    cjs: '\ue718',
+    json: '\ue60b',
+    vue: '\ue6a0',
+    css: '\ue749',
+    scss: '\ue749',
+    sass: '\ue749',
+    html: '\ue736',
+    md: '\ue73e',
+    default: '\uf15b',
+};

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

@@ -0,0 +1,19 @@
+import type { ProfileResult, ResolvedConfig } from '../../types.js';
+/**
+ * Context passed to reporters containing all data needed for rendering.
+ */
+export interface ReportContext {
+    result: ProfileResult;
+    config: ResolvedConfig;
+    cwd: string;
+}
+/**
+ * Strategy interface for rendering profile reports.
+ * Implementations can render to console, TUI, file, etc.
+ */
+export interface Reporter {
+    /**
+     * Renders the complete report using the provided context.
+     */
+    render(context: ReportContext): void | Promise<void>;
+}

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

@@ -0,0 +1,9 @@
+/*
+|--------------------------------------------------------------------------
+| Reporter Types
+|--------------------------------------------------------------------------
+|
+| Type definitions for the reporter strategy pattern.
+|
+*/
+export {};

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

@@ -0,0 +1,8 @@
+import type { ReportContext, Reporter } from './base_reporter.js';
+export declare class ConsoleReporter implements Reporter {
+    #private;
+    /**
+     * Renders the complete report to console.
+     */
+    render(context: ReportContext): void;
+}