@densetsuuu/docteur 0.1.1-beta

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright (c) 2023
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# Docteur
+
+> AdonisJS cold start profiler - Analyze and optimize your application boot time
+
+Docteur profiles your AdonisJS application's cold start performance. It measures how long each module takes to load and helps you identify bottlenecks in your boot process.
+
+## Installation
+
+Install globally:
+
+```bash
+npm install -g @densetsuuu/docteur
+# or
+pnpm add -g @densetsuuu/docteur
+```
+
+## Usage
+
+Navigate to your AdonisJS project and run:
+
+```bash
+# Quick diagnosis
+docteur diagnose
+
+# Interactive explorer
+docteur xray
+```
+
+### Commands
+
+#### `docteur diagnose`
+
+Analyzes cold start performance and displays a report.
+
+```bash
+docteur diagnose [options]
+```
+
+| Option              | Description                             | Default         |
+| ------------------- | --------------------------------------- | --------------- |
+| `--top`             | Number of slowest modules to display    | 20              |
+| `--threshold`       | Only show modules slower than this (ms) | 1               |
+| `--no-node-modules` | Exclude node_modules from analysis      | false           |
+| `--no-group`        | Don't group modules by package          | false           |
+| `--entry`           | Custom entry point to profile           | `bin/server.ts` |
+
+#### `docteur xray`
+
+Interactive TUI for exploring module dependencies.
+
+```bash
+docteur xray [options]
+```
+
+| Option    | Description               | Default         |
+| --------- | ------------------------- | --------------- |
+| `--entry` | Custom entry point        | `bin/server.ts` |
+
+**Features:**
+- Browse slowest modules
+- Drill down into module dependencies
+- See why a module was loaded (import chain)
+- View lazy import recommendations for heavy dependencies
+- Explore provider lifecycle times (register, boot, start, ready)
+
+**Keyboard shortcuts:**
+- `↑/↓` Navigate
+- `Enter` Select
+- `Tab` Switch between Modules/Providers view
+- `←/Backspace/ESC` Go back
+- `q` Quit
+
+### Example Output
+
+```
+  🩺 Docteur - Cold Start Analysis
+  ─────────────────────────────────
+
+  📊 Summary
+
+  Total boot time:       459.26ms
+  Total modules loaded:  447
+    App modules:         19
+    Node modules:        221
+    AdonisJS modules:    186
+  Module import time:    72.91ms
+  Provider exec time:    12.35ms
+
+  📁 App Files by Category
+
+  🚀 Start Files (4 files, 15.23ms)
+  ┌───────────────────────┬──────────┬──────────┬────────────────────────┐
+  │ routes.ts             │ 10.53ms  │ 0.19ms   │ █████████████████████  │
+  │ kernel.ts             │  2.15ms  │ 0.08ms   │ ████░░░░░░░░░░░░░░░░░  │
+  │ env.ts                │  1.89ms  │ 0.12ms   │ ████░░░░░░░░░░░░░░░░░  │
+  └───────────────────────┴──────────┴──────────┴────────────────────────┘
+
+  ⚡ Provider Execution Times
+  Time spent in register() and boot() methods
+
+  ┌─────────────────────┬──────────┬──────────┬──────────┬────────────┐
+  │ Provider            │ Register │ Boot     │ Total    │            │
+  ├─────────────────────┼──────────┼──────────┼──────────┼────────────┤
+  │ EdgeServiceProvider │ 0.15ms   │ 2.76ms   │ 2.91ms   │ ████████   │
+  │ HashServiceProvider │ 0.08ms   │ 1.23ms   │ 1.31ms   │ ████       │
+  └─────────────────────┴──────────┴──────────┴──────────┴────────────┘
+
+  ✅ No major issues detected!
+```
+
+## How It Works
+
+Docteur measures cold start performance through two complementary approaches:
+
+1. **Module Loading**: Uses Node.js ESM loader hooks to intercept every `import()` and measure how long each module takes to load.
+
+2. **Provider Lifecycle**: Subscribes to AdonisJS's built-in tracing channels to measure the duration of provider lifecycle methods (register, boot, start, ready).
+
+### Timing Columns
+
+- **Total**: Time including all transitive dependencies (cascading impact)
+- **Self**: Time for just that file (excluding dependencies)
+
+### Execution Flow
+
+```
+1. docteur diagnose
+       │
+       ▼
+2. Spawns child process with --import loader.ts
+       │
+       ▼
+3. loader.ts registers ESM hooks + subscribes to tracing channels
+       │
+       ▼
+4. hooks.ts intercepts every import, measures load time
+       │
+       ▼
+5. AdonisJS app starts, HTTP server listens
+       │
+       ▼
+6. CLI detects "started HTTP server", requests results
+       │
+       ▼
+7. Results sent via IPC, report displayed
+```
+
+## Requirements
+
+- AdonisJS v7+
+- Node.js 21+
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Export types for consumers
+ */
+export type { ModuleTiming, ProviderTiming, ProfileResult, ProfileSummary, DocteurConfig, ResolvedConfig, AppFileCategory, AppFileGroup, } from './src/types.js';
+/**
+ * Export profiler for programmatic usage
+ */
+export { profile, isAdonisProject, findEntryPoint } from './src/profiler/profiler.js';
+/**
+ * Export collector class for advanced usage
+ */
+export { ProfileCollector, type PackageGroup } from './src/profiler/collector.js';
+/**
+ * Export reporters for custom reporting
+ */
+export type { Reporter, ReportContext } from './src/profiler/reporters/base_reporter.js';
+export { ConsoleReporter } from './src/profiler/reporters/console_reporter.js';
+export { TuiReporter } from './src/profiler/reporters/tui_reporter.js';
+export { colorDuration, createBar, formatDuration, getCategoryIcon, getEffectiveTime, simplifyUrl, ui, } from './src/profiler/reporters/format.js';
+/**
+ * Export registries for customization
+ */
+export { categories, fileIcons, symbols, type CategoryDefinition, type SymbolKey, } from './src/profiler/registries/index.js';

package/build/index.js

@@ -0,0 +1,23 @@
+/*
+|--------------------------------------------------------------------------
+| Package entrypoint
+|--------------------------------------------------------------------------
+|
+| Export values from the package entrypoint as you see fit.
+|
+*/
+/**
+ * Export profiler for programmatic usage
+ */
+export { profile, isAdonisProject, findEntryPoint } from './src/profiler/profiler.js';
+/**
+ * Export collector class for advanced usage
+ */
+export { ProfileCollector } from './src/profiler/collector.js';
+export { ConsoleReporter } from './src/profiler/reporters/console_reporter.js';
+export { TuiReporter } from './src/profiler/reporters/tui_reporter.js';
+export { colorDuration, createBar, formatDuration, getCategoryIcon, getEffectiveTime, simplifyUrl, ui, } from './src/profiler/reporters/format.js';
+/**
+ * Export registries for customization
+ */
+export { categories, fileIcons, symbols, } from './src/profiler/registries/index.js';

package/build/src/cli/commands/diagnose.d.ts

@@ -0,0 +1,27 @@
+export declare const diagnoseCommand: import("citty").CommandDef<{
+    readonly top: {
+        readonly type: "string";
+        readonly description: "Number of slowest modules to display";
+        readonly default: "20";
+    };
+    readonly threshold: {
+        readonly type: "string";
+        readonly description: "Only show modules slower than this threshold (in ms)";
+        readonly default: "1";
+    };
+    readonly 'node-modules': {
+        readonly type: "boolean";
+        readonly description: "Include node_modules in the analysis";
+        readonly default: true;
+    };
+    readonly group: {
+        readonly type: "boolean";
+        readonly description: "Group modules by package name";
+        readonly default: true;
+    };
+    readonly entry: {
+        readonly type: "string";
+        readonly description: "Entry point to profile";
+        readonly default: "bin/server.ts";
+    };
+}>;

package/build/src/cli/commands/diagnose.js

@@ -0,0 +1,67 @@
+import { defineCommand } from 'citty';
+import { isAdonisProject, profile } from '../../profiler/profiler.js';
+import { ConsoleReporter } from '../../profiler/reporters/console_reporter.js';
+import { ui } from '../../profiler/reporters/format.js';
+export const diagnoseCommand = defineCommand({
+    meta: {
+        name: 'diagnose',
+        description: 'Analyze cold start performance',
+    },
+    args: {
+        'top': {
+            type: 'string',
+            description: 'Number of slowest modules to display',
+            default: '20',
+        },
+        'threshold': {
+            type: 'string',
+            description: 'Only show modules slower than this threshold (in ms)',
+            default: '1',
+        },
+        'node-modules': {
+            type: 'boolean',
+            description: 'Include node_modules in the analysis',
+            default: true,
+        },
+        'group': {
+            type: 'boolean',
+            description: 'Group modules by package name',
+            default: true,
+        },
+        'entry': {
+            type: 'string',
+            description: 'Entry point to profile',
+            default: 'bin/server.ts',
+        },
+    },
+    async run({ args }) {
+        const cwd = process.cwd();
+        if (!isAdonisProject(cwd)) {
+            ui.logger.error('Not an AdonisJS project. Make sure adonisrc.ts exists.');
+            process.exit(1);
+        }
+        ui.logger.info('Starting cold start analysis...');
+        ui.logger.info(`Entry point: ${args.entry}`);
+        try {
+            const result = await profile(cwd, { entryPoint: args.entry });
+            const reporter = new ConsoleReporter();
+            reporter.render({
+                result,
+                cwd,
+                config: {
+                    topModules: Number.parseInt(args.top, 10),
+                    threshold: Number.parseInt(args.threshold, 10),
+                    includeNodeModules: args['node-modules'],
+                    groupByPackage: args.group,
+                },
+            });
+        }
+        catch (error) {
+            ui.logger.error('Profiling failed');
+            if (error instanceof Error) {
+                ui.logger.error(error.message);
+            }
+            process.exit(1);
+        }
+    },
+});

package/build/src/cli/commands/xray.d.ts

@@ -0,0 +1,7 @@
+export declare const xrayCommand: import("citty").CommandDef<{
+    readonly entry: {
+        readonly type: "string";
+        readonly description: "Entry point to profile";
+        readonly default: "bin/server.ts";
+    };
+}>;

package/build/src/cli/commands/xray.js

@@ -0,0 +1,49 @@
+import { defineCommand } from 'citty';
+import { isAdonisProject, profile } from '../../profiler/profiler.js';
+import { TuiReporter } from '../../profiler/reporters/tui_reporter.js';
+import { ui } from '../../profiler/reporters/format.js';
+export const xrayCommand = defineCommand({
+    meta: {
+        name: 'xray',
+        description: 'Interactive module dependency explorer',
+    },
+    args: {
+        entry: {
+            type: 'string',
+            description: 'Entry point to profile',
+            default: 'bin/server.ts',
+        },
+    },
+    async run({ args }) {
+        const cwd = process.cwd();
+        if (!isAdonisProject(cwd)) {
+            ui.logger.error('Not an AdonisJS project. Make sure adonisrc.ts exists.');
+            process.exit(1);
+        }
+        ui.logger.info('Starting cold start analysis...');
+        try {
+            const result = await profile(cwd, {
+                entryPoint: args.entry,
+                suppressOutput: true,
+            });
+            const reporter = new TuiReporter();
+            await reporter.render({
+                result,
+                cwd,
+                config: {
+                    topModules: 20,
+                    threshold: 1,
+                    includeNodeModules: true,
+                    groupByPackage: true,
+                },
+            });
+        }
+        catch (error) {
+            ui.logger.error('Profiling failed');
+            if (error instanceof Error) {
+                ui.logger.error(error.message);
+            }
+            process.exit(1);
+        }
+    },
+});

package/build/src/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/src/cli/main.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/*
+|--------------------------------------------------------------------------
+| Docteur CLI
+|--------------------------------------------------------------------------
+|
+| Standalone CLI for profiling AdonisJS cold start performance.
+| Can be installed globally and run in any AdonisJS project.
+|
+*/
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineCommand, runMain } from 'citty';
+import { diagnoseCommand } from './commands/diagnose.js';
+import { xrayCommand } from './commands/xray.js';
+const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '../../../package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+const main = defineCommand({
+    meta: {
+        name: 'docteur',
+        version: pkg.version,
+        description: pkg.description,
+    },
+    subCommands: {
+        diagnose: diagnoseCommand,
+        xray: xrayCommand,
+    },
+});
+runMain(main);

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

@@ -0,0 +1,16 @@
+import type { AppFileGroup, ModuleTiming, ProfileResult, ProfileSummary, ProviderTiming, ResolvedConfig } from '../types.js';
+export interface PackageGroup {
+    name: string;
+    totalTime: number;
+    modules: ModuleTiming[];
+}
+export declare class ProfileCollector {
+    #private;
+    constructor(modules?: ModuleTiming[], providers?: ProviderTiming[]);
+    groupAppFilesByCategory(): AppFileGroup[];
+    groupModulesByPackage(): PackageGroup[];
+    computeSummary(): ProfileSummary;
+    filterModules(config: ResolvedConfig): ModuleTiming[];
+    getTopSlowest(count: number): ModuleTiming[];
+    collectResults(totalTime: number): ProfileResult;
+}

package/build/src/profiler/collector.js

@@ -0,0 +1,142 @@
+/*
+|--------------------------------------------------------------------------
+| Profile Collector
+|--------------------------------------------------------------------------
+|
+| Collects and analyzes module timing data. Computes subtree times
+| (cascading impact including dependencies) and groups modules by
+| category or package.
+|
+*/
+import { categories } from './registries/index.js';
+export class ProfileCollector {
+    #modules;
+    #providers;
+    constructor(modules = [], providers = []) {
+        this.#modules = modules;
+        this.#providers = providers;
+        // Compute subtree times if not already done (skip after filtering to avoid incomplete graph)
+        if (modules.length > 0 && modules[0].subtreeTime === undefined) {
+            this.#populateSubtreeTimes();
+        }
+    }
+    #populateSubtreeTimes() {
+        const byUrl = new Map(this.#modules.map((m) => [m.resolvedUrl, m]));
+        const children = new Map();
+        for (const m of this.#modules) {
+            if (m.parentUrl) {
+                const list = children.get(m.parentUrl) || [];
+                list.push(m.resolvedUrl);
+                children.set(m.parentUrl, list);
+            }
+        }
+        const compute = (url, seen) => {
+            if (seen.has(url))
+                return 0;
+            seen.add(url);
+            const mod = byUrl.get(url);
+            if (!mod)
+                return 0;
+            let total = mod.loadTime;
+            for (const child of children.get(url) || []) {
+                total += compute(child, seen);
+            }
+            return total;
+        };
+        for (const m of this.#modules) {
+            m.subtreeTime = compute(m.resolvedUrl, new Set());
+        }
+    }
+    #time(m) {
+        return m.subtreeTime ?? m.loadTime;
+    }
+    #sumTime(modules) {
+        return modules.reduce((sum, m) => sum + this.#time(m), 0);
+    }
+    #sortByTime(modules) {
+        return [...modules].sort((a, b) => this.#time(b) - this.#time(a));
+    }
+    #moduleCategory(url) {
+        if (url.startsWith('node:'))
+            return 'node';
+        if (url.includes('node_modules/@adonisjs/'))
+            return 'adonis';
+        if (url.includes('node_modules/'))
+            return 'node_modules';
+        return 'user';
+    }
+    #appFileCategory(url) {
+        const path = url.toLowerCase();
+        for (const [cat, def] of Object.entries(categories)) {
+            if (def.patterns.some((p) => path.includes(p))) {
+                return cat;
+            }
+        }
+        return 'other';
+    }
+    #packageName(url) {
+        const match = url.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
+        return match?.[1] || 'app';
+    }
+    groupAppFilesByCategory() {
+        const userModules = this.#modules.filter((m) => this.#moduleCategory(m.resolvedUrl) === 'user');
+        const grouped = Object.groupBy(userModules, (m) => this.#appFileCategory(m.resolvedUrl));
+        return Object.entries(grouped)
+            .filter((e) => e[1] !== undefined)
+            .map(([category, files]) => ({
+            category,
+            displayName: categories[category].displayName,
+            files: this.#sortByTime(files),
+            totalTime: this.#sumTime(files),
+        }))
+            .sort((a, b) => b.totalTime - a.totalTime);
+    }
+    groupModulesByPackage() {
+        const grouped = Object.groupBy(this.#modules, (m) => this.#packageName(m.resolvedUrl));
+        return Object.entries(grouped)
+            .filter((e) => e[1] !== undefined)
+            .map(([name, mods]) => ({
+            name,
+            totalTime: this.#sumTime(mods),
+            modules: this.#sortByTime(mods),
+        }))
+            .sort((a, b) => b.totalTime - a.totalTime);
+    }
+    computeSummary() {
+        const grouped = Object.groupBy(this.#modules, (m) => this.#moduleCategory(m.resolvedUrl));
+        return {
+            totalModules: this.#modules.length,
+            userModules: grouped.user?.length ?? 0,
+            nodeModules: grouped.node_modules?.length ?? 0,
+            adonisModules: grouped.adonis?.length ?? 0,
+            totalModuleTime: this.#sumTime(this.#modules),
+            totalProviderTime: this.#providers.reduce((sum, p) => sum + p.totalTime, 0),
+            appFileGroups: this.groupAppFilesByCategory(),
+        };
+    }
+    filterModules(config) {
+        return this.#modules.filter((m) => {
+            if (this.#time(m) < config.threshold)
+                return false;
+            if (m.resolvedUrl.startsWith('node:'))
+                return false;
+            if (!config.includeNodeModules) {
+                const cat = this.#moduleCategory(m.resolvedUrl);
+                if (cat === 'node_modules' || cat === 'adonis')
+                    return false;
+            }
+            return true;
+        });
+    }
+    getTopSlowest(count) {
+        return this.#sortByTime(this.#modules).slice(0, count);
+    }
+    collectResults(totalTime) {
+        return {
+            totalTime,
+            modules: this.#modules,
+            providers: this.#providers,
+            summary: this.computeSummary(),
+        };
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { MessagePort } from 'node:worker_threads';
+type ResolveFn = (specifier: string, context?: {
+    parentURL?: string;
+}) => Promise<{
+    url: string;
+}>;
+type LoadFn = (url: string, context?: {
+    format?: string;
+}) => Promise<{
+    format: string;
+    source: string | ArrayBuffer | SharedArrayBuffer;
+}>;
+export declare function initialize(data: {
+    port: MessagePort;
+}): void;
+export declare function resolve(specifier: string, context: {
+    parentURL?: string;
+}, next: ResolveFn): Promise<{
+    url: string;
+}>;
+export declare function load(url: string, context: {
+    format?: string;
+}, next: LoadFn): Promise<{
+    format: string;
+    source: string | ArrayBuffer | SharedArrayBuffer;
+}>;
+export {};

package/build/src/profiler/hooks.js

@@ -0,0 +1,45 @@
+/*
+|--------------------------------------------------------------------------
+| ESM Loader Hooks
+|--------------------------------------------------------------------------
+|
+| Tracks module loading times and parent-child relationships.
+| - resolve: captures which module imported which (for subtree calculation)
+| - load: measures how long each module takes to load
+|
+*/
+import { performance } from 'node:perf_hooks';
+let port;
+const queue = [];
+let pending = false;
+function send(msg) {
+    queue.push(msg);
+    if (!pending) {
+        pending = true;
+        setImmediate(() => {
+            pending = false;
+            port?.postMessage({ type: 'batch', messages: queue.splice(0) });
+        });
+    }
+}
+export function initialize(data) {
+    port = data.port;
+}
+export async function resolve(specifier, context, next) {
+    const result = await next(specifier, context);
+    if (context.parentURL && result.url.startsWith('file://')) {
+        send({ type: 'parent', child: result.url, parent: context.parentURL });
+    }
+    return result;
+}
+export async function load(url, context, next) {
+    if (!url.startsWith('file://')) {
+        return next(url, context);
+    }
+    const start = performance.now();
+    const result = await next(url, context);
+    if (result.format === 'module') {
+        send({ type: 'timing', url, loadTime: performance.now() - start });
+    }
+    return result;
+}

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

@@ -0,0 +1 @@
+export {};